Referencia de endpoints

Todas las rutas son relativas a la URL base y requieren un token Bearer. Los importes están en céntimos; los nombres de campo usan snake_case.

Entidades (clientes y proveedores)

Una entidad es la parte a la que facturas o que te factura. Las facturas referencian una entidad mediante recipient_id.

Método	Ruta	Descripción
GET	/v1/entities	Lista todas las entidades de tu empresa.
POST	/v1/entities	Crea una entidad.
GET	/v1/entities/{id}	Obtiene una entidad concreta.

Crear una entidad

curl -X POST https://api.uninvoice.app/v1/entities \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme S.L.",
    "type": "ES-company",
    "country": "ES",
    "fiscal_id": "B12345678",
    "address_lines": ["Calle Mayor 1"],
    "address_zipcode": "28013",
    "address_city": "Madrid",
    "currency_code": "EUR"
  }'

name, type y country son obligatorios. type codifica tanto el país como la forma jurídica (p. ej. ES-company, ES-individual) y determina cómo se trata la entidad a efectos fiscales y legales. Campos opcionales: fiscal_id, vies_vat_id, los campos address_*, currency_code y under_recargo_equivalencia (recargo de equivalencia).

Facturas

Las facturas se crean como borradores y luego se emiten. Un borrador no tiene número de factura y no es definitivo; al emitir se asigna el número, se congela una instantánea de los datos de la empresa y del destinatario, se genera el registro Veri*Factu cuando corresponde y se produce el PDF definitivo.

Método	Ruta	Descripción
GET	/v1/invoices	Lista las facturas (elementos resumidos).
POST	/v1/invoices	Crea una factura en borrador.
GET	/v1/invoices/{id}	Obtiene una factura completa con sus líneas.
POST	/v1/invoices/{id}/issue	Emite un borrador (asigna el número y lo finaliza).
POST	/v1/invoices/{id}/correct	Crea una factura rectificativa de una ya emitida.
GET	/v1/invoices/{id}/pdf	Descarga el PDF de la factura (binario).
POST	/v1/taxes/prefill	Calcula las líneas de impuestos para un conjunto de líneas en borrador.

Crear una factura en borrador

curl -X POST https://api.uninvoice.app/v1/invoices \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "ent_...",
    "supply_type": "services",
    "lines": [
      {
        "idx": 1,
        "concept": "Consultoría — junio 2026",
        "quantity": 10,
        "quantity_unit": "horas",
        "unit_price": 20000
      }
    ]
  }'

Campos:

• recipient_id (obligatorio) — la entidad a la que se factura.
• supply_type — services o goods (por defecto services).
• lines (obligatorio) — las líneas. Cada línea tiene un idx (orden basado en 1), un concept y, opcionalmente, quantity, quantity_unit, unit_price (céntimos), unit_unit, date_start/date_end y subtotal. Una línea con "is_tax": true y un tax_amount representa una línea de impuesto explícita.
• Los campos de rectificación (correction_reason, correction_type, corrected_invoice_id) solo aplican a facturas rectificativas — usa preferentemente el endpoint /correct.

Los impuestos normalmente se calculan por ti a partir de la empresa y del destinatario. Para ver las líneas de impuestos antes de crear la factura, envía el mismo recipient_id y lines a /v1/taxes/prefill, que devuelve las líneas con los impuestos rellenados.

Emitir una factura

curl -X POST https://api.uninvoice.app/v1/invoices/inv_.../issue \
  -H "Authorization: Bearer <token>"

Los emisores en España deben autorizar Veri*Factu primero

Para los emisores establecidos en España, la emisión está bloqueada hasta que hayas otorgado el apoderamiento ante la AEAT. Hasta entonces la factura sigue siendo un borrador y issue devuelve 403 con error: "verifactu_authorization_required". Consulta Autorizar a uninvoice.app.

Proformas

Las proformas son presupuestos sin efectos fiscales. Se pueden editar y eliminar, y promocionar a una factura real cuando se aceptan.

Método	Ruta	Descripción
GET	/v1/proformas	Lista las proformas.
POST	/v1/proformas	Crea una proforma.
GET	/v1/proformas/{id}	Obtiene una proforma.
DELETE	/v1/proformas/{id}	Elimina una proforma.
POST	/v1/proformas/{id}/promote	Promociona una proforma a factura en borrador.
GET	/v1/proformas/{id}/pdf	Descarga el PDF de la proforma (binario).

Empresa

Método	Ruta	Descripción
GET	/v1/companies/current	Lee la configuración de tu empresa.
PUT	/v1/companies/current	Actualiza la configuración de tu empresa.
GET	/v1/companies/current/api-tokens	Lista los tokens de API.
POST	/v1/companies/current/api-tokens	Crea un token de API.
DELETE	/v1/companies/current/api-tokens/{token_id}	Revoca un token de API.

Autorización Veri*Factu

Lee y confirma el estado del apoderamiento Veri*Factu de tu empresa. Consulta la guía Veri*Factu para el flujo completo.

Método	Ruta	Descripción
GET	/v1/verifactu/authorization	Estado actual de la autorización.
POST	/v1/verifactu/authorization/confirm	Registra que has otorgado el poder ante la AEAT.

Un flujo de integración típico

1. Crea el destinatario con POST /v1/entities (o reutiliza uno existente de GET /v1/entities).
2. (Opcional) Previsualiza los impuestos con POST /v1/taxes/prefill.
3. Crea el borrador con POST /v1/invoices.
4. Emítelo con POST /v1/invoices/{id}/issue — esto asigna el número de factura y, para emisores en España, lo remite a la AEAT.
5. Descarga el PDF con GET /v1/invoices/{id}/pdf.