Get Document via Document Number

Retrieve a single e-invoice document by its document number

Request Method

GET

Request URL

https://api.eu.cleartax.com/be/einvoice/v1/documents

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty	Mandatory. User auth token.
x-clear-branch	String	Should be a valid branch from the user account	Optional. Branch name (store name) added in the user account.
x-clear-vat	String	Cannot be empty	Mandatory. VAT of the entity
x-request-id	UUID	Should be unique for every request	Optional. Unique request ID.

Request Path Params

There are no path parameters for this API.

Request Query Params

Parameter	Data Type	Field Validations	Description
einvoice-type	ENUM	PURCHASE	Mandatory. It is a fixed value and must be passed as PURCHASE.
document-number	String	-	Mandatory. Document number needs to be provided mandatorily for fetching doc

Request Body

There will be no request body for this API.

Response Status Codes

HTTP Status Code	Description
200	For a successful retrieval
400	For any kind of validation issues
401	If the user is not authenticated for the operation
403	If the user is not authorized for the operation
5XX	Unhandled exception

Response Schema

This API will return a JSON response compliant with the Peppol-defined standard for Sales Documents.

To view the schema, use this Link.

Sample Request & Response

Request

NA

Response - Success:

HTTP Status Code: 200

{
    "ID": "APITest1",
    "IssueDate": "2025-01-08",
    "InvoiceTypeCode": "380",
    "Note": "Invoice for June services",
    "DocumentCurrencyCode": "EUR",
    "BuyerReference": "REF-001",
    "InvoicePeriod": {
        "StartDate": "2025-06-25",
        "EndDate": "2025-06-28"
    },
    "BillingReference": [
        {
            "InvoiceDocumentReference": {
                "ID": null
            }
        }
    ],
    "AccountingSupplierParty": {
        "Party": {
            "EndpointID": {
                "Value": "BE1234567890",
                "SchemeID": "9925"
            },
            "PartyIdentification": [
                {
                    "ID": {
                        "Value": "BE0120240102",
                        "SchemeID": "0002"
                    }
                }
            ],
            "PostalAddress": {
                "StreetName": "Nike Store Antwerpen",
                "AdditionalStreetName": "Meir 55, 2000 Antwerpen",
                "CityName": "Belgium",
                "PostalZone": "2000",
                "CountrySubentity": "Flemish Region",
                "AddressLine": [
                    {
                        "Line": "Nike Store Antwerpen"
                    },
                    {
                        "Line": "Meir 55, 2000 Antwerpen"
                    }
                ],
                "Country": {
                    "IdentificationCode": "BE"
                }
            },
            "PartyTaxScheme": [
                {
                    "CompanyID": "BE0120240102",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                }
            ],
            "PartyLegalEntity": {
                "RegistrationName": "ClearTax BE",
                "CompanyID": {
                    "Value": null,
                    "SchemeID": null
                }
            },
            "Contact": {
                "Name": "David",
                "Telephone": "3232328210",
                "ElectronicMail": "[email protected]"
            }
        }
    },
    "AccountingCustomerParty": {
        "Party": {
            "EndpointID": {
                "Value": "01202401021160",
                "SchemeID": "0193"
            },
            "PartyIdentification": [
                {
                    "ID": {
                        "Value": "BE0120240103",
                        "SchemeID": "0003"
                    }
                }
            ],
            "PostalAddress": {
                "StreetName": "Beta Avenue 20",
                "AdditionalStreetName": "Floor 3",
                "CityName": "Ghent",
                "PostalZone": "9000",
                "CountrySubentity": "East Flanders",
                "AddressLine": [
                    {
                        "Line": "Beta Avenue 20"
                    },
                    {
                        "Line": "Floor 3"
                    }
                ],
                "Country": {
                    "IdentificationCode": "BE"
                }
            },
            "PartyLegalEntity": {
                "RegistrationName": "Zeta NV",
                "CompanyID": {
                    "Value": "BE0120240103",
                    "SchemeID": null
                }
            },
            "Contact": {
                "Name": "Ben Buyer",
                "Telephone": "32 89 84 52 58",
                "ElectronicMail": "[email protected]"
            }
        }
    },
    "TaxRepresentativeParty": {
        "PostalAddress": {
            "StreetName": null,
            "CityName": null,
            "PostalZone": null,
            "AddressLine": [
                {
                    "Line": null
                }
            ],
            "Country": {
                "IdentificationCode": null
            }
        },
        "PartyTaxScheme": [
            {
                "CompanyID": null,
                "TaxScheme": {
                    "ID": "VAT"
                }
            }
        ],
        "PartyName": {
            "Name": null
        }
    },
    "PayeeParty": {
        "PartyName": {
            "Name": null
        }
    },
    "Delivery": {
        "ActualDeliveryDate": "2025-06-25",
        "DeliveryLocation": {
            "ID": {
                "Value": null,
                "SchemeID": null
            },
            "Address": {
                "StreetName": "Consulting St 34",
                "AdditionalStreetName": "HQ",
                "CityName": "Brussels",
                "PostalZone": "1000",
                "CountrySubentity": "Brussels Capital",
                "AddressLine": [
                    {
                        "Line": "Consulting St 34"
                    },
                    {
                        "Line": "HQ"
                    },
                    {
                        "Line": "L3"
                    }
                ],
                "Country": {
                    "IdentificationCode": "BE"
                }
            }
        },
        "DeliveryParty": {
            "PartyName": {
                "Name": "Energy Dept"
            }
        }
    },
    "PaymentMeans": {
        "PaymentMeansCode": {
            "Name": {
                "en": "Mutually defined"
            }
        },
        "PayeeFinancialAccount": {
            "ID": "BE88 4567 8901 2345",
            "Name": "Supplier Theta Ltd",
            "FinancialInstitutionBranch": {
                "ID": "KREDBEBB"
            }
        }
    },
    "PaymentTerms": {
        "Note": "Payment within 14 days"
    },
    "AllowanceCharge": [
        {
            "TaxCategory": {
                "Percent": null,
                "TaxScheme": {
                    "ID": "VAT"
                }
            }
        }
    ],
    "TaxTotal": [
        {
            "TaxAmount": {
                "Value": "99.75",
                "CurrencyID": "EUR"
            },
            "TaxSubtotal": [
                {
                    "TaxableAmount": {
                        "Value": "475.00",
                        "CurrencyID": "EUR"
                    },
                    "TaxAmount": {
                        "Value": "99.75",
                        "CurrencyID": "EUR"
                    },
                    "TaxCategory": {
                        "ID": "S",
                        "Percent": "21.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                }
            ]
        }
    ],
    "LegalMonetaryTotal": {
        "LineExtensionAmount": {
            "Value": "475.00",
            "CurrencyID": "EUR"
        },
        "TaxExclusiveAmount": {
            "Value": "475.00",
            "CurrencyID": "EUR"
        },
        "TaxInclusiveAmount": {
            "Value": "574.75",
            "CurrencyID": "EUR"
        },
        "AllowanceTotalAmount": {
            "Value": "0.00",
            "CurrencyID": "EUR"
        },
        "ChargeTotalAmount": {
            "Value": "0.00",
            "CurrencyID": "EUR"
        },
        "PrepaidAmount": {
            "Value": "100.00",
            "CurrencyID": "EUR"
        },
        "PayableRoundingAmount": {
            "Value": "0.00",
            "CurrencyID": "EUR"
        },
        "PayableAmount": {
            "Value": "474.75",
            "CurrencyID": "EUR"
        }
    },
    "InvoiceLine": [
        {
            "ID": "1",
            "InvoicedQuantity": {
                "Quantity": "1",
                "UnitCode": "AE"
            },
            "LineExtensionAmount": {
                "Value": "475.00",
                "CurrencyID": "EUR"
            },
            "AllowanceCharge": [
                {
                    "ChargeIndicator": "false",
                    "AllowanceChargeReasonCode": "41",
                    "MultiplierFactorNumeric": 10.0,
                    "Amount": {
                        "Value": "50.00",
                        "CurrencyID": "EUR"
                    },
                    "BaseAmount": {
                        "Value": "500.00",
                        "CurrencyID": "EUR"
                    }
                },
                {
                    "ChargeIndicator": "true",
                    "AllowanceChargeReasonCode": "ZZZ",
                    "MultiplierFactorNumeric": 5.0,
                    "Amount": {
                        "Value": "25.00",
                        "CurrencyID": "EUR"
                    },
                    "BaseAmount": {
                        "Value": "500.00",
                        "CurrencyID": "EUR"
                    }
                }
            ],
            "Item": {
                "Description": "Standard widget",
                "Name": "Widget A",
                "OriginCountry": {
                    "IdentificationCode": "JP"
                },
                "CommodityClassification": [
                    {
                        "ItemClassificationCode": {
                            "SchemeID": "AA",
                            "Value": "9348023"
                        }
                    }
                ],
                "ClassifiedTaxCategory": [
                    {
                        "ID": "S",
                        "Percent": "21.00",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                ]
            },
            "Price": {
                "PriceAmount": {
                    "Value": "500.00",
                    "CurrencyID": "EUR"
                }
            }
        }
    ]
}

Response - Error:

HTTP Status Code: 404

{
    "ErrorDetails": [
        {
            "ErrorCode": "404",
            "ErrorMessage": "Document with number 'INV-8802' not found",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

HTTP Status Code: 400

{
    "ErrorDetails": [
        {
            "ErrorCode": "400",
            "ErrorMessage": "document-number is required",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

HTTP Status Code: 403

{
    "ErrorDetails": [
        {
            "ErrorCode": "403",
            "ErrorMessage": "FORBIDDEN",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

API Limitations

Currently there are no known validations for this API.

API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

2. If the auth token is valid, but the user does not have the authorization to get a list of documents, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role.

3. A valid document number should be passed that exists in db, else 404 will be returned.