{
"info": {
"name": "FacturaX.app API",
"description": "Official FacturaX.app collection ā Spanish invoice OCR extraction, Facturae 3.2.2 generation and XAdES-BES signing.\n\n## Quick setup\n1. Import this collection into Postman\n2. Go to the \"Variables\" tab and paste your API Key into `api_key`\n3. Run any request\n\n## Base URL\nhttps://api.facturax.app\n\n## Full documentation\nhttps://parse.facturax.app/docs\n\n## Integration guide\nhttps://parse.facturax.app/integration-guide",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_postman_id": "facturax-api-v2-en"
},
"variable": [
{
"key": "base_url",
"value": "https://api.facturax.app",
"type": "string"
},
{
"key": "api_key",
"value": "fct_PASTE_YOUR_API_KEY_HERE",
"type": "string",
"description": "Your FacturaX API Key. Find it in Dashboard ā API Keys"
},
{
"key": "certificate_id",
"value": "",
"type": "string",
"description": "Managed certificate ID. Obtained via POST /certificates"
}
],
"item": [
{
"name": "š OCR Extraction",
"item": [
{
"name": "PDF ā structured JSON",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"src": "",
"description": "Invoice in PDF, JPG or PNG (max. 20MB)"
}
]
},
"url": {
"raw": "{{base_url}}/extract",
"host": [
"{{base_url}}"
],
"path": [
"extract"
]
},
"description": "Extracts the data from a PDF invoice using OCR + AI.\n\nReturns: vendor, buyer, invoice number, date, amounts, VAT, withholding tax, IBAN, line items and accounting category.\n\nā ļø Consumes 1 credit."
},
"response": [
{
"name": "200 OK ā Extracted data",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"vendor_name\": \"Suministros Garc\\u00eda S.L.\",\n \"vendor_vat\": \"B12345678\",\n \"vendor_address\": \"Calle Mayor 1, Madrid\",\n \"buyer_name\": \"My Company Ltd.\",\n \"buyer_vat\": \"A87654321\",\n \"invoice_number\": \"F2024-0892\",\n \"invoice_date\": \"2024-06-15\",\n \"subtotal\": 1000.00,\n \"tax_rate\": 21,\n \"tax\": 210.00,\n \"total\": 1210.00,\n \"currency\": \"EUR\",\n \"iban\": \"ES21 0049 0001 5021 0001 3303\",\n \"pgc_category\": \"628 - Utilities\",\n \"confidence_score\": 0.97,\n \"warnings\": [],\n \"log_id\": 1234\n}"
}
]
},
{
"name": "Batch ā multiple PDFs",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "files",
"type": "file",
"src": [],
"description": "Up to 50 PDFs in a single call"
}
]
},
"url": {
"raw": "{{base_url}}/extract/batch",
"host": [
"{{base_url}}"
],
"path": [
"extract",
"batch"
]
},
"description": "Send up to 50 invoices in a single call. Processed in the background.\n\nReturns a `job_id` ā check status with GET /extract/batch/{job_id}.\n\nā ļø Consumes 1 credit per processed invoice."
},
"response": []
},
{
"name": "Batch status",
"request": {
"method": "GET",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/extract/batch/:job_id",
"host": [
"{{base_url}}"
],
"path": [
"extract",
"batch",
":job_id"
],
"variable": [
{
"key": "job_id",
"value": "job_abc123",
"description": "Job ID returned by POST /extract/batch"
}
]
},
"description": "Checks the status of a batch job. When `status` is `done`, it includes the results for all invoices."
},
"response": []
}
]
},
{
"name": "š Generate Facturae XML",
"item": [
{
"name": "JSON ā signed Facturae",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"vendor_name\": \"Your Company Ltd.\",\n \"vendor_vat\": \"B12345678\",\n \"vendor_address\": \"Calle Mayor 1\",\n \"vendor_city\": \"Madrid\",\n \"vendor_postal_code\": \"28001\",\n \"vendor_country\": \"ESP\",\n \"buyer_name\": \"Ayuntamiento de Alcobendas\",\n \"buyer_vat\": \"P2800200B\",\n \"buyer_address\": \"Plaza Mayor 1\",\n \"buyer_city\": \"Alcobendas\",\n \"buyer_postal_code\": \"28100\",\n \"invoice_number\": \"F2024-001\",\n \"invoice_date\": \"2024-06-15\",\n \"due_date\": \"2024-07-15\",\n \"subtotal\": 1000.00,\n \"tax\": 210.00,\n \"total\": 1210.00,\n \"currency\": \"EUR\",\n \"payment_method\": \"bank_transfer\",\n \"iban\": \"ES21 0049 0001 5021 0001 3303\",\n \"line_items\": [\n {\n \"description\": \"Maintenance service\",\n \"quantity\": 10,\n \"unit_price\": 100.00,\n \"total\": 1000.00,\n \"tax_rate\": 21\n }\n ]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/convert",
"host": [
"{{base_url}}"
],
"path": [
"convert"
]
},
"description": "Generates a Facturae 3.2.2 XML signed with XAdES-BES from JSON data.\n\nIf you have a .p12 certificate saved in your profile, or you pass `X-Certificate-ID`, the XML is signed automatically.\n\nā ļø Consumes 1 credit."
},
"response": [
{
"name": "200 OK ā Signed XML",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"xml\": \"......\",\n \"xml_base64\": \"PD94bWwg...\",\n \"signed\": true,\n \"source\": \"json\",\n \"filename\": \"facturae_F2024-001.xml\",\n \"log_id\": 1234,\n \"invoice\": {\n \"vendor_name\": \"Tu Empresa S.L.\",\n \"invoice_number\": \"F2024-001\",\n \"total\": 1210.0\n },\n \"warnings\": [],\n \"confidence\": 1.0\n}"
}
]
},
{
"name": "PDF ā signed Facturae",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"src": "",
"description": "Invoice PDF (max. 20MB)"
}
]
},
"url": {
"raw": "{{base_url}}/convert",
"host": [
"{{base_url}}"
],
"path": [
"convert"
]
},
"description": "Upload a PDF ā the AI extracts the data and generates the signed Facturae 3.2.2 XML in a single call.\n\nā ļø Consumes 1 credit."
},
"response": []
},
{
"name": "JSON ā Facturae with managed certificate",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
},
{
"key": "X-Certificate-ID",
"value": "{{certificate_id}}",
"type": "text",
"description": "Managed certificate ID (recommended for multi-client ERPs)"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"vendor_name\": \"Your Company Ltd.\",\n \"vendor_vat\": \"B12345678\",\n \"buyer_name\": \"Ministerio de Hacienda\",\n \"buyer_vat\": \"S2800012B\",\n \"invoice_number\": \"F2024-001\",\n \"invoice_date\": \"2024-06-15\",\n \"subtotal\": 1000.00,\n \"tax\": 210.00,\n \"total\": 1210.00\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/convert",
"host": [
"{{base_url}}"
],
"path": [
"convert"
]
},
"description": "For multi-client ERPs. Use a managed certificate by its ID.\n\nFlow:\n1. POST /certificates ā get a `certificate_id`\n2. Save it in your DB linked to the client\n3. Use it on every call via `X-Certificate-ID`\n\nThe end client doesn't need to interact ā fully transparent."
},
"response": []
}
]
},
{
"name": "āļø Sign existing XML",
"item": [
{
"name": "XML ā signed XML (file)",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
},
{
"key": "X-Certificate-ID",
"value": "{{certificate_id}}",
"type": "text",
"description": "Optional if you have a managed certificate"
},
{
"key": "X-External-Ref",
"value": "F2024-001",
"type": "text",
"description": "Your internal ID ā included in the invoice.signed webhook"
}
],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"src": "",
"description": "Unsigned Facturae XML (.xml)"
}
]
},
"url": {
"raw": "{{base_url}}/sign",
"host": [
"{{base_url}}"
],
"path": [
"sign"
]
},
"description": "For ERPs that already generate their own Facturae XML but don't have XAdES-BES signing built in.\n\nSend the unsigned XML, get back the same .xml with the XAdES-BES signature embedded, ready to upload to FACe.\n\n**Certificate priority:**\n1. `X-Certificate-ID` (recommended for ERPs)\n2. `X-P12-B64` + `X-P12-Password`\n3. Certificate stored in the user's profile\n\nā ļø Consumes 1 credit."
},
"response": [
{
"name": "200 OK ā Signed XML",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"xml\": \"......\",\n \"xml_base64\": \"PD94bWwg...\",\n \"signed\": true,\n \"source\": \"sign\",\n \"filename\": \"factura.xml\",\n \"log_id\": 1234\n}"
}
]
},
{
"name": "XML ā signed XML (raw body)",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
},
{
"key": "X-Certificate-ID",
"value": "{{certificate_id}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/xml",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "\n\n \n",
"options": {
"raw": {
"language": "xml"
}
}
},
"url": {
"raw": "{{base_url}}/sign",
"host": [
"{{base_url}}"
],
"path": [
"sign"
]
},
"description": "Alternative to file upload: send the XML directly in the body with Content-Type: application/xml.\n\nMore convenient for server-to-server integrations where you already have the XML in memory."
},
"response": []
}
]
},
{
"name": "š Managed certificates",
"item": [
{
"name": "Upload .p12 certificate",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"src": "",
"description": "Client's .p12 or .pfx certificate"
},
{
"key": "password",
"value": "p12_password",
"type": "text",
"description": "Certificate password"
},
{
"key": "name",
"value": "Client Company Ltd.",
"type": "text",
"description": "Display name (optional)"
}
]
},
"url": {
"raw": "{{base_url}}/certificates",
"host": [
"{{base_url}}"
],
"path": [
"certificates"
]
},
"description": "Upload a client's .p12 once and get a `certificate_id`.\n\nSave the `certificate_id` in your DB linked to the client. From then on, use it via `X-Certificate-ID` on every call to /sign or /convert.\n\nThe client never needs to upload the certificate again ā fully transparent.\n\n**Requires Pro or Business plan.**"
},
"response": [
{
"name": "200 OK ā Certificate saved",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"certificate_id\": \"cert_abc123def456\",\n \"name\": \"Empresa Cliente S.L.\",\n \"subject\": \"CN=EMPRESA CLIENTE SL, O=EMPRESA CLIENTE SL, C=ES\",\n \"expires_at\": \"2027-05-15T00:00:00Z\",\n \"active\": true\n}"
}
]
},
{
"name": "List certificates",
"request": {
"method": "GET",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/certificates",
"host": [
"{{base_url}}"
],
"path": [
"certificates"
]
},
"description": "Lists all managed certificates in your account with their status and expiry date."
},
"response": []
},
{
"name": "Delete certificate",
"request": {
"method": "DELETE",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/certificates/:certificate_id",
"host": [
"{{base_url}}"
],
"path": [
"certificates",
":certificate_id"
],
"variable": [
{
"key": "certificate_id",
"value": "{{certificate_id}}"
}
]
},
"description": "Deletes a managed certificate. This cannot be undone."
},
"response": []
}
]
},
{
"name": "š„ Download signed invoices",
"item": [
{
"name": "Download signed XML by log_id",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/invoices/:log_id/facturae",
"host": [
"{{base_url}}"
],
"path": [
"invoices",
":log_id",
"facturae"
],
"variable": [
{
"key": "log_id",
"value": "1234",
"description": "Log ID returned in the response of /convert or /sign"
}
]
},
"description": "Downloads the signed Facturae XML of an already-processed invoice.\n\nThe `log_id` is returned in the response of /convert or /sign. It's also included in the `invoice.signed` webhook."
},
"response": []
}
]
},
{
"name": "š Webhooks",
"item": [
{
"name": "List webhooks",
"request": {
"method": "GET",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/webhooks",
"host": [
"{{base_url}}"
],
"path": [
"webhooks"
]
},
"description": "Lists the webhooks configured for your API key."
},
"response": []
},
{
"name": "Create webhook",
"request": {
"method": "POST",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"url\": \"https://your-server.com/webhooks/facturax\",\n \"events\": [\"invoice.signed\", \"invoice.extracted\", \"invoice.error\"]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "{{base_url}}/webhooks",
"host": [
"{{base_url}}"
],
"path": [
"webhooks"
]
},
"description": "Creates a webhook. FacturaX will POST to your URL on every event.\n\n**Available events:**\n- `invoice.signed` ā signed XML ready\n- `invoice.extracted` ā data extracted from the PDF\n- `invoice.error` ā processing error\n- `*` ā all events\n\nSave the `secret` from the response to verify the HMAC-SHA256 signature of each delivery."
},
"response": [
{
"name": "200 OK ā Webhook created",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"id\": 42,\n \"url\": \"https://tu-servidor.com/webhooks/facturax\",\n \"events\": [\"invoice.signed\"],\n \"secret\": \"whsec_abc123...\",\n \"active\": true\n}"
}
]
},
{
"name": "Delete webhook",
"request": {
"method": "DELETE",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/webhooks/:webhook_id",
"host": [
"{{base_url}}"
],
"path": [
"webhooks",
":webhook_id"
],
"variable": [
{
"key": "webhook_id",
"value": "42"
}
]
},
"description": "Deletes a webhook."
},
"response": []
}
]
},
{
"name": "š API Keys",
"item": [
{
"name": "My key info",
"request": {
"method": "GET",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/keys/me",
"host": [
"{{base_url}}"
],
"path": [
"keys",
"me"
]
},
"description": "Returns information about your current API key: plan, used quota, remaining quota, reset date.\n\nUseful for showing usage to the user in your software."
},
"response": [
{
"name": "200 OK",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"id\": 95,\n \"name\": \"My integration\",\n \"plan\": \"business\",\n \"quota\": 7000,\n \"used\": 142,\n \"remaining\": 6858,\n \"quota_reset_at\": \"2024-07-01T00:00:00Z\",\n \"active\": true\n}"
}
]
},
{
"name": "List all my keys",
"request": {
"method": "GET",
"header": [
{
"key": "X-API-Key",
"value": "{{api_key}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/keys/list",
"host": [
"{{base_url}}"
],
"path": [
"keys",
"list"
]
},
"description": "Lists all API keys in your account with their usage and status."
},
"response": []
}
]
},
{
"name": "āļø System",
"item": [
{
"name": "Health check",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{base_url}}/status",
"host": [
"{{base_url}}"
],
"path": [
"status"
]
},
"description": "Checks that the API is operational. No authentication required.\n\nUseful for monitoring ā if it returns 200, the API is up."
},
"response": [
{
"name": "200 OK",
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"body": "{\n \"status\": \"ok\",\n \"version\": \"1.0\",\n \"b2\": \"ok\",\n \"stripe\": \"ok\"\n}"
}
]
}
]
}
]
}