API e webhooks

Ligue o Help Desk aos outros sistemas: abra e acompanhe chamados por API e receba avisos assinados a cada evento.

Para a equipe de TI que integra o Help Desk a outros sistemas (ERP, portal do cidadão, sistema de patrimônio, painel de indicadores). Quem configura o Help Desk cria as chaves e os webhooks; o seu sistema usa a API.

Visão geral

Onde encontrar: Help Desk API e webhooks. O documento técnico completo (OpenAPI 3.0) fica em https://sistema.brasmobi.com/api/chamados/v1/index.php?rota=openapi.json — abra numa ferramenta como Swagger UI, Postman ou Insomnia.

Aba Documentação com o endereço da API, o exemplo de pedido e como conferir a assinatura

Chaves da API

Em Chaves da API, clique em Nova chave: dê um nome (o sistema que vai usar), escolha como quem ela age, os escopos, o limite por minuto e, se quiser, os IPs de onde ela pode ser usada.

Token da chave nova mostrado uma única vez
Lista de chaves com escopos, limite e último uso
O token (brhd_…) aparece uma vez. Guardamos só uma impressão dele: se perder, revogue e crie outra.
A chave age como uma pessoa. Valem as permissões, os departamentos e o acesso por campo de quem você escolheu — conferidos a cada pedido (ler contatos, por exemplo, exige que ela atenda chamados, como no painel). Se essa pessoa sair do Help Desk, a chave para de funcionar. Escolha alguém (ou um usuário técnico) com o mínimo necessário.

Validade (opcional). Ao criar a chave você pode dar uma data de validade: ela vale até o fim desse dia e depois responde 401 token_expirado. Em branco, a chave não vence — revogue quando não precisar mais. A lista mostra a validade de cada chave e marca as vencidas.

EscopoPermite
chamados:lerListar e ler chamados, mensagens.
chamados:escreverAbrir e alterar chamados.
comentarios:escreverResponder ao solicitante ou escrever nota interna.
anexos:ler / anexos:escreverBaixar (link de 5 minutos) e enviar anexos.
contatos:ler / contatos:escreverLer e cadastrar solicitantes (cadastro único de pessoas).
objetos:ler / objetos:escreverLer, criar e alterar registros dos objetos personalizados e ligá-los a chamados.

Usando a API

Endereço: https://sistema.brasmobi.com/api/chamados/v1/index.php?rota=<recurso>. Envie a chave em Authorization: Bearer brhd_…. Corpo em JSON (ou multipart quando houver anexos, no campo anexos[]). A sessão do navegador não vale aqui — só a chave.

curl -X POST 'https://sistema.brasmobi.com/api/chamados/v1/index.php?rota=chamados' \
  -H 'Authorization: Bearer brhd_SUA_CHAVE' \
  -H 'Idempotency-Key: pedido-2026-000123' \
  -H 'Content-Type: application/json' \
  -d '{"assunto":"Impressora sem toner","descricao":"Sala 12, recepção",
       "id_departamento":3,"solicitante":{"nome":"Maria","email":"maria@prefeitura.mg.gov.br"},
       "campos":{"equipamento":"impressora"}}'

Recursos

RotaO que faz
GET chamadosLista (filtros: situacao, id_status, id_departamento, id_responsavel, protocolo, atualizado_desde, busca; pagina de 1 a 100.000, por_pagina até 100 — fora disso, 400).
POST chamadosAbre um chamado (canal "API"). Ele nasce no status padrão — a etapa inicial do fluxo, quando o departamento tem fluxo. id_status não é aceito aqui (422 status_na_abertura): mude o status depois.
GET chamados/{id}Um chamado, com campos, fórmulas e a etapa do fluxo.
PATCH chamados/{id}Altera — exige versao (a que você leu). Mudança de status segue o fluxo, inclusive quando o departamento ou a categoria mudam junto (vale a regra do fluxo de antes e a etapa de entrada do novo).
GET/POST chamados/{id}/comentariosMensagens (nota interna só para quem pode ver) e nova mensagem.
GET/POST chamados/{id}/anexosAnexos com link de download (5 min) e envio.
GET/POST chamados/{id}/objetos, DELETE chamados/{id}/objetos/{idRegistro}Registros personalizados ligados ao chamado.
GET/POST contatos, GET contatos/{id}Solicitantes. Cadastrar com o mesmo e-mail devolve o contato existente. Documento sai mascarado.
GET objetos, GET/POST objetos/{slug}/registros, GET/PATCH/DELETE objetos/{slug}/registros/{id}Objetos personalizados e os registros.

Limites e erros

Erros vêm como {"erro": {"codigo": "...", "mensagem": "..."}}: 400 (paginação fora da faixa), 401 (chave ausente, inválida, revogada ou vencida), 403 (escopo, permissão do usuário da chave, IP ou plano), 404 (inclusive id que não é número), 409 (alguém alterou antes — leia de novo), 422 (dados recusados, com a mensagem), 429 (limite).

  • Por minuto, por chave (padrão 120) — 429 limite_minuto;
  • Por mês, pelo plano do negócio — 429 cota_mensal.

As respostas 429 trazem Retry-After (segundos). Os limites valem mesmo com pedidos simultâneos.

Repetir com segurança

Em POST, PATCH e DELETE envie Idempotency-Key (8 a 128 caracteres). Se a conexão cair e você repetir o mesmo pedido com a mesma chave, recebe a mesma resposta (cabeçalho Idempotent-Replayed: true) — o chamado não é aberto duas vezes. A mesma chave com outro corpo é recusada (422) — no envio de arquivos conta o conteúdo de cada arquivo, não só o nome e o tamanho. Vale por 24 horas.

Webhooks

Em Webhooks, cadastre o endereço https do seu sistema e os eventos: chamado aberto, alterado, nova mensagem, atribuído, status, resolvido/fechado, reaberto, anexo, spam, aprovação, transição de fluxo, SLA perto de vencer e vencido, registro personalizado salvo ou excluído e a ação "Chamar webhook" das regras de automação.

Lista de webhooks e as entregas recentes com a situação e a resposta
POST https://seu-sistema.com.br/webhooks/helpdesk
X-Brasmobi-Evento: chamado.status
X-Brasmobi-Entrega: ent_9182
X-Brasmobi-Assinatura: t=1762400000,v1=5f2c…

{"id":"ent_9182","evento":"chamado.status","ocorrido_em":"2026-11-06T10:15:00-03:00",
 "dados":{"idStatusAntes":3,"idStatus":5,"categoria":"resolvido"},
 "chamado":{"id":120,"protocolo":"HD-2026-000120","assunto":"…","status":{…},"url":"…"}}
Use o botão Testar para mandar um teste.ping e ver a resposta do seu sistema na hora.

Conferir a assinatura

Ao criar o webhook você recebe o segredo (whsec_…, mostrado uma vez). Calcule HMAC-SHA256 de t + "." + corpo com o segredo e compare com v1; recuse pedidos com t velho (mais de 5 minutos).

[$t, $v1] = …;   // de X-Brasmobi-Assinatura: t=…,v1=…
$esperado = hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $segredo);
if (!hash_equals($esperado, $v1) || abs(time() - (int)$t) > 300) { http_response_code(401); exit; }

Entregas e falhas

Responda com um código 2xx em até 4 segundos (a conexão tem 2 segundos). Resposta mais lenta conta como falha, mesmo com 2xx — receba, guarde e processe depois. A consulta ao DNS do seu domínio entra nesse tempo (até 2 segundos; respostas grandes, com muitos endereços, são aceitas — pedimos de novo por TCP quando vêm truncadas): DNS que não responde também conta como falha por lentidão, e por 10 minutos as entregas desse webhook ficam só com as retentativas (a cada minuto), sem sair na hora do evento. Usamos o endereço IPv4 do seu domínio quando há um; se ele só tiver IPv6 e o nosso servidor não alcançar IPv6, a entrega falha com "sem rota IPv6" — publique um registro A. A entrega sai logo depois do evento (até 3 por ação; as demais em até 1 minuto) e o envio de um negócio não atrasa o dos outros. Outro código, tempo esgotado ou erro de conexão = nova tentativa em 1, 5 e 15 minutos, 1, 3, 6 e 12 horas. Depois de 15 falhas seguidas o webhook é desligado e quem configura recebe aviso no sino; corrija o endereço e religue. Entregas que falharam podem ser reenviadas à mão por 7 dias.

Consumo e plano

A aba Consumo mostra os pedidos à API no mês e nos últimos 30 dias, por chave e por rota, os webhooks ativos e as entregas, o uso de inteligência artificial e as mensagens enviadas (e-mails, WhatsApp, Telegram). Quando um recurso chega a 80% e a 100% do plano, quem configura recebe um aviso no sino (uma vez por mês).

Consumo da API, webhooks, IA e mensagens, com o gráfico dos últimos 30 dias
Consumo no celular

Segurança e privacidade

  • Token da chave e segredo do webhook são mostrados uma vez; o segredo fica cifrado e o token, só como impressão.
  • Webhook só para https com nome de domínio público: endereço que aponta para rede interna é recusado (ao salvar e a cada envio).
  • Por padrão o webhook não leva nome, e-mail e telefone do solicitante nem, em "nova mensagem", o texto e o nome de quem escreveu (vai só o tipo do autor: agente, solicitante ou sistema). Ligue "Enviar dados pessoais" no webhook se o seu sistema precisar. Nota interna avisa o webhook sem o texto, sempre.
  • O registro dos pedidos guarda método, rota, código, tempo e o IP encurtado — nunca o corpo nem dados pessoais. Tudo o que a API altera vai para a trilha de auditoria em nome do usuário da chave.
  • O Help Desk não executa código do cliente: sua lógica fica no seu sistema, avisada pelos webhooks (veja Por que não há "script").