Para a equipe de TI do órgão gestor

API MobiCidades

API REST para o sistema do órgão gestor ler a fila de ocorrências, devolver o andamento do atendimento e receber eventos em tempo real. Respostas em JSON, autenticação por chave, especificação em OpenAPI 3.1.

openapi.json Emitir chave de API

Autenticação

Toda requisição precisa de uma chave emitida no Portal do Gestor. A chave completa é exibida uma única vez na criação — no banco fica apenas o hash SHA-256. Cada chave tem escopos e limite de requisições por minuto, e pode ser revogada na hora.

Cabeçalho da requisição

X-API-Key: ca_live_xxxxxxxx_yyyyyyyyyyyyyyyy

# ou, equivalente:
Authorization: Bearer ca_live_xxxxxxxx_yyyyyyyyyyyyyyyy

Envelope da resposta

{
  "ok": true,
  "dados": [ ... ],
  "meta": { "pagina": 1, "por_pagina": 50, "total": 128, "paginas": 3 }
}

// em caso de erro
{ "ok": false, "erro": "Chave inválida ou revogada." }

Escopos

ocorrencias:lerLer ocorrênciasListar e consultar ocorrências e sua trilha de atendimento.
ocorrencias:atenderAtender ocorrênciasMudar status, responder oficialmente e devolver o protocolo do sistema do órgão.
ocorrencias:escreverRegistrar ocorrênciasCriar ocorrências a partir de outro canal (ouvidoria, telefone, WhatsApp).
linhas:lerLer linhasConsultar o cadastro de linhas e empresas.
estatisticas:lerLer estatísticasConsultar indicadores agregados e desempenho de SLA.

Endpoints

Base: https://mobicidades.maisfacilteresina.com.br/api/v1

GET/ocorrenciasocorrencias:ler
Lista a fila de ocorrências do órgão, com filtros e paginação.
status
nova, triagem, encaminhada, em_atendimento, resolvida, improcedente (separados por vírgula)
tipo
slug do tipo (quebrado, atraso, lotacao…), separados por vírgula
linha
código da linha, ex.: 0203
bairro
busca parcial no bairro
desde / ate
recorte de data no formato ISO 8601
sla
vencidas | no_prazo
pagina / por_pagina
paginação; por_pagina vai até 200
GET/ocorrencias/{id|protocolo}ocorrencias:ler
Detalha uma ocorrência com toda a trilha de atendimento, inclusive notas internas.
id
UUID da ocorrência ou o protocolo (MC-2026-000123)
PATCH/ocorrencias/{id|protocolo}ocorrencias:atender
Devolve o andamento: muda a situação, publica a resposta oficial e amarra o protocolo interno do órgão.
status
triagem | em_atendimento | resolvida | improcedente
resposta
texto da resposta oficial ao cidadão
protocolo_externo
número usado no sistema do órgão
sistema_externo
nome do sistema de origem, ex.: SIGEP
publicar_resposta
false registra como nota interna
POST/ocorrenciasocorrencias:escrever
Registra no mapa público uma demanda que chegou pela ouvidoria, telefone ou atendimento presencial.
tipo
slug do tipo (obrigatório)
linha_codigo
código da linha
veiculo_prefixo
prefixo do ônibus
latitude / longitude
coordenadas do local
descricao, endereco, bairro
detalhes do relato
protocolo_externo
protocolo de origem no órgão
GET/linhaslinhas:ler
Cadastro de linhas com contagem de ocorrências abertas e dos últimos 30 dias.
busca
filtro por código ou nome
ativas
false inclui linhas desativadas
GET/tiposocorrencias:ler
Tipos de ocorrência disponíveis e o prazo (SLA) de cada um.
GET/estatisticasestatisticas:ler
Indicadores agregados prontos para dashboard: resumo, série diária, ranking e SLA por órgão.
dias
janela de análise, 1 a 365 (padrão 30)

Exemplos

1. Puxar a fila com prazo vencido

bash

curl -s "https://mobicidades.maisfacilteresina.com.br/api/v1/ocorrencias?sla=vencidas&por_pagina=100" \
  -H "X-API-Key: $CHEGO_API_KEY" | jq '.dados[] | {protocolo, tipo: .tipo.nome, linha: .linha.codigo, prazo_sla}'

2. Devolver o andamento e publicar a resposta ao cidadão

bash

curl -s -X PATCH "https://mobicidades.maisfacilteresina.com.br/api/v1/ocorrencias/MC-2026-000123" \
  -H "X-API-Key: $CHEGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolvida",
    "resposta": "Veículo recolhido para manutenção e substituído na linha no mesmo dia. Equipe de fiscalização notificou a operadora.",
    "protocolo_externo": "2026/0001234",
    "sistema_externo": "SIGEP",
    "publicar_resposta": true
  }'

3. Registrar uma demanda que chegou pela ouvidoria

bash

curl -s -X POST "https://mobicidades.maisfacilteresina.com.br/api/v1/ocorrencias" \
  -H "X-API-Key: $CHEGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "nao_passou",
    "linha_codigo": "0203",
    "descricao": "Usuária relatou por telefone que o ônibus das 6h20 não passou.",
    "bairro": "Dirceu",
    "latitude": -5.0892,
    "longitude": -42.8019,
    "protocolo_externo": "OUV-2026-4471"
  }'

Webhooks

Em vez de ficar consultando a API, o órgão pode cadastrar uma URL e receber os eventos na hora. Cada entrega vai assinada em HMAC-SHA256; entregas que falham são reenviadas com espera progressiva (1, 5, 15, 60 e 360 minutos).

ocorrencia.criada
ocorrencia.status_alterado
ocorrencia.resolvida
ocorrencia.confirmada
ocorrencia.sla_vencido

Requisição recebida pelo órgão

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-Chego-Evento: ocorrencia.criada
X-Chego-Entrega: 4f1c…
X-Chego-Assinatura: t=1767225600,v1=9a3f…

{
  "evento": "ocorrencia.criada",
  "dados": {
    "protocolo": "MC-2026-000123",
    "status": "encaminhada",
    "tipo": { "slug": "quebrado", "nome": "Ônibus quebrado", "sla_horas": 24 },
    "linha": { "codigo": "0203", "nome": "Dirceu / Centro" },
    "prazo_sla": "2026-01-02T10:00:00.000Z"
  },
  "enviado_em": "2026-01-01T10:00:00.000Z"
}

Validação da assinatura (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

function assinaturaValida(cabecalho, corpoCru, segredo) {
  const partes = Object.fromEntries(
    cabecalho.split(",").map((p) => p.split("=")),
  );
  const esperada = createHmac("sha256", segredo)
    .update(partes.t + "." + corpoCru)
    .digest("hex");

  // rejeita entregas antigas (proteção contra reenvio)
  if (Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return false;

  return timingSafeEqual(
    Buffer.from(esperada, "hex"),
    Buffer.from(partes.v1, "hex"),
  );
}