Skip to main content

Process purchase invoices​

When a purchase invoice is received or uploaded to Banqup, the Document Processor app extracts and validates the invoice data. Once processing is complete, you can advance the document flow by applying the appropriate action—such as cancel, refuse, or mark as paid.
This recipe explains how to perform these actions on a purchase invoice.

Prerequisites​


Step 1: Create file

Endpoint: /documents/core/transaction/v1/spaces/{spaceId}/files


Path parameter: spaceId


Requires a JSON request body (see curl example below).

curl -L 'https://{{serverURL}}/documents/core/transaction/v1/spaces/{spaceId}/files' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "filename": "S_BE0479909676_888",
    "description": "xml upload for document ABC2026-23-06",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "fileSize": 66080,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "metadata": {
        "folder": "PURCHASES",
        "documentCategory": "INVOICE"
    }
}'

Successful response: Save the fileId returned in the response for further use.


Presigned URL expiration

The generated uploadUrl is time-limited. Delayed background jobs or uploads outside its validity window will fail at the storage layer. Do not store URLs for deferred processing—always request a fresh URL immediately before initiating the file transfer.


{
    "id": "1af5b819-527f-4ac5-8287-107bd8bd0be6",
    "filename": "S_BE0479909676_888",
    "description": "xml upload for document ABC2026-23-06",
    "creatorSubject": "60f7a33f-e5d3-419f-b795-f3252bdb1a12",
    "creatorType": "application",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "status": "AWAITING_UPLOAD",
    "fileSize": 66080,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/file/673f78ab-aea7-4d88-8262-86f0527ad388/2106ce16-b53c-4f3e-9b54-6ab625493e99?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20260623%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260623T074926Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=01ea59126d4c7399a90e765d137fc02ed3cb8d614974127f3f50064c15628ab5fd00e26996db6dd215be7161e85c5c5c3439d362922e80e34a0e42908f83fe391a29cc5a36e306eaa27063479c517ab484e3838a6fcff73b0521397b90961f34efd29192c6fd896d6be4c7e937a4382905a6328b41c6fdbc44cc0917399f42858d0b23a6465c838a035440d7031e6d21760495c8e16ee88b540d56e5d73415139289d66e53deb96df25554afcda2b0f9ad20e7225b7a576cf14e8b78deb8158156c2da92cc4e3edc9eab3bee530ed2d6a6679a40e5ee9a7ab30248351e584362f2b82729e025133ebd66e5513ffe17d7d153aec645e358d98e59c08f8ec1791e",
    "children": [],
    "tags": [],
    "metadata": {
        "folder": "PURCHASES",
        "documentCategory": "INVOICE"
        },
    "createdAt": "2026-06-23T07:49:26.713400850Z",
    "updatedAt": "2026-06-23T07:49:26.713400850Z"
}

Step 2: Upload file

Endpoint: /uploadUrl (returned in the previous response).


The uploadUrl is a presigned URL in GCP (Google Cloud Platform) which allows users to temporarily and securely access bucket resources for upload.


Request body: Attach the file in PDF, UBL or XML format. Content type: binary.


Upload requirement

To prevent 403 Forbidden or 400 Bad Request errors from the uploadUrl, the Content-Type in the header must exactly match the contentType value specified in the Step 1 POST request body (e.g., application/xml).


curl -L -X PUT 'https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/file/673f78ab-aea7-4d88-8262-86f0527ad388/22473145-434f-4ade-9da2-a1c2456c1a36?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20260514%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260514T141707Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=1e8757583a432b398ace0291d894ef7b20eb8ab19db4ae9f34fa03e65034af713fc856d15e0a08d841cf41dc9390a7b6b33eccdfdb12706bbc71a143ed95686db5e0d5f4b91b591f555fdbe73261a4cb08d497aef7c7cbe43becdb7c114299c64668af44358987723b08c17584e57eabdaa53a9ce1b5b72d61d1f0353077145e5bfdfef924328ad8343f87f69dae3c61f73f44f14989934b3ea22144d5f396c8288d55106e8eb58671373cda66ece6505cb94414c9db8611718f6f8a485cfb412f8b64903afe88118ce84ab871a49e7e7960564a58a29eb214c7e62e08f0554138782c0484adbad71a4025508f1f44c539c8bbf50f9b9bb75461cf6907bfe7ec' \
-H 'Content-Type: application/xml' \
-data-binary '@/C:/Users/Louis/Desktop/documents/btx/S_BE0479909676_777.xml'

Successful response: The file has been accepted for processing and receives a status.


View file details and status

The file status can be checked by retrieving the file details. Possible file statuses


Endpoint: /documents/core/transaction/v1/spaces/{spaceId}/files/{fileId}


Path parameters:

  • spaceId
  • fileId

Step 3: Retrieve document Id

Endpoint: /documents/core/transaction/v1/spaces/{spaceId}/files/{fileId}/documents


Path parameters:

  • spaceId
  • fileId

curl -L 'https://{{serverURL}}/documents/core/transaction/v1/spaces/{spaceId}/files/{fileId}/documents' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:


Empty response

If no documents are returned, it is possible that the file has status ERROR, because it might not be valid: e.g. duplicate invoice number, invalid company numbers, etc.


{
    "documents": [
        {
            "id": "213d22ab-0a81-475c-b545-2e6e48c2197b"
        }
    ]
}

Step 4: Execute a document action


Cancel

Endpoint: /documents/core/v1/spaces/{spaceId}/documents/{documentId}:cancel


Path parameters:

  • spaceId
  • documentId

Requires a JSON request body (see curl example below).


curl -L 'https://{{serverURL}}/documents/core/v1/spaces/{spaceId}/documents/{documentId}:cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "comment": "invoice not required anymore"
}'

Successful response: The document has been successfully canceled.

Dispute

Endpoint: /documents/core/v1/spaces/{spaceId}/documents/{documentId}:dispute


Requires a JSON request body (see curl example below).
See the possible reasons for disputing a document in the documentation.

curl -L 'https://{{serverURL}}/documents/core/v1/spaces/{spaceId}/documents/{documentId}:dispute' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "reason": "INCORRECT_VAT_RATE"
}'

Successful response: The document has been successfully disputed.

Refuse

Endpoint: /documents/core/v1/spaces/{spaceId}/documents/{documentId}:refuse


Requires a JSON request body (see curl example below).
See the possible reasons for refusing a document in the documentation.

curl -L 'https://{{serverURL}}/documents/core/v1/spaces/{spaceId}/documents/{documentId}:refuse' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "reason": "INCORRECT_VAT_RATE"
}'

Successful response: The document has been refused successfully.

Resolve

Endpoint: /documents/core/v1/spaces/{spaceId}/documents/{documentId}:resolve


curl -L -X POST 'https://{{serverURL}}/documents/core/v1/spaces/{spaceId}/documents/{documentId}:resolve' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response: The document has been resolved successfully.

Mark as paid

Endpoint: /payments/reconciliation/documents/v1/spaces/{spaceId}/documents/{documentId}:markAsPaid


Requires a JSON request body (see curl example below).


curl -L 'https://{{serverURL}}/payments/reconciliation/documents/v1/spaces/{spaceId}/documents/{documentId}:markAsPaid' \
-H 'Content-Type: application/json' \
-d '{
        "comment": "prepaid", 
        "paymentAmount": "62.72",
        "paymentDate": "2026-08-18",
        "paymentReferenceNumber": "123abc",
        "paymentMethod": "BANK_TRANSFER",
        "sharePaymentStatus": true
}'

Successful response: The document has been successfully marked as paid.

Mark as unpaid

Endpoint: /payments/reconciliation/documents/v1/spaces/{spaceId}/documents/{documentId}:markAsUnpaid


Requires a JSON request body (see curl example below).
To get the balance offsets of a document call this endpoint.


curl -L 'https://{{serverURL}}/payments/reconciliation/documents/v1/spaces/{spaceId}/documents/{documentId}:markAsUnpaid' \
-H 'Content-Type: application/json' \
-d '{
        "comment": "not paid",
        "reason": "duplicate",
        "email": "john.smith@example.com",
        "balanceOffsetIds": [
            "08e7060e-6cfd-4ff4-ad36-5b8d64c8a273"
],
        "sharePaymentStatus": true
}'

Successful response: The document has been successfully marked as unpaid.

Step 5: View results

Endpoint: documents/core/transaction/v2/spaces/{spaceId}/documents/{documentId}


Path parameters:

  • spaceId
  • documentId

curl -L 'https://{{serverURL}}/documents/core/transaction/v2/spaces/{spaceId}/documents/{documentId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
        "id": "213d22ab-0a81-475c-b545-2e6e48c2197b",
        "spaceId": "da3484f2-cd38-4039-85b1-f833d0c841da",
        "source": "documentprocessor",
        "folder": "PURCHASES",
        "status": {
        "pay": "UNPAID",
            "document": "VALIDATED",
            "processing": "GENERATED_DOCUMENT_NUMBER",
            "spaceExtensions": {
            "com.unifiedpost.btx.connectors": {
                "document-processor": {
                    "processing": "FINALIZED_DOCUMENT"
                }
            }
        }
    },
    "category": "INVOICE",
        "metadata": {
        "$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
            "dueDate": "2025-10-23",
            "customer": {
            "address": {
                "country": "BE",
                    "postCode": "1000",
                    "townName": "Brussels",
                    "streetName": "1234 Orient"
            },
            "legalName": "Coco Em",
                "tradeName": "Coco Em",
                "globalIdentifiers": {
                "be:en": "0417297106",
                    "be:vat": "BE0417297106",
                    "global:email": [],
                    "global:phoneNumber": [],
                    "global:participantId": "0208:0419497106"
            }
        },
        "supplier": {
            "address": {
                "country": "BE",
                    "postCode": "104569",
                    "townName": "Brussels",
                    "streetName": "12 Bloemen"
            },
            "legalName": "BamBam",
                "tradeName": "BamBam",
                "globalIdentifiers": {
                "be:en": "0405352242",
                    "be:vat": "0405352242",
                    "global:email": [
                    "elizabeth.bennet@example.com"
                ],
                    "global:phoneNumber": [],
                    "global:participantId": "0208:0805372241"
            }
        },
        "issueDate": "2025-09-23",
            "vatDetails": [
            {
                "netAmount": "20.0",
                "vatAmount": "4.2",
                "vatPercentage": "21.0"
            }
        ],
            "invoiceType": "380",
            "currencyCode": "EUR",
            "documentNumber": "ABC000008",
            "documentTotals": {
            "netAmount": "20.0",
                "vatAmount": "4.2",
                "grossAmount": "24.2",
                "payableAmount": "24.2"
        }
    },
    "tags": [
        "SEEN"
    ],
        "retentionTime": "2035-10-10T11:47:58.535376Z",
        "balanceOffsets": []
}

Step 6: Download purchase invoice
Step 6.1: Retrieve document representation(s)

Endpoint: /documents/core/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations


Path parameters:

  • spaceId
  • documentId

curl -L 'https://{{serverURL}}/documents/core/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
    "document_representations": [
        {
            "id": "ca23a28b-135c-243f-a767-f83802f081fc",
            "documentId": "2d4b9560-08ef-458e-8bfd-a7c17cb7cc83",
            "retentionTime": "2034-07-29T15:51:28.071Z",
            "type": "legal_xml",
            "filename": "sales_invoice.xml",
            "contentType": "application/xml",
            "size": 45330,
            "metadata": {},
            "status": "VIRUS_SCANNED",
            "main": true,
            "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/transaction/da3484f2-cd58-4036-85b1-f833d0c841da/2d4b7560-88ef-458e-8bfd-a7c17cb7cc83/ca23a28b-135c-442f-a767-f83802f081fc?GoogleAccessId=sw-btxdata-3fac8c-uat-eu@pj-bu-btxdata-uat-eu.iam.gserviceaccount.com&Expires=1762942936&Signature=EUEh8UvR4Fw6gWg6zWLE9j9pC9n0G8TA0MCkrZNMItkNzqdq5W7mS0rOrE6wjzJgYgGpr6RSihUB3ETJ1PFTd7%2FDXYd5hM18ZdkfhdgZuEg0YUOsltz4ftMFW9BNE2dwzS2x68opuVG%2FNEcLcA2u%2F94fN6bwIs8e2g%3D%3D",
            "md5Hash": "EDpLVfRF0IS7hDcxKdVN6g==",
            "createdAt": "2025-11-12T08:57:24.408842Z",
            "updatedAt": "2025-11-12T08:57:33.820318Z",
            "original": true
        },
        {
            "id": "9e9286cf-a974-481c-a32a-81e3a7692a68",
            "documentId": "2d4b7360-08ef-458e-8bfd-a7c17cb7cc83",
            "retentionTime": "2030-11-12T09:02:13.753634Z",
            "type": "com.unifiedpost.btx.pdf:invoice:1.0",
            "filename": "2d4b7520-08ef-458e-8bfd-a7c17cb7cc83_com.unifiedpost.btx.pdf_invoice_1.0.pdf",
            "contentType": "application/pdf",
            "size": 44841,
            "metadata": {},
            "status": "VIRUS_SCANNED",
            "main": false,
            "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/transaction/da3484f2-cd58-2039-85b1-f833d0c841da/2d4b8560-08ef-458e-8bfd-a7c17cb7cc83/9e9288cf-a974-481c-a31a-81e3a7692a68?GoogleAccessId=sw-btxdata-3fac8c-uat-eu@pj-bu-btxdata-uat-eu.iam.gserviceaccount.com&Expires=1762942936&Signature=Vmd%2F%2FQFSO15E1VyEUmVcOIWLIUTWHODnKKwvm%2BuK2o2Dl7%2F8hbBgZQvQCUJFvVMSwoF2Xv%2Bstw6jgRYNfESea%2F6WVq7U0fIaYxcONRiCzwUDDUFDc511D8qDruby5hQj0Pdn6ZFhrrEm%2FJ0Mi3llcUsiiKqdAoM7fsVcRsqCu6V%2BzMzD%2Bh4iRuAXrjGSRV4a5irpQk9faAsGJlQ%2FSlTMrj5SFTI2cs8b4XYtEGlMAgwfoGGqBGvOoMxg%3D%3D",
            "md5Hash": "WcxVMWcQZxRhiEsmKRWcrA==",
            "createdAt": "2025-11-12T09:02:13.753799Z",
            "updatedAt": "2025-11-12T09:02:15.084239Z",
            "original": false
        },
        {
            "id": "92782eb5-90b3-4a23-9f31-f4b160ab4739",
            "documentId": "2d4b7360-08ef-458e-8bfd-a7c17cb7cc83",
            "retentionTime": "2030-11-12T09:02:15.186811Z",
            "type": "eu.peppol.bis3:invoice:2024.11",
            "filename": "2d4b7560-09ef-458e-8bfd-a7c17cb7cc83_eu.peppol.bis3_invoice.xml",
            "contentType": "application/xml",
            "size": 64224,
            "metadata": {},
            "status": "VIRUS_SCANNED",
            "main": false,
            "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/transaction/da3484f2-cd58-2039-85b1-f833d0c841da/2d4b7560-98ef-458e-8bfd-a7c17cb7cc83/92787eb5-90b3-4a13-9f31-f4b160ab4739?GoogleAccessId=sw-btxdata-3fac8c-uat-eu@pj-bu-btxdata-uat-eu.iam.gserviceaccount.com&Expires=1762942936&Signature=mVc3iPpD%2BGn%2BxoIVJbJmdCotyuoihvA50MQRaNyu9mXtA1hdpbeENFD056xE0sCbu%2BomM8VkniaSC3IBuUYDKu8DzJ5txH3zzRCJuq5zayM0avdwkRaDkJ7cdo%2FYL4HGRpXc9jmoSdcKH0%2BxVjJTw%2Fo5ZEE3%2FKw0hMXRGr9xbtS%2Fsb2eYOWBJUsDL98jIPvkXJ%2Fqnm24YoR0dRwlW%2FqvTLJLJ57%2FAJOHqirhmC3zDIC3%2FG%2BYVgZIaQ%3D%3D",
            "md5Hash": "Z8Xq/kubUK0zC6fW7F8k/A==",
            "createdAt": "2025-11-12T09:02:15.186975Z",
            "updatedAt": "2025-11-12T09:02:15.861886Z",
            "original": false
        }
    ],
    "currentPage": 0,
    "pageSize": 20
}

Step 6.2: Retrieve document content

Endpoint: uploadUrl


Use the appropriate uploadUrl from the previous response based on the type of document you wish to download (XML or PDF).


curl -L 'https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/transaction/da3484f2-cd58-4036-85b1-f833d0c841da/2d4b7560-88ef-458e-8bfd-a7c17cb7cc83/ca23a28b-135c-442f-a767-f83802f081fc?GoogleAccessId=sw-btxdata-3fac8c-uat-eu@pj-bu-btxdata-uat-eu.iam.gserviceaccount.com&Expires=1762942936&Signature=EUEh8UvR4Fw6gWg6zWLE9j9pC9n0G8TA0MCkrZNMItkNzqdq5W7mS0rOrE6wjzJgYgGpr6RSihUB3ETJ1PFTd7%2FDXYd5hM18ZdkfhdgZuEg0YUOsltz4ftMFW9BNE2dwzS2x68opuVG%2FNEcLcA2u%2F94fN6bwIs8e2g%3D%3D'

Successful response:


The document content is returned in the response body.