Auditoría IA

uninvoice.app lo manejan personas (la aplicación web, mediante una sesión de navegador) e IAs (un agente de IA usando el servidor MCP, o la API HTTP con un token de API). Como las facturas tienen valor legal, uninvoice.app nunca deja que una IA modifique tus datos por su cuenta: cada acción de escritura que solicita una IA se intercepta antes de que surta efecto, se registra para su revisión y queda retenida hasta que una persona la aprueba o la rechaza.

Esta barrera se llama Auditoría IA. Revisas la cola en la página Auditoría IA de la aplicación web, o desde la CLI.

Cómo funciona

Un llamante de IA envía una petición de escritura (crear una factura, emitirla, crear un gasto, eliminar una proforma, …).
En lugar de ejecutarse, la petición se registra como una entrada de Auditoría IA pendiente que captura quién la pidió, la acción y la carga útil exacta. La API responde 202 Accepted y la acción no se ejecuta.
Una persona abre la cola de Auditoría IA y:
- la aprueba — la petición original se reproduce exactamente como se capturó y por fin surte efecto, o
- la rechaza — no se ejecuta nada y la entrada se cierra.

Las lecturas (GET) nunca se retienen — solo POST, PUT, PATCH y DELETE.

Quién cuenta como IA

Que una petición se retenga depende de quién la maneja, no del endpoint:

Llamante	Se trata como	¿Retenido?
Aplicación web (sesión de navegador)	Persona	No — se ejecuta al momento
Token de API sin una cabecera `X-Human-Proof` válida	IA	Sí — las escrituras quedan a la espera de aprobación
Token de API con una cabecera `X-Human-Proof` válida	Persona	No — se ejecuta al momento
Servidor MCP	IA	Sí, siempre — las herramientas de escritura quedan a la espera de aprobación

Así, el mismo token de API puede actuar como persona o como IA petición a petición, según presente o no la cabecera X-Human-Proof (consulta Hacer que un token actúe como persona más abajo). El servidor MCP se trata siempre como una IA y no puede salir de la barrera.

La respuesta `202 pending_approval`

Cuando se captura una petición de escritura de IA, la API devuelve 202 Accepted con un cuerpo JSON en lugar del resultado normal. El handler nunca se ejecuta:

{
  "status": "pending_approval",
  "auditId": "a1b2c3d4-5e6f-4a7b-8c9d-ef0123456789",
  "action": "invoice.create",
  "message": "This action was recorded for human review and has NOT been applied. A person must approve it in the uninvoice.app audit log before it takes effect."
}

Tu integración debe tratar 202 pending_approval como «aún no hecho»: guarda el auditId y sondea la entrada (o vigila la página de Auditoría IA) hasta que pase a approved (con un resourceId) o a rejected.

action es una etiqueta lógica estable de la petición capturada, por ejemplo invoice.create, invoice.issue, invoice.correct, proforma.create, proforma.promote, expense.create, entity.create, entity.update, company.update o apiToken.create.

Revisar la cola

Estos endpoints exponen la cola y permiten a una persona resolver entradas. Son los únicos endpoints que nunca se retienen — y solo puede manejarlos una persona (una sesión web, o un token de API que presenta un X-Human-Proof válido; ver abajo). Un llamante de IA no puede aprobar sus propias peticiones.

Método	Ruta	Descripción
`GET`	`/v1/ai-audit`	Lista las entradas capturadas. Filtra con `?status=pending\|approved\|rejected\|failed`.
`GET`	`/v1/ai-audit/{id}`	Obtiene una entrada concreta.
`POST`	`/v1/ai-audit/{id}/approve`	Aprueba y reproduce la petición capturada.
`POST`	`/v1/ai-audit/{id}/reject`	Rechaza la entrada; no se ejecuta nada.

Una entrada tiene un status de pending, approved, rejected o failed (una acción aprobada cuya reproducción encontró un error de negocio, p. ej. un requisito de autorización Veri*Factu). Si tiene éxito, resourceId apunta al recurso que la reproducción creó o modificó.

Aprobar una entrada

curl -X POST https://api.uninvoice.app/v1/ai-audit/<id-de-auditoria>/approve \
  -H "Authorization: Bearer <token>" \
  -H "X-Human-Proof: <human-proof>"

Hacer que un token actúe como persona

No toda automatización debe pasar por la cola de revisión. Un script supervisado, una tarea de back-office o una persona ejecutando la CLI ya son «una persona al mando» — deberían ejecutarse al momento. Para afirmarlo, presenta la prueba humana (human proof) del token.

Al crear un token eliges su tipo. Una clave API estándar se crea con un secreto acompañante, su prueba humana, devuelto una sola vez al crearla. (Una clave API para MCP es manejada por IA por diseño: se crea sin prueba humana — nunca se guarda ninguna — así que nunca puede salir de la barrera y cada escritura que hace está siempre retenida. Elige una clave estándar si necesitas presentar prueba humana.)

La prueba humana se devuelve una sola vez, al crearla:

{
  "id": "9b1f7c2a-3d4e-4f5a-8b6c-1d2e3f4a5b6c",
  "humanProof": "7c4a8d09-1e2f-4b3c-9a8d-0f1e2d3c4b5a",
  "createdAt": "2026-07-14T10:00:00Z"
}

Guarda humanProof junto al token — igual que el token, solo se muestra al crearlo y nunca más. Después, en cualquier petición que quieras ejecutar sin auditoría, añádelo como cabecera:

Authorization: Bearer <token-de-api>
X-Human-Proof: <human-proof>

Con un X-Human-Proof que coincide, la petición se trata como manejada por una persona: se ejecuta al momento y nunca se audita. Presentarlo también permite al token revisar la cola (aprobar/rechazar) vía API o CLI. Omítelo — o envía un valor incorrecto — y el token vuelve a tratarse como una IA, así que sus escrituras quedan a la espera de aprobación.

Para crear un token mediante la API, haz POST /v1/companies/current/api-tokens con {"mcp": true} para una clave MCP manejada por IA (sin prueba humana), u omite mcp (o envía false) para una clave estándar que devuelve humanProof.

La prueba humana omite la Auditoría IA

Presentar un X-Human-Proof válido omite efectivamente la barrera de Auditoría IA para esa petición. Añádelo solo a automatizaciones que una persona supervise de verdad, y protégelo con el mismo cuidado que el propio token. Los tokens creados antes de que existiera la Auditoría IA no tienen prueba humana y, por tanto, se tratan siempre como IAs — crea un token nuevo si necesitas uno que pueda presentar prueba humana.

Desde la CLI

La uninvoice.app-cli revisa la cola directamente:

uninvoice.app-cli ai-audit list
uninvoice.app-cli ai-audit approve <id>
uninvoice.app-cli ai-audit reject  <id>

La CLI pasa su prueba humana (mediante --human-proof o la variable de entorno UNINVOICE_HUMAN_PROOF) como la cabecera X-Human-Proof, de modo que una persona que ejecuta la CLI se trata como persona y puede revisar las acciones que las IAs han encolado.

Cómo funciona​

Quién cuenta como IA​

La respuesta 202 pending_approval​

Revisar la cola​

Hacer que un token actúe como persona​

Desde la CLI​