# 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                                | <p>Mandatory.</p><p>User auth token.</p>                                   |
| x-clear-branch                | String    | Should be a valid branch from the user account | <p>Optional.</p><p>Branch name (store name) added in the user account.</p> |
| <p>x-clear-vat</p><p><br></p> | String    | Cannot be empty                                | <p>Mandatory.</p><p>VAT of the entity</p><p><br></p>                       |
| x-request-id                  | UUID      | Should be unique for every request             | <p>Optional.</p><p>Unique request ID.</p>                                  |

### Request Path Params

There are no path parameters for this API.&#x20;

### Request Query Params

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

### 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](https://docs.cleartax.in/cleartax-docs/e-invoicing-belgium-api/e-invoicing-belgium-api-reference/resources-and-masters/e-invoice-object).&#x20;

### Sample Request & Response <a href="#sample-request-and-response" id="sample-request-and-response"></a>

#### **Request**

NA

#### Response - Success:&#x20;

HTTP Status Code: 200

```json
{
    "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": "Globalclear@clear.in"
            }
        }
    },
    "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": "buyer@clear.in"
            }
        }
    },
    "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

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

HTTP Status Code: 400

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

HTTP Status Code: 403

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

### API Limitations&#x20;

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.