YoRobot.

Esta página en Markdown: /docs/api.md

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étodoRutaAlcanceQué hace
GET/api/v1/agenteslecturaLos agentes de la organización
GET/api/v1/agentes/{id}lecturaUn agente: gasto contra su tope, 30 días y lo que espera tu firma
PUT/api/v1/agentes/{id}/topetopes o escrituraFijar o sacar el tope de gasto del mes de un agente
GET/api/v1/membresialecturaLa membresía de la organización y si hay algo que pagar
POST/api/v1/agentes/{id}/tareasescrituraPedirle una tarea a un agente
POST/api/v1/agentes/{id}/charlaescrituraPreguntarle a un agente de lectura, con cita
GET/api/v1/agentes/{id}/charlalecturaCuánto le queda hoy al sujeto para charlar
POST/api/v1/agentes/{id}/charla/reportarescrituraReportar una conversación para que la revisemos
GET/api/v1/consolaslecturaLas consolas publicadas y su URL de puesto
POST/api/v1/ticketsescrituraCrear una tarea de desarrollo en un proyecto
GET/api/v1/tickets/{id}lecturaEstado de una tarea
GET/api/v1/ticketslecturaLas tareas de la organización, con cursor
GET/api/v1/agentes/{id}/metricaslecturaCómo viene trabajando un agente, y cada versión
GET/api/v1/agentes/{id}/actividadlecturaTodo lo que hizo un agente, paginado
GET/api/v1/conversacioneslecturaLas conversaciones de los canales
GET/api/v1/conversaciones/{id}lecturaUna conversación con sus mensajes
GET/api/v1/aprobacioneslecturaLo que espera la aprobación de una persona
POST/api/v1/tickets/{id}/cancelescrituraCancelar una tarea que todavía no terminó
POST/api/v1/tickets/{id}/messagesescrituraMandarle un mensaje al agente sobre una tarea
POST/api/v1/cerebro/transcripcionesescrituraCargar la transcripción de una call al Cerebro
GET/api/v1/cerebro/coleccioneslecturaLas colecciones del Cerebro
POST/api/v1/cerebro/coleccionesescrituraCrear una colección del Cerebro
POST/api/v1/cerebro/loteescrituraCargar documentos al Cerebro, hasta 20 por pedido
POST/api/v1/triajesescrituraPedir un triaje por el método (Manchester)
GET/api/v1/triajes/{id}lecturaEstado y firma de un triaje
POST/api/v1/inferenciasescrituraUna inferencia por propósito declarado
GET/api/v1/inferenciaslecturaLos propósitos de inferencia disponibles
GET/api/v1/usagelecturaConsumo del mes contra el tope
GET/api/v1/webhookslecturaLos webhooks configurados y los eventos que aceptan
GET/api/v1/webhooks/{id}/entregaslecturaLas entregas de un webhook, de la más nueva a la más vieja
GET/api/v1/webhooks/entregas/{entregaId}lecturaUna entrega con su cuerpo crudo, una firma fresca y el curl para reproducirla
POST/api/v1/webhooks/entregas/{entregaId}/reenviarescrituraReenviar una entrega ahora, con el mismo sobre
POST/api/v1/webhooks/{id}/pruebaescrituraMandar un aviso de prueba firmado a un webhook
DELETE/api/v1/vinculos/{id}lecturaDar de baja una aplicación conectada, desde la app
GET/api/v1/auditoriaauditoriaLa bitácora en NDJSON para el SIEM
POST/api/v1/automatizaciones/{id}/dispararescrituraDisparar una automatización ahora
POST/api/v1/rutinas/{id}/dispararescrituraAlias de /automatizaciones/{id}/disparar
GET/api/v1/peoneslecturaAlias de /agentes
POST/api/v1/peones/{id}/tareasescrituraAlias 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»).

CampoTipoQué es
tope_mes_usd (requerido)number o nullEl 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.

CampoTipoQué es
entradaobjectLos campos que el agente declara como entrada. Vacío si no pide ninguno. Por defecto {}.
ambientedev · staging · prodContra 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.
titulostringCó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.

CampoTipoQué es
historia (requerido)arrayLa conversación completa. El último turno de persona es la pregunta.
fijosobjectParámetros que el servidor pone en cada llamada a una herramienta. El modelo no los ve ni los cambia. Por defecto {}.
sujetostringDe parte de quién se pregunta. El tope diario se cuenta contra esto; si falta, contra el agente entero.
lecturas_previasarrayLo leído en turnos anteriores de ESTA conversación, tal como lo devolvió el evento fin. Lo guarda quien llama. Por defecto [].
solo_lecturabooleanContestar 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ámetroQué es
sujetoQuién pregunta (para el tope por persona). Si falta, el tope es del agente.
consultaEl 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.

CampoTipoQué es
turnos (requerido)arrayLa conversación que salió mal, completa.
lecturasarrayLas lecturas de esa conversación con sus argumentos: es lo que permite ver con qué datos contestó. Por defecto [].
sujetostringDe parte de quién se conversaba. Es lo que después permite filtrar por empresa.
notastringLo 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.

CampoTipoQué es
projectId (requerido)stringEl proyecto (repositorio) al que pertenece.
title (requerido)stringTítulo corto.
descriptionstringQué hay que hacer, en detalle.
budgetUsdnumberPresupuesto 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ámetroQué es
agenteId del agente (de GET /agentes). Uno fuera de tu alcance da 404.
estadoUn estado de tarea (needs_human, verified, running…).
desdeCreadas desde este instante ISO, inclusive.
hastaCreadas antes de este instante ISO.
limiteCuántas por página, de 1 a 100 (50 por defecto).
cursorEl 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ámetroQué es
diasLa 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ámetroQué es
desdeSólo lo posterior a este instante ISO (el cursor del flujo en vivo).
paginaPágina, desde 1.
limiteHechos por página, de 1 a 100 (50 por defecto).
claseFiltrar por clase: tarea, herramienta, freno, mensaje, llamada, registro… (separadas por coma).
solo_errorestrue 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ámetroQué es
agenteId del agente.
canalId del canal.
estadoabierta o cerrada.
paginaPágina, desde 1.
limiteConversaciones 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ámetroQué es
agenteSó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

CampoTipoQué es
texto (requerido)stringLo 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.

CampoTipoQué es
titulo (requerido)stringCómo se lee en el Cerebro: «Call de discovery — logística».
fecha (requerido)stringCuándo fue la call, ISO.
participantesarrayQuiénes hablaron. Por defecto [].
empresastringLa empresa del otro lado, si la hay. Va al índice del Cerebro.
origen (requerido)stringDe dónde sale: fireflies, tldv, zoom, meet, manual.
textostringLa transcripción, en texto plano o Markdown.
contenido_base64stringEn vez de texto: el archivo (.pdf, .md o .txt) en base64.
nombre_archivostringCon contenido_base64, el nombre con extensión: de ahí sale cómo se extrae el texto.
agentes (requerido)arrayLas claves de los agentes que la pueden leer, y sólo ellos: una call trae nombres y cifras de clientes.
rutinastringLa 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.

CampoTipoQué es
nombre (requerido)stringCómo se llama: «Contratos de proveedores». No se repite en la organización.
descripcionstringQué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento.
plantillaparrafos · clausulas · filasDónde se corta cada documento: clausulas (contratos: donde empieza cada cláusula numerada), filas (planillas) o parrafos (por defecto).
alcancetenant · proyecto · agenteQuién lee sus documentos: toda la organización (por defecto), un proyecto o un agente.
proyecto_idstringObligatorio con alcance proyecto.
agente_idstringObligatorio 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.

CampoTipoQué es
agente (requerido)stringEl agente que atiende el método. Sin default: elegirlo es decisión del cliente.
idempotencyKey (requerido)stringLa acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar.
texto (requerido)stringLo que contó la persona, tal cual. No se le pide un color ni una clasificación.
referenciastringEl id del caso del lado del cliente, para volver a unir las dos mitades.
centrostringEl centro que atiende, si ya se sabe. Si no, lo reparte una persona.
ambientedev · staging · prodContra 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.

CampoTipoQué es
proposito (requerido)stringEl uso declarado por el rubro. No hay campo modelo: lo elige la plataforma.
idempotencyKey (requerido)stringLa acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar.
instruccionstringCómo tiene que trabajar el modelo. Es conocimiento de la app del cliente.
texto (requerido)stringLos datos del caso: el dictado, el resumen, lo que haya.
jsonbooleantrue si la respuesta se espera como objeto JSON. Por defecto false.
adjuntoobjectUn 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ámetroQué es
paginaPá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.

CampoTipoQué es
eventotarea.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.borradorQué 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ámetroQué es
desdeInstante ISO del cursor anterior.
desde-idId del cursor anterior.
limiteFilas 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

CampoTipoQué es
entradaobjectLos campos que el agente declara como entrada. Vacío si no pide ninguno. Por defecto {}.
ambientedev · staging · prodContra 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.
titulostringCó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.

ClaveNombreEntregaPágina de vueltaAlcances del token
che-tiendaChe Tiendahttps://www.chetienda.com/api/yorobot/vinculohttps://www.chetienda.com/estudiolectura, 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:

{
  "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ódigoCuerpoQué 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

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"}'