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>

Se aceptan dos tipos de token, y ambos resuelven la misma identidad — un usuario actuando dentro de una empresa:

• Tokens de API — tokens UUID de larga duración pensados para integraciones, scripts y clientes MCP. No caducan; siguen siendo válidos hasta que los eliminas. Es lo que debes usar para cualquier cosa que se ejecute fuera del navegador.
• Tokens de sesión (JWT) — tokens de corta duración (24 h) que se emiten a la aplicación web cuando un usuario inicia sesión. Útiles para hacer scripting contra tu propia sesión, pero no pensados para integraciones permanentes.

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

Crear un token de API

Los tokens de API se gestionan dentro de tu empresa. Con una sesión autenticada existente, crea uno con:

curl -X POST https://api.uninvoice.app/v1/companies/current/api-tokens \
  -H "Authorization: Bearer <token-de-sesión>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Integración de contabilidad"}'

La respuesta devuelve el registro del token:

{
  "id": "3f2b1c9a-...-a1b2c3d4e5f6",
  "description": "Integración de contabilidad",
  "createdAt": "2026-07-03T10:00:00Z"
}

El id es el valor del token — envíalo como credencial Bearer en las peticiones siguientes. Guárdalo de forma segura; trátalo como una contraseña.

Lista y revoca tokens con:

• GET /v1/companies/current/api-tokens — lista los tokens activos (solo metadatos; el valor solo se muestra una vez, al crearlo).
• DELETE /v1/companies/current/api-tokens/{token_id} — revoca un token.

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.

Convenciones

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) y not_available (la cuenta está fuera de la lista de disponibilidad actual).

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. Las operaciones de cuenta y facturación propias de la aplicación web — inicio de sesión, cambio de empresa, suscripciones, recargas de puntos, aceptación legal y la función de administración «shadow user» — no forman parte de la superficie de integración y solo se documentan donde es relevante.

Continúa en la Referencia de endpoints.