Order references
If you integrate Fakturnia with a shop or another sales system, you can link a document to the order in your system. The link is visible in the app and lets you tell documents issued by the integration apart from those issued manually.
Required scope: documents:update-external-reference.
Setting a reference
curl -s -X PATCH https://prod.api.fakturnia.pl/external/v1/documents/{id}/external-reference \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"externalSource": "woocommerce",
"externalOrderId": "10241",
"externalOrderNumber": "ORD/2026/10241"
}'
| Field | Meaning |
|---|---|
externalSource |
identifier of your system (e.g. woocommerce, allegro, your own name), required |
externalOrderId |
the order identifier in your system, required |
externalOrderNumber |
the human-readable order number, optional |
The response returns the current state of the reference:
{
"success": true,
"message": "External reference updated.",
"data": {
"id": "665f0c...",
"externalSource": "woocommerce",
"externalOrderId": "10241",
"externalOrderNumber": "ORD/2026/10241"
}
}
Removing a reference
curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/documents/{id}/external-reference \
-H "Authorization: Bearer $TOKEN"
The document stays unchanged, only the order link is removed.
Filtering by reference
On the document list, onlyUnlinked=true returns only documents without a reference. Handy when you are attaching existing documents to orders and want to find the ones not yet assigned:
curl -s "https://prod.api.fakturnia.pl/external/v1/documents?onlyUnlinked=true&buyerNip=5252248481" \
-H "Authorization: Bearer $TOKEN"
The other document list filters (type, date range, buyer details) are covered in Pagination and filtering.
A typical integration flow: issue the document with POST /documents, then immediately set the reference with this endpoint using the order identifier from your system.