--- updatedAt: 2026-07-20T11:47:41.000Z agentTools: projectIndex: https://docs.falco-app.be/llms.txt --- # Upload a PDF file + metadata to generate a UBL file (and optionally send it) Required scopes: `invoices:ingest:pdf` Optional scopes: `invoices:send` # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "PDF & UBL Imports", "version": "1.0.0", "description": "`X-Falco-App-Secret` + `X-Falco-Api-Key`.\n" }, "servers": [ { "url": "https://api.falco-app.be/v1", "description": "Production" }, { "url": "https://api.sandbox.falco-app.be/v1", "description": "Sandbox" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Falco-App-Secret", "description": "`X-Falco-App-Secret`: Falco Application Secret associated to your application. Use together with the `X-Falco-Api-Key` header.", "x-scopes": [ "articles:read", "articles:write", "customers:read", "customers:write", "invoices:read", "invoices:write", "invoices:attachments:read", "invoices:attachments:write", "invoices:send", "invoices:ingest:ubl", "invoices:ingest:pdf", "peppol:inbound:read", "peppol:participants:read" ] } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "trace_id": { "type": "string" } } }, "ImportedDocument": { "type": "object", "properties": { "document_id": { "type": "string" }, "peppol_status": { "type": "object", "properties": { "peppol_identifier": { "type": "string" }, "error_message": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "failed" ] } } }, "accounting_status": { "type": "object", "properties": { "peppol_identifier": { "type": "string" }, "error_message": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "failed" ] } } } } } } }, "paths": { "/invoices/imports/pdf": { "post": { "summary": "Upload a PDF file + metadata to generate a UBL file (and optionally send it)", "tags": [ "Imports" ], "description": "Required scopes: `invoices:ingest:pdf` Optional scopes: `invoices:send`\n", "parameters": [ { "name": "X-Falco-Api-Key", "in": "header", "required": true, "description": "Falco Api Key (provided by the client - required in addition to X-Falco-App-Secret).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF bytes" }, "metadata": { "type": "string", "description": "JSON string containing the document metadata to be imported. This field must contain an object following the schema.\n### Main fields\n- **document_type** *(string, required)* \n Allowed values: `sale_invoice`, `sale_credit_note`.\n\n- **document_date** *(date, required)* \n (format `YYYY-MM-DD`)\n\n- **due_date** *(date)*\n- **invoice_period** *(object)*\n - **start_date** *(date, required)*\n - **end_date** *(date, required)*\n - **description_code** *(string)*\n Must be part of UBL list https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL2005/\n\n- **number** *(string, required)*\n- **note** *(string)*\n- **accounting_cost** *(string)*\n- **buyer_reference** *(string)*\n- **purchase_order_reference** *(string)*\n- **sales_order_reference** *(string)*\n- **despatch_document_reference** *(string)*\n- **receipt_document_reference** *(string)*\n- **originator_document_reference** *(string)*\n- **contract_document_reference** *(string)*\n- **project_reference** *(string)*\n- **sender** *(object, required)*\n - **name**\n - **vat_number** (must match the organization's VAT).\n - **party_identifications** *(array, optional)*\n - **scheme_id** *(string, optional)* 4-digit ISO 6523 ICD code, or `SEPA`.\n - **id** *(string, required)*\n - **contact** *(optional)*\n - **name**\n - **phone**\n - **email**\n - **address** *(required)*\n - **line1**\n - **zip**\n - **city**\n - **region**\n - **country**\n\n- **receiver** *(object, required)*\n - **name**\n - **vat_number**\n - **company_number**\n - **peppol_identifier** (deduced from VAT if missing).\n - **party_identification** *(optional)*\n - **scheme_id** *(string, optional)* 4-digit ISO 6523 ICD code.\n - **id** *(string, required)*\n - **contact** *(optional)*\n - **name**\n - **phone**\n - **email**\n - **address** *(required)*\n - **line1**\n - **zip**\n - **city**\n - **region**\n - **country** *(required)*\n\n- **delivery** *(object)*\n - **date** *(date)*\n - **location_id**\n - **scheme_id**\n - **party_name**\n - **location_address** *(object)*\n - **line1**\n - **line2**\n - **zip**\n - **city**\n - **region**\n - **country** *(required)* \n\n- **payment_means** *(array)* : List of payment methods \n Each element includes: \n - **code** \n - Use one of `debit_transfer`, `credit_transfer`, `cash`, or one of the codes found at `https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4461/`. \n - **communication**\n - **iban**\n - **bic**\n - **payment_account_name**\n - **mandate_reference**\n\n- **payment_terms** *(string)*\n- **billing_references** *(array)*\n Each element includes:\n - **id** *(string, required)*\n - **issue_date** *(date)*\n\n- **currency** *(string)*\n Currency code (`EUR` by default)\n\n- **base_amount** *(string, required)*\n- **total_amount** *(string, required)*\n- **prepaid_amount** *(string)* \n- **tax_subtotals** *(array, required)*\n Each element includes:\n - **tax_rate**\n - **base_amount**\n - **tax_amount**\n - **tax_regime** *(object, required)*\n - **type** (string, required)\n Use `standard` for default VAT rates.\n\n Use `vat_reverse_charge`, `intra_community`, `export`, `zero_rated_goods`, `taxes_not_applicable`, or `other_exoneration` for 0% VAT.\n\n - **legal_exoneration_text** (string, optional) Only for `other_exoneration`.\n\n- **lines** *(array, required)*\n Each line includes: \n - **name** *(string, required)*\n - **description** *(string, required)*\n - **origin_country_code** *(string)*\n - **quantity** *(string, required)*\n - **unit_price** *(string, required)*\n - **tax_rate** *(string, required)*\n - **base_amount** *(string, required)*\n - **tax_regime_type** *(string, required)* \n Use `standard` for default VAT rates.\n\n Use `vat_reverse_charge`, `intra_community`, `export`, `zero_rated_goods`, `taxes_not_applicable`, or `other_exoneration` for 0% VAT.\n - **account_number**\n - **cost_code**\n - **unit_of_measure** (default `EA`, must be part of UBL list https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/)\n - **order_line_reference** *(string)*\n - **buyers_item_identification** *(string)*\n - **sellers_item_identification** *(string)*\n - **standard_item_identification** *(string)*\n - **standard_item_identification_scheme_id** *(string)*\n - **invoice_period** *(object)*\n - **start_date** *(date)*\n - **end_date** *(date)*\n - **allowance_charges** *(array)*\n Each element includes:\n - **is_charge** *(boolean, required)*\n - **amount** *(string, required)*\n - **base_amount** *(string)*\n - **percentage** *(string)*\n - **reason** *(string)*\n - **reason_code** *(string)*\n - If charge : Must be part of UBL list (https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/)\n - If allowance : Must be part of UBL list (https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5189/)\n - **additional_item_properties** *(array)*\n Each element includes:\n - **name** *(string, required)*\n - **value** *(string, required)*\n\n- **send_peppol** *(boolean)*\n If `true`, the document will be sent through the Peppol network. \n\n- **send_accounting** *(boolean)*\n If `true`, the document will be forwarded to the accounting software (Horus Office). \n\n- **accounting_info** *(object, optional)*\n Additional accounting details (only when linked to Horus Office). \n - **number** \n Internal accounting document number. \n - **journal**\n Journal search key.\n\n### Example\n```json\n{\n \"document_type\": \"sale_invoice\",\n \"document_date\": \"2025-10-30\",\n \"due_date\": \"2025-11-15\",\n \"number\": \"INV-2025-00123\",\n \"buyer_reference\": \"N/A\",\n \"sender\": {\n \"name\": \"SANDBOX SRL\",\n \"vat_number\": \"BE0000000097\",\n \"address\": {\n \"line1\": \"Sandbox street\", \n \"zip\": \"1000\", \n \"city\": \"Brussels\", \n \"country\": \"BE\" \n }\n },\n \"receiver\": {\n \"name\": \"Horus Software SA\",\n \"vat_number\": \"BE0478696879\",\n \"address\": { \n \"line1\": \"Square des conduites d'eau 9\", \n \"zip\": \"4031\", \n \"city\": \"Angleur\", \n \"country\": \"BE\" \n }\n },\n \"currency\": \"EUR\",\n \"base_amount\": \"1000.00\",\n \"total_amount\": \"1210.00\",\n \"tax_subtotals\": [\n { \n \"tax_rate\": \"21.0\", \n \"base_amount\": \"1000.00\", \n \"tax_amount\": \"210.00\", \n \"tax_regime\": {\n \"type\": \"standard\"\n }\n }\n ],\n \"lines\": [\n { \n \"name\": \"Accounting service\", \n \"description\": \"Monthly fee\", \n \"quantity\": \"1\", \n \"unit_price\": \"1000.00\", \n \"tax_rate\": \"21.0\", \n \"base_amount\": \"1000.00\", \n \"tax_regime_type\": \"standard\"\n }\n ],\n \"send_peppol\": false,\n \"send_accounting\": true\n}\n", "example": "{\n \"document_type\": \"sale_invoice\",\n \"document_date\": \"2025-10-30\",\n \"due_date\": \"2025-11-15\",\n \"number\": \"INV-2025-00123\",\n \"sender\": {\n \"name\": \"ACME SRL\",\n \"vat_number\": \"BE0123456789\",\n \"address\": { \n \"line1\": \"Rue des Entrepreneurs 12\", \n \"zip\": \"1000\", \n \"city\": \"Brussels\", \n \"country\": \"BE\" \n }\n },\n ...\n}\n" } } }, "encoding": { "metadata": { "contentType": "application/json" } } } } }, "responses": { "201": { "description": "Accepted import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportedDocument" } } } }, "default": { "description": "Error (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } } } ````