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:
- front end already knows ByDesign sales order number.
- one sales order only maps to one invoice
- 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.
Hi Rohan,
I like your blog post promoting the new functionality we provide.
When it comes to the documentation, I would like to point you to our new footprint in the SAP API Business Hub. This is only available as of two weeks ago.
When you search for "output" you will find the web service documentation.
Best regards
Otfried
Dear Otfried,
Thank you for your input. I wasn't aware of the API hub, and it looks really nice!
Currently, the link leads to a documentation page that has very basic data about this service (screenshot attached). Would it be a good idea to direct this link to the API hub page?
Thanks and regards,
Rohan
Hi Rohan,
the link in the ByD Service Explorer should show the same content as you can see in the API Business Hub. We plan to fix that as soon as possible.
Thanks for pointing us to the issue and best regards,
Knut
Thanks, Knut.
That is indeed helpful.
Best regards,
Rohan
Hello experts,
I am trying to use the "ReadOutputPDF" operation with SOAPUI.
I get an answer with an HTTP status of 200 but the PDF is not included in the SOAP response.
Request :
Response :
Can you help me to resolve this issue ?
Thanks in advance,
Maxime
Hi Mixime,
Looks like you are trying to read the document in XML format. I tried this, and got a response as you can see in the screenshot. Not sure why you don't get a response, maybe create a ticket for SAP?
It might also help to try to read the document in PDF, with a request like this, to see if that works.
Regards,
Rohan
Hello,
I Have the same problem with the response, was that solved?
Dear Rohan,
Thanks for your sharing.
I would like to know for two things.
As your Assumptions:3 : we can use this process for SO>OutboundDelivery>CIV flow only. Right?
Can we use this process for third party case? E.g: PO>SO>PO>OutboundDelivery>CIV flow.
And I tried as your sharing document, but when I input CIV's UUID to "DocumentOutputRequestByElementsQuery_sync" scenario and retrieve the "DocumentUUID" for PDF query, I get the following error:
"<html><head><title>Logon Error Message</title><META http-equiv="Content-Type" content="text/html;charset=UTF-8"><style type="text/css">body { font-family:tahoma,helvetica,sans-serif;color:#333333;background-color:#FFFFFF; }td { font-family:tahoma,helvetica,sans-serif;font-size:70%;color:#333333; }h1 { font-family:tahoma,helvetica,sans-serif;font-size:160%;font-weight:bold;margin-top:15px;margin-bottom:3px;color:#003366; }h2 { font-family:verdana,helvetica,sans-serif;font-size:120%;font-style:italic;font-weight:bold;margin-top:6px;margin-bottom:6px;color:#999900; }p { font-family:tahoma,helvetica,sans-serif;color:#333333;margin-top:4px;margin-bottom:4px; }ul { font-family:tahoma,helvetica,sans-serif;color:#333333;list-style-type:square;margin-top:8px;margin-bottom:8px; }li { font-family:tahoma,helvetica,sans-serif;color:#33333;margin-top:4px; }.emphasize { color:#333333;background-color:#C8E3FF;padding:5px;}.note { color:#CC6600; }a { font-family:tahoma,helvetica,sans-serif;text-decoration:underline;color:#336699; }a:visited { color:#001166; }a:hover { text-decoration:none; }</style></head><body><table cellpadding="0" cellspacing="0" border="0" width="100%"><tr><td><h1>Logon failed</h1></td></tr></table></body></html>"
Could you please advice for my error?
my request is as follow:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
<soap:Header/>
<soap:Body>
<glob:DocumentOutputRequestByElementsQuery_sync>
<!--Optional:-->
<DocumentOutputRequestSelectionByElements>
<SelectionByHostObjectUUID>
<!--Optional:-->
<InclusionExclusionCode>I</InclusionExclusionCode>
<!--Optional:-->
<IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
<!--Optional:-->
<LowerBoundaryUUID>00163e0e-2105-1eea-81b8-8db63ea6edc8</LowerBoundaryUUID>
</SelectionByHostObjectUUID>
</DocumentOutputRequestSelectionByElements>
<ProcessingConditions>
<QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>
</ProcessingConditions>
</glob:DocumentOutputRequestByElementsQuery_sync>
</soap:Body>
</soap:Envelope>
Thanks and regards,
Su Mon