# 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](https://docs.uninvoice.app/es/api/reference)**. Si controlas la API desde un agente de IA, consulta el **[servidor MCP](https://docs.uninvoice.app/es/api/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](https://app.uninvoice.app/company#api-keys)** 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](https://docs.uninvoice.app/es/api/ai-audit)**, 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](https://docs.uninvoice.app/es/api/ai-audit)** 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` (autoriza antes a uninvoice.app para [Veri\*Factu](https://docs.uninvoice.app/es/verifactu/authorize)).

## 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](https://docs.uninvoice.app/es/api/reference)**.