GetInvoiceSpecificationPDF

Invoicing service 1.1: Generates and returns, as base64 PDF bytes, the specification pages of an invoice, credit note, voucher or reminder by its integer ID.


Service	Invoicing 1.1
Endpoint	`POST https://app{server-number}.timelog.com/{account}/WebServices/Invoicing/V1_1/InvoicingServiceSecure.svc`
SOAPAction	`GetInvoiceSpecificationPDFRequest`
Content-Type	`text/xml; charset=utf-8`
Authentication	A token from GetToken
Changes data	No
Safe to retry	Yes

The same operation is in Invoicing 1.2 (.../WebServices/Invoicing/V1_2/InvoicingServiceSecure.svc) with an identical request and response. Invoicing 1.0 (.../V1_0/...) is obsolete: it takes the token values in http://www.timelog.com/api/tlp/v1_1, and returns the older response envelope in namespace http://www.timelog.com/api/tlp/v1_1, without IsReturnPaged and TotalPageCount. Use 1.1 or 1.2.

How it works

It does not return the invoice page itself. Despite the name, invoiceID can be the ID of ANY invoicing document: invoice, credit note, voucher or reminder. The specification template is the one linked to the document's own print template; the document is rendered as it is now. The PDF is generated on every call and the whole document is buffered into the response - there is no streaming or MTOM. Large specifications therefore produce large SOAP messages; raise your client's maximum received message size accordingly. An unknown ID returns a misleading null-reference error.

Parameters

Each parameter has one label: Required, Conditional (required depending on other values) or Optional. Send them in the order shown.

invoiceIDinteger

Required

Integer ID of the invoicing document - not the GUID and not the invoice number (InvoiceNo). You get it as ID on the invoices that the other Invoicing operations return (for example GetInvoicesModifiedInPeriodPaged), as the ID attribute of tlp:Invoice in the Reporting API's GetInvoicesRaw, or as InvoiceID in GetInvoiceLinesRaw.

tokenSecurityToken

Required

The token from GetToken: Initials, Expires and Hash, with their values sent back unchanged. Put them in namespace http://www.timelog.com/api/tlp/v1_3, as in the request example. GetToken (Security 1.2) returns them in http://www.timelog.com/api/tlp/v1_2, so don't copy the token XML from its response as it is: that gives a DeserializationFailed SOAP fault.

Request

POST /{account}/WebServices/Invoicing/V1_1/InvoicingServiceSecure.svc HTTP/1.1
Host: app{server-number}.timelog.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "GetInvoiceSpecificationPDFRequest"

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:invoicing="http://www.timelog.com/api/tlp/v1"
                  xmlns:tok="http://www.timelog.com/api/tlp/v1_3">
  <soapenv:Body>
    <invoicing:GetInvoiceSpecificationPDF>
      <invoicing:invoiceID>{invoiceID}</invoicing:invoiceID>
      <invoicing:token>
        <tok:Initials>{Initials from GetToken}</tok:Initials>
        <tok:Expires>{Expires from GetToken, unchanged}</tok:Expires>
        <tok:Hash>{Hash from GetToken}</tok:Hash>
      </invoicing:token>
    </invoicing:GetInvoiceSpecificationPDF>
  </soapenv:Body>
</soapenv:Envelope>

curl -X POST "https://app{server-number}.timelog.com/{account}/WebServices/Invoicing/V1_1/InvoicingServiceSecure.svc" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPAction: "GetInvoiceSpecificationPDFRequest"' \
  --data-binary @request.xml

import requests

URL = "https://app{server-number}.timelog.com/{account}/WebServices/Invoicing/V1_1/InvoicingServiceSecure.svc"
SOAP_ACTION = '"GetInvoiceSpecificationPDFRequest"'

envelope = """<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:invoicing="http://www.timelog.com/api/tlp/v1"
                  xmlns:tok="http://www.timelog.com/api/tlp/v1_3">
  <soapenv:Body>
    <invoicing:GetInvoiceSpecificationPDF>
      <invoicing:invoiceID>{invoiceID}</invoicing:invoiceID>
      <invoicing:token>
        <tok:Initials>{Initials from GetToken}</tok:Initials>
        <tok:Expires>{Expires from GetToken, unchanged}</tok:Expires>
        <tok:Hash>{Hash from GetToken}</tok:Hash>
      </invoicing:token>
    </invoicing:GetInvoiceSpecificationPDF>
  </soapenv:Body>
</soapenv:Envelope>"""

response = requests.post(
    URL,
    data=envelope.encode("utf-8"),
    headers={"Content-Type": "text/xml; charset=utf-8", "SOAPAction": SOAP_ACTION},
    timeout=60,
)
result = parse_result(response)  # see "Responses and errors"

Replace every {…} placeholder with your own value.

Response

The call returns the standard response envelope. Check ResponseState first: a failed call still returns HTTP 200.

ResponseStatestring

Required

Success, Invalid or Error.

ErrorCodeinteger

0 on success, otherwise the error code. See Errors.

ReturnInvoiceSpecification[]

Response<InvoiceSpecification>: Return[0].specification = the PDF bytes. No 'Successfully called' message. Never empty on success.

Example response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetInvoiceSpecificationPDFResponse xmlns="http://www.timelog.com/api/tlp/v1">
      <GetInvoiceSpecificationPDFResult xmlns:a="http://api.timelog.com"
                                        xmlns:b="http://www.timelog.com/api/tlp/v1"
                                        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Return>
          <b:InvoiceSpecification>
            <a:Action>Original</a:Action>
            <a:IsCustomFieldsLoaded>false</a:IsCustomFieldsLoaded>
            <a:CustomFields i:nil="true"/>
            <a:IsExternalKeysLoaded>false</a:IsExternalKeysLoaded>
            <a:ExternalKeys i:nil="true"/>
            <b:specification>AAAAAAAAAAA=</b:specification>
          </b:InvoiceSpecification>
        </a:Return>
        <a:ReturnTypeDescription>InvoiceSpecification</a:ReturnTypeDescription>
        <a:Request>…</a:Request>
        <a:ResponseState>Success</a:ResponseState>
        <a:Messages>
          <a:APIMessage>
            <a:Message>Duration of call was 0,0421337 sec.</a:Message>
            <a:Severity>Message</a:Severity>
            <a:ErrorCode>0</a:ErrorCode>
          </a:APIMessage>
        </a:Messages>
        <a:ErrorCode>0</a:ErrorCode>
        <a:IsReturnPaged>false</a:IsReturnPaged>
        <a:TotalPageCount>1</a:TotalPageCount>
      </GetInvoiceSpecificationPDFResult>
    </GetInvoiceSpecificationPDFResponse>
  </s:Body>
</s:Envelope>

Illustrative example: built from the service description (WSDL) in the same format as a real response, with made-up values. The Request block is shortened.

Errors

Errors from TimeLog come back with HTTP 200: check ResponseState, ErrorCode and Messages. The errors every operation can return (expired or invalid token, API not enabled, HTTPS required, general errors) are listed once in Responses and errors.

A request that TimeLog cannot read never reaches it. It comes back as a SOAP fault with HTTP 500 instead, without a response envelope (see SOAP faults). For this operation:

faultcode	Cause	What to do
`a:ActionNotSupported`	The `SOAPAction` header is not `GetInvoiceSpecificationPDFRequest`.	Send the SOAPAction exactly as in the request example.
`a:InternalServiceFault` ("The server was unable to process the request due to an internal error")	The element inside `Body` is not `GetInvoiceSpecificationPDF` in namespace `http://www.timelog.com/api/tlp/v1`, for example the misspelling `GetInvoiceSpecificationsPDF`.	Copy the element name and namespace from the request example.
`a:DeserializationFailed`, the message names `invoiceID`	`invoiceID` is not an integer, for example a GUID or an invoice number.	Send the integer ID (see the `invoiceID` parameter).
`a:DeserializationFailed`, the message names `token`	The token values are in the wrong namespace, one of them is missing, or `Expires` was reformatted.	Send the three values in `http://www.timelog.com/api/tlp/v1_3`, unchanged.

Errors specific to this operation:

ResponseState	ErrorCode	Message	What it means	What to do
Error	40001	Error during call on TimeLog.API, Message 'Object reference not set to an instance of an object.'	No invoicing document has this ID.	Check the invoice ID.

Was this page helpful?