Generate and send Factur-X documents
The Factur-X standard is a hybrid electronic invoicing format that combines a human-readable PDF with structured XML data in a single document. This API recipe demonstrates how to generate a valid invoice that meets the Factur-X schema requirements.
Prerequisites
- Valid JSON with metadata
- PDF file
- Banqup permissions
- Connectors are installed and activated in the Network Connectors app
Step 1: Create document
Step 1.1: Create document with JSON
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents
Path parameter:
spaceId
Request body: View documentation
Notes:
- All 3 statuses (pay, delivery, document) need to be defined in the JSON.
- If the customer exists in Banqup, add the connection information in the JSON to skip the step of assigning the connection to the document later in the recipe.
curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"source": "documentcreator",
"connections": [
{
"displayName": "Traffic acc.",
"relationType": "CUSTOMER",
"id": "486df746-5968-4910-9fc8-d8fd91ca5be6"
}
],
"spaceId": "sa6484f2-cd58-4039-85b1-f833d0c841da",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"delivery": "RECEIVED",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata" : {
"$schema" : "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"dueDate" : "2025-12-12",
"customer" : {
"address" : {
"country" : "BE",
"postCode" : "1310",
"townName" : "Antwerp",
"streetName" : "Bloemen",
"buildingNumber" : "1"
},
"legalName" : "Traffic acc.",
"tradeName" : "Traffic acc.",
"globalIdentifiers" : {
"be:en" : "1404666914",
"be:vat" : "BE1404666914",
"global:email" : [ "atticus.finch@example.com" ]
}
},
"supplier": {
"address": {
"streetName": "51 route de Verneuil",
"townName": "Les Mureaux",
"postCode": "78130",
"country": "FR"
},
"legalName": "ARIANEGROUP SAS",
"tradeName": "ARIANEGROUP SAS",
"globalIdentifiers": {
"fr:siren": "319032247",
"fr:siret": "31903224700040",
"fr:vat": "FR81519032247",
"global:email": [
"hester.prynne@example.com"
],
"global:participantId": "0208:0577548453"
}
},
"issueDate" : "2025-11-12",
"vatDetails" : [ {
"netAmount" : "25.00",
"vatAmount" : "0",
"vatCategory" : "E",
"vatPercentage" : "0",
"exemptionReason" : "VAT exempt"
} ],
"invoiceType" : "380",
"currencyCode" : "EUR",
"documentNumber" : "ABC1211255698",
"documentTotals" : {
"netAmount" : "25.00",
"vatAmount" : "0",
"grossAmount" : "25.00",
"payableAmount" : "25.00"
}
},
"lines": [
{
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_line/v1/document-line-schema.json",
"quantity": "1",
"unit": "EA",
"netAmount": "25.00",
"currency": "EUR",
"metadata": {
"externalLineId": "L001",
"notes": [
{
"code": "AAA",
"text": "Pièces automobiles - frein avant"
},
{
"code": "AAB",
"text": "Net 30"
}
],
"buyerAccountingReference": "REM-TRAFFIC-FR",
"invoiceReferences": [
{
"invoiceReference": "IN-000244",
"invoiceType": "380",
"issueDate": "2025-10-20",
"invoiceNumber": "IN-221125"
}
],
"delivery": {
"name": "REM. TRAFFIC",
"address": {
"department": "Service achat",
"streetName": "Fleurs",
"buildingNumber": "12",
"townName": "Paris",
"postCode": "75001",
"country": "FR"
},
"deliveryDate": "2025-10-20"
},
"startDate": "2025-10-20",
"endDate": "2025-10-20",
"allowances": [],
"charges": []
},
"pricing": {
"itemNetPrice": "25.00",
"itemGrossPrice": "25.00",
"itemPriceQuantity": "1",
"itemPriceDiscount": "0.00"
},
"vatDetails": {
"vatCategory": "E",
"vatPercentage": "0",
"vatAmount": "0.00"
},
"productIdentifiers": {
"itemId": "ITEM-001",
"itemCategory": "Automobile",
"itemDescription": "Kit de freins avant pour véhicule utilitaire"
}}],
"retentionTime": "2029-01-14T19:58:47+02:00"
}'
Successful response:
{
"timestamps": {
"createdAt": "2025-11-21T07:26:18.591431939Z",
"updatedAt": "2025-11-21T07:26:18.591431939Z"
},
"lines": [
{
"id": "a58aafc3-9cbe-4137-a587-a3f85d3c14e8",
"sequence": 1,
"data": {
"productIdentifiers": {
"itemId": "ITEM-001",
"itemCategory": "Automobile",
"itemDescription": "Kit de freins avant pour véhicule utilitaire"
},
"unit": "EA",
"metadata": {
"externalLineId": "L001",
"notes": [
{
"code": "AAA",
"text": "Pièces automobiles - frein avant"
},
{
"code": "AAB",
"text": "Net 30"
}
],
"buyerAccountingReference": "REM-TRAFFIC-FR",
"invoiceReferences": [
{
"invoiceReference": "IN-000244",
"invoiceType": "380",
"issueDate": "2025-10-20",
"invoiceNumber": "IN-221125"
}
],
"delivery": {
"name": "REM. TRAFFIC",
"address": {
"department": "Service achat",
"streetName": "Fleurs",
"buildingNumber": "12",
"townName": "Paris",
"postCode": "75001",
"country": "FR"
},
"deliveryDate": "2025-10-20"
},
"startDate": "2025-10-20",
"endDate": "2025-10-20",
"allowances": [],
"charges": []
},
"quantity": "1",
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_line/v1/document-line-schema.json",
"netAmount": "25.00",
"currency": "EUR",
"vatDetails": {
"vatCategory": "E",
"vatPercentage": "0",
"vatAmount": "0.00"
},
"pricing": {
"itemNetPrice": "25.00",
"itemGrossPrice": "25.00",
"itemPriceQuantity": "1",
"itemPriceDiscount": "0.00"
}
}
}
],
"customCategories": {},
"connections": [],
"id": "ela4eb01-37f9-4310-aea8-e69dd4434174",
"spaceId": "sa3484f2-cd58-4039-85b1-f833d0c841da",
"source": "documentcreator",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"delivery": "RECEIVED",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"dueDate": "2025-12-12",
"customer": {
"address": {
"country": "BE",
"postCode": "1310",
"townName": "Antwerp",
"streetName": "Bloemen",
"buildingNumber": "1"
},
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"globalIdentifiers": {
"be:en": "1404866914",
"be:vat": "BE1404866914",
"global:email": [
"atticus.finch@example.com"
]
}
},
"supplier": {
"address": {
"streetName": "51 route de Verneuil",
"townName": "Les Mureaux",
"postCode": "78130",
"country": "FR"
},
"legalName": "ARIANEGROUP SAS",
"tradeName": "ARIANEGROUP SAS",
"globalIdentifiers": {
"fr:siren": "319032247",
"fr:siret": "31903224700040",
"fr:vat": "FR85519032247",
"global:email": [
"hester.prynne@example.com"
],
"global:participantId": "0208:0577542463"
}
},
"issueDate": "2025-11-12",
"vatDetails": [
{
"netAmount": "25.00",
"vatAmount": "0",
"vatCategory": "E",
"vatPercentage": "0",
"exemptionReason": "VAT exempt"
}
],
"invoiceType": "380",
"currencyCode": "EUR",
"documentNumber": "ABC1211255698",
"documentTotals": {
"netAmount": "25.00",
"vatAmount": "0",
"grossAmount": "25.00",
"payableAmount": "25.00"
}
},
"tags": [],
"retentionTime": "2029-01-14T17:58:47Z"
}
Step 1.2: Create document representation
Endpoint:
/datastore/documents/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations
Path parameters:
spaceIddocumentId
Request body: View documentation
curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"fileSize": 5236,
"retentionTime": "2034-07-29T15:51:28.071Z",
"type": "legal_xml",
"filename": "sales_invoice.xml",
"contentType": "application/xml",
"main": true,
"md5Hash": "string",
"original": true
}'
Successful response:
{
"id": "12f8mc19-1f37-4cf2-9c27-deb44867485e",
"documentId": "efa4ep01-37f9-4310-aea8-e69dd4434174",
"retentionTime": "2034-07-29T15:51:28.071Z",
"type": "legal_xml",
"filename": "sales_invoice.xml",
"contentType": "application/xml",
"size": 5236,
"metadata": {},
"status": "AWAITING_UPLOAD",
"main": true,
"uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/da3484f2-xd58-4039-85b1-f833d0c841da/efa3eb01-37f9-4310-aea8-e69dd4434174/12f8bc19-1f37-8cf2-9c27-deb44867485e?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20251121%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20251121T072635Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=8c9e4d3622eb16bda2de7c6d7d8c63eecf4e84c9a8452420d25aa384bb4c31c4d95f540ba2fc53da51f6746415754777602d2e4ff4510e5344e231aa6f78a20ae236bd5ca071c0db6cc6a70587bbf70f4092bfdf9057986ddb7fa01dcf6512f886398f7eb4344deb895a3dedbc94b8569cbcc80c8621174264598a2c4caddeb788faccdcb083af65c95a761d0d21e5c390e95a1e35e3792b1f7fe15f4ac4a71b2a866f8446249298e03cb35bd1fa5c7813abfb9c8131b84b4c72883a96e05486cb8bda45c0eff080f5ac342cac3b95be20a0faadc55f2d574f8830b15e8463ff00875d2229db2ca6c5320059012368d42acd",
"md5Hash": "string",
"createdAt": "2025-11-21T07:26:35.230140019Z",
"updatedAt": "2025-11-21T07:26:35.230140019Z",
"original": true
}
Step 1.3: Upload PDF
Endpoint: /uploadUrl (returned in the response of the previous step).
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 format. Content type: binary.
curl -L -X PUT 'https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/da3484f2-xd58-4039-85b1-f833d0c841da/efa3eb01-37f9-4310-aea8-e69dd4434174/12f8bc19-1f37-8cf2-9c27-deb44867485e?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20251121%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20251121T072635Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=8c9e4d3622eb16bda2de7c6d7d8c63eecf4e84c9a8452420d25aa384bb4c31c4d95f540ba2fc53da51f6746415754777602d2e4ff4510e5344e231aa6f78a20ae236bd5ca071c0db6cc6a70587bbf70f4092bfdf9057986ddb7fa01dcf6512f886398f7eb4344deb895a3dedbc94b8569cbcc80c8621174264598a2c4caddeb788faccdcb083af65c95a761d0d21e5c390e95a1e35e3792b1f7fe15f4ac4a71b2a866f8446249298e03cb35bd1fa5c7813abfb9c8131b84b4c72883a96e05486cb8bda45c0eff080f5ac342cac3b95be20a0faadc55f2d574f8830b15e8463ff00875d2229db2ca6c5320059012368d42acd' \
-H 'Content-Type: application/xml' \
-H 'Authorization: Bearer YOUR_TOKEN'
Successful response:
The file is uploaded successfully.
Step 2: Set connection and connector(s)
Step 2.1: Check connection
Endpoint: datastore/documents/transaction/v2/spaces/{spaceId}/connections
Path parameter:
spaceId
Query parameters: optional.
namerelationTypes
curl -L -X GET 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/connections?name=MEDICA&relationTypes=CUSTOMER' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'
Successful response:
If no results are returned, it means that the connection doesn't exist, and it needs to be created in the next step.
{
"connections": [
{
"type": "business",
"id": "4a25293f-20c7-45d0-88de-af49d62131f3",
"globalIdentifiers": {
"be:en": "1412887923",
"be:vat": "BE1412887923",
"global:email": [
"atticus.finch@example.com"
]
},
"assignedAccountId": "000045",
"alias": "UP",
"connectionStatus": "CONNECTED",
"relationTypes": [
"CUSTOMER"
],
"addresses": {
"main": {
"streetName": "Bloemen",
"buildingNumber": "1",
"postalCode": "1310",
"city": "Antwerp",
"country": "Belgium",
"countryCode": "BE"
}
},
"tags": [
"favorite",
"liked"
],
"active": true,
"createdAt": "2025-11-12T11:46:22.799633Z",
"metadata": {
"notes": "pieces automobiles",
"channels": {
"main": "delivery_on_platform",
"secondary": "email"
},
"industry": "Automative",
"department": "Accounting"
},
"connectors": [
{
"name": "peppol",
"active": true,
"settings": {
"peppolID": "0002:010641962",
"peppolAccessPoint": "unifiedpost"
},
"namespace": "com.unifiedpost.btx.connectors",
"extensionId": "baf65b82-e645-4c75-89f1-69df0c023ec3"
}
],
"displayName": "Traffic acc.",
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"businessType": "ENTERPRISE"
},
{
"type": "business",
"id": "c803e99d-a95a-4172-ae55-0e5b5f2bfe26",
"globalIdentifiers": {
"be:en": "1207436775",
"be:vat": "BE1207436775",
"global:email": [
"atticus.finch@example.com"
]
},
"assignedAccountId": "000048",
"alias": "UP",
"connectionStatus": "CONNECTED",
"relationTypes": [
"CUSTOMER"
],
"addresses": {
"main": {
"streetName": "Bloemen",
"buildingNumber": "1",
"postalCode": "1310",
"city": "Antwerp",
"country": "Belgium",
"countryCode": "BE"
}
},
"tags": [
"favorite",
"liked"
],
"active": true,
"createdAt": "2025-11-21T07:16:26.553190Z",
"metadata": {
"notes": "pieces automobiles",
"channels": {
"main": "delivery_on_platform",
"secondary": "email"
},
"industry": "Automative",
"department": "Accounting"
},
"connectors": [],
"displayName": "Traffic acc.",
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"businessType": "ENTERPRISE"
},
{
"type": "business",
"id": "58085aa0-3bbc-41e8-be41-de907226c263",
"globalIdentifiers": {
"be:en": "1404866914",
"be:vat": "BE1404866914",
"global:email": [
"atticus.finch@example.com"
]
},
"assignedAccountId": "000049",
"alias": "UP",
"connectionStatus": "CONNECTED",
"relationTypes": [
"CUSTOMER"
],
"addresses": {
"main": {
"streetName": "Bloemen",
"buildingNumber": "1",
"postalCode": "1310",
"city": "Antwerp",
"country": "Belgium",
"countryCode": "BE"
}
},
"tags": [
"favorite",
"liked"
],
"active": true,
"createdAt": "2025-11-21T07:27:33.675227Z",
"metadata": {
"notes": "pieces automobiles",
"channels": {
"main": "delivery_on_platform",
"secondary": "email"
},
"industry": "Automative",
"department": "Accounting"
},
"connectors": [
{
"name": "peppol",
"active": true,
"settings": {
"peppolID": "0002:010471962",
"peppolAccessPoint": "unifiedpost"
},
"namespace": "com.unifiedpost.btx.connectors",
"extensionId": "baf65c92-e645-4c75-89f1-69df0c023ec3"
}
],
"displayName": "Traffic acc.",
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"businessType": "ENTERPRISE"
}
],
"currentPage": 0,
"pageSize": 20
}
Step 2.2: Create connection
You can skip this step if the connection already exists in Banqup.
Endpoint: solution/business/v1/spaces/{spaceId}/network/connections
Path parameter:
spaceId
Request body: View documentation
curl -L -X POST 'https://{{serverURL}}/solution/business/v1/spaces/{spaceId}/network/connections' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"type": "BUSINESS",
"globalIdentifiers": {
"be:en": "1404866914",
"be:vat": "BE1404866914",
"global:email": [
"atticus.finch@example.com"
]
},
"alias": "UP",
"connectionStatus": "CONNECTED",
"relationTypes": [
"CUSTOMER"
],
"addresses": {
"main": {
"streetName": "Bloemen",
"house": "1",
"postalCode": "1310",
"city": "Antwerp",
"country": "Belgium",
"countryCode": "BE"
}
},
"tags": [
"favorite",
"liked"
],
"active": true,
"metadata": {
"channels": {
"main": "delivery_on_platform",
"secondary": "email"
},
"department": "Accounting",
"notes": "pieces automobiles",
"industry": "Automative"
},
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"businessType": "ENTERPRISE"
}'
Successful response:
{
"type": "BUSINESS",
"id": "58489aa0-3bbc-41e8-be41-de907226c263",
"globalIdentifiers": {
"be:en": "1404866914",
"be:vat": "BE1404866914",
"global:email": [
"atticus.finch@example.com"
]
},
"assignedAccountId": "000049",
"alias": "UP",
"connectionStatus": "CONNECTED",
"relationTypes": [
"CUSTOMER"
],
"addresses": {
"main": {
"streetName": "Bloemen",
"buildingNumber": "1",
"postalCode": "1310",
"city": "Antwerp",
"country": "Belgium",
"countryCode": "BE"
}
},
"tags": [
"favorite",
"liked"
],
"active": true,
"createdAt": "2025-11-21T07:27:33.675226679Z",
"metadata": {
"channels": {
"main": "delivery_on_platform",
"secondary": "email"
},
"department": "Accounting",
"notes": "pieces automobiles",
"industry": "Automative"
},
"connectors": [],
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"businessType": "ENTERPRISE"
}
Step 2.3: List available connectors
Endpoint: /solution/business/v1/spaces/{spaceId}/network/connections/{connectionId}/connectors
Path parameters:
spaceIdconnectionId
Request body: View documentation
curl -L -X GET 'https://{{serverURL}}/solution/business/v1/spaces/{spaceId}/network/connections/{connectionId}/connectors' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'
Successful response:
Email connector:
{
"connectors": [
{
"extensionId": "c1fb7056-dfb3-4e55-9922-8fc76473a48e",
"active": false,
"name": "email",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"email": "atticus.finch@example.com"
},
"searchResults": [
{
"name": "atticus.finch@example.com",
"settings": {
"email": "atticus.finch@example.com"
}
}
]
}
]
}
Peppol connector:
{
"extensionId": "ba365c92-e645-4c75-89f1-69df0c023ec3",
"active": false,
"name": "peppol",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"matches": {
"docTypes": [
{
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
"scheme": "busdox-docid-qns"
},
{
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1",
"scheme": "busdox-docid-qns"
},
{
"value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
"scheme": "busdox-docid-qns"
},
{
"value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
"scheme": "busdox-docid-qns"
}
],
"participantId": {
"value": "0002:441397214",
"scheme": "iso6523-actorid-upis"
}
}
},
"searchResults": [
{
"name": "Traffic acc.",
"settings": {
"matches": {
"participantId": {
"scheme": "iso6523-actorid-upis",
"value": "0002:441387714"
},
"docTypes": [
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1"
}
]
}
}
},
{
"name": "Traffic acc.",
"settings": {
"matches": {
"participantId": {
"scheme": "iso6523-actorid-upis",
"value": "9957:FR07443387214"
},
"docTypes": [
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1"
}
]
}
}
},
{
"name": "Traffic acc.",
"settings": {
"matches": {
"participantId": {
"scheme": "iso6523-actorid-upis",
"value": "0225:440387214"
},
"docTypes": [
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1"
},
{
"scheme": "busdox-docid-qns",
"value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1"
}
]
}
}
}
]
}
Step 2.4: Set connector for connection
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/connections/{connectionId}/connectors
Path parameter:
spaceIdconnectionId
Request body: View documentation
Email connector:
curl -L -X PUT 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/connections/{connectionId}/connectors' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '[
{
"extensionId": "c1fc6056-dfb3-4e55-9922-8fc76473a48e",
"active": true,
"name": "email",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"email": "atticus.finch@example.com"
},
"searchResults": [
{
"name": "atticus.finch@example.com",
"settings": {
"email": "atticus.finch@example.com"
}
}
]
}
]'
Peppol connector:
curl -L -X PUT 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/connections/{connectionId}/connectors' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '[
{
"active": true,
"extensionId": "baf85c82-e645-4c75-89f1-69df0c023ec3",
"name": "peppol",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"peppolAccessPoint": "unifiedpost",
"peppolID": "0002:010641962"
}
}
]'
Successful response:
Email connector:
[
{
"extensionId": "c1fc7856-dfb3-4e55-9922-8fc76473a48e",
"active": true,
"name": "email",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"email": "atticus.finch@example.com"
},
"searchResults": [
{
"name": "atticus.finch@example.com",
"settings": {
"email": "atticus.finch@example.com"
}
}
]
}
]
Peppol connector:
[
{
"active": true,
"extensionId": "baf63c82-e645-4c75-89f1-69df0c023ec3",
"name": "peppol",
"namespace": "com.unifiedpost.btx.connectors",
"settings": {
"peppolAccessPoint": "unifiedpost",
"peppolID": "0002:010641962"
}
}
]
Step 2.5: Assign connection to document
If the connection didn't exist in Banqup upon document creation (step 1) or if it existed but it wasn't added in the JSON, it needs to be linked to the document in this step.
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}:assignConnection
Path parameter:
spaceIddocumentId
Request body: View documentation
curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}:assignConnection' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"id": "58089aa0-36bbc-41e8-be41-de907226c263",
"relationType": "CUSTOMER"
}'
Successful response:
{
"connections": [
{
"displayName": "Traffic acc.",
"relationType": "CUSTOMER",
"id": "58039aa0-3bbc-41e8-be41-de907226c263"
}
],
"id": "efa4eb01-37f9-4910-aea8-e69dd4434174",
"spaceId": "da3414f2-cd58-4039-85b1-f833d0c841da",
"source": "documentcreator",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"delivery": "RECEIVED",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"dueDate": "2025-12-12",
"customer": {
"address": {
"country": "BE",
"postCode": "1310",
"townName": "Antwerp",
"streetName": "Bloemen",
"buildingNumber": "1"
},
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"globalIdentifiers": {
"be:en": "1404866914",
"be:vat": "BE1404866914",
"global:email": [
"atticus.finch@example.com"
]
}
},
"supplier": {
"address": {
"country": "FR",
"postCode": "78130",
"townName": "Les Mureaux",
"streetName": "51 route de Verneuil"
},
"legalName": "ARIANEGROUP SAS",
"tradeName": "ARIANEGROUP SAS",
"globalIdentifiers": {
"fr:vat": "FR82519032247",
"fr:siren": "319032247",
"fr:siret": "31903224700040",
"global:email": [
"hester.prynne@example.com"
],
"global:participantId": "0208:0579562453"
}
},
"issueDate": "2025-11-12",
"vatDetails": [
{
"netAmount": "25.00",
"vatAmount": "0",
"vatCategory": "E",
"vatPercentage": "0",
"exemptionReason": "VAT exempt"
}
],
"invoiceType": "380",
"currencyCode": "EUR",
"documentNumber": "ABC1211255698",
"documentTotals": {
"netAmount": "25.00",
"vatAmount": "0",
"grossAmount": "25.00",
"payableAmount": "25.00"
}
},
"tags": [],
"retentionTime": "2029-01-14T17:58:47Z",
"balanceOffsets": []
}
Step 3: Validate document
Step 3.1: Validate JSON
Endpoint: /connectors/core/v1/spaces/documents:validate
Request body: View documentation
curl -L -X POST 'https://{{serverURL}}/connectors/core/v1/spaces/documents:validate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"data": {
"dryRun": true,
"shouldTriggerHitl": true
},
"documentIds": [
"efa4eb01-37i9-4310-aea8-e69dd4434174"
],
"spaceId": "da3484f2-cd48-4039-85b1-f833d0c841da"
}'
Successful response:
{
"validationId": "f947f581-e298-44f6-a262-0565967fe354",
"successResults": [
{
"documentId": "efa4eb01-37i9-4310-aea8-e69dd4434174"
}
],
"failureResults": []
}
Step 3.2: Check validation outcome
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}
Path parameter:
spaceIddocumentId
Query parameter:
include: validationData
curl -L -X GET 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}?include=validationData' \
--header 'Authorization: Bearer YOUR_TOKEN'
Successful response:
{
"id": "9479e6f6-7060-4a43-b75c-5b2da939801e",
"spaceId": "Sa3484f2-cd58-4039-85b1-f833d0c841da",
"source": "documentcreator",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"delivery": "RECEIVED",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"dueDate": "2025-12-12",
"customer": {
"address": {
"country": "BE",
"postCode": "1310",
"townName": "Antwerp",
"streetName": "Bloemen",
"buildingNumber": "1"
},
"legalName": "Traffic acc.",
"tradeName": "Traffic acc.",
"globalIdentifiers": {
"be:en": "1421961084",
"be:vat": "BE1421961084",
"global:email": [
"atticus.finch@example.com"
]
}
},
"supplier": {
"address": {
"country": "FR",
"postCode": "78130",
"townName": "Les Mureaux",
"streetName": "51 route de Verneuil"
},
"legalName": "ARIANEGROUP SAS",
"tradeName": "ARIANEGROUP SAS",
"globalIdentifiers": {
"fr:vat": "FR72519032247",
"fr:siren": "319032247",
"fr:siret": "31903224700040",
"global:email": [
"hester.prynne@example.com"
],
"global:participantId": "0208:0577942453"
}
},
"issueDate": "2025-11-12",
"vatDetails": [
{
"netAmount": "25.00",
"vatAmount": "0",
"vatCategory": "E",
"vatPercentage": "0",
"exemptionReason": "VAT exempt"
}
],
"invoiceType": "380",
"currencyCode": "EUR",
"documentNumber": "ABC124598",
"documentTotals": {
"netAmount": "25.00",
"vatAmount": "0",
"grossAmount": "25.00",
"payableAmount": "25.00"
}
},
"tags": [],
"retentionTime": "2029-01-14T17:58:47Z",
"validationData": {
"spaceExtensions": {
"com.unifiedpost.btx.documents.validators": {
"general": {
"status": "COMPLETED",
"validationId": "3a394d95-ce40-407c-b334-d258b57e112f"
}
},
"com.unifiedpost.btx.connectors.validators": {
"peppol": {
"status": "COMPLETED",
"validationId": "3a174d95-ce40-407c-b334-d258b57e112f"
},
"dataExtraction": {
"status": "COMPLETED",
"validationId": "3a294d95-ce40-407c-b334-d258b57e112f"
}
}
}
},
"balanceOffsets": []
}
Step 4: Send document
Endpoint: connectors/core/v1/spaces/documents:send
curl -L POST 'https://{{serverURL}}/connectors/core/v1/spaces/documents:send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
"spaceId": "sa3484f2-cd58-4069-65b1-f833d0c841da",
"documents": [
"97f902fb-4487-4651-9c20-b26bd9039e2f"
]
}'
Successful response:
{
"success": [
"97f902fb-4487-4651-9c20-b26bd9039e2f"
],
"failure": []
}