Para desarrolladores

API y MCP de benflow

Conecta Hermes, OpenClaw, Claude Code o el sistema de tu tienda al tablero del proyecto. Con una clave por conexión, la IA o el sistema abre tarjetas, comenta, sigue lo que cambió y organiza la cola.

Crear la clave Paso a paso en la ayuda

MCP remoto

Para IAs: Hermes, OpenClaw, Claude Code, Cursor y cualquier cliente MCP por HTTP.

https://benflow.net/mcp

API REST

Para sistemas y automatizaciones: n8n, Zapier, el sistema de la tienda o el ERP.

https://benflow.net/api/v1

Funciona con

Hermes
OpenClaw
Claude Code
Cursor
n8n
Zapier

Empezar en 3 pasos

1
Crea la clave
En el panel, en Conexiones, en la fila IAs externas (MCP y API), toca Conectar. Elige la IA o el sistema, lo que la clave puede hacer y el sector de las tarjetas. Solo el administrador del proyecto crea claves, y cada clave aparece una sola vez.
2
Pégala en la IA o en el sistema
La ventana muestra el fragmento correcto para cada uno, ya con la clave dentro. Los mismos fragmentos están justo abajo, con el lugar de la clave marcado.
3
Prueba la conexión
Pide a la IA que use la herramienta quem_sou o llama GET /api/v1/eu: la respuesta trae el proyecto y los permisos de la clave.

Probar la clave

curl https://benflow.net/api/v1/eu \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Conecta tu IA o tu sistema

Las IAs entran por el servidor MCP; sistemas y automatizaciones, por la API. Elige abajo y copia el fragmento: cambia bfx_sua_chave por la clave creada en el panel.

Hermes

El agente de Nous Research que lee correos y conversa por WhatsApp y Telegram.

En el archivo ~/.hermes/config.yaml, dentro de mcp_servers:

~/.hermes/config.yaml

mcp_servers:
  benflow:
    url: "https://benflow.net/mcp"
    headers:
      Authorization: "Bearer bfx_sua_chave"

Después, en la conversación con Hermes, envía /reload-mcp. Para comprobar en la terminal: hermes mcp test benflow.

Orientación para la IA (opcional). Al conectar, el servidor MCP ya envía a la IA el proyecto, los permisos de la clave y cómo usar las herramientas. Para reforzarlo, pega esto en su prompt:

Prompt

Você está ligado ao Benflow, o quadro de chamados do projeto, como "Hermes do atendimento" (servidor MCP benflow).
Quando chegar um pedido (e-mail, WhatsApp, Telegram), abra o card com abrir_chamado, mandando referencia_externa (o Message-ID do e-mail ou o id da conversa) e o solicitante: a mesma referência não abre outro card.
Acompanhe com acompanhar, guardando o "agora" da resposta para a próxima vez, e avise quem pediu quando a etapa mudar ou a equipe comentar.
Antes de mudar prioridade ou responsáveis, olhe avaliar_fila e avaliar_carga e explique o motivo em decidir.

Autenticación

Toda llamada lleva la clave en la cabecera Authorization, en formato Bearer. La clave empieza con bfx_ y tiene 43 caracteres más. En los ejemplos, está en la variable de entorno BENFLOW_CHAVE.

Cabecera

Authorization: Bearer bfx_sua_chave

Una clave por IA o sistema: la tarjeta y el comentario muestran su nombre (por ejemplo, Hermes do atendimento), y desactivar una no afecta a las demás.
La clave aparece solo al crearla. benflow guarda su resumen (sha256) y los 4 últimos caracteres: si la pierdes, crea otra.
Desactivar rechaza la clave en la próxima llamada y no tiene vuelta atrás. Las tarjetas y comentarios que hizo siguen en el proyecto.
Hasta 20 claves activas por proyecto. Sin cookie, sin sesión y sin CSRF: solo la cabecera.

Lo que cada clave puede hacer

Permiso	Lo que permite	En la clave nueva
Leer (toda clave)	Tarjetas, comentarios públicos, historial, cola, carga, personas y sectores.	Siempre
Abrir tarjetas	Abrir tarjetas en Por hacer, con el contacto de quien pidió.	Activado
Comentar	Comentario público (quien pidió lo ve) o nota interna.	Activado
Decidir	Prioridad, responsables, plazo, sector y la etapa entre Por hacer, En curso y Cerrado.	Desactivado

La clave también puede tener un sector: las tarjetas que abre sin sector entran en él. El administrador cambia los permisos y el sector cuando quiera, sin cambiar la clave.

Referencia de la API

Dirección base https://benflow.net/api/v1. Pedidos y respuestas en JSON (UTF-8), con los campos en portugués, los mismos nombres del MCP. Fechas y horas en ISO 8601 (UTC); plazo en AAAA-MM-DD. Todo vale solo en el proyecto de la clave, y el número de la tarjeta es el mismo del panel.

Quién es la clave

GET/api/v1/eu

El proyecto vinculado a la clave y sus permisos. Es la primera prueba después de pegar la clave.

Permiso: Leer (toda clave)

curl https://benflow.net/api/v1/eu \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "chave": "Hermes do atendimento",
  "projeto": {
    "nome": "Aurora Móveis",
    "endereco": "https://benflow.net/o/aurora-moveis"
  },
  "permissoes": {
    "ler": true,
    "abrir": true,
    "comentar": true,
    "decidir": false
  }
}

Listar tarjetas

GET/api/v1/chamados

Las tarjetas del proyecto, de la que cambió por último a la más antigua. Sin filtro, vienen las abiertas: Por hacer, En curso, En homologación y En producción.

Permiso: Leer (toda clave)

En la dirección (query)

etapastring: Una etapa (a_fazer | em_andamento | em_homologacao | em_producao | concluido | fechado), abertos (predeterminado) o todos.
buscastring: Texto en el título, la descripción o el pedido original, o el número de la tarjeta. Hasta 200 caracteres.
responsavelinteger: Id de la persona (mira GET /pessoas).
setorinteger: Id del sector (mira GET /pessoas).
atrasadosboolean: Solo las tarjetas con el plazo vencido.
referencia_externastring: Encuentra la tarjeta de un correo o pedido ya enviado (hasta 300 caracteres). Devuelve 0 o 1 tarjeta.
minha_iaboolean: Solo las tarjetas que abrió esta clave.
limiteinteger: De 1 a 100. Predeterminado: 30. El total de la respuesta cuenta todas las que pasaron el filtro.

curl "https://benflow.net/api/v1/chamados?etapa=abertos&busca=cupom&limite=10" \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "total": 2,
  "cards": [
    {
      "numero": 128,
      "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
      "etapa": "a_fazer",
      "etapa_nome": "A fazer",
      "prioridade": "alta",
      "tipo": "bug",
      "setor": "Loja virtual",
      "prazo": null,
      "atrasado": false,
      "responsaveis": [],
      "origem": "IA de fora: Hermes do atendimento",
      "card_principal": null,
      "ia": null,
      "aberto_em": "2026-10-19T12:41:07.512Z",
      "atualizado_em": "2026-10-19T12:41:07.512Z",
      "link": "https://benflow.net/o/aurora-moveis/c/128"
    },
    {
      "numero": 131,
      "titulo": "Parcelamento em 12x no checkout",
      "etapa": "em_andamento",
      "etapa_nome": "Em andamento",
      "prioridade": "normal",
      "tipo": "funcionalidade",
      "setor": "Loja virtual",
      "prazo": "2026-10-24",
      "atrasado": false,
      "responsaveis": [
        {
          "id": 9,
          "nome": "Diego"
        }
      ],
      "origem": "Painel",
      "card_principal": null,
      "ia": {
        "etapa": "desenvolvimento",
        "percentual": 45,
        "situacao": "rodando",
        "agente": "Bento"
      },
      "aberto_em": "2026-10-17T18:02:44.120Z",
      "atualizado_em": "2026-10-19T11:58:10.004Z",
      "link": "https://benflow.net/o/aurora-moveis/c/131"
    }
  ]
}

Abrir una tarjeta

POST/api/v1/chamados

Abre la tarjeta en Por hacer, con el nombre de la clave como origen y el contacto de quien pidió. Con la misma referencia_externa, devuelve la tarjeta que ya existe en vez de abrir otra.

Permiso: Abrir tarjetas

201 con criado: true cuando nace la tarjeta; 200 con criado: false y la tarjeta anterior cuando la referencia ya existía.

En el cuerpo (JSON)

titulostringobligatorio: De 3 a 200 caracteres.
descricaostring: El pedido en pocas líneas, hasta 5.000 caracteres. Una contraseña o token pegado en el texto sale enmascarado.
prioridadestring: urgente | alta | normal | baixa
tipostring: bug | melhoria | funcionalidade
prazostring: Fecha en formato AAAA-MM-DD.
setorinteger: Id del sector. Sin él, la tarjeta entra en el sector de la clave.
responsaveisinteger[]: Ids de las personas, hasta 10.
referencia_externastring: El Message-ID del correo, o el id de la conversación o del pedido en el sistema de origen, hasta 300 caracteres.
solicitanteobject: Quién pidió: nome (hasta 120), email (hasta 200) y telefone (hasta 40), todos opcionales.

curl -X POST https://benflow.net/api/v1/chamados \
  -H "Authorization: Bearer $BENFLOW_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
    "descricao": "A cliente tentou usar o cupom pelo celular e o carrinho mostra Cupom inválido.",
    "prioridade": "alta",
    "tipo": "bug",
    "referencia_externa": "<CAH7x2k9QmZ@mail.gmail.com>",
    "solicitante": {
      "nome": "Carla Souza",
      "email": "carla@exemplo.com"
    }
  }'

Respuesta 201

{
  "criado": true,
  "card": {
    "numero": 128,
    "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
    "etapa": "a_fazer",
    "etapa_nome": "A fazer",
    "prioridade": "alta",
    "tipo": "bug",
    "setor": "Loja virtual",
    "prazo": null,
    "atrasado": false,
    "responsaveis": [],
    "origem": "IA de fora: Hermes do atendimento",
    "card_principal": null,
    "ia": null,
    "aberto_em": "2026-10-19T12:41:07.512Z",
    "atualizado_em": "2026-10-19T12:41:07.512Z",
    "link": "https://benflow.net/o/aurora-moveis/c/128"
  }
}

Ver una tarjeta

GET/api/v1/chamados/{numero}

Todo de una tarjeta: descripción, pedido original, quién pidió, la referencia, los comentarios y el historial (los últimos 30 cambios).

Permiso: Leer (toda clave)

La clave lee los comentarios públicos y las notas internas que ella misma dejó. Las notas internas del equipo quedan fuera.
Una tarjeta archivada o en la papelera responde 404.

curl https://benflow.net/api/v1/chamados/128 \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "numero": 128,
  "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
  "etapa": "em_andamento",
  "etapa_nome": "Em andamento",
  "prioridade": "alta",
  "tipo": "bug",
  "setor": "Loja virtual",
  "prazo": null,
  "atrasado": false,
  "responsaveis": [
    {
      "id": 14,
      "nome": "Julia"
    }
  ],
  "origem": "IA de fora: Hermes do atendimento",
  "card_principal": null,
  "ia": null,
  "aberto_em": "2026-10-19T12:41:07.512Z",
  "atualizado_em": "2026-10-19T14:13:05.877Z",
  "link": "https://benflow.net/o/aurora-moveis/c/128",
  "descricao": "A cliente tentou usar o cupom pelo celular e o carrinho mostra Cupom inválido.",
  "pedido_original": null,
  "solicitante": {
    "nome": "Carla Souza",
    "email": "carla@exemplo.com",
    "telefone": null
  },
  "referencia_externa": "<CAH7x2k9QmZ@mail.gmail.com>",
  "comentarios": [
    {
      "id": 911,
      "autor": "Julia",
      "texto": "Achei o problema no cálculo do frete, corrijo hoje.",
      "interno": false,
      "em": "2026-10-19T14:13:05.877Z"
    }
  ],
  "historico": [
    {
      "em": "2026-10-19T12:41:07.512Z",
      "o_que": "Card aberto",
      "quem": "Hermes do atendimento"
    },
    {
      "em": "2026-10-19T14:12:31.090Z",
      "o_que": "Responsáveis: entrou Julia",
      "quem": "Diego"
    },
    {
      "em": "2026-10-19T14:12:40.201Z",
      "o_que": "Etapa: de A fazer para Em andamento",
      "quem": "Julia"
    }
  ]
}

Comentar

POST/api/v1/chamados/{numero}/comentarios

Responde en la tarjeta. Público (el predeterminado): quien pidió lo ve, y en la tarjeta que llegó por Telegram la respuesta va allí. Con interno, se vuelve una nota solo del equipo.

Permiso: Comentar

En el cuerpo (JSON)

textostringobligatorio: De 1 a 5.000 caracteres.
internoboolean: true para nota interna. Predeterminado: false.

curl -X POST https://benflow.net/api/v1/chamados/128/comentarios \
  -H "Authorization: Bearer $BENFLOW_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "texto": "Oi, Carla! A equipe já está corrigindo o cupom. Aviso aqui assim que voltar a funcionar."
  }'

Respuesta 201

{
  "id": 912,
  "interno": false,
  "card": 128
}

Decidir

PATCH/api/v1/chamados/{numero}

Cambia prioridad, responsables, plazo, sector y la etapa de entrada. Envía solo lo que cambia; la respuesta trae la tarjeta como quedó.

Permiso: Decidir

La etapa solo cambia en una tarjeta en Por hacer o En curso y sin la IA del equipo trabajando en ella (si no, 409). Homologación, producción y Concluido siguen con la cadena de benflow, no con la clave.
Llevar a En curso una tarjeta con un plan esperando aprobación responde 403.

En el cuerpo (JSON)

prioridadestring: urgente | alta | normal | baixa
responsaveisinteger[]: Reemplaza la lista entera, hasta 10 ids.
prazostring | null: AAAA-MM-DD; null quita el plazo.
setorinteger | null: Id del sector; null quita el sector.
etapastring: a_fazer | em_andamento | fechado
motivostring: Por qué decidió, hasta 2.000 caracteres. Va al historial y, si la clave puede comentar, se vuelve una nota interna en la tarjeta.

curl -X PATCH https://benflow.net/api/v1/chamados/128 \
  -H "Authorization: Bearer $BENFLOW_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "prioridade": "urgente",
    "responsaveis": [
      14
    ],
    "prazo": "2026-10-20",
    "motivo": "Três clientes relataram o mesmo erro hoje e a Julia é quem cuida do carrinho, com a menor carga da equipe."
  }'

Respuesta 200

{
  "numero": 128,
  "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
  "etapa": "a_fazer",
  "etapa_nome": "A fazer",
  "prioridade": "urgente",
  "tipo": "bug",
  "setor": "Loja virtual",
  "prazo": "2026-10-20",
  "atrasado": false,
  "responsaveis": [
    {
      "id": 14,
      "nome": "Julia"
    }
  ],
  "origem": "IA de fora: Hermes do atendimento",
  "card_principal": null,
  "ia": null,
  "aberto_em": "2026-10-19T12:41:07.512Z",
  "atualizado_em": "2026-10-19T12:55:19.330Z",
  "link": "https://benflow.net/o/aurora-moveis/c/128"
}

Seguir lo que cambió

GET/api/v1/acompanhar

Las tarjetas que cambiaron desde una hora dada: etapa, responsables y campos, comentarios públicos del equipo y el avance de la IA del equipo.

Permiso: Leer (toda clave)

Guarda el agora de la respuesta y envíalo en desde la próxima vez. Vienen hasta 50 tarjetas por respuesta.

En la dirección (query)

desdestring: Fecha y hora en ISO 8601, por ejemplo 2026-10-19T14:00:00Z. Predeterminado: las últimas 24 horas; como máximo 7 días atrás.
numerointeger: Solo una tarjeta.
minha_iaboolean: Solo las tarjetas que abrió esta clave.

curl "https://benflow.net/api/v1/acompanhar?desde=2026-10-19T14%3A00%3A00Z" \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "agora": "2026-10-19T15:00:02.118Z",
  "desde": "2026-10-19T14:00:00.000Z",
  "cards": [
    {
      "numero": 128,
      "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
      "etapa_nome": "Em andamento",
      "link": "https://benflow.net/o/aurora-moveis/c/128",
      "mudancas": [
        "Responsáveis: entrou Julia, por Diego (2026-10-19T14:12:31.090Z)",
        "Etapa: de A fazer para Em andamento, por Julia (2026-10-19T14:12:40.201Z)",
        "Comentário de Julia (2026-10-19T14:13:05.877Z): Achei o problema no cálculo do frete, corrijo hoje."
      ],
      "ia": null
    }
  ]
}

Evaluar la cola

GET/api/v1/fila

Las abiertas por etapa y prioridad, bugs, sin responsable, atrasadas, las que vencen en 3 días, lo que entró y salió en la semana, las más antiguas en Por hacer y la cola de la IA del equipo. Las observaciones son solo hechos contados.

Permiso: Leer (toda clave)

curl https://benflow.net/api/v1/fila \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "abertos": 23,
  "por_etapa": {
    "A fazer": 9,
    "Em andamento": 8,
    "Em homologação": 4,
    "Em produção": 2
  },
  "por_prioridade": {
    "urgente": 1,
    "alta": 6,
    "normal": 13,
    "baixa": 3
  },
  "bugs_abertos": 7,
  "sem_responsavel": 3,
  "atrasados": 2,
  "vencem_em_3_dias": 4,
  "entraram_7_dias": 15,
  "concluidos_7_dias": 11,
  "mais_antigos_a_fazer": [
    {
      "numero": 97,
      "titulo": "Filtro por cor some na busca do celular",
      "prioridade": "normal",
      "dias_esperando": 9,
      "responsaveis": []
    }
  ],
  "ia_da_equipe": {
    "rodando": 2,
    "na_fila": 3,
    "paradas": 0
  },
  "observacoes": [
    "1 card(s) urgente(s) ou de alta prioridade sem responsável.",
    "2 card(s) com o prazo vencido.",
    "Na semana entraram 15 card(s) e 11 foram concluídos: a fila cresceu.",
    "O card #97 espera em A fazer há 9 dias."
  ]
}

Evaluar la carga

GET/api/v1/carga

La carga de cada persona (abiertas, en curso, atrasadas, urgentes y altas, concluidas en la semana), de la más cargada a la menos, y lo que cada Claude del equipo hace ahora y tiene en cola.

Permiso: Leer (toda clave)

curl https://benflow.net/api/v1/carga \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "pessoas": [
    {
      "id": 14,
      "nome": "Julia",
      "papel": "membro",
      "abertos": 6,
      "em_andamento": 4,
      "atrasados": 1,
      "urgentes_e_altas": 2,
      "concluidos_7_dias": 5
    },
    {
      "id": 9,
      "nome": "Diego",
      "papel": "admin",
      "abertos": 4,
      "em_andamento": 2,
      "atrasados": 0,
      "urgentes_e_altas": 1,
      "concluidos_7_dias": 3
    }
  ],
  "sem_responsavel": 3,
  "ia_da_equipe": [
    {
      "agente": "Bento",
      "dono": "Diego",
      "online": true,
      "trabalhando_em": [
        {
          "numero": 131,
          "titulo": "Parcelamento em 12x no checkout",
          "etapa": "desenvolvimento",
          "percentual": 45
        }
      ],
      "na_fila": 2
    }
  ]
}

Personas y sectores

GET/api/v1/pessoas

Quién puede ser responsable y los sectores del proyecto, con los ids para abrir y decidir.

Permiso: Leer (toda clave)

curl https://benflow.net/api/v1/pessoas \
  -H "Authorization: Bearer $BENFLOW_CHAVE"

Respuesta 200

{
  "pessoas": [
    {
      "id": 9,
      "nome": "Diego",
      "papel": "admin"
    },
    {
      "id": 14,
      "nome": "Julia",
      "papel": "membro"
    },
    {
      "id": 21,
      "nome": "Rafael",
      "papel": "membro"
    }
  ],
  "setores": [
    {
      "id": 3,
      "nome": "Atendimento"
    },
    {
      "id": 4,
      "nome": "Loja virtual"
    }
  ]
}

La tarjeta en la respuesta

Listar, abrir y decidir devuelven la tarjeta en este formato. Ver trae los mismos campos y además los del detalle.

Campos de la tarjeta

numerointeger: El número de la tarjeta en el proyecto, el mismo del panel (#128).
titulostring: El título.
etapastring: a_fazer | em_andamento | em_homologacao | em_producao | concluido | fechado
etapa_nomestring: El nombre de la etapa como aparece en el tablero (A fazer, Em andamento...).
prioridadestring: urgente | alta | normal | baixa
tipostring | null: bug | melhoria | funcionalidade
setorstring | null: El nombre del sector.
prazostring | null: AAAA-MM-DD.
atrasadoboolean: Plazo vencido en una tarjeta aún abierta.
responsaveisobject[]: { id, nome }
origemstring: Por dónde llegó la tarjeta, en portugués: IA de fora (con el nombre de la clave), Telegram, E-mail, Widget do site, Link externo, Reunião, Terminal, la herramienta de monitoreo o Painel.
card_principalinteger | null: El número de la tarjeta principal, cuando esta es una subtarjeta.
iaobject | null: El trabajo de la IA del equipo en la tarjeta: { etapa, percentual, situacao, agente }.
aberto_emstring: Fecha y hora en ISO 8601 (UTC).
atualizado_emstring: El último cambio, en ISO 8601 (UTC).
linkstring: La dirección de la tarjeta en el panel.

Solo al ver una tarjeta

descricaostring: La descripción, con contraseñas y tokens enmascarados.
pedido_originalstring | null: El texto original del pedido, cuando la tarjeta guarda uno.
solicitanteobject | null: { nome, email, telefone }
referencia_externastring | null: La referencia enviada al abrir.
comentariosobject[]: { id, autor, texto, interno, em }
historicoobject[]: { em, o_que, quem }

Card

{
  "numero": 128,
  "titulo": "Cupom FRETEGRATIS não aplica no carrinho",
  "etapa": "a_fazer",
  "etapa_nome": "A fazer",
  "prioridade": "alta",
  "tipo": "bug",
  "setor": "Loja virtual",
  "prazo": null,
  "atrasado": false,
  "responsaveis": [],
  "origem": "IA de fora: Hermes do atendimento",
  "card_principal": null,
  "ia": null,
  "aberto_em": "2026-10-19T12:41:07.512Z",
  "atualizado_em": "2026-10-19T12:41:07.512Z",
  "link": "https://benflow.net/o/aurora-moveis/c/128"
}

Herramientas del MCP

El servidor MCP está en https://benflow.net/mcp, con el transporte Streamable HTTP y sin sesión: cada pedido es un POST con la clave en la cabecera, y la respuesta llega en JSON, sin flujo SSE. El nombre del servidor es benflow, y las herramientas usan los mismos campos de la API.

Herramienta	Qué hace	En la API	Permiso
`quem_sou`	El proyecto y los permisos de la clave.	GET`/eu`	Leer (toda clave)
`listar_chamados`	Lista y filtra las tarjetas.	GET`/chamados`	Leer (toda clave)
`ver_chamado`	Todo de una tarjeta.	GET`/chamados/{numero}`	Leer (toda clave)
`abrir_chamado`	Abre la tarjeta, sin repetir la referencia.	POST`/chamados`	Abrir tarjetas
`comentar`	Comentario público o nota interna.	POST`/chamados/{numero}/comentarios`	Comentar
`acompanhar`	Lo que cambió desde la última vez.	GET`/acompanhar`	Leer (toda clave)
`avaliar_fila`	La cola del proyecto.	GET`/fila`	Leer (toda clave)
`avaliar_carga`	La carga de cada persona y de cada Claude.	GET`/carga`	Leer (toda clave)
`listar_pessoas`	Personas y sectores, con los ids.	GET`/pessoas`	Leer (toda clave)
`decidir`	Prioridad, responsables, plazo, sector y etapa de entrada.	PATCH`/chamados/{numero}`	Decidir

Al conectar, el servidor envía a la IA las instrucciones de uso: el proyecto, los permisos de la clave y cómo abrir sin repetir, seguir y decidir.
En el decidir del MCP, el motivo es obligatorio (al menos 3 caracteres); en la API, es opcional.
Una operación rechazada (sin permiso, tarjeta no encontrada, límite de tarjetas) vuelve como resultado con isError y el mensaje, sin cortar la conversación de la IA.
Una clave incorrecta o el límite de llamadas superado vuelven antes de la herramienta, como error JSON-RPC con el estado HTTP: -32001, o -32029 en el 429.
GET y DELETE en /mcp responden 405: sin sesión, no hay flujo que abrir ni sesión que cerrar.

Sin tarjetas repetidas

Envía referencia_externa en toda tarjeta que abras: el Message-ID del correo, el id de la conversación en WhatsApp o Telegram, el número del pedido en el sistema.
La misma referencia en el mismo proyecto devuelve la tarjeta que ya existe, con criado: false y estado 200, y no cuenta en el límite de tarjetas por hora.
Dos llamadas con la misma referencia al mismo tiempo: la base de datos frena la segunda, y esta recibe la tarjeta de la primera.
Así la IA puede releer la bandeja de entrada o repetir la llamada después de un error de red sin abrir dos tarjetas del mismo pedido.
Para encontrar la tarjeta de una referencia sin abrir nada, usa GET /chamados?referencia_externa=....

Seguir los cambios

benflow todavía no llama a tu IA cuando una tarjeta cambia: ella pregunta.
Llama GET /acompanhar (o la herramienta acompanhar) de vez en cuando, enviando en desde el agora de la respuesta anterior.
Vienen solo las tarjetas que cambiaron, con cada cambio en una línea y los comentarios públicos del equipo. Los comentarios de la propia clave quedan fuera.
Sin desde, vienen las últimas 24 horas; lo más lejos es 7 días, y cada respuesta trae hasta 50 tarjetas.
Una consulta cada pocos minutos cabe holgadamente en el límite de 600 llamadas cada 10 minutos.

Errores

En la API, el error vuelve con el estado HTTP y el cuerpo { "error": "..." }, con el mensaje en el idioma de la cabecera Accept-Language (portugués, inglés o español).

Estado	Cuándo
400	Campo fuera de formato o de límite, o nada que cambiar en el decidir.
401	Clave inválida, desactivada o sin la cabecera.
402	La prueba gratis o la suscripción del proyecto terminó.
403	La clave no tiene el permiso, el proyecto está desactivado o la tarjeta tiene un plan esperando aprobación.
404	Tarjeta no encontrada, archivada o en la papelera.
409	Etapa fuera del alcance de la clave: la tarjeta ya pasó de En curso o la IA del equipo está trabajando en ella.
429	Límite de llamadas, de tarjetas nuevas o de claves incorrectas. El mensaje dice cuánto esperar.

Respuesta 403

{
  "error": "Esta chave não tem a permissão de decidir. Ligue em Conexões, IAs de fora."
}

Límites

Qué	Límite
Llamadas por clave	600 cada 10 minutos, MCP y API sumados
Tarjetas nuevas por clave	60 por hora (la referencia repetida no cuenta)
Claves incorrectas	30 por dirección IP cada 10 minutos
Claves activas	20 por proyecto
Listar tarjetas	30 por respuesta (hasta 100 con limite)
Seguir	Hasta 7 días atrás y 50 tarjetas por respuesta
Textos	Título de 3 a 200, descripción 5.000, comentario 5.000 y motivo 2.000 caracteres

Seguridad

La clave es secreta

Quien tiene la clave actúa en el proyecto con sus permisos. Guárdala en una variable de entorno o en la bóveda de secretos, nunca en el código. Si se filtra, desactívala y crea otra.

El texto de la tarjeta es dato, no instrucción

Título, descripción y comentarios vienen de clientes y de otras personas. Tu IA debe tratar ese texto como dato, nunca como orden (prompt injection).

El secreto pegado sale enmascarado

Una contraseña o token pegado en la descripción o en el comentario se enmascara antes de llegar a la IA y de quedar en la tarjeta.

La IA ve solo lo que es suyo

La clave lee los comentarios públicos y las notas internas que ella misma dejó. Las notas internas del equipo quedan fuera.

¿Listo para conectar tu IA?

Crea la clave en Conexiones y haz la primera tarjeta por la API en pocos minutos.

Crear la clave Ver en la ayuda