# Referencia de endpoints

La referencia completa y siempre actualizada se genera a partir de la especificación OpenAPI de la API en funcionamiento:

- **[Abrir la referencia interactiva →](https://docs.uninvoice.app/es/api/)**: todos los endpoints, parámetros, peticiones y respuestas, navegables y con búsqueda (Redoc).
- **[Descargar la especificación OpenAPI (JSON) →](https://docs.uninvoice.app/es/openapi.json)**: la especificación en crudo, para importar en Postman/Insomnia, generar un cliente o alimentar tus propias herramientas.

Como se genera directamente desde el backend en ejecución, nunca se desincroniza de la API real. Todas las rutas son relativas a la [URL base](https://docs.uninvoice.app/es/api/overview#url-base) y requieren un [token Bearer](https://docs.uninvoice.app/es/api/overview#autenticaci%C3%B3n); los importes van en [céntimos](https://docs.uninvoice.app/es/api/overview#importes) y los nombres de campo son `snake_case`.

## 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`: asigna el número de factura y, para emisores españoles, la comunica a la AEAT.
5. **Descarga el PDF** con `GET /v1/invoices/{id}/pdf`.

> **Si estás establecido en España**
>
> La emisión está bloqueada hasta que tu autorización Veri\*Factu esté **en vigor**: un documento de autorización firmado que haya superado nuestras comprobaciones (la vía habitual), o bien un _apoderamiento_ otorgado ante la AEAT **y confirmado por ella** (se comprueba una vez al día: confirmar el otorgamiento en la app no levanta el bloqueo por sí solo). Hasta entonces la factura sigue siendo un borrador y `issue` devuelve `403` con `error: "verifactu_authorization_required"`. Consulta la [guía de Veri\*Factu](https://docs.uninvoice.app/es/verifactu/overview).

Las mutaciones de una IA se retienen para aprobación

Una petición mutante realizada con un token de API que **no** presenta una cabecera `X-Human-Proof` válida no se ejecuta: se registra para revisión humana y devuelve `202 pending_approval`. Después, una persona la aprueba (la reejecuta) o la rechaza. Consulta la [guía de Auditoría de IA](https://docs.uninvoice.app/es/api/ai-audit).