LBHM Tasks

API — Visão geral

O LBHM Tasks expõe uma API HTTP (JSON) para que outros sistemas criem e consultem tarefas automaticamente. O uso típico é enviar tarefas geradas por um sistema (uma pendência, uma exceção, uma solicitação) para que a equipe certa as receba e acompanhe.

Endereço base

Todas as rotas ficam sob o prefixo /api/v1 no endereço da sua organização:

https://suaorganizacao.tasks.lbhm.com.br/api/v1

O endereço exato é informado pela LBHM.

Autenticação

A API usa um token enviado no cabeçalho Authorization:

Authorization: Bearer SEU_TOKEN

Se o sistema de origem não permitir montar o cabeçalho Authorization, envie o mesmo valor em X-Api-Token:

X-Api-Token: SEU_TOKEN

Os tokens ficam em Tokens de API, no menu lateral: cada um tem um nome e pode ser revogado quando você quiser — ao revogar, as chamadas que usam aquele token param de ser aceitas na hora. O valor completo aparece uma única vez, no momento em que o token é gerado; copie-o ali. Trate-o como um segredo: ele dá acesso à API da sua organização. Requisições sem token válido recebem 401 Unauthorized.

Formato

  • Corpo das requisições e respostas em JSON (Content-Type: application/json).
  • Datas em texto no formato AAAA-MM-DD HH:MM:SS (horário de Brasília) ou ISO 8601.
  • Códigos de resposta seguem o padrão HTTP: 200/201 em sucesso, 401 sem autenticação, 422 quando faltam campos obrigatórios, 404 quando o recurso não existe. Cada recusa e o que fazer com ela estão em Erros e respostas da API.

Valores de referência

  • Status de tarefa: aberta, em_andamento, bloqueada, concluida, cancelada, resolvido, nao_se_aplica.
  • Prioridade: baixa, media, alta, urgente.

Quatro desses status — concluida, cancelada, resolvido e nao_se_aplica — encerram a tarefa. Nas rotas de atualização (PATCH /api/v1/tasks/by-ref e PATCH /api/v1/tasks/{id}/status), aplicar um deles exige o campo motivo com a explicação do desfecho; sem ele a requisição volta com 422 e a tarefa permanece como está.

Na criação (POST /api/v1/tasks) o motivo não é cobrado: uma tarefa enviada já com um status de encerramento é criada 201, encerrada, com a data do desfecho carimbada — e o histórico dela fica sem a explicação, que ninguém consegue acrescentar depois. Se o desfecho importa, crie a tarefa aberta e encerre-a pelo PATCH, com o motivo.

Onde cada valor é conferido

O ponto em que um valor fora da lista aparece como erro muda conforme a rota:

  • status — na criação, um valor fora da lista não é recusado: a tarefa nasce aberta. Nas rotas de atualização, volta 422 status inválido.
  • prioridade — em qualquer rota, um valor fora da lista vira media, sem recusa.

Confira o texto que a sua integração envia: um valor escrito errado nesses dois campos não gera erro na criação, e a diferença só aparece na tela, na tarefa já gravada.

Idempotência

Ao enviar tarefas, informe um par origem + referencia_externa (veja Tarefas). Reenviar a mesma combinação atualiza a tarefa existente em vez de criar uma duplicada — útil para reentregas e reprocessamentos seguros.

Conferir a instância antes de subir carga

GET /health/deep
Authorization: Bearer SEU_TOKEN

Responde com a situação da instância — é a forma de confirmar que o endereço está certo e que o seu token vale, sem criar nenhuma tarefa para descobrir. Usa a mesma autenticação das rotas /api/v1 (fora do prefixo, por ser um endereço de verificação).

{
  "instance": "LBHM Tasks",
  "version": "0.17.1",
  "status": "ok",
  "latency_ms": 38,
  "checked_at": "2026-08-11T09:14:22-03:00"
}

O campo status vale ok, degraded (a instância atende, mas algo de que ela depende está oscilando) ou down. Só o down responde 503; os outros dois respondem 200. Trate degraded como no ar: envie as tarefas normalmente e, se o sintoma persistir, fale com a LBHM.

Próximas páginas