# API v1

Base: `https://yorobot.ai`. Autenticación: `Authorization: Bearer <token de API>`, creado en Ajustes → Accesos con uno de estos alcances: `lectura`, `escritura`, `auditoria`, `topes`. La especificación completa está en [/openapi.json](/openapi.json), generada de los mismos esquemas que validan cada pedido.

Respuestas comunes: `401` token inválido o revocado; `403` el token no tiene el alcance, o la organización está en el plan gratis y la persona del token todavía no confirmó su correo (`correo_sin_confirmar: true`: hasta confirmarlo, sólo lectura); `429` demasiados pedidos, con `Retry-After`; `503 esquema_desactualizado` la base está por detrás del código y una migración está en curso.

Toda respuesta trae `X-Request-Id` (búscalo en Accesos → Pedidos o con `listar_pedidos`) y, con un token que autenticó, `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`. Los límites por plan están en [Límites y planes](/docs/limites).

## Para un dashboard propio

MCP es para configurar y construir; para **mostrar** en una pantalla tuya, la API y los webhooks. Con un token de `lectura`: `GET /api/v1/tickets` (las tareas, con cursor), `GET /api/v1/agentes/{id}/metricas`, `GET /api/v1/agentes/{id}/actividad`, `GET /api/v1/conversaciones` y `GET /api/v1/aprobaciones`. Ven sólo lo que ve la persona del token (si su membresía está acotada a algunos agentes, esos), y un id de otra organización da `404`, igual que uno inexistente.

Para una **tarjeta por agente** (lo que muestra Che Tienda): `GET /api/v1/agentes` trae de cada uno la última actividad, el gasto del mes, su tope, si hoy frena (`bloqueado`), cuánto espera tu firma (`te_esperan`) y `portal_url`; `GET /api/v1/agentes/{id}` agrega el gasto contra su tope y el de la organización, cómo le fue en 30 días y `esperan_tu_firma` con su `aprobar_en`; `GET /api/v1/aprobaciones?agente=<id>` filtra la cola; `GET /api/v1/membresia` dice el plan y si hay algo que pagar. El tope del mes de un agente se fija con `PUT /api/v1/agentes/{id}/tope` (alcance `topes` o `escritura`; por MCP, `fijar_tope_de_agente`): cuando su gasto del mes llega ahí, sus tareas nuevas frenan igual que con el tope de la organización, y nunca puede ser mayor que el de la organización. Un error ahí trae `error` (un código) y `mensaje` (el texto para la persona).

Cada respuesta trae `contexto` —organización, `hoy`, `zona_horaria`, moneda—; las fechas en ISO UTC y, al lado, `*_local` en la zona de la organización; la etiqueta que muestra el portal junto a cada valor (`estado_texto`, `veredicto_texto`, `clase_texto`…) y booleanos que no admiten lectura (`terminada`, `verificada`, `espera_persona`, `discrepancia`). Si una lista está recortada, `total`, `recortado` y `aviso` lo dicen en el dato: para contar usá `total`, no el largo de la lista. Para enterarte sin preguntar: los webhooks `aprobacion.pendiente`, `conversacion.mensaje` y `tarea.terminada`. Nada de esto aprueba: lo irreversible lo decide una persona en el portal (`aprobar_en`).

## Endpoints

| Método | Ruta | Alcance | Qué hace |
|---|---|---|---|
| `GET` | `/api/v1/agentes` | lectura | Los agentes de la organización |
| `GET` | `/api/v1/agentes/{id}` | lectura | Un agente: gasto contra su tope, 30 días y lo que espera tu firma |
| `PUT` | `/api/v1/agentes/{id}/tope` | topes o escritura | Fijar o sacar el tope de gasto del mes de un agente |
| `GET` | `/api/v1/membresia` | lectura | La membresía de la organización y si hay algo que pagar |
| `POST` | `/api/v1/agentes/{id}/tareas` | escritura | Pedirle una tarea a un agente |
| `POST` | `/api/v1/agentes/{id}/charla` | escritura | Preguntarle a un agente de lectura, con cita |
| `GET` | `/api/v1/agentes/{id}/charla` | lectura | Cuánto le queda hoy al sujeto para charlar |
| `POST` | `/api/v1/agentes/{id}/charla/reportar` | escritura | Reportar una conversación para que la revisemos |
| `GET` | `/api/v1/consolas` | lectura | Las consolas publicadas y su URL de puesto |
| `POST` | `/api/v1/tickets` | escritura | Crear una tarea de desarrollo en un proyecto |
| `GET` | `/api/v1/tickets/{id}` | lectura | Estado de una tarea |
| `GET` | `/api/v1/tickets` | lectura | Las tareas de la organización, con cursor |
| `GET` | `/api/v1/agentes/{id}/metricas` | lectura | Cómo viene trabajando un agente, y cada versión |
| `GET` | `/api/v1/agentes/{id}/actividad` | lectura | Todo lo que hizo un agente, paginado |
| `GET` | `/api/v1/conversaciones` | lectura | Las conversaciones de los canales |
| `GET` | `/api/v1/conversaciones/{id}` | lectura | Una conversación con sus mensajes |
| `GET` | `/api/v1/aprobaciones` | lectura | Lo que espera la aprobación de una persona |
| `POST` | `/api/v1/tickets/{id}/cancel` | escritura | Cancelar una tarea que todavía no terminó |
| `POST` | `/api/v1/tickets/{id}/messages` | escritura | Mandarle un mensaje al agente sobre una tarea |
| `POST` | `/api/v1/cerebro/transcripciones` | escritura | Cargar la transcripción de una call al Cerebro |
| `GET` | `/api/v1/cerebro/colecciones` | lectura | Las colecciones del Cerebro |
| `POST` | `/api/v1/cerebro/colecciones` | escritura | Crear una colección del Cerebro |
| `POST` | `/api/v1/cerebro/lote` | escritura | Cargar documentos al Cerebro, hasta 20 por pedido |
| `POST` | `/api/v1/triajes` | escritura | Pedir un triaje por el método (Manchester) |
| `GET` | `/api/v1/triajes/{id}` | lectura | Estado y firma de un triaje |
| `POST` | `/api/v1/inferencias` | escritura | Una inferencia por propósito declarado |
| `GET` | `/api/v1/inferencias` | lectura | Los propósitos de inferencia disponibles |
| `GET` | `/api/v1/usage` | lectura | Consumo del mes contra el tope |
| `GET` | `/api/v1/webhooks` | lectura | Los webhooks configurados y los eventos que aceptan |
| `GET` | `/api/v1/webhooks/{id}/entregas` | lectura | Las entregas de un webhook, de la más nueva a la más vieja |
| `GET` | `/api/v1/webhooks/entregas/{entregaId}` | lectura | Una entrega con su cuerpo crudo, una firma fresca y el `curl` para reproducirla |
| `POST` | `/api/v1/webhooks/entregas/{entregaId}/reenviar` | escritura | Reenviar una entrega ahora, con el mismo sobre |
| `POST` | `/api/v1/webhooks/{id}/prueba` | escritura | Mandar un aviso de prueba firmado a un webhook |
| `DELETE` | `/api/v1/vinculos/{id}` | lectura | Dar de baja una aplicación conectada, desde la app |
| `GET` | `/api/v1/auditoria` | auditoria | La bitácora en NDJSON para el SIEM |
| `POST` | `/api/v1/automatizaciones/{id}/disparar` | escritura | Disparar una automatización ahora |
| `POST` | `/api/v1/rutinas/{id}/disparar` | escritura | Alias de `/automatizaciones/{id}/disparar` |
| `GET` | `/api/v1/peones` | lectura | Alias de `/agentes` |
| `POST` | `/api/v1/peones/{id}/tareas` | escritura | Alias de `/agentes/{id}/tareas` |

## `GET /api/v1/agentes`

_alcance: lectura_

Los que ve la persona del token (si su membresía está acotada a algunos agentes, esos), con `total` y `contexto`. Cada uno con id, nombre, oficio, si está activo, en qué ambientes tiene versión publicada, la entrada que espera y sus herramientas; y para una tarjeta: `ultima_actividad` (ISO o `null`) con `ultima_actividad_local`, `gasto_mes_usd` (mes calendario UTC, la misma cuenta que el tope de la organización), `tope_mes_usd` (o `null` si no tiene tope propio), `bloqueado` (sus tareas nuevas frenan hoy por plata) con `bloqueado_texto`, `te_esperan` (aprobaciones pendientes) y `portal_url`. Es por dónde se empieza: el resto pide un `id` de acá.

## `GET /api/v1/agentes/{id}`

_alcance: lectura_

`gasto`: `mes_usd` y `hoy_usd` (el mes calendario UTC y el día en la zona de la organización, como los topes de la organización), `tope_mes_usd` y `porciento` (`null` sin tope propio), `bloqueado` con `bloqueado_por` (`agente` u `organizacion`) y `bloqueado_texto`, y `tope_organizacion_mes_usd` (`null` si la organización no tiene tope). `tareas_30_dias`: total, verificadas, `a_la_primera_texto` y discrepancias (lo mismo que `/metricas`). `esperan_tu_firma`: cada tarea con `por_que`, costo, `creada`/`creada_local` y `aprobar_en` (se aprueba en el portal). Otra organización, inexistente o fuera del recorte: 404.

## `PUT /api/v1/agentes/{id}/tope`

_alcance: topes o escritura_

Con `topes` (el alcance de una aplicación conectada, que no sirve para nada más) o `escritura`. Cuando el gasto del mes del agente llega al tope, sus tareas nuevas frenan igual que con el tope de la organización; los demás siguen. No puede ser mayor que el tope mensual de la organización. Ponerle uno o bajarlo lo hace quien opera el agente; subirlo o sacarlo (`null`), un técnico o un admin. Contesta `{ contexto, gasto }` con la forma de `GET /agentes/{id}`. Si falla después del token: `{ error, mensaje }` — `error` es un código (`cuerpo_invalido`, `tope_invalido`, `supera_el_tope_de_la_organizacion`, `sin_permiso`) y `mensaje` el texto para la persona; 404 (`no_existe`) si el agente no está a su alcance, 422 lo demás. Queda en la auditoría a nombre de la persona del token, con la aplicación conectada si es de un vínculo («vía Che Tienda»).

| Campo | Tipo | Qué es |
|---|---|---|
| `tope_mes_usd` **(requerido)** | number o null | El tope de gasto del MES de este agente, en USD, mayor que cero y no mayor que el tope mensual de la organización. `null` lo saca: manda sólo el de la organización. |

## `GET /api/v1/membresia`

_alcance: lectura_

`plan` (la clave) y `plan_texto` (la palabra del portal), `estado`, `hay_que_pagar`, `vence` y `pagar_en`. Mientras YoRobot no cobre por la web: `estado: "sin_facturacion"`, `pagar_en: null` y `hay_que_pagar: false`. `mensaje` es el texto para la persona.

## `POST /api/v1/agentes/{id}/tareas`

_alcance: escritura_

Encola una tarea con la entrada declarada. Responde 201 con `id`, `estado` y `ambiente`; el resultado llega por webhook (`tarea.terminada`) o con `GET /api/v1/tickets/{id}`. La tarea nace con el presupuesto y los límites del agente; lo irreversible espera aprobación de una persona.

| Campo | Tipo | Qué es |
|---|---|---|
| `entrada` | object | Los campos que el agente declara como entrada. Vacío si no pide ninguno. Por defecto `{}`. |
| `ambiente` | `dev` · `staging` · `prod` | Contra qué versión corre. Si falta, vale la cabecera `X-YoRobot-Ambiente`, y si tampoco está, `dev` — a propósito: la primera prueba de una integración no le pega al sistema real. Si cuerpo y cabecera se contradicen, 403. |
| `titulo` | string | Cómo se va a ver la tarea en la lista. Si falta, se arma con el nombre del agente. |

## `POST /api/v1/agentes/{id}/charla`

_alcance: escritura_ · responde `application/x-ndjson`

NDJSON, un objeto por línea con `t`: `leyendo` (qué herramienta está leyendo), y al final `fin` (la respuesta entera y las lecturas para mandar en el turno siguiente) o `error`. Pide `escritura` porque gasta modelo aunque no cree una tarea. El agente sólo lee; una respuesta sin cita textual sale advertida. Cuenta contra el tope diario del `sujeto`. Si sus lecturas usan la credencial del cliente, la contesta el worker sin contenedor y el `fin` trae `via: "worker"` y `consulta_id` (y `requiere_tarea` si pidió algo que escribe, que no se hace); un agente que también escribe entra por ahí sólo con `solo_lectura: true`.

| Campo | Tipo | Qué es |
|---|---|---|
| `historia` **(requerido)** | array | La conversación completa. El último turno de persona es la pregunta. |
| `fijos` | object | Parámetros que el servidor pone en cada llamada a una herramienta. El modelo no los ve ni los cambia. Por defecto `{}`. |
| `sujeto` | string | De parte de quién se pregunta. El tope diario se cuenta contra esto; si falta, contra el agente entero. |
| `lecturas_previas` | array | Lo leído en turnos anteriores de ESTA conversación, tal como lo devolvió el evento fin. Lo guarda quien llama. Por defecto `[]`. |
| `solo_lectura` | boolean | Contestar sólo con las lecturas del agente aunque también tenga herramientas que escriben. Si el modelo pide una que escribe, no se ejecuta y la respuesta trae requiere_tarea. |

## `GET /api/v1/agentes/{id}/charla`

_alcance: lectura_

El tope diario de la charla para el `sujeto` (o el agente si no se pasa): `usadoUsd`, `topeUsd`, `porciento` y `bloqueado`.

| Parámetro | Qué es |
|---|---|
| `sujeto` | Quién pregunta (para el tope por persona). Si falta, el tope es del agente. |
| `consulta` | El `consulta_id` de una charla que contestó el worker: devuelve cómo va y la respuesta, en vez del tope. |

## `POST /api/v1/agentes/{id}/charla/reportar`

_alcance: escritura_

`POST /charla` no guarda nada a propósito. Esto guarda UNA conversación —los turnos y las lecturas con sus argumentos— cuando una persona aprieta «esto salió mal». No es una grabación: es lo único que después permite leer dónde falló. Pide `escritura` porque deja rastro, aunque no gaste modelo.

| Campo | Tipo | Qué es |
|---|---|---|
| `turnos` **(requerido)** | array | La conversación que salió mal, completa. |
| `lecturas` | array | Las lecturas de esa conversación con sus argumentos: es lo que permite ver con qué datos contestó. Por defecto `[]`. |
| `sujeto` | string | De parte de quién se conversaba. Es lo que después permite filtrar por empresa. |
| `nota` | string | Lo que la persona quiera aclarar sobre qué salió mal. |

## `GET /api/v1/consolas`

_alcance: lectura_

Las consolas publicadas y su URL de puesto

## `POST /api/v1/tickets`

_alcance: escritura_

Para el oficio programador: la tarea corre contra el repositorio del proyecto, el verificador relee en limpio y una persona aprueba el resultado.

| Campo | Tipo | Qué es |
|---|---|---|
| `projectId` **(requerido)** | string | El proyecto (repositorio) al que pertenece. |
| `title` **(requerido)** | string | Título corto. |
| `description` | string | Qué hay que hacer, en detalle. |
| `budgetUsd` | number | Presupuesto duro en USD para esta tarea. Si falta, el del proyecto. |

## `GET /api/v1/tickets/{id}`

_alcance: lectura_

Estado, costo en USD, verificación independiente y si espera aprobación. El claim del agente nunca es la verdad: mirá `verificacion`.

## `GET /api/v1/tickets`

_alcance: lectura_

De la más nueva a la más vieja, sólo las de los agentes a los que llega la persona del token. Cada tarea trae `estado_texto` y `veredicto_texto` (las palabras del portal) y booleanos sin interpretación: `terminada`, `verificada`, `espera_persona`, `discrepancia`; `creada` en UTC y `creada_local` en la zona de la organización; `costo_usd` suma todos los intentos. `total` cuenta todo lo que coincide con el filtro; si hay más, `siguiente` es el cursor y `aviso` lo dice.

| Parámetro | Qué es |
|---|---|
| `agente` | Id del agente (de `GET /agentes`). Uno fuera de tu alcance da 404. |
| `estado` | Un estado de tarea (`needs_human`, `verified`, `running`…). |
| `desde` | Creadas desde este instante ISO, inclusive. |
| `hasta` | Creadas antes de este instante ISO. |
| `limite` | Cuántas por página, de 1 a 100 (50 por defecto). |
| `cursor` | El `siguiente` de la página anterior, tal cual. |

## `GET /api/v1/agentes/{id}/metricas`

_alcance: lectura_

`ventana`: tareas, `verificadas` (las que la verificación ya midió: el denominador), `a_la_primera` con su tasa y su texto («3 de 5 verificadas»), `discrepancias`, `te_esperan`, costo y duración mediana ya formateados, y `por_dia` (días UTC, con cero los días sin trabajo). `ultimas_tareas` con el veredicto en palabras. `versiones`: por versión, tareas, `pasaron_la_verificacion`, discrepancias, `rechazadas_o_escaladas`, costo y ensayo; cada tasa con su denominador. Todo con `contexto` (organización, hoy y zona).

| Parámetro | Qué es |
|---|---|
| `dias` | La ventana, de 1 a 90 días (30 por defecto). |

## `GET /api/v1/agentes/{id}/actividad`

_alcance: lectura_

Tareas, llamadas al modelo, herramientas, frenos, verificaciones, esperas, mensajes, llamadas y registros, de lo más nuevo a lo más viejo, cada hecho con `clase_texto`, `salio_mal` y `espera_a_una_persona`. Para leer en vivo, mandá en `desde` el `mas_nuevo` de la respuesta anterior. El flujo se lee con un tope de 500 hechos: `total_es_exacto`, `recortado` y `aviso` lo dicen en el dato.

| Parámetro | Qué es |
|---|---|
| `desde` | Sólo lo posterior a este instante ISO (el cursor del flujo en vivo). |
| `pagina` | Página, desde 1. |
| `limite` | Hechos por página, de 1 a 100 (50 por defecto). |
| `clase` | Filtrar por clase: `tarea`, `herramienta`, `freno`, `mensaje`, `llamada`, `registro`… (separadas por coma). |
| `solo_errores` | `true` para ver sólo lo que salió mal. |

## `GET /api/v1/conversaciones`

_alcance: lectura_

Chat, WhatsApp y mensajería, de la del último mensaje más reciente para atrás, sólo de los agentes a los que llega la persona del token. Cada una con `canal_texto`, `abierta`, `mensajes_recibidos`, el resumen del agente y las fechas en UTC y en la zona de la organización. La clave del interlocutor (su teléfono, el id del hilo) no sale.

| Parámetro | Qué es |
|---|---|
| `agente` | Id del agente. |
| `canal` | Id del canal. |
| `estado` | `abierta` o `cerrada`. |
| `pagina` | Página, desde 1. |
| `limite` | Conversaciones por página, de 1 a 100 (50 por defecto). |

## `GET /api/v1/conversaciones/{id}`

_alcance: lectura_

Los turnos en orden: lo que escribió la persona (`persona`), lo que contestó el agente (`agente`, `respondido`) y el estado de la tarea que lo atendió, con la hora en UTC y local. Más lo que el agente ya averiguó (`datos`).

## `GET /api/v1/aprobaciones`

_alcance: lectura_

La misma cola que Aprobaciones del portal, en el mismo orden (discrepancias primero). Cada tarea con `medicion_texto`, `por_que`, lo que dijo el agente, el costo y `aprobar_en`: el enlace al portal. **No se aprueba por API** (`se_aprueba_por_api: false`): lo irreversible lo decide una persona con su sesión. El aviso `aprobacion.pendiente` trae la misma forma.

| Parámetro | Qué es |
|---|---|
| `agente` | Sólo las de este agente (id de `GET /agentes`). Uno fuera de tu alcance da 404. |

## `POST /api/v1/tickets/{id}/cancel`

_alcance: escritura_

Cancelar una tarea que todavía no terminó

## `POST /api/v1/tickets/{id}/messages`

_alcance: escritura_

Mandarle un mensaje al agente sobre una tarea

| Campo | Tipo | Qué es |
|---|---|---|
| `texto` **(requerido)** | string | Lo que se le dice al agente sobre la tarea. |

## `POST /api/v1/cerebro/transcripciones`

_alcance: escritura_

Entra con alcance de agente: sólo la leen los agentes que nombrás. Se publica sola salvo que el escaneo marque un fragmento (queda en borrador para que alguien lo lea). Mandar la misma transcripción dos veces devuelve el documento que ya estaba. Con `rutina`, dispara esa automatización con el documento cargado.

| Campo | Tipo | Qué es |
|---|---|---|
| `titulo` **(requerido)** | string | Cómo se lee en el Cerebro: «Call de discovery — logística». |
| `fecha` **(requerido)** | string | Cuándo fue la call, ISO. |
| `participantes` | array | Quiénes hablaron. Por defecto `[]`. |
| `empresa` | string | La empresa del otro lado, si la hay. Va al índice del Cerebro. |
| `origen` **(requerido)** | string | De dónde sale: fireflies, tldv, zoom, meet, manual. |
| `texto` | string | La transcripción, en texto plano o Markdown. |
| `contenido_base64` | string | En vez de `texto`: el archivo (.pdf, .md o .txt) en base64. |
| `nombre_archivo` | string | Con `contenido_base64`, el nombre con extensión: de ahí sale cómo se extrae el texto. |
| `agentes` **(requerido)** | array | Las claves de los agentes que la pueden leer, y sólo ellos: una call trae nombres y cifras de clientes. |
| `rutina` | string | La clave de la automatización a disparar con la call ya cargada («minar-call»). Tiene que estar prendida. |

## `GET /api/v1/cerebro/colecciones`

_alcance: lectura_

Cada una con su plantilla de corte (`plantilla` y `plantilla_texto`), su alcance y cuántos documentos tiene: `documentos`, `publicados`, `borradores` (los que todavía no ve ninguna corrida) y `fragmentos`.

## `POST /api/v1/cerebro/colecciones`

_alcance: escritura_

Una colección es un conjunto que se sube por lote y se busca adentro: «Contratos de proveedores». Sus documentos heredan el alcance y la plantilla de corte: `clausulas` parte un contrato donde empieza cada cláusula numerada, `filas` una planilla por grupos de filas con el encabezado, `parrafos` todo lo demás. El nombre no se repite en la organización.

| Campo | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Cómo se llama: «Contratos de proveedores». No se repite en la organización. |
| `descripcion` | string | Qué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento. |
| `plantilla` | `parrafos` · `clausulas` · `filas` | Dónde se corta cada documento: `clausulas` (contratos: donde empieza cada cláusula numerada), `filas` (planillas) o `parrafos` (por defecto). |
| `alcance` | `tenant` · `proyecto` · `agente` | Quién lee sus documentos: toda la organización (por defecto), un proyecto o un agente. |
| `proyecto_id` | string | Obligatorio con alcance `proyecto`. |
| `agente_id` | string | Obligatorio con alcance `agente`: el único agente que la lee. |

## `POST /api/v1/cerebro/lote`

_alcance: escritura_

Formulario `multipart/form-data` (`curl -F archivos=@contrato.pdf -F archivos=@otro.pdf -F coleccion=Contratos`). Entran Markdown, texto, PDF con texto y HTML; el cuerpo entero no puede pasar de 4 MB. Cada archivo se procesa solo y la respuesta dice qué pasó con cada uno: `ingerida` (con `publicada` y, si quedó en borrador, `por_que`), `duplicada` (el mismo archivo ya estaba: `documento_id` y en qué colección) o `rechazada` (con `motivo` y `detalle`). Un rechazo no deja nada cargado. Cuenta contra el techo de documentos del plan.

## `POST /api/v1/triajes`

_alcance: escritura_

El agente aporta evidencia y la plataforma calcula el color; la firma la pone una persona en la consola. Idempotente por `idempotencyKey`. Contrato completo en `docs/CONTRATO-TRIAJE.md`.

| Campo | Tipo | Qué es |
|---|---|---|
| `agente` **(requerido)** | string | El agente que atiende el método. Sin default: elegirlo es decisión del cliente. |
| `idempotencyKey` **(requerido)** | string | La acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar. |
| `texto` **(requerido)** | string | Lo que contó la persona, tal cual. No se le pide un color ni una clasificación. |
| `referencia` | string | El id del caso del lado del cliente, para volver a unir las dos mitades. |
| `centro` | string | El centro que atiende, si ya se sabe. Si no, lo reparte una persona. |
| `ambiente` | `dev` · `staging` · `prod` | Contra qué versión del agente corre. Por defecto `"dev"`. |

## `GET /api/v1/triajes/{id}`

_alcance: lectura_

Estado y firma de un triaje

## `POST /api/v1/inferencias`

_alcance: escritura_

La app del cliente dice para qué (`proposito`), no con qué modelo. Se guarda el hash y la medición; la respuesta 24 h; el adjunto nunca. Contrato en `docs/CONTRATO-INFERENCIAS.md`.

| Campo | Tipo | Qué es |
|---|---|---|
| `proposito` **(requerido)** | string | El uso declarado por el rubro. No hay campo modelo: lo elige la plataforma. |
| `idempotencyKey` **(requerido)** | string | La acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar. |
| `instruccion` | string | Cómo tiene que trabajar el modelo. Es conocimiento de la app del cliente. |
| `texto` **(requerido)** | string | Los datos del caso: el dictado, el resumen, lo que haya. |
| `json` | boolean | true si la respuesta se espera como objeto JSON. Por defecto `false`. |
| `adjunto` | object | Un archivo del caso. No se guarda: se mide y se descarta. |

## `GET /api/v1/inferencias`

_alcance: lectura_

Lista `propositos` según el rubro de la organización: `clave` (lo que `POST` acepta en `proposito`), `titulo`, `maxEntrada`, si admite `adjunto` y con qué `medios`/`maxBytes`, y el `filtro` de salida. Nunca dice el modelo.

## `GET /api/v1/usage`

_alcance: lectura_

Consumo del mes contra el tope

## `GET /api/v1/webhooks`

_alcance: lectura_

Los webhooks configurados y los eventos que aceptan

## `GET /api/v1/webhooks/{id}/entregas`

_alcance: lectura_

Evento, estado (`entregado`/`pendiente`/`fallado`), intentos, status HTTP, error y fechas; 20 por página con `hay_mas`. El cuerpo crudo y la firma se piden por entrega.

| Parámetro | Qué es |
|---|---|
| `pagina` | Página, desde 1. |

## `GET /api/v1/webhooks/entregas/{entregaId}`

_alcance: lectura_

La firma se calcula sobre el cuerpo tal cual viajó, con el secreto real del webhook y la hora de ahora, así el `curl` pasa la comprobación del receptor. Exige que la persona del token sea operador: con esto se puede falsificar un aviso contra el endpoint del cliente.

## `POST /api/v1/webhooks/entregas/{entregaId}/reenviar`

_alcance: escritura_

Reinicia los intentos y vuelve a mandar el mismo cuerpo; el receptor idempotente la reconoce por `x-yorobot-sobre`. 200 si el endpoint contestó 2xx, 502 si quedó pendiente o fallada (el detalle dice por qué).

## `POST /api/v1/webhooks/{id}/prueba`

_alcance: escritura_

Cierra el ciclo recibir → comprobar firma → 2xx sin esperar a que una tarea termine. Queda como una entrega más, marcada `prueba: true`. 200 si el endpoint contestó 2xx, 502 si no.

| Campo | Tipo | Qué es |
|---|---|---|
| `evento` | `tarea.creada` · `tarea.terminada` · `tarea.necesita_firma` · `tarea.firmada` · `tarea.rechazada` · `discrepancia.detectada` · `consumo.tope_80` · `tarea.frenada` · `promocion.pendiente` · `conexion.pedida` · `consola.escalada` · `rutina.absorbiendo` · `consumo.tope_100` · `plan.cambiado` · `aprobacion.pendiente` · `conversacion.mensaje` · `briefing.listo` · `briefing.borrador` | Qué evento simular. El aviso lleva `prueba: true` y sale firmado con el secreto real del webhook, esté o no suscripto a ese evento. Por defecto `"tarea.terminada"`. |

## `DELETE /api/v1/vinculos/{id}`

_alcance: lectura_

Para una aplicación conectada con vínculo (Che Tienda): con `Authorization: Bearer <token de ESE vínculo>` —ningún otro sirve: otro token da 403— revoca el token, borra la credencial sellada y las conexiones que creó el vínculo, y contesta 204. Después de contestar le manda a la app el aviso firmado `vinculo.revocado`. Un vínculo que no existe o ya se dio de baja da 404 (o 401, si ya se revocó su token). Ver «Aplicaciones conectadas» abajo.

## `GET /api/v1/auditoria`

_alcance: auditoria_ · responde `application/x-ndjson`

Una línea por evento. El cursor vuelve en las cabeceras `x-yorobot-hasta` y `x-yorobot-hasta-id` y se manda tal cual en el pedido siguiente; `x-yorobot-sha256` es del cuerpo entero. Exige alcance `auditoria`, que sólo ve.

| Parámetro | Qué es |
|---|---|
| `desde` | Instante ISO del cursor anterior. |
| `desde-id` | Id del cursor anterior. |
| `limite` | Filas por página, hasta 5000. |

## `POST /api/v1/automatizaciones/{id}/disparar`

_alcance: escritura_

Si ya hay una corrida en curso y la automatización no admite concurrencia, responde `estado: coalesced` con quién la tapa.

## `POST /api/v1/rutinas/{id}/disparar`

_alcance: escritura_

Alias de `/automatizaciones/{id}/disparar`

## `GET /api/v1/peones`

_alcance: lectura_

Alias de `/agentes`

## `POST /api/v1/peones/{id}/tareas`

_alcance: escritura_

Alias de `/agentes/{id}/tareas`

| Campo | Tipo | Qué es |
|---|---|---|
| `entrada` | object | Los campos que el agente declara como entrada. Vacío si no pide ninguno. Por defecto `{}`. |
| `ambiente` | `dev` · `staging` · `prod` | Contra qué versión corre. Si falta, vale la cabecera `X-YoRobot-Ambiente`, y si tampoco está, `dev` — a propósito: la primera prueba de una integración no le pega al sistema real. Si cuerpo y cabecera se contradicen, 403. |
| `titulo` | string | Cómo se va a ver la tarea en la lista. Si falta, se arma con el nombre del agente. |

## Aplicaciones conectadas

Una aplicación conocida se conecta a una organización **sin que nadie copie un token**: YoRobot le entrega uno nuevo de servidor a servidor, firmado, y la app le devuelve su propia credencial por el mismo camino. Ninguna credencial pasa por el chat ni por la pantalla de nadie. Desde la IA es `conectar_aplicacion` (MCP); desde la app, un botón que lleva a `https://yorobot.ai/conectar/<clave>`. La carga manual —crear un token en Ajustes → Accesos y copiarlo una vez— queda como alternativa en Ajustes → Aplicaciones.

### Registro

Lo carga YoRobot, no el usuario: el destino de un token es siempre una dirección revisada.

| Clave | Nombre | Entrega | Página de vuelta | Alcances del token |
|---|---|---|---|---|
| `che-tienda` | Che Tienda | `https://www.chetienda.com/api/yorobot/vinculo` | `https://www.chetienda.com/estudio` | `lectura`, `topes` |

### Firma

- Ed25519, sin secretos compartidos. La llave pública está en `https://yorobot.ai/.well-known/jwks.json`: `{ "keys": [{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "…", "use": "sig" }] }`. Mientras no esté configurada, contesta `503`.
- Cada entrega trae `YoRobot-Firma: t=<unix en segundos>,kid=<kid>,v1=<firma>`. La firma es Ed25519 sobre los bytes de `"<t>.<cuerpo crudo>"`, en base64url sin relleno. El `kid` es el thumbprint RFC 7638 de la llave.
- La app busca la llave por `kid`, verifica sobre el cuerpo crudo (antes de parsearlo) y rechaza un `t` de más de 5 minutos.
- Para rotar, la llave nueva se publica en el JWKS **antes** de firmar con ella: un `kid` desconocido es motivo para releer el JWKS.

### Entrega (YoRobot → app)

`POST <entrega>`, `Content-Type: application/json`, 10 s de tiempo máximo y sin seguir redirecciones:

```json
{
  "evento": "vinculo.creado",
  "vinculo_id": "uuid, nuevo en cada intento",
  "organizacion": { "id": "uuid", "nombre": "…" },
  "cuenta": { "email": "persona@dominio", "email_verificado": true },
  "tienda": "lo que dijo la persona, o null",
  "estado": "el estado opaco del botón, tal cual, o null",
  "token": "el token de API nuevo",
  "alcances": ["lectura", "topes"]
}
```

- El token es nuevo y exclusivo del vínculo, de la persona que conectó (ve lo mismo que ella), no vence, se puede revocar y figura en Accesos como «<Nombre> (aplicación conectada)».
- Si la app no contesta 200, el token se revoca y el vínculo no queda. El cuerpo de la entrega no se guarda en ningún registro: lleva el token.
- No se reintenta con el mismo `vinculo_id`: un reintento es un vínculo nuevo, con otro token.
- Un vínculo nuevo de la misma organización y aplicación reemplaza al anterior: su token se revoca y las conexiones pasan al nuevo, con la credencial nueva.

### Respuestas de la app

A la IA y a la persona les llega sólo `mensaje`. Nunca el token ni la credencial.

| Código | Cuerpo | Qué hace YoRobot |
|---|---|---|
| `200` | `{ "estado": "conectada", "tienda": { "id", "nombre" }, "mensaje", "credencial": { "tipo": "openapi", "openapi_url", "cabecera": "Authorization", "valor": "Bearer …" } }` | Sella `credencial.valor` en la bóveda y declara como conexiones activas, de riesgo `read`, todas las lecturas (GET) del documento. El documento tiene que estar en el host de la app, y sus servidores también; tiene que declarar cómo viaja la credencial (`securitySchemes`, p. ej. `http bearer`). Sin `credencial`, el vínculo queda sin conexiones. |
| `409` | `{ "estado": "varias_tiendas", "tiendas": [...], "mensaje" }` | Revoca el token. La IA pregunta cuál y reintenta con `tienda` (vínculo nuevo). |
| `409` | `{ "estado": "repetido", "mensaje" }` | Revoca el token. |
| `404` | `{ "estado": "sin_tienda", "mensaje", "conectar_en" }` | Revoca el token. |
| `403` | `{ "estado": "correo_sin_verificar", "mensaje" }` | Revoca el token. |
| `400` | `{ "estado": "estado_vencido", "mensaje" }` | Revoca el token; el botón vuelve con `motivo=estado_vencido`. |
| `400` | `{ "estado": "entrega_invalida", "mensaje" }` | Revoca el token. |
| `401` | `{ "estado": "firma_invalida", "mensaje" }` | Revoca el token. |
| `503` | `{ "estado": "jwks_no_disponible", "mensaje" }` | Revoca el token; se puede reintentar como vínculo nuevo. |
| otro, o sin respuesta | — | Revoca el token (`estado`: el de la respuesta, `http_<código>`, `redireccion` o `sin_respuesta`). |

### Conexión con un botón

`GET https://yorobot.ai/conectar/<clave>?estado=<opaco>&volver=<url>`

1. `volver` tiene que ser la página de vuelta registrada; si no, se rechaza ahí mismo.
2. Sin sesión, la persona pasa por el login y vuelve. Con varias organizaciones elige una (sólo donde es técnico o admin).
3. Ve qué va a poder hacer la app y toca **Conectar**. YoRobot hace la entrega con el `estado` tal como llegó.
4. Vuelve a `volver?yorobot=conectada`, a `volver?yorobot=error&motivo=<estado de la respuesta>` o, si cancela, a `volver?yorobot=cancelada`.

### Baja

- **Desde YoRobot** (`desconectar_aplicacion` o Ajustes → Aplicaciones): revoca el token, borra la credencial sellada y las conexiones que creó el vínculo, y le manda a la app una entrega firmada igual, sin token: `{ "evento": "vinculo.revocado", "vinculo_id", "organizacion": { "id", "nombre" } }`. La app contesta `200 { "estado": "desconectada", "mensaje" }`, también si ese vínculo ya no existía.
- **Desde la app:** `DELETE /api/v1/vinculos/{vinculo_id}` con `Authorization: Bearer <token del vínculo>`. Hace lo mismo y contesta `204`; sólo sirve el token de ese mismo vínculo.

### Por MCP

- `conectar_aplicacion { aplicacion, tienda? }` (técnico o admin): crea el vínculo y hace la entrega. Devuelve `conectada`, `estado`, `mensaje` y, si conectó, la tienda y las conexiones creadas.
- `listar_aplicaciones_conectadas`: cada vínculo con la tienda, quién lo conectó, cuándo, los últimos 4 del token y sus conexiones.
- `desconectar_aplicacion { vinculo_id }`: la baja desde YoRobot.
- La IA nunca pide un token en el chat ni lo muestra: «conectá mi tienda de Che Tienda con YoRobot» es `conectar_aplicacion { aplicacion: "che-tienda" }`.

## Ejemplo

```bash
curl -X POST https://yorobot.ai/api/v1/agentes/AGENTE_ID/tareas \
  -H "Authorization: Bearer TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"entrada":{"factura":"A-0001"},"ambiente":"dev"}'
```
