Web Service Calls to Get Customer Invoice PDF from ByDesign

With the 1808 release, there is a new web service available: ‘QueryDocumentOutputRequestIn’. Using this web service, it is now possible to retrieve the output forms from ByDesign in either PDF or XML format.

While understandably since this is a new web service, and the documentation is not yet available from SAP, there is already a bit of interest from some developers (me included), so here is some basic information, based on my recent experience.

Questions posted on the forum earlier:

https://answers.sap.com/questions/565274/retrieving-customer-invoice-pdf-files-from-bydesig.html

https://answers.sap.com/questions/433046/customer-invoice-output-over-edi-possible.html

Let us consider the following problem statement. You have a front end web shop and backend ByDesign. The sales order is first entered in the front-end web shop, and subsequently replicated to ByDesign. The requirement is to obtain ByDesign’s invoice PDF (or XML) document on the front end.

Assumptions:

1. front end already knows ByDesign sales order number.
2. one sales order only maps to one invoice
3. only preceding document type for invoice is ‘sales order’

Step 1: Get the invoice UUID

use web service ‘QueryCustomerInvoiceIn’ to get the invoice UUID.

example request, consider sales order ID is ‘123’:

Customer Invoice Query Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
    <soapenv:Header/>
    <soapenv:Body>
        <glob:CustomerInvoiceByElementsQuery_sync>
            <CustomerInvoiceSelectionByElements>
                <SelectionByBaseBTDReferenceID>
                    <InclusionExclusionCode>I</InclusionExclusionCode>
                    <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
                    <LowerBoundaryName>123</LowerBoundaryName>
                </SelectionByBaseBTDReferenceID>
             </CustomerInvoiceSelectionByElements>
        </glob:CustomerInvoiceByElementsQuery_sync>
    </soapenv:Body>
</soapenv:Envelope>

example response:

Customer Invoice Query Response

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Header/>
    <soap-env:Body>
        <n0:CustomerInvoiceByElementsResponse_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
            <CustomerInvoice>
                <ID>456</ID>
                <UUID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</UUID>
                ...etc.
            </CustomerInvoice>
        </n0:CustomerInvoiceByElementsResponse_sync>
    </soapenv:Body>
</soapenv:Envelope>

here, you see that the customer invoice ID is ‘456’.

make a note of the ‘UUID’: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Important note: see ‘Assumptions’ above.

Step 2: get the Document UUID

Use web service ‘QueryDocumentOutputRequestIn’ to get the document UUID.

operation name: FindByElements

Continuing with the example, the customer invoice UUID is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

example request:

Document Output Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
    <soapenv:Header/>
    <soapenv:Body>
        <glob:DocumentOutputRequestByElementsQuery_sync>
            <DocumentOutputRequestSelectionByElements>
                <SelectionByHostObjectUUID>
                    <InclusionExclusionCode>I</InclusionExclusionCode>
                    <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
                    <LowerBoundaryUUID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</LowerBoundaryUUID>
                </SelectionByHostObjectUUID>
            </DocumentOutputRequestSelectionByElements>
            <ProcessingConditions>
                <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>
            </ProcessingConditions>
        </glob:DocumentOutputRequestByElementsQuery_sync>
    </soapenv:Body>
</soapenv:Envelope>

example response:

Document Output Response

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Header/>
    <soap-env:Body>
        <n0:DocumentOutputRequestByElementsResponse_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
            <DocumentOutputRequestInformation>
                ...
                <DocumentUUID>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</DocumentUUID> 
                ...etc.
            </DocumentOutputRequestInformation>
        </n0:DocumentOutputRequestByElementsResponse_sync>
    </soap-env:Body>
</soap-env:Envelope>

note down the document uuid: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Step 3: Get the document in PDF

once you have the Document UUID, you can use the web service ‘QueryDocumentOutputRequestIn’ and operation ‘ReadOutputPDF’ to get the PDF file.

continuing with the example, our document UUID is yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

example request:

PDF request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
    <soapenv:Header/>
    <soapenv:Body>
        <glob:DocumentOutputRequestPdf_sync>
            <DocumentOutputRequestPDFInformation>
                <ReadByDocumentUUID>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</ReadByDocumentUUID>
            </DocumentOutputRequestPDFInformation>
       </glob:DocumentOutputRequestPdf_sync>
    </soapenv:Body>
</soapenv:Envelope>

the response will contain the PDF file content.

Step 4: Get the document in XML

Similar as step 3, but use the web service operation ‘ReadOutputXML’.

Thanks to SAP for closing this crucial gap. With this new web service, it is now possible to retrieve the output documents over a web service call. In my experience, the invoice PDF is of very high importance, but I can imagine several use cases which require the retrieval of other output forms too.