La API HTTP

uninvoice.app ofrece una API HTTP para que puedas crear entidades (clientes y proveedores), preparar y emitir facturas, descargar sus PDF y leer la configuración de tu empresa desde tus propias herramientas e integraciones. Es la misma API que utiliza la aplicación web.

Esta sección cubre la autenticación y las convenciones comunes a todos los endpoints. La lista completa está en la Referencia de endpoints. Si controlas la API desde un agente de IA, consulta el servidor MCP, que expone las mismas operaciones a través del Model Context Protocol.

URL base

La API está versionada bajo /v1:

Entorno	URL base
Producción	https://api.uninvoice.app

Cada ruta de la referencia es relativa a esta base, por ejemplo GET /v1/invoices.

Autenticación

Todas las peticiones se autentican con un token Bearer en la cabecera Authorization:

Authorization: Bearer <token>

El token es un token de API: un UUID de larga duración que identifica a un usuario actuando dentro de una empresa. Los tokens de API no caducan; siguen siendo válidos hasta que los eliminas. Usa uno para cualquier cosa que se ejecute fuera del navegador: integraciones, scripts y clientes MCP.

Las peticiones sin token, con un token desconocido o con un token eliminado reciben 401 Unauthorized.

Crear un token de API

Crea y gestiona tus tokens de API desde la sección Empresa de tu configuración en la aplicación web. Ahí puedes emitir un nuevo token, darle una descripción, ver los tokens ya activos y revocar los que ya no necesites.

El valor de un token se muestra una sola vez, al crearlo: cópialo entonces y guárdalo de forma segura; trátalo como una contraseña. Tiene la forma 3f2b1c9a-...-a1b2c3d4e5f6; envíalo como credencial Bearer en cada petición.

Un token está limitado a un usuario dentro de una empresa. Cada llamada que hace actúa como ese usuario en esa empresa; un token de API no puede cambiar de empresa.

Actuar como persona o como IA

Por defecto un token de API se trata como una IA: sus peticiones de escritura (crear o emitir una factura, eliminar una proforma, …) no se ejecutan al momento: quedan retenidas para que una persona las apruebe mediante Auditoría IA, y la API responde 202 pending_approval.

Al crear un token estándar también recibes un secreto de un solo uso, la prueba humana (humanProof). Presentarlo en la cabecera X-Human-Proof afirma que una persona maneja la petición, de modo que se ejecuta al momento y no se audita. Úsalo para automatizaciones que una persona supervise de verdad. Un token creado para un cliente MCP es manejado por IA y no recibe prueba humana, así que siempre pasa por la barrera. Consulta Auditoría IA para el flujo completo.

Convenciones que siguen todos los endpoints

Estas convenciones se aplican a todos los endpoints.

JSON

Las peticiones y respuestas son JSON. Los nombres de campo usan snake_case (p. ej. recipient_id, unit_price), salvo un pequeño conjunto de campos de metadatos explícitamente en camelCase (p. ej. createdAt).

Importes

Los importes monetarios son enteros en la unidad mínima de la moneda (céntimos), nunca decimales. unit_price, subtotal, tax_amount y el total de la factura están todos en céntimos. Por ejemplo, 1.250,00 € es 125000. Las monedas son códigos ISO 4217 (currency_code, p. ej. EUR).

Fechas y horas

Las marcas de tiempo siguen RFC 3339 / ISO 8601 en UTC (p. ej. 2026-07-03T10:00:00Z).

Errores

Los errores usan códigos de estado HTTP estándar. La mayoría llevan un cuerpo de texto plano:

Estado	Significado
400 Bad Request	La petición es incorrecta o incumple una regla de negocio. El cuerpo describe qué corregir.
401 Unauthorized	Token ausente, inválido o revocado.
403 Forbidden	Autenticado, pero sin permiso para esta acción.
404 Not Found	El recurso no existe o no es visible para tu empresa.
500 Internal Server Error	Error inesperado del servidor.

Algunas respuestas 403 que requieren una acción concreta devuelven un cuerpo JSON con un código error legible por máquina y un message para humanos, por ejemplo:

{
  "error": "verifactu_authorization_required",
  "message": "You must authorize uninvoice.app to report on your behalf before issuing invoices.",
  "requiresAuthorizationUrl": "/verifactu/authorization"
}

Códigos que puedes encontrar: company_not_settled (completa antes el alta de la empresa), agreement_required (acepta antes los términos legales vigentes), verifactu_authorization_required (otorga antes el apoderamiento Veri*Factu).

Qué puede y qué no puede hacer un token

Un token de API puede leer y escribir los recursos de su empresa: entidades, facturas, proformas, impuestos, configuración de la empresa y el estado de autorización Veri*Factu.

Continúa en la Referencia de endpoints.