Formatos y exportación

Descarga una factura emitida en un formato electrónico o en PDF, e importa en XML las facturas que te envían tus proveedores.

Todas las rutas cuelgan de https://app.faxtal.com/api/v1.1 y se autentican con la cabecera X-API-Key (ver Autenticación).

Exportar una factura emitida

GET /api/v1.1/issued-invoices/{invoice_id}/export?format=...

Permiso de la clave: invoices:read.

`format`	Formato	Qué recibes
`facturae_3_2_2`	Facturae 3.2.2	XML firmado (XAdES)
`facturae_3_2_1`	Facturae 3.2.1	XML firmado (XAdES)
`ubl_2_1`	UBL 2.1 (EN 16931)	XML validado contra EN 16931
`cii_d16b`	UN/CEFACT CII D16B (EN 16931)	XML validado contra EN 16931

Condiciones:

Solo se exportan facturas en estado issued o sent.
Facturae se firma con el certificado activo de la empresa.
Exportar no cambia el estado de la factura.
Facturae 3.2 solo se admite al importar, no al exportar.

curl -s "https://app.faxtal.com/api/v1.1/issued-invoices/00000000-0000-0000-0000-000000000001/export?format=facturae_3_2_2" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -o factura.xml

Respuesta: 200 con Content-Type: application/xml y el fichero como adjunto (Content-Disposition: attachment; filename="invoice_inv_ABC123_facturae.xml").

Facturas que solo salen en Facturae

EN 16931 no modela algunos casos españoles. Estas facturas se exportan a Facturae, pero con ubl_2_1 o cii_d16b responden 422. El código empieza por ubl_export_ o cii_export_ según el formato pedido:

Caso	Final del código
Factura simplificada	`simplified_invoice_not_supported`
Sin cliente identificado (falta `customer.name`)	`missing_buyer`
Con retención (`taxes_withheld`, p. ej. IRPF)	`withholding_not_supported`
Con recargo de equivalencia	`equivalence_surcharge_not_supported`
Rectificativa por sustitución (`correction_type: "S"`)	`substitution_not_supported`
Alguna línea no sujeta (categoría `O`)	`not_subject_not_supported`

Ejemplo: una factura con IRPF pedida en UBL responde ubl_export_withholding_not_supported. Las exentas (categoría E) sí se exportan a UBL y CII.

Errores al exportar

Los errores llegan con el formato {"detail": {"code": "...", "message": "...", "request_id": "..."}} (ver Errores).

HTTP	`code`	Causa
`403`	`scope_missing`	La clave no tiene `invoices:read`.
`404`	`invoice_not_found`	La factura no existe en la empresa de la clave o es una recibida.
`409`	`invoice_not_issued_for_export`	La factura no está en `issued` ni en `sent`.
`422`	`ubl_export_` / `cii_export_`	Caso no admitido por EN 16931 (tabla anterior).
`422`	`ubl_en16931_validation_error` / `cii_en16931_validation_error`	El XML generado no supera la validación EN 16931. El detalle va en `errors`.
`422`	`facturae_signing_error`	No se ha podido firmar. Revisa el certificado de la empresa.
`422`	`export_validation_error`	La factura no se ha podido convertir al formato pedido.
`422`	`request_validation_error`	Falta `format` o no es uno de los admitidos.
`500`	`ubl_validation_runtime_error` / `cii_validation_runtime_error`	El validador EN 16931 no ha podido ejecutarse. Reintenta más tarde.

Descargar el PDF

GET /api/v1.1/issued-invoices/{invoice_id}/pdf
GET /api/v1.1/received-invoices/{invoice_id}/pdf

Permiso de la clave: invoices:read.

El PDF usa la plantilla y la marca (logo, color y fuente) de la empresa. Si la factura tiene registro VeriFactu, lleva su QR.

Parámetro	Obligatorio	Descripción
`template`	No	Plantilla general para esta descarga, como `<diseño>-<estilo>`: diseño `clasica`, `honorarios`, `catalogo`, `ticket`, `consumidor`, `suscripcion`, `tiempo` o `exportacion`, y estilo `suizo`, `editorial`, `diagonal`, `bloque`, `lateral`, `organico`, `capsulas` o `papel` (por ejemplo, `honorarios-editorial`). Sin él, o con un valor desconocido, se usa la de la serie de la factura o, si no tiene, la de la empresa. Los ids anteriores (`estandar`, `ticket`, `servicios`, `productos`, `resumen`, `classic`, `modern`, `minimal`) y los estilos anteriores (`sobrio`, `corporativo`, `minimal`, `contraste`, `tecnico`) se siguen aceptando.

curl -s "https://app.faxtal.com/api/v1.1/issued-invoices/00000000-0000-0000-0000-000000000001/pdf?template=servicios" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -o factura.pdf

Respuesta: 200 con Content-Type: application/pdf (filename="invoice_inv_ABC123.pdf").

Si la factura no existe o pertenece a la otra dirección (una recibida pedida por issued-invoices, o al revés), responde 404 invoice_not_found.

Importar facturas en XML

La API importa XML solo para facturas recibidas:

POST /api/v1.1/received-invoices/import?format=...

Permiso de la clave: received:write.

format: facturae_3_2_2, facturae_3_2_1, facturae_3_2, ubl_2_1 o cii_d16b.
Cuerpo: el XML tal cual, con Content-Type: application/xml o text/xml. Máximo 10 MB.

curl -s -X POST "https://app.faxtal.com/api/v1.1/received-invoices/import?format=ubl_2_1" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/xml" \
  --data-binary @factura-proveedor.xml

{
  "success": true,
  "id": "00000000-0000-0000-0000-000000000001",
  "errors": []
}

Errores propios del fichero: 400 empty_body (cuerpo vacío), 413 payload_too_large (más de 10 MB) y 415 unsupported_media_type (otro Content-Type). La validación de la factura y la deduplicación se cuentan en Facturas recibidas.

Las emitidas no se importan en XML. Para registrar emitidas fuera de Faxtal, envíalas en formato canónico con POST /api/v1.1/issued-invoices/import (ver Importación).

Ver también

Envío por email: adjunta el PDF y los formatos configurados en el cliente.
Facturas emitidas
Facturas recibidas
Importación
Errores
Referencia interactiva