Para desenvolvedores

API e MCP do benflow

Ligue o Hermes, o OpenClaw, o Claude Code ou o sistema da sua loja ao quadro do projeto. Com uma chave por conexão, a IA ou o sistema abre cards, comenta, acompanha o que mudou e organiza a fila.

Criar a chave Passo a passo na ajuda

MCP remoto

Para IAs: Hermes, OpenClaw, Claude Code, Cursor e qualquer cliente MCP por HTTP.

https://benflow.net/mcp

API REST

Para sistemas e automações: n8n, Zapier, o sistema da loja ou o ERP.

https://benflow.net/api/v1

Funciona com

Hermes
OpenClaw
Claude Code
Cursor
n8n
Zapier

Começar em 3 passos

1
Crie a chave
No painel, em Conexões, na linha IAs de fora (MCP e API), toque em Conectar. Escolha a IA ou o sistema, o que a chave pode fazer e o setor dos cards. Só o administrador do projeto cria chaves, e cada chave aparece uma vez só.
2
Cole na IA ou no sistema
A janela mostra o trecho certo para cada um, já com a chave dentro. Os mesmos trechos estão logo abaixo, com o lugar da chave marcado.
3
Teste a ligação
Peça para a IA usar a ferramenta quem_sou ou chame GET /api/v1/eu: a resposta traz o projeto e as permissões da chave.

Testar a chave

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

Ligue a sua IA ou o seu sistema

As IAs entram pelo servidor MCP; sistemas e automações, pela API. Escolha abaixo e copie o trecho: troque bfx_sua_chave pela chave criada no painel.

Hermes

O agente da Nous Research que lê e-mails e conversa pelo WhatsApp e pelo Telegram.

No arquivo ~/.hermes/config.yaml, dentro de mcp_servers:

~/.hermes/config.yaml

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

Depois, na conversa com o Hermes, mande /reload-mcp. Para conferir no terminal: hermes mcp test benflow.

Orientação para a IA (opcional). Ao ligar, o servidor MCP já manda à IA o projeto, as permissões da chave e como usar as ferramentas. Para reforçar, cole no prompt dela:

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.

Autenticação

Toda chamada leva a chave no cabeçalho Authorization, no formato Bearer. A chave começa com bfx_ e tem mais 43 caracteres. Nos exemplos, ela está na variável de ambiente BENFLOW_CHAVE.

Cabeçalho

Authorization: Bearer bfx_sua_chave

Uma chave por IA ou sistema: o card e o comentário mostram o nome dela (por exemplo, Hermes do atendimento), e desligar uma não derruba as outras.
A chave aparece só na hora de criar. O benflow guarda o resumo dela (sha256) e os 4 últimos caracteres: se perder, crie outra.
Desligar recusa a chave na próxima chamada e não tem volta. Os cards e comentários que ela fez continuam no projeto.
Até 20 chaves ligadas por projeto. Sem cookie, sem sessão e sem CSRF: só o cabeçalho.

O que cada chave pode fazer

Permissão	O que libera	Na chave nova
Ler (toda chave)	Cards, comentários públicos, histórico, fila, carga, pessoas e setores.	Sempre
Abrir cards	Abrir cards em A fazer, com o contato de quem pediu.	Ligada
Comentar	Comentário público (quem pediu vê) ou nota interna.	Ligada
Decidir	Prioridade, responsáveis, prazo, setor e a etapa entre A fazer, Em andamento e Fechado.	Desligada

A chave também pode ter um setor: os cards que ela abre sem setor entram nele. O administrador muda as permissões e o setor a qualquer hora, sem trocar a chave.

Referência da API

Endereço base https://benflow.net/api/v1. Pedidos e respostas em JSON (UTF-8), com os campos em português, os mesmos nomes do MCP. Datas e horas em ISO 8601 (UTC); prazo em AAAA-MM-DD. Tudo vale só no projeto da chave, e o número do card é o mesmo do painel.

Quem é a chave

GET/api/v1/eu

O projeto ligado à chave e as permissões dela. É o primeiro teste depois de colar a chave.

Permissão: Ler (toda chave)

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

Resposta 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 cards

GET/api/v1/chamados

Os cards do projeto, do que mudou por último ao mais antigo. Sem filtro, vêm os abertos: A fazer, Em andamento, Em homologação e Em produção.

Permissão: Ler (toda chave)

No endereço (query)

etapastring: Uma etapa (a_fazer | em_andamento | em_homologacao | em_producao | concluido | fechado), abertos (padrão) ou todos.
buscastring: Texto no título, na descrição ou no pedido original, ou o número do card. Até 200 caracteres.
responsavelinteger: Id da pessoa (veja GET /pessoas).
setorinteger: Id do setor (veja GET /pessoas).
atrasadosboolean: Só os cards com o prazo vencido.
referencia_externastring: Acha o card de um e-mail ou pedido já mandado (até 300 caracteres). Devolve 0 ou 1 card.
minha_iaboolean: Só os cards que esta chave abriu.
limiteinteger: De 1 a 100. Padrão: 30. O total da resposta conta todos os que passaram no filtro.

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

Resposta 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 um card

POST/api/v1/chamados

Abre o card em A fazer, com o nome da chave como origem e o contato de quem pediu. Com a mesma referencia_externa, devolve o card que já existe em vez de abrir outro.

Permissão: Abrir cards

201 com criado: true quando o card nasce; 200 com criado: false e o card de antes quando a referência já existia.

No corpo (JSON)

titulostringobrigatório: De 3 a 200 caracteres.
descricaostring: O pedido em poucas linhas, até 5.000 caracteres. Senha ou token colado no texto sai mascarado.
prioridadestring: urgente | alta | normal | baixa
tipostring: bug | melhoria | funcionalidade
prazostring: Data no formato AAAA-MM-DD.
setorinteger: Id do setor. Sem ele, o card entra no setor da chave.
responsaveisinteger[]: Ids das pessoas, até 10.
referencia_externastring: O Message-ID do e-mail, o id da conversa ou do pedido no sistema de origem, até 300 caracteres.
solicitanteobject: Quem pediu: nome (até 120), email (até 200) e telefone (até 40), todos opcionais.

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

Resposta 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 um card

GET/api/v1/chamados/{numero}

Tudo de um card: descrição, pedido original, quem pediu, a referência, os comentários e o histórico (as últimas 30 mudanças).

Permissão: Ler (toda chave)

A chave lê os comentários públicos e as notas internas que ela mesma deixou. As notas internas da equipe ficam de fora.
Card arquivado ou na lixeira responde 404.

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

Resposta 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 no card. Público (o padrão): quem pediu vê, e no card que veio pelo Telegram a resposta vai para lá. Com interno, vira nota só da equipe.

Permissão: Comentar

No corpo (JSON)

textostringobrigatório: De 1 a 5.000 caracteres.
internoboolean: true para nota interna. Padrão: 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."
  }'

Resposta 201

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

Decidir

PATCH/api/v1/chamados/{numero}

Muda prioridade, responsáveis, prazo, setor e a etapa de entrada. Mande só o que muda; a resposta traz o card como ficou.

Permissão: Decidir

A etapa só muda num card em A fazer ou Em andamento e sem a IA da equipe trabalhando nele (senão, 409). Homologação, produção e Concluído seguem com a esteira do benflow, não com a chave.
Levar para Em andamento um card com plano esperando aprovação responde 403.

No corpo (JSON)

prioridadestring: urgente | alta | normal | baixa
responsaveisinteger[]: Substitui a lista inteira, até 10 ids.
prazostring | null: AAAA-MM-DD; null tira o prazo.
setorinteger | null: Id do setor; null tira o setor.
etapastring: a_fazer | em_andamento | fechado
motivostring: Por que decidiu, até 2.000 caracteres. Vai para o histórico e, se a chave pode comentar, vira nota interna no card.

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

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

Acompanhar o que mudou

GET/api/v1/acompanhar

Os cards que mudaram desde uma hora: etapa, responsáveis e campos, comentários públicos da equipe e o andamento da IA da equipe.

Permissão: Ler (toda chave)

Guarde o agora da resposta e mande em desde na próxima vez. Vêm até 50 cards por resposta.

No endereço (query)

desdestring: Data e hora em ISO 8601, por exemplo 2026-10-19T14:00:00Z. Padrão: as últimas 24 horas; no máximo 7 dias para trás.
numerointeger: Só um card.
minha_iaboolean: Só os cards que esta chave abriu.

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

Resposta 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
    }
  ]
}

Avaliar a fila

GET/api/v1/fila

Os abertos por etapa e prioridade, bugs, sem responsável, atrasados, os que vencem em 3 dias, o que entrou e saiu na semana, os mais antigos em A fazer e a fila da IA da equipe. As observações são só fatos contados.

Permissão: Ler (toda chave)

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

Resposta 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."
  ]
}

Avaliar a carga

GET/api/v1/carga

A carga de cada pessoa (abertos, em andamento, atrasados, urgentes e altas, concluídos na semana), da mais carregada à menos, e o que cada Claude da equipe faz agora e tem na fila.

Permissão: Ler (toda chave)

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

Resposta 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
    }
  ]
}

Pessoas e setores

GET/api/v1/pessoas

Quem pode ser responsável e os setores do projeto, com os ids para abrir e decidir.

Permissão: Ler (toda chave)

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

Resposta 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"
    }
  ]
}

O card na resposta

A lista, o abrir e o decidir devolvem o card neste formato. O ver traz os mesmos campos e mais os do detalhe.

Campos do card

numerointeger: O número do card no projeto, o mesmo do painel (#128).
titulostring: O título.
etapastring: a_fazer | em_andamento | em_homologacao | em_producao | concluido | fechado
etapa_nomestring: O nome da etapa como aparece no quadro (A fazer, Em andamento...).
prioridadestring: urgente | alta | normal | baixa
tipostring | null: bug | melhoria | funcionalidade
setorstring | null: O nome do setor.
prazostring | null: AAAA-MM-DD.
atrasadoboolean: Prazo vencido num card ainda aberto.
responsaveisobject[]: { id, nome }
origemstring: Por onde o card chegou: IA de fora (com o nome da chave), Telegram, E-mail, Widget do site, Link externo, Reunião, Terminal, a ferramenta de monitoramento ou Painel.
card_principalinteger | null: O número do card principal, quando este é um subcard.
iaobject | null: O trabalho da IA da equipe no card: { etapa, percentual, situacao, agente }.
aberto_emstring: Data e hora em ISO 8601 (UTC).
atualizado_emstring: A última mudança, em ISO 8601 (UTC).
linkstring: O endereço do card no painel.

Só no ver um card

descricaostring: A descrição, com senhas e tokens mascarados.
pedido_originalstring | null: O texto original do pedido, quando o card guarda um.
solicitanteobject | null: { nome, email, telefone }
referencia_externastring | null: A referência mandada ao 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"
}

Ferramentas do MCP

O servidor MCP fica em https://benflow.net/mcp, no transporte Streamable HTTP e sem sessão: cada pedido é um POST com a chave no cabeçalho, e a resposta vem em JSON, sem fluxo SSE. O nome do servidor é benflow, e as ferramentas usam os mesmos campos da API.

Ferramenta	O que faz	Na API	Permissão
`quem_sou`	O projeto e as permissões da chave.	GET`/eu`	Ler (toda chave)
`listar_chamados`	Lista e filtra os cards.	GET`/chamados`	Ler (toda chave)
`ver_chamado`	Tudo de um card.	GET`/chamados/{numero}`	Ler (toda chave)
`abrir_chamado`	Abre o card, sem repetir a referência.	POST`/chamados`	Abrir cards
`comentar`	Comentário público ou nota interna.	POST`/chamados/{numero}/comentarios`	Comentar
`acompanhar`	O que mudou desde a última vez.	GET`/acompanhar`	Ler (toda chave)
`avaliar_fila`	A fila do projeto.	GET`/fila`	Ler (toda chave)
`avaliar_carga`	A carga de cada pessoa e de cada Claude.	GET`/carga`	Ler (toda chave)
`listar_pessoas`	Pessoas e setores, com os ids.	GET`/pessoas`	Ler (toda chave)
`decidir`	Prioridade, responsáveis, prazo, setor e etapa de entrada.	PATCH`/chamados/{numero}`	Decidir

Ao ligar, o servidor manda para a IA as instruções de uso: o projeto, as permissões da chave e como abrir sem repetir, acompanhar e decidir.
No decidir do MCP, o motivo é obrigatório (no mínimo 3 caracteres); na API, é opcional.
Operação recusada (sem a permissão, card não encontrado, limite de cards) volta como resultado com isError e a mensagem, sem derrubar a conversa da IA.
Chave errada ou limite de chamadas estourado voltam antes da ferramenta, como erro JSON-RPC com o status HTTP: -32001, ou -32029 no 429.
GET e DELETE em /mcp respondem 405: sem sessão, não há fluxo para abrir nem sessão para encerrar.

Sem card repetido

Mande referencia_externa em todo card aberto: o Message-ID do e-mail, o id da conversa no WhatsApp ou no Telegram, o número do pedido no sistema.
A mesma referência no mesmo projeto devolve o card que já existe, com criado: false e status 200, e não conta no limite de cards por hora.
Duas chamadas com a mesma referência ao mesmo tempo: o banco segura a segunda, e ela recebe o card da primeira.
Assim a IA pode reler a caixa de e-mail ou repetir a chamada depois de um erro de rede sem abrir dois cards do mesmo pedido.
Para achar o card de uma referência sem abrir nada, use GET /chamados?referencia_externa=....

Acompanhar as mudanças

O benflow ainda não chama a sua IA quando um card muda: ela pergunta.
Chame GET /acompanhar (ou a ferramenta acompanhar) de tempos em tempos, mandando em desde o agora da resposta anterior.
Vêm só os cards que mudaram, com cada mudança numa linha e os comentários públicos da equipe. Os comentários da própria chave ficam de fora.
Sem desde, vêm as últimas 24 horas; o mais longe é 7 dias, e cada resposta traz até 50 cards.
Uma pergunta a cada poucos minutos cabe folgado no limite de 600 chamadas a cada 10 minutos.

Erros

Na API, o erro volta com o status HTTP e o corpo { "error": "..." }, com a mensagem no idioma do cabeçalho Accept-Language (português, inglês ou espanhol).

Status	Quando
400	Campo fora do formato ou do limite, ou nada para mudar no decidir.
401	Chave inválida, desligada ou sem o cabeçalho.
402	O teste grátis ou a assinatura do projeto acabou.
403	A chave não tem a permissão, o projeto está desativado ou o card tem plano esperando aprovação.
404	Card não encontrado, arquivado ou na lixeira.
409	Etapa fora do alcance da chave: o card já passou de Em andamento ou a IA da equipe está trabalhando nele.
429	Limite de chamadas, de cards novos ou de chaves erradas. A mensagem diz quanto esperar.

Resposta 403

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

Limites

O quê	Limite
Chamadas por chave	600 a cada 10 minutos, MCP e API somados
Cards novos por chave	60 por hora (referência repetida não conta)
Chaves erradas	30 por endereço IP a cada 10 minutos
Chaves ligadas	20 por projeto
Listar cards	30 por resposta (até 100 com limite)
Acompanhar	Até 7 dias para trás e 50 cards por resposta
Textos	Título de 3 a 200, descrição 5.000, comentário 5.000 e motivo 2.000 caracteres

Segurança

A chave é segredo

Quem tem a chave age no projeto com as permissões dela. Guarde em variável de ambiente ou no cofre de segredos, nunca no código. Vazou: desligue e crie outra.

Texto de card é dado, não instrução

Título, descrição e comentários vêm de clientes e de outras pessoas. A sua IA deve tratar esse texto como dado, nunca como ordem (prompt injection).

Segredo colado sai mascarado

Senha ou token colado na descrição ou no comentário é mascarado antes de chegar à IA e de ficar no card.

A IA vê só o que é dela

A chave lê os comentários públicos e as notas internas que ela mesma deixou. As notas internas da equipe ficam de fora.

Pronto para ligar a sua IA?

Crie a chave em Conexões e faça o primeiro card pela API em poucos minutos.

Criar a chave Ver na ajuda