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, 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.
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, contesta503. - 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. Elkides el thumbprint RFC 7638 de la llave. - La app busca la llave por
kid, verifica sobre el cuerpo crudo (antes de parsearlo) y rechaza untde más de 5 minutos. - Para rotar, la llave nueva se publica en el JWKS antes de firmar con ella: un
kiddesconocido 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:
{
"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>
volvertiene que ser la página de vuelta registrada; si no, se rechaza ahí mismo.- Sin sesión, la persona pasa por el login y vuelve. Con varias organizaciones elige una (sólo donde es técnico o admin).
- Ve qué va a poder hacer la app y toca Conectar. YoRobot hace la entrega con el
estadotal como llegó. - Vuelve a
volver?yorobot=conectada, avolver?yorobot=error&motivo=<estado de la respuesta>o, si cancela, avolver?yorobot=cancelada.
Baja
- Desde YoRobot (
desconectar_aplicaciono 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 contesta200 { "estado": "desconectada", "mensaje" }, también si ese vínculo ya no existía. - Desde la app:
DELETE /api/v1/vinculos/{vinculo_id}conAuthorization: Bearer <token del vínculo>. Hace lo mismo y contesta204; 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. Devuelveconectada,estado,mensajey, 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
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"}'