Registrar facturas¶

Crear factura¶

POST /api/v1/invoices
Authorization: Bearer TU_API_KEY

Campos obligatorios¶

Campo	Tipo	Descripción
`taxpayer_id`	uuid	ID del contribuyente emisor
`computer_system_id`	uuid	ID del sistema informático
`invoice_number`	string	Nº factura (máx. 60 chars, único por NIF)
`invoice_date`	date	Fecha expedición (≤ hoy)
`invoice_type`	string	`F1`, `F2`, `F3` (ver tipos)
`description`	string	Descripción operación (máx. 500 chars)
`breakdown`	array	Desglose fiscal (mín. 1 línea)
`total_amount`	numeric	Importe total factura
`total_tax_amount`	numeric	Total cuotas impositivas

Campos opcionales¶

Campo	Tipo	Descripción
`operation_date`	date	Fecha operación (si distinta a expedición)
`issued_by`	string	`issuer` / `recipient` / `third_party`
`third_party_nif`	string	NIF del tercero (requerido si `issued_by=third_party`)
`third_party_name`	string	Nombre del tercero
`regime_types`	array	Regímenes fiscales (ej: `["01"]`)
`reverse_charge`	boolean	Inversión de sujeto pasivo
`recipient_nif`	string	NIF destinatario
`recipient_name`	string	Nombre destinatario
`not_subject_amount`	numeric	Importe no sujeto
`not_subject_cause`	string	`RL` (Reglas localización) / `OT` (Otros)

Desglose (`breakdown`)¶

Cada línea del desglose:

Campo	Tipo	Descripción
`tax_type`	string	`01` (IVA), `02` (IPSI), `03` (IGIC), `05` (Otros)
`regime_type`	string	Clave régimen (ver tablas)
`operation_type`	string	`S1`, `S2`, `N1`, `N2`, `E1`-`E6`
`base_amount`	numeric	Base imponible
`tax_rate`	numeric	Tipo impositivo (%)
`tax_amount`	numeric	Cuota
`surcharge_rate`	numeric	Recargo equivalencia (%) — opcional
`surcharge_amount`	numeric	Cuota recargo — opcional

Ejemplo completo¶

{
  "taxpayer_id": "uuid-contribuyente",
  "computer_system_id": "uuid-sistema",
  "invoice_number": "F-2026-042",
  "invoice_date": "2026-03-13",
  "invoice_type": "F1",
  "description": "Mantenimiento mensual",
  "regime_types": ["01"],
  "recipient_nif": "A98765432",
  "recipient_name": "Cliente SA",
  "breakdown": [
    {
      "tax_type": "01",
      "regime_type": "01",
      "operation_type": "S1",
      "base_amount": 500.00,
      "tax_rate": 21.00,
      "tax_amount": 105.00
    },
    {
      "tax_type": "01",
      "regime_type": "01",
      "operation_type": "S1",
      "base_amount": 200.00,
      "tax_rate": 10.00,
      "tax_amount": 20.00
    }
  ],
  "total_amount": 825.00,
  "total_tax_amount": 125.00
}

Respuesta `201`¶

{
  "message": "Invoice registered successfully.",
  "data": {
    "id": "uuid-factura",
    "invoice_number": "F-2026-042",
    "hash": "SHA256...",
    "qr_url": "https://prewww2.aeat.es/...",
    "aeat_status": "queued",
    "record_type": "registration"
  }
}

Consultar factura¶

GET /api/v1/invoices/{id}

Devuelve todos los datos de la factura, incluyendo desglose, hash, QR y estado AEAT.

Consultar estado¶

GET /api/v1/invoices/{id}/status

{
  "data": {
    "aeat_status": "accepted",
    "aeat_response": { ... }
  }
}

Descargar PDF¶

GET /api/v1/invoices/{id}/pdf

Devuelve el PDF con QR de verificación y sello VERI*FACTU.

Obtener XML¶

GET /api/v1/invoices/{id}/xml

Devuelve el XML generado para el envío a la AEAT.

Obtener URL del QR¶

GET /api/v1/invoices/{id}/qr

Listar facturas de un contribuyente¶

GET /api/v1/taxpayers/{nif}/invoices?status=accepted&page=1

Parámetro	Tipo	Descripción
`status`	string	Filtrar por estado AEAT
`page`	integer	Paginación

Reenviar factura rechazada¶

POST /api/v1/invoices/{id}/retry

Solo disponible para facturas con estado rejected o error.

Validaciones automáticas

La API aplica automáticamente:

Número único por NIF: No puedes registrar dos facturas con el mismo número para el mismo contribuyente.
Orden cronológico: Las fechas deben ser iguales o posteriores a la última factura registrada.
Inmutabilidad: Una factura aceptada no puede modificarse.