Facturas

Con /external/v1/invoices tu aplicación emite facturas en nombre de sus usuarios, con la numeración de tu organización o en una serie que tu organización le haya reservado, y las consulta, descarga o anula. Todas las peticiones llevan la cabecera X-Api-Key con una clave activa, exigen que la facturación de la aplicación esté encendida y tienen un límite de 60 peticiones por minuto.

Cada clave solo opera sobre las facturas de su propia aplicación, y el userId filtra además por el usuario indicado.

Plan y permisos

Antes que el permiso de la aplicación se comprueba el plan de tu organización. Sin el aplicativo Finanzas contratado, todos estos endpoints responden 403 con errorCode: 'MODULE_NOT_ENABLED' y la clave del aplicativo que falta.

Sin el permiso adecuado, los endpoints responden 403 INSUFFICIENT_SCOPE con un mensaje genérico que no dice cuál falta. No hay periodo de gracia: el permiso se exige desde la primera llamada, también en aplicaciones creadas hace tiempo, así que concédelos antes de integrar. crm:invoices:cancel y crm:invoices:rectify son críticos financieros: solo los concede un Super Administrador, con un motivo. El catálogo completo y las reglas de concesión están en Permisos de la API.

Las acciones sobre una factura ya emitida (enviarla por correo, cobrarla, marcarla pagada, devolver el dinero o pedir su enlace público) están en Acciones sobre una factura emitida. Las rectificativas, cuando devuelves el dinero con tu propia pasarela o un contracargo deja la venta sin efecto, están en Facturas rectificativas. Las facturas con el IVA del país del consumidor por la ventanilla única (taxSystem: "EU_OSS") están en «Próximamente»: hasta que estén disponibles para tu organización, responden 403 FEATURE_COMING_SOON.

Ordinaria o simplificada

Por esta ruta se emiten dos tipos de factura, que se eligen con type:

El destinatario de una simplificada depende de lo que mandes en recipient:

UTILIA OS no copia en la factura datos del usuario que no vengan en recipient. Una ordinaria sin recipient responde 400 INVOICE_RECIPIENT_REQUIRED, y con datos incompletos, 400 INVOICE_RECIPIENT_INCOMPLETE con missingFields. Las rectificativas no se crean aquí: tienen su propia ruta.

Crear una factura

Cuerpo de la petición

Si el bloque user no trae taxId o billingAddress y el usuario tampoco los tiene guardados, se toman del recipient que se imprime en el documento y se escriben en su ficha. Lo que declare user manda siempre, y un dato ya guardado nunca se pisa con el del receptor. Es una red, no la vía principal: manda los datos fiscales con identify en cuanto los tengas, porque una factura emitida a un cliente sin identificador fiscal obliga a rectificarla.

Ejemplo de petición

curl -X POST https://os.utilia.ai/api/external/v1/invoices \
  -H "X-Api-Key: utl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "externalId": "user_01HXYZ",
      "email": "cliente@empresa.com",
      "name": "Empresa de Canarias SL",
      "taxId": "B76543210"
    },
    "recipient": {
      "name": "Empresa de Canarias SL",
      "taxId": "B76543210",
      "address": "Avenida de Canarias 12",
      "city": "Las Palmas",
      "postalCode": "35001",
      "country": "España"
    },
    "issueDate": "2026-04-19",
    "dueDate": "2026-05-19",
    "taxSystem": "IGIC",
    "lines": [
      {
        "name": "Plan Premium mensual",
        "quantity": 1,
        "unitPrice": 49.95,
        "taxType": "IGIC_7"
      }
    ],
    "sendEmail": true,
    "idempotencyKey": "ord_01HXYZ-invoice"
  }'

Respuesta correcta (201)

{
  "id": "ckinv1234567890",
  "invoiceNumber": "202600042",
  "displayNumber": "2026-00042",
  "type": "STANDARD",
  "seriesCode": "DEFAULT",
  "taxSystem": "IGIC",
  "consumerCountryCode": null,
  "ossScheme": null,
  "status": "SENT",
  "legalMentions": [],
  "originalInvoiceId": null,
  "issuancePending": false,
  "issuanceDeliveryStatus": "complete",
  "issuanceMessage": "La factura está emitida y su entrega ha terminado.",
  "emailDelivery": {
    "status": "sent",
    "message": "La factura se ha enviado por correo.",
    "attempts": 1,
    "lastAttemptAt": "2026-10-01T09:12:45.000Z",
    "sentAt": "2026-10-01T09:12:46.000Z"
  },
  "cancellationPending": false,
  "totalAmount": 53.45,
  "paidAmount": 0,
  "currency": "eur",
  "issueDate": "2026-10-01T00:00:00.000Z",
  "dueDate": "2026-10-08T00:00:00.000Z",
  "pdfUrl": "/api/external/v1/invoices/ckinv1234567890/pdf?userId=user_01HXYZ",
  "externalUserId": "user_01HXYZ",
  "createdAt": "2026-10-01T09:12:44.000Z",
  "idempotent": false,
  "emailSent": true
}

displayNumber, issuanceDeliveryStatus, issuanceMessage y emailDelivery vuelven en todas las lecturas de la factura (el detalle, el listado y las respuestas de las acciones), con su valor de ese momento. emailSent e idempotent solo los trae la respuesta del alta.

El PDF, los correos y el panel presentan el número con un guion entre el año y el número de orden (T-2026-00001): es displayNumber. El número registrado, el de los libros registro y, si la factura lo lleva, el de su código QR, va sin guion (T-202600001): es invoiceNumber, y es el que debes guardar, buscar y conciliar. El guion solo es presentación.

Precios con impuestos incluidos

Si tu aplicación cobra un precio cerrado, por ejemplo 39,99 €, manda pricesIncludeTax: true y ese precio en unitPrice. UTILIA OS busca la base exacta al céntimo para que el total de la línea sea exactamente lo cobrado:

En las líneas exentas o no sujetas, la base es el propio importe. Si un importe no tiene una base exacta al céntimo con su tipo, la respuesta es 422 TAX_INCLUSIVE_PRICE_NOT_REPRESENTABLE con el número de línea en lineNumber (empieza en 1): ajusta un céntimo o usa cantidad 1. Nunca se emite una factura cuyo total difiera del cobrado.

Una factura que ya cobraste con tu pasarela

Si tu aplicación cobra con su propia pasarela (por ejemplo, su cuenta de Stripe) y usa UTILIA OS solo para facturar, manda el bloque payment. La factura se emite y queda cobrada por su total en el mismo acto, y si se envía por correo sale con la plantilla de factura pagada: tu cliente recibe un único correo.

Si el registro del cobro falla, la factura ya está emitida y su emisión está completa: paymentRegistered llega en false e issuanceDeliveryStatus en complete. Para no pedirle a tu cliente que pague algo que ya pagó, el correo no sale (emailDelivery.status en withheld, con reason: PAYMENT_NOT_REGISTERED). Registra el cobro con mark-paid (o tu equipo, con Registrar cobro en la ficha de la factura): paymentRegistered pasa a true y después la envías con send. Repetir la clave de idempotencia no lo reintenta. Un cobro sin registrar no impide rectificar ni anular la factura. Sin payment, la factura queda pendiente de cobro, como hasta ahora.

Residencia del consumidor

Con consumerResidence dejas constancia de dónde reside el consumidor y de cómo lo sabes. Es tu aplicación quien lo conoce: UTILIA OS no lo deduce si no lo mandas. Si lo mandas, se coteja con el sistema fiscal de la factura:

• CANARIAS exige IGIC.
• PENINSULA_BALEARES exige IVA.
• CEUTA_MELILLA, OTHER_EU y NON_EU no admiten IGIC.

Si no cuadra, la respuesta es 400 TAX_SYSTEM_RESIDENCE_MISMATCH. La residencia se guarda con la factura, no se imprime y no se devuelve en metadata. Con un consumidor de otro país de la Unión (OTHER_EU), la respuesta trae su país en consumerCountryCode.

Cuando la ventanilla única del IVA esté disponible para tu organización (hoy está en «Próximamente») y una venta a un consumidor de la Unión ya tribute en el país del consumidor, una factura con IVA español a ese consumidor se rechazará con 400 OSS_THRESHOLD_EXCEEDED u OSS_DESTINATION_VAT_REQUIRED. Para las demás organizaciones no cambia nada.

Régimen del pequeño empresario del IGIC (REPEP)

Si tu organización es un autónomo canario y tiene declarado el Régimen especial del pequeño empresario o profesional (REPEP) en Finanzas, Ajustes, Fiscal, Regímenes especiales, sus ventas con IGIC dentro de un periodo del régimen están exentas:

• Manda las líneas con taxType: "EXEMPT" y sin exemptionReason. UTILIA OS les pone la causa EXEMPT_IGIC_SMALL_BUSINESS («Pequeño empresario (franquicia fiscal)») y la factura lleva la mención «Exención franquicia fiscal».
• Una línea con cuota de IGIC, también IGIC_0, responde 400 IGIC_SMALL_BUSINESS_TAXED_LINE con lineNumber. El tipo cero no es una exención.
• Solo afecta a facturas con taxSystem: "IGIC". Las ventas a consumidores de Península y Baleares llevan IVA y no cambian; mandar la causa del REPEP en una factura que no es IGIC responde 400 IGIC_SMALL_BUSINESS_REQUIRES_IGIC.
• Mandar la causa con una fecha fuera de cualquier periodo del régimen responde 400 IGIC_SMALL_BUSINESS_NOT_ACTIVE.

Qué es el régimen, quién puede declararlo y qué cambia en los modelos está en Impuestos.

Ejemplo completo: simplificada de 39,99 € en el REPEP, cobrada en el acto

Un consumidor residente en Tenerife paga 39,99 € con la tarjeta en la pasarela de tu aplicación. Tu organización está en el REPEP.

curl -X POST https://os.utilia.ai/api/external/v1/invoices \
  -H "X-Api-Key: utl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SIMPLIFIED",
    "user": { "externalId": "user_01HXYZ", "email": "ana@example.com" },
    "taxSystem": "IGIC",
    "pricesIncludeTax": true,
    "lines": [
      { "name": "Plan Básico mensual", "quantity": 1, "unitPrice": 39.99, "taxType": "EXEMPT" }
    ],
    "payment": { "method": "CARD", "reference": "pi_3QabcDEF" },
    "consumerResidence": {
      "region": "CANARIAS",
      "evidence": "Dirección de facturación y tarjeta en Santa Cruz de Tenerife."
    },
    "sendEmail": true,
    "idempotencyKey": "pedido-4471"
  }'

Con la línea exenta, pricesIncludeTax no cambia nada (la base es el total), pero conviene mandarlo si tu aplicación siempre trabaja con precios cerrados: si algún día la venta lleva cuota, el total seguirá siendo el cobrado.

{
  "id": "cksimp1234567890",
  "invoiceNumber": "T-202600001",
  "displayNumber": "T-2026-00001",
  "type": "SIMPLIFIED",
  "seriesCode": "DEFAULT",
  "status": "PAID",
  "legalMentions": [
    "Factura simplificada (RD 1619/2012 art. 7)",
    "Exención franquicia fiscal"
  ],
  "pricesIncludeTax": true,
  "paymentRegistered": true,
  "originalInvoiceId": null,
  "issuancePending": false,
  "issuanceDeliveryStatus": "complete",
  "issuanceMessage": "La factura está emitida y su entrega ha terminado.",
  "emailDelivery": {
    "status": "sent",
    "message": "La factura se ha enviado por correo.",
    "attempts": 1,
    "lastAttemptAt": "2026-10-13T09:30:13.000Z",
    "sentAt": "2026-10-13T09:30:14.000Z"
  },
  "totalAmount": 39.99,
  "paidAmount": 39.99,
  "currency": "eur",
  "issueDate": "2026-10-13T00:00:00.000Z",
  "dueDate": null,
  "pdfUrl": "/api/external/v1/invoices/cksimp1234567890/pdf?userId=user_01HXYZ",
  "externalUserId": "user_01HXYZ",
  "createdAt": "2026-10-13T09:30:12.000Z",
  "idempotent": false,
  "emailSent": true
}

El PDF imprime «T-2026-00001» como número, «Consumidor final» como destinatario, sin dirección, «IGIC: exento» en lugar de un tipo y la mención «Exención franquicia fiscal». Si más adelante devuelves el dinero, emite su rectificativa con Facturas rectificativas.

Reintentar sin duplicar la factura

Emitir una factura hace varias cosas en el mismo paso (numerarla, registrarla, generar su PDF y, si lo pides, registrar el cobro y enviar el correo), así que la respuesta puede tardar varios segundos. Pon a tu cliente HTTP un tiempo de espera de al menos 30 segundos para POST /external/v1/invoices: uno más corto corta peticiones que sí terminan.

Si aun así se corta la conexión, no sabes si la factura llegó a emitirse. Repite la petición con la misma idempotencyKey y el mismo cuerpo, nunca con una clave nueva: durante 24 horas, UTILIA OS reconoce la clave y no emite otra. Si la primera petición todavía se está ejecutando, la repetición devuelve esa misma factura con issuanceDeliveryStatus: processing; consulta de nuevo con la misma clave hasta que llegue complete.

Estado de la emisión

issuanceDeliveryStatus dice si la emisión ha terminado. Habla solo del cierre fiscal (el número, el sello, el registro y los efectos del documento, como su PDF y su código QR), no de la entrega:

Un correo que no sale o un cobro del bloque payment que no se registra no dejan la emisión pendiente: la factura queda complete, y su resultado viaja aparte, en emailDelivery y paymentRegistered, para completarlo sin tocar la factura. Tampoco impiden rectificarla ni anularla.

Dar por revisada está en el aviso «Emisión pendiente de revisión» de la ficha de la factura, en Finanzas › Facturas, necesitas entrar con tu cuenta, y lo ve quien tiene los permisos «Editar aplicaciones externas» y «Emitir facturas». Solo se acepta si la factura tiene número y su PDF original está generado y verificado; no reemite ni envía nada y queda en el registro de auditoría con el nombre de quien lo hizo. Después, la aplicación ya puede rectificarla o anularla repitiendo su petición. La ruta del panel que usa está en Panel de aplicaciones externas.

El correo de la factura

Si pides el correo (sendEmail: true, o sin sendEmail con el interruptor de la aplicación encendido), UTILIA OS intenta enviarla dentro de la misma petición, con la plantilla, el remitente y el PDF de tu organización. El destinatario es el contacto de facturación principal del cliente del CRM; si no hay, el correo del usuario (user.email) y, en último lugar, el del destinatario de la factura (recipient.email). El resultado llega en emailDelivery:

{
  "emailDelivery": {
    "status": "retrying",
    "reason": "PDF_NOT_READY",
    "message": "Todavía no se ha enviado por correo porque su PDF original se estaba terminando de preparar. UTILIA la enviará sola en unos minutos; no hace falta que la reenvíes.",
    "attempts": 1,
    "lastAttemptAt": "2026-10-19T10:00:09.000Z"
  }
}

statusenumobligatorio

sent, retrying, failed o withheld (ver la tabla siguiente).

reasonenum

Motivo estable cuando no se ha enviado. No viaja con sent.

messagestringobligatorio

Qué ha pasado y qué hacer, en castellano y listo para mostrar a tu equipo o a tu soporte.

attemptsnumber

Intentos de envío hechos hasta ahora.

lastAttemptAtstring

Último intento, en ISO 8601.

sentAtstring

Momento en que salió, en ISO 8601. Solo con sent.

Cómo reintenta UTILIA OS un correo en retrying:

1. Dentro de la petición de alta espera al PDF original unos 8 segundos, como mucho. Si no está listo, no retiene la respuesta: el correo queda en retrying.
2. Si el fallo fue del PDF, del almacén o del servidor de correo, hace un reintento rápido a los 45 segundos, más o menos.
3. Después lo recoge la recuperación de envíos automáticos, que pasa cada 10 minutos, hasta 12 intentos en total (unas dos horas).
4. Si se agotan, emailDelivery pasa a failed con RETRIES_EXHAUSTED y la persona que figura como creadora de la factura (la persona responsable de la aplicación cuando se emitió) recibe en UTILIA OS el aviso «Factura sin enviar».

Cada intento, y también cada decisión de no enviarla, queda en el bloque Comunicaciones con el cliente de la ficha de la factura, como «Factura enviada automáticamente», con su resultado. Si alguien la envía mientras tanto desde la ficha o con POST /send, emailDelivery pasa a sent y el reintento automático se detiene: la factura nunca sale dos veces por esta vía. Mientras la emisión está en processing, emailDelivery no viaja.

Para ensayar el correo sin emitir nada, POST /external/v1/invoices/validate dice en preview.email si saldría y a qué dirección: ver Probar la facturación sin emitir facturas.

Errores al crear

• 403 MODULE_NOT_ENABLED: el plan de tu organización no incluye el aplicativo Finanzas. Es una decisión comercial, no un fallo técnico: no reintentes.
• 403 INSUFFICIENT_SCOPE: la aplicación no tiene concedido crm:invoices:write o crm:invoices:issue. La creación exige los dos, porque crea y emite en el mismo paso.
• 403 BILLING_NOT_ENABLED: la facturación de la aplicación está apagada. La enciende un Super Administrador con Activar la facturación, en Dinero › Facturación de la ficha de la aplicación. Para descubrirlo antes de la primera factura real, POST /external/v1/invoices/validate lo devuelve como bloqueo, y el Resumen y la pestaña Pruebas de la aplicación lo marcan como paso pendiente.
• 403 BILLING_AMOUNT_EXCEEDS_LIMIT: el total supera el tope por factura configurado para la aplicación.
• 409 BILLING_IDEMPOTENCY_CONFLICT: la clave de idempotencia ya se usó con otro contenido.
• 400 INVOICE_SERIES_NOT_AVAILABLE: la serie de seriesCode no existe o no es de tu aplicación. El mensaje es el mismo en los dos casos.
• 400 INVOICE_SERIES_TYPE_MISMATCH: la serie es de otro tipo de documento (una de ordinarias para una simplificada, o al revés).
• 409 INVOICE_SERIES_INACTIVE: la serie está desactivada. Usa otra o pide a tu organización que la reactive.
• 400 INVOICE_ISSUE_DATE_OUT_OF_ORDER: issueDate es futura o anterior a la de la última factura de la misma serie. Llegan issueDate y today o lastIssueDate y seriesCode.
• 400 INVOICE_RECIPIENT_REQUIRED: factura ordinaria sin recipient.
• 400 INVOICE_RECIPIENT_INCOMPLETE: factura ordinaria con el destinatario incompleto. Los campos que faltan llegan en missingFields.
• 400 SIMPLIFIED_RECIPIENT_INCOMPLETE: simplificada con NIF sin el resto de datos del destinatario. Los que faltan llegan en missingFields.
• 422 SIMPLIFIED_INVOICE_AMOUNT_EXCEEDED: simplificada por encima de 400 € impuestos incluidos. Emite una ordinaria.
• 422 TAX_INCLUSIVE_PRICE_NOT_REPRESENTABLE: con pricesIncludeTax, el importe de la línea lineNumber no tiene base exacta al céntimo.
• 400 TAX_INCLUSIVE_GLOBAL_DISCOUNT_UNSUPPORTED: pricesIncludeTax con un discountPercent mayor que cero.
• 400 TAX_SYSTEM_RESIDENCE_MISMATCH: la residencia del consumidor no cuadra con el sistema fiscal.
• 400 IGIC_SMALL_BUSINESS_TAXED_LINE, IGIC_SMALL_BUSINESS_REQUIRES_IGIC o IGIC_SMALL_BUSINESS_NOT_ACTIVE: reglas del régimen del pequeño empresario del IGIC (ver arriba).
• 403 FEATURE_COMING_SOON: la petición lleva algo de la ventanilla única del IVA, que todavía no está disponible para tu organización. No es un bloqueo de plan: no lo reintentes.
• 400 OSS_*: reglas de la ventanilla única del IVA, que está en «Próximamente»; antes, 403 FEATURE_COMING_SOON.
• 400 VALIDATION_ERROR: uno o más campos no cumplen las restricciones.

Series disponibles

Sin hacer nada, las facturas ordinarias de tu aplicación se numeran en la serie general de tu organización, intercaladas con las que emite el equipo, y las simplificadas en T-. Si quieres que las de tu aplicación vayan aparte (por ejemplo, APP-202600001), una persona de tu organización con el permiso «Editar organización» crea una serie para la aplicación en Ajustes › Organización, necesitas entrar con tu cuenta, pestaña Facturas, bloque Series de facturación, y puede fijarla como serie por defecto de la aplicación en su pantalla Facturación. Tu aplicación no crea ni cambia series con la clave de API: solo las consulta y elige entre las suyas.

Respuesta (200)

{
  "fiscalYear": 2026,
  "series": [
    { "code": "DEFAULT", "documentType": "STANDARD", "prefix": null, "example": "202600001", "description": null, "isAppDefault": false, "selectable": true },
    { "code": "APP", "documentType": "STANDARD", "prefix": "APP", "example": "APP-202600001", "description": "Facturas de la aplicación de reservas", "isAppDefault": true, "selectable": true },
    { "code": "DEFAULT", "documentType": "SIMPLIFIED", "prefix": "T", "example": "T-202600001", "description": null, "isAppDefault": true, "selectable": true },
    { "code": "DEFAULT", "documentType": "RECTIFYING", "prefix": "R", "example": "R-202600001", "description": null, "isAppDefault": false, "selectable": false }
  ]
}

fiscalYearnumberobligatorio

Año en curso en la zona horaria de tu organización.

series[].codestringobligatorio

El valor que mandas en seriesCode. DEFAULT es la serie de siempre de su tipo.

series[].documentTypeenumobligatorio

STANDARD (ordinarias), SIMPLIFIED (simplificadas) o RECTIFYING (la de rectificativas, solo informativa).

series[].prefixstring | nullobligatorio

Prefijo impreso delante del número. La serie general puede no tener prefijo.

series[].examplestringobligatorio

El primer número del año con el formato real de la serie. No es el siguiente número: la respuesta no lo da, porque revelaría cuántas facturas emite tu organización.

series[].descriptionstring | nullobligatorio

Motivo de la serie que indicó tu organización al crearla.

series[].isAppDefaultbooleanobligatorio

Es la que se usa para su tipo cuando el alta no trae seriesCode: la serie por defecto de la aplicación o, si no tiene, la de siempre.

series[].selectablebooleanobligatorio

Se puede elegir en seriesCode. La de rectificativas llega en false: las rectificativas van siempre a ella, sin elegirla.

Solo aparecen las series activas reservadas a tu aplicación: nunca las de otra aplicación ni las que el equipo usa en sus facturas.

Qué serie lleva cada factura

1. Si mandas seriesCode, esa serie. DEFAULT fuerza la de siempre aunque la aplicación tenga una por defecto.
2. Si no, la serie por defecto de la aplicación para el tipo (ordinaria o simplificada).
3. Si no tiene, la de siempre: la general para las ordinarias y T- para las simplificadas.

La serie tiene que ser de tu aplicación (400 INVOICE_SERIES_NOT_AVAILABLE), del mismo tipo que la factura (400 INVOICE_SERIES_TYPE_MISMATCH) y estar activa (409 INVOICE_SERIES_INACTIVE). Todo se comprueba antes de numerar: un rechazo nunca consume un número ni deja hueco en la serie. Cada serie lleva su propia numeración correlativa, que empieza de nuevo cada año, y la respuesta dice en seriesCode en cuál se numeró.

Las rectificativas van siempre a la serie de rectificativas (R-), aunque la factura original esté en una serie de tu aplicación. Las suscripciones también admiten seriesCode: ver Suscripciones.

Fecha de expedición

Con la serie, issueDate queda acotada para que la numeración nunca retroceda:

• No puede ser futura en la zona horaria de tu organización.
• No puede ser anterior a la de la última factura ya expedida en la misma serie.
• Su año es el de la numeración: una factura con fecha de 2026 lleva un número de 2026.

Si no se cumple, la respuesta es 400 INVOICE_ISSUE_DATE_OUT_OF_ORDER, sin numerar, con issueDate y, según el caso, today o lastIssueDate y seriesCode. Si omites issueDate, se usa el día de hoy en la zona horaria de tu organización.

Listar facturas

Parámetros de consulta

userIdstring

Filtra por externalId del usuario.

statusenum

DRAFT, ISSUED, SENT, PAID, PARTIALLY_PAID, OVERDUE, CANCELLED, DISPUTED, OVERDUE_UNCOLLECTABLE, REFUNDED, PARTIALLY_REFUNDED o RECTIFIED.

typeenum

STANDARD, SIMPLIFIED, RECTIFYING o CREDIT_NOTE.

seriesCodestring

Código de una serie de tu aplicación o DEFAULT (las series de siempre de cada tipo; combínalo con type para acotar).

fromDatedate

Fecha de emisión mínima (AAAA-MM-DD).

toDatedate

Fecha de emisión máxima (AAAA-MM-DD).

pageinteger

Página (por defecto, 1).

limitinteger

Elementos por página (por defecto 20, máximo 100).

Respuesta (200)

{
  "invoices": [
    {
      "id": "inv-uuid",
      "invoiceNumber": "202600001",
      "displayNumber": "2026-00001",
      "type": "STANDARD",
      "seriesCode": "DEFAULT",
      "status": "PAID",
      "issuancePending": false,
      "issuanceDeliveryStatus": "complete",
      "issueDate": "2026-04-19T00:00:00.000Z",
      "dueDate": "2026-05-19T00:00:00.000Z",
      "totalAmount": 53.45,
      "paidAmount": 53.45,
      "currency": "eur",
      "pdfUrl": "/api/external/v1/invoices/inv-uuid/pdf?userId=user_01HXYZ",
      "externalUserId": "user_01HXYZ"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Detalle de factura

Parámetros

idpathobligatorio

Identificador de la factura en UTILIA OS.

userIdqueryobligatorio

externalId del usuario propietario.

Además de los campos de la respuesta del alta, el detalle trae:

lines[].exemptionReasonenum | nullobligatorio

Causa de la exención de la línea, o nulo si no está exenta. EXEMPT_IGIC_SMALL_BUSINESS es el régimen del pequeño empresario del IGIC.

lines[].exemptbooleanobligatorio

true en líneas exentas o no sujetas, que no repercuten cuota. Úsalo en lugar de taxRate: un tipo cero no es una exención.

lines[].vatRateClass / lines[].ossSupplyTypeenum | nullobligatorio

Solo en líneas EU_VAT de la ventanilla única: clase del tipo y servicios o bienes. En ellas, taxRate es el tipo del país del consumidor congelado al emitir. Nulos en el resto.

taxes[].vatRateClassenum | nullobligatorio

Solo en tramos EU_VAT: clase del tipo del tramo. Nulo en el resto.

rectificationsarrayobligatorio

Rectificativas de la factura, de la más antigua a la más reciente, con id, invoiceNumber, displayNumber (el número impreso, con guion entre el año y el número de orden), issueDate, totalAmount (negativo), rectificationCode y status. Vacía si no tiene o si el documento es a su vez una rectificativa.

effectiveTotalnumber

Total vigente: el de la factura más el de sus rectificativas emitidas, que restan. Solo en facturas que no son rectificativas ni abonos.

rectificationCodeenum

Solo en rectificativas y abonos: R1, R2, R3, R4 o R5. Las que emite la API externa son R1 o R5.

rectificationTypeenum

Solo en rectificativas y abonos: DIFFERENCE (por diferencias) o COMPLETE (sustitución, solo desde UTILIA OS).

En una simplificada sin destinatario, recipientName es «Consumidor final» y la dirección, la ciudad y el código postal llegan con un guion.

Errores del detalle

• 403 INSUFFICIENT_SCOPE: la aplicación no tiene concedido crm:invoices:read.
• 404 EXTERNAL_USER_NOT_FOUND: no hay ningún usuario de la aplicación con ese userId.
• 404 INVOICE_NOT_ACCESSIBLE: la factura no existe, es de otra aplicación o no es de ese usuario. Es siempre la misma respuesta, para no revelar si la factura existe.

Descargar PDF

Parámetros

idpathobligatorio

Identificador de la factura.

userIdqueryobligatorio

externalId del usuario propietario.

Devuelve el binario con Content-Type: application/pdf y Content-Disposition: attachment; filename="factura-...pdf".

Anular factura

Anular es para una factura que no debió emitirse (un duplicado, un error). Si la venta existió y devuelves el dinero, no la anules: emite una rectificativa.

Cuerpo

reasonstring

Motivo de la anulación. Se guarda en las notas internas de la factura.

userId (el externalId del propietario) va como parámetro de consulta, igual que en el detalle.

Errores de la anulación

• 403 INSUFFICIENT_SCOPE: la aplicación no tiene concedido crm:invoices:cancel.
• 409 INVOICE_STATE_INVALID: no se pueden anular borradores.
• 409 INVOICE_ALREADY_CANCELLED: ya estaba anulada.
• 409 BILLING_IDEMPOTENCY_CONFLICT: la emisión sigue en curso (repite la anulación en unos segundos), su cierre fiscal se interrumpió y tu equipo tiene que darla por revisada antes (ver Estado de la emisión) o una anulación anterior aún no ha terminado. Un correo o un cobro del alta que no salieron no impiden anularla.

Estadísticas del usuario

Parámetros de consulta

userIdstringobligatorio

externalId del usuario.

Respuesta (200)

{
  "total": 12,
  "paid": 8,
  "pending": 3,
  "overdue": 1,
  "totalAmount": 641.40,
  "totalPaid": 427.60,
  "totalPending": 213.80,
  "currency": "eur"
}

totalnumberobligatorio

Total de facturas emitidas a ese usuario externo.

paidnumberobligatorio

Facturas en estado PAID.

pendingnumberobligatorio

Facturas en estado ISSUED, SENT o PARTIALLY_PAID.

overduenumberobligatorio

Facturas en estado OVERDUE.

totalAmountnumberobligatorio

Suma del importe total facturado.

totalPaidnumberobligatorio

Suma del importe ya cobrado.

totalPendingnumberobligatorio

Diferencia entre lo facturado y lo cobrado (nunca negativa).

currencystringobligatorio

Divisa de tu organización en minúsculas (por ejemplo, eur).

Cabeceras comunes

X-Api-Keyheaderobligatorio

Clave de API de la aplicación externa.

X-Request-Idheader

Identificador para seguir la petición; UTILIA OS lo devuelve en la respuesta.

Content-Typeheaderobligatorio

application/json en las peticiones con cuerpo.

Límite de uso

Todos los endpoints de este grupo comparten un límite de 60 peticiones por minuto por clave, además del límite general de la clave (1.000 peticiones por hora). Al superarlo, la respuesta es 429 Too Many Requests con la cabecera Retry-After, que indica los segundos que hay que esperar.

Siguiente paso

• Acciones sobre una facturaEnviar, cobrar, marcar pagada, devolver y enlace público.
• Facturas rectificativasDocumentar una devolución o un contracargo que deja la venta sin efecto.
• SuscripcionesCuotas que se generan, envían y cobran solas cada periodo.
• Guía de facturaciónEl recorrido completo, del alta del usuario al cobro recurrente.