# Purchase Invoice v1
The /purchaseInvoice endpoints are used to receive documents. A full tutorial on how to receive documents can be found here.
# Status
When a document is received, a hook is send to the receiver. This hook contains the documentId used to identify the received document. GET /api/v1/{partyId}/purchaseInvoice/{documentId}/status can be used to check the status of the received document. {partyId} should be the receiver's partyId and {documentId} the documentId found in the hook.
# Download
To download the received document, call GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download. {partyId} should be the receiver's partyId and {documentId} the documentId found in the hook. The response body will contain the received document.
# Query recipient party
The POST /api/v1/{partyId}/purchaseInvoice/queryRecipientParty endpoint can be used to confirm if the seller supports invoice response messages. The {partyId} specified in the route should be the sender's partyId. The request body accepts an array of partyIds, in JSON. The response will contain the recipient party that should be used as endpointId in the invoice response, as well as the delivery channel.
The query parameter ?preferredDocumentTypeId can be used if a specific documentTypeId is preferred. Specifying a preferred documentTypeId will make sure the documentTypeId is prioritized in the lookup.
# Response
The POST /api/v1/{partyId}/purchaseInvoice/{documentId}/response endpoint can be used to send an Invoice Response (opens new window) to the seller. Follow the Tutorial: Responding to the supplier via "Invoice Response".
The {partyId} should be the receiver's partyId and {documentId} the documentId found in the hook. The response body is a JSON payload based on these fields:
| Field | Usage |
|---|---|
status* | Status codes used as Invoice Response Codes (AB, IP, UA, RE, AP, PD) |
reasons** | Depending on the status code, a clarification may be needed to state the buyer’s reason for the status. (NON, REF, LEG, REC, QUA, DEL, PRI, QTY, ITM, PAY, UNR, FIN, PDD, OTH) |
| actions | Expectations towards the seller. (NOA, PIN, NIN, CNEF, CNP, CNA, OTH) |
| note | You may give comments or instructions that apply to the whole response. |
* Status code is required.
** Required for status codes "UQ, CA, RE".
# Delete
By default, received documents are kept for 90 days. After the document has been downloaded by the receiver, it’s retained for 7 more days. If you want to delete the document sooner, call DELETE /api/v1/{partyId}/purchaseInvoice/{documentId}.
# Recognize
The POST /api/v1/{partyId}/purchaseInvoice/recognize endpoint can be used to recognize non-standard documents like a PDF invoice and convert them to a UBL invoice. The {partyId} specified in the route should be the sender's partyId.
The document to recognize should be added to the request body as a binary file with content type multipart/form-data. The current maximum size that can be uploaded is 15MB, if a file is larger then 15MB, we will throw Error code 413.
The response will contain a documentId, which can be used to check the status of the document. When the process is complete and the document is converted, a "PurchaseInvoiceRecognized" hook will trigger. If manual verification is needed a "PurchaseInvoiceRecognizedPending" hook is sent and when the document is rejected after verification a "PurchaseInvoiceRecognizedRejected" hook will trigger. When things go wrong the hook will have the "PurchaseInvoiceRecognizedError" topic instead.
For a more detailed description, refer to the recognize tutorial.
← Sales invoice Hook →