bFocus API

{
  "openapi": "3.1.0",
  "info": {
    "title": "bFocus API pública",
    "version": "1.0.0",
    "description": "API pública do bFocus. Use as SDKs oficiais (Python, Node/TS, PHP, .NET, Java, Go, Ruby) ou HTTP direto.\n\n## Autenticação\n`Authorization: Bearer <chave>`. Crie chaves em **Integrações → Chaves de API**, cada uma com os\nescopos que precisa. A chave legada (`bf_sk…`) só alcança clientes (`customers:*`).\n\n## Escopos\n- `customers:read` — Ler clientes, contatos, pessoas, produtos vinculados e interações\n- `customers:write` — Cadastrar, atualizar e excluir clientes, contatos, pessoas, identificadores extras e interações\n- `products:read` — Ler o catálogo de produtos\n- `products:write` — Cadastrar, atualizar e arquivar produtos\n- `kb:read` — Ler e buscar artigos da base de conhecimento\n- `kb:write` — Criar, atualizar, publicar e excluir artigos da base de conhecimento\n- `ai_agents:read` — Ler os agentes de IA\n- `ai_agents:preview` — Testar a resposta de um agente de IA (consome IA do tenant)\n- `widget:sign` — Assinar a identidade do usuário do widget (sem guardar segredo no seu servidor)\n- `tickets:read` — Ler chamados e a conversa deles\n- `tickets:write` — Comentar em chamados e mudar status, prioridade, responsável\n- `tickets:reply` — Responder ao cliente nos chamados (sai por e-mail ou widget, em nome de quem responde)\n- `tasks:read` — Ler tarefas e a conversa delas\n- `tasks:write` — Comentar em tarefas e mudar status, prioridade, responsável e prazo\n- `release_notes:read` — Ler release notes\n- `release_notes:write` — Criar, atualizar e publicar release notes\n- `projects:read` — Ler projetos, a situação deles e a leitura do radar de risco\n- `monitor:read` — Ler os erros capturados pelo Monitoramento (resumo, lista e detalhe com ocorrências)\n- `monitor:write` — Agir nos erros do Monitoramento: resolver, ignorar, juntar, investigar e abrir demanda\n\n## Respostas\nSucesso: `{\"code\": <status>, \"data\": …, \"message\": \"…\"}` (listas paginadas trazem `pagination`).\nErro: `{\"code\": <status>, \"data\": null, \"message\": \"<CÓDIGO>\", \"error\": \"<CÓDIGO>\", \"validation\": {}, \"request_id\": \"…\"}`.\n**Use sempre `error`** na sua lógica — é estável. Toda resposta traz `X-Request-Id`.\n\n## Erros comuns a todas as operações\n- `INTEGRATION_KEY_MISSING` — 401 — faltou `Authorization: Bearer <chave>`\n- `INTEGRATION_KEY_INVALID` — 401 — chave desconhecida\n- `INTEGRATION_KEY_REVOKED` — 401 — chave revogada\n- `INTEGRATION_DISABLED` — 403 — chave desligada no painel\n- `INTEGRATION_HOST_FORBIDDEN` — 403 — o IP de origem não está na lista de IPs liberados da chave\n- `INTEGRATION_SCOPE_MISSING` — 403 — a chave não tem o escopo da operação (header `X-Required-Scope`)\n- `MODULE_NOT_CONTRACTED` — 403 — a empresa não contratou o módulo da operação (header `X-Required-Module`; ver `x-module`)\n- `TENANT_NOT_FOUND` — 404 — conta inativa\n- `VALIDATION_ERROR` — 422 — corpo ou parâmetro inválido (detalhe em `validation`)\n- `RATE_LIMITED` — 429 — limite de requisições da chave (header `Retry-After`)\n- `IDEMPOTENCY_KEY_INVALID` — 422 — `Idempotency-Key` vazia ou com mais de 255 caracteres\n- `IDEMPOTENCY_KEY_REUSED` — 422 — a mesma `Idempotency-Key` com outra requisição\n- `IDEMPOTENCY_IN_PROGRESS` — 409 — a requisição original com esta chave ainda está rodando\n- `INTERNAL_ERROR` — 500 — erro interno (informe o `request_id`)\n\n## Idempotência\nEnvie `Idempotency-Key: <uuid>` em POST/PUT/PATCH/DELETE: repetir a chamada com a mesma chave\n(e a mesma requisição) devolve a resposta original com `Idempotent-Replayed: true`, sem executar\nde novo. As SDKs fazem isso sozinhas em toda nova tentativa.\n\n## SDK em uso\nAs SDKs enviam `X-Bfocus-Client: bfocus-<linguagem>/<versão>`. É assim que avisamos você quando\numa correção exigir atualizar a SDK.\n",
    "contact": {
      "name": "Berni Software",
      "url": "https://bfocus.com.br"
    }
  },
  "servers": [
    {
      "url": "https://api.bfocus.com.br",
      "description": "bFocus API host"
    }
  ],
  "paths": {}
}