Skip to main content

This document is hidden in Docs Portal until further notice

Send sales invoices with manual validation

In Banqup, any uploaded document goes through the Document Processor app, where the invoice data are extracted and checked for sanity and accuracy.
In case of PDF documents or UBL/XML documents with insufficient data, the data extraction process might not be performed optimally (some fields will not be identified) and the invoice delivery will need to be done manually, by updating the missing information and then approving the invoice.

After a successful document processing, the document format will be automatically converted to be compliant with the format required by the receiver.

Prerequisites​


Step 1: Upload invoice

Step 1.1: Create a file


Endpoint: POST/spaces/{spaceId}/files


Request body: View details


Path parameter:

  • spaceId
curl -L 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/:spaceId/files' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "filename": "S_BE0479909676_999.xml",
    "description": "XML upload for document FAC-001",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "fileSize": 57308,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "metadata": {
        "folder": "SALES",
        "documentCategory": "INVOICE"
    }
}

Successful response:

{
    "id": "5db18794-cd31-4582-adba-5e9ff0f02f4b",
    "filename": "S_BE0479909676_999.xml",
    "description": "XML upload for document FAC-001",
    "creatorSubject": "15d02643-04e4-4cb7-b3df-a1c30900576b",
    "creatorType": "application",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "status": "AWAITING_UPLOAD",
    "fileSize": 57308,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "uploadUrl": "https://storage.googleapis.com/gcs-oaxzkhsk-eu-datastore-test/transaction/file/7cbc7e1a-a705-455e-bhj8-152974aa09e1/5db18794-cd31-4582-adba-5e9ff0f02f4b?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-btxdata-datastore-test-eu%40pj-bu-btxdata-test-eu.iam.gserviceaccount.com%2F20241209%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20241209T114309Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=a7913259d2861ac109067c056942030bc7e481700e395f0861d5d2e915ee216886d5dcc2cfaa96fa008e08e78d87652faa82d54cbe85a79c462f08be435959ffd249e3a7df628c9cfce1054d9d630b7ff8d900bdb97a8e2056333b0f7cd8a5f03ad6444ba02c0067f114802c04e39108146812f748ae9d8a790c258b7c1b825b9984e066cb0a7996f18f03db99ac3044dca8f075e58fc81723a9bb23005d5c6e7db2d5d907a39ff26f8fd25cc96fb90faf0b15b90146c514592b74bedab7a0f714f6c28f837b7ba52a0332e3cc2c7908913ce6e5da09c800c2fb11fc4e18082206c4c41a4914c9e1df92ecfd34527d7010f5e30bfbda2a4486ce113317a0a4fd",
    "metadata": {
        "folder": "SALES",
        "documentCategory": "INVOICE"
    },
    "createdAt": "2024-12-09T11:43:09.615410027Z",
    "updatedAt": "2024-12-09T11:43:09.615410027Z"
}

Step 1.2: Upload file


Endpoint: PUT/uploadUrl (returned in the previous response).
The uploadUrl is a presigned URL in GCP which allows users to temporarily and securely access bucket resources for upload.


Request body (binary): Attach the file in PDF, UBL or XML format.


Successful response: The file has been accepted for processing.

Step 2: Get the details of extension point 'Document actions'

To approve the sales invoice for delivery, you need to identify the base path URL associated with the approval task, which is obtained by executing steps 2 and 3.


Endpoint: GET/core/plugin/api/v1/extensionPoints/{extensionPointID}


Path parameter: View details

  • extensionPointID of Document actions extension
curl -L -X GET 'https://{{serverURL}}/core/plugin/api/v1/extensionPoints/{extensionPointID}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR TOKEN'

Successful response


{
  "extensionPointId": "e1b9173e-2390-4c65-bf0e-e875f2839a85",
  "namespace": "com.unifiedpost.btx",
  "name": "documentActions",
  "version": "1.0",
  "authorizationEndpoint": {
    "url": "string",
    "authorizationHeader": "string",
    "httpSignature": true
  },
  "public": true
}

Step 3: Get the base path associated with document approval task

Endpoint: GET/core/plugin/api/v1/extensionPoints/{extensionPointID}/extensions


Path parameter: View details

  • extensionPointID of Document actions extension
curl -L -X GET 'https://{{serverURL}}/core/plugin/api/v1/extensionPoints/{extensionPointID}/extensions' \
-H 'Accept: application/json'
-H 'Authorization: Bearer YOUR TOKEN'

All available extensions associated with document actions are returned in the response, together with the base paths. The one you need is .../tasks/approve.


Note: You can also integrate the partial approval task. Partial approval of an invoice will lead to a reconciliation flow and partial payment. For more information, check out the sales invoice flow.


{
    "extensions": [
        {
            "extensionId": "74be0d46-642c-4cae-a6c6-4b19923c4ef9",
            "data": {
                "name": "com.unifiedpost.btx.data:dispute",
                "label": "Dispute",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/dispute",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "68c3972e-6406-4084-8bf4-6cc2f61d55d1",
            "data": {
                "name": "com.unifiedpost.btx.data:complete",
                "label": "Complete",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/complete",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "79760144-d413-4bae-af6b-daa72b5676e7",
            "data": {
                "name": "com.unifiedpost.btx.data:markAsPaid",
                "label": "Mark Paid",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/markAsPaid",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "232def5a-a49b-471a-89b0-15a0b2dcd7aa",
            "data": {
                "name": "com.unifiedpost.btx.data:markAsWontBePaid",
                "label": "Mark as won't be paid",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/markAsWontBePaid",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "6759547f-3248-4f33-94f2-44cd83035087",
            "data": {
                "name": "com.unifiedpost.btx.aggregation:markAsPaid",
                "label": "Mark Paid",
                "basePath": "https://{{serverURL}}/pay/aggregation/documents/v1/actions/markAsPaid",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "0708b90d-3a4e-4721-9ed2-79d81e906433",
            "data": {
                "name": "com.unifiedpost.btx.data:reject",
                "label": "Reject",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/reject",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "24ff52bc-0f18-4fa6-bd24-37a05f9679d5",
            "data": {
                "name": "com.unifiedpost.btx.data:refuse",
                "label": "Refuse",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/refuse",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "c258f703-e941-4161-bbc3-be3f8283e084",
            "data": {
                "name": "com.unifiedpost.btx.data:approve",
                "label": "Approve",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/approve",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "932c2778-f844-4868-a870-3d40e093f8e2",
            "data": {
                "name": "com.unifiedpost.btx.data:partiallyApprove",
                "label": "Partially Approve",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/partiallyApprove",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "27bbd144-5840-4600-bdb0-4b491b910dc2",
            "data": {
                "name": "com.unifiedpost.btx.data:markAsUnpaid",
                "label": "Mark Unpaid",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/markAsUnpaid",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "b5cfe8da-83f9-4548-b244-2c86fd3e841d",
            "data": {
                "name": "com.unifiedpost.btx.data:markAsRefused",
                "label": "Mark as refused",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/markAsRefused",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "20addebe-a30e-4235-bd12-5e6df52589af",
            "data": {
                "name": "com.unifiedpost.btx.data:markAsResolved",
                "label": "Mark as resolved",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/markAsResolved",
                "synchronous": true,
                "supportBatch": true
            }
        },
        {
            "extensionId": "2df3226c-3cc9-47b0-b37e-fabba57929ba",
            "data": {
                "name": "com.unifiedpost.btx.data:suspend",
                "label": "Suspend",
                "basePath": "https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/suspend",
                "synchronous": true,
                "supportBatch": true
            }
        }
    ]
}

Step 4: Approve the document

Endpoint: POST/tasks/approve


Path parameter: View details

  • spaceID
  • documents
curl -L -X POST 'https://{{serverURL}}/datastore/documents/documentTasks/v1/tasks/approve' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR TOKEN' \
--data-raw '{
  "spaceId": "d44698da-6363-473f-503d-8eb213a2940e",
  "documents": "56079d21-a756-49lb-9286-9859c354aa69"
}'

Successful response


{
  "success": [
    "56079d21-a756-49lb-9286-9859c354aa69"
  ],
  "failure": []
}

Once the approval step is successfully performed, the invoice will be sent to the customer, via the pre-selected channel.

Step 5: View results

Endpoint: GET/spaces/{spaceId}/{folder}/documents/{documentId}


Path parameters: View details

  • folder
  • spaceId
  • documentId
curl -L -X GET 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/{folder}/documents/{documentId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response

{
  "id": "0ca2797b-6365-4bf2-a490-247075e3cede",
  "spaceId": "56079d21-a756-49fb-9286-9859c354aa69",
  "description": "Invoice",
  "source": "email",
  "folder": "SALES",
  "supplier": {
    "id": "d44698da-6363-476f-903d-8eb113a2940e"
  },
  "customer": {
    "id": "0639a36a-f5c2-49f8-a2db-2d60d4284362"
  },
  "status": {
    "pay": "FULLY_PAID"
  },
  "category": "INVOICE",
  "metadata": {
    "virus": "hidden"
  },
  "tags": [
    "new"
  ],
  "tasks": [
    {
      "extensionName": "com.unifiedpost.btx.data:approve",
      "status": "approve"
    }
  ],
  "retentionTime": "2023-10-04T14:20:31.502921Z",
  "lines": [
    {
      "id": "7a1cf570-db5c-4e41-992e-9890532212ae",
      "sequence": 1,
      "identifier": "ID569874",
      "description": "A4 copy paper",
      "itemId": "Item1",
      "itemCategory": "office supplies",
      "productIdentifiers": {
        "commodityCode": "BGT1256"
      },
      "quantity": 2,
      "unit": "PCS",
      "startDate": "2024-01-23",
      "endDate": "2024-06-23",
      "discounts": {
        "value": "20.0"
      },
      "charges": {
        "value": "76.67"
      },
      "unitPrice": "40.278192",
      "netAmount": "80.56",
      "grossAmount": "96.67",
      "vatAmount": "16.11",
      "currency": "USD",
      "vatRate": "0.2",
      "vatCode": "VAT"
    }
  ],
  "createdAt": "2023-10-04T14:20:31.502921Z",
  "updatedAt": "2023-10-04T14:20:31.502921Z"
}