Recursos
Material de apoyo para integrar con la API: lo que hay hoy y lo que está previsto.
Colección Postman / Insomnia
:::info Roadmap Está prevista una colección lista para importar. Todavía no hay fecha. :::
Mientras tanto, importa en Postman o Insomnia la especificación OpenAPI que carga la Referencia API. Los dos generan una petición por operación. Después:
- Define la cabecera
X-API-Keya nivel de colección. - Usa
https://app.faxtal.comcomo servidor. Las rutas ya empiezan por/api/v1.1.
SDKs
:::info Roadmap Los SDKs oficiales están en el roadmap. Todavía no hay fecha. :::
Mientras tanto, genera un cliente en tu lenguaje con un generador de OpenAPI (por ejemplo,
openapi-generator) a partir de la misma especificación. Ten en cuenta dos cosas:
- La especificación solo declara el error
422, y con un esquema que no es el real. Trata los errores con el formato que describe Errores. - El PDF, los XML exportados y los documentos adjuntos llegan como binario, no como JSON.
Glosario
Qué significa cada término dentro de la API. Para el detalle de campos, ver el formato canónico.
| Término | En la API |
|---|---|
| API key | Credencial de integración. Se envía en la cabecera X-API-Key y está ligada a una sola empresa. |
| Scope | Permiso de una API key, como invoices:read o invoices:issue. Sin él, la operación responde 403 con scope_missing. |
| Empresa | La organización que factura. La API la deduce de la API key. |
| Formato canónico | El JSON json_1_1 con el que la API recibe, valida y guarda las facturas, vengan del formato que vengan. |
| Dirección | meta.direction: issued para las emitidas y received para las recibidas. |
| Estado | Estado público de una factura: draft, issued, sent, cancelled o queued. |
| Borrador | Factura emitida todavía sin número ni fecha de expedición. Su estado es draft. |
| Emitir | Convertir un borrador en factura: el sistema asigna número y fecha. |
| Importar | Registrar una factura ya emitida fuera de Faxtal, con su número y su fecha. |
| Serie | header.invoice_series_code. Agrupa la numeración de las facturas. |
external_ref | Tu referencia de la factura, en meta. Sirve para enlazarla con tu sistema y deduplicar. |
| Lote | Petición a una ruta .../batch con varias facturas. La respuesta trae el resultado de cada una. |
| Rectificativa | Factura que corrige otra: invoice_type_code 03, o 04 si es simplificada, con el bloque header.corrective. |
| Simplificada | Factura con invoice_type_code 02. |
| NIF | Identificador fiscal español. La API valida su formato y su dígito de control. |
| IVA / IGIC | Grupos de impuesto indirecto que admite una factura (issue_data.tax_group_code). Cada factura usa uno solo. |
| TAI | Territorio de aplicación del IVA. No se envía: el sistema lo deduce del domicilio del emisor (is_tai). |
| VeriFactu | Sistema de la AEAT al que Faxtal envía un registro por cada factura emitida, si la empresa lo tiene activo. |
| Registro VeriFactu | Alta o anulación asociada a una factura, con su estado, su huella y su qr_url. |
| Huella | Hash encadenado de cada registro VeriFactu (huella, huella_anterior). |
| QR VeriFactu | Enlace de cotejo de la factura en la AEAT. Viene en qr_url y se imprime en el PDF. |
| CSV | Código seguro de verificación que devuelve la AEAT para un envío aceptado (aeat_csv). |
| Evento SIF | Registro de inicio o fin de uso del sistema de facturación (/verifactu/sif). |
| SII | Suministro Inmediato de Información de la AEAT. |
| TicketBAI | Sistema de facturación de las haciendas forales del País Vasco. |
| Facturae | Formato XML español de factura electrónica. Puede ir firmado con XAdES. |
| UBL / CII | Las dos sintaxis XML de la factura electrónica europea EN 16931: UBL 2.1 y UN/CEFACT CII. |
| MCP | Model Context Protocol. El servidor MCP permite a un asistente de IA operar con la API. |