Referência: quem chama o quê, eventos, erros
O que a API gerada não carrega: quem pode chamar cada verbo, quem recebe cada evento no , os três ids, as duas famílias de erro e o cadastro do . Tudo aqui vem do manifesto e da exposição; contrato jornada 1.0.0 e ocorrencia 1.0.0.
Modelo e status
: registrada → despachada → em_atendimento → controlada → encerrada, ou cancelada de qualquer status não terminal exceto controlada. O agregado traz id, versao (monotônica a partir de 1), criadoEm, atualizadoEm, registradaEm, status, os dados de negócio, referenciaExterna, e encerradaEm ou canceladaEm com motivoCancelamento no status correspondente.
: designado → aceito → em_deslocamento → no_local → encerrado, ou recusado e cancelado. Traz id, ocorrenciaId, recurso ({ tipo: 'guarnicao', guarnicaoId, <Termo id="t-052">viatura</Termo>, composicao, identificador } ou recurso avulso), instrucoes, um instante por marco e resultado no encerramento. Cancelar o último despacho aberto devolve a ocorrência a registrada.
: apresentada → iniciada → encerrada → liberada, com em_pausa entre. { id, usuario, status, versao } mais apresentadaEm, iniciadaEm e posto ({ modalidade, unidade?, descricao? }; a modalidade é id do catálogo do ), encerradaEm e pendencias nas terminais.
: constituida → disponivel → designada → em_deslocamento → no_local, com em_pausa, em_desmobilizacao, e as terminais desmobilizada e dissolvida. `{ id, viatura, composicao: [{ usuario,
comandante, motorista, patrulheiro. A guarnição acompanha o despacho, e o evento carrega o despachoId.
Pausa: tipos refeicao_principal, lanche, descanso_regulamentar, pessoal, medica, tecnica, administrativa, abastecimento, manutencao_emergencial; status em_curso, concluida, interrompida.
Todas as rotas
Sob /plugins, com Bearer. "Quem" é o papel que alcança o verbo; fora disso, 403 SEM_CAPACIDADE. Os caminhos de cada operação, os corpos e as respostas estão na API.
| Ocorrência | verbo | quem |
|---|---|---|
POST /ocorrencias | registrarOcorrencia | , central |
GET /ocorrencias | listarOcorrenciasAbertas | leitura |
GET /ocorrencias/{id} | obterOcorrencia | leitura |
PATCH /ocorrencias/{id} | atualizarOcorrencia | CAD, central |
POST /ocorrencias/{id}/controle | declararControlada | CAD, central, no local |
POST /ocorrencias/{id}/encerramento | encerrarOcorrencia | CAD, central, equipe no local |
POST /ocorrencias/{id}/cancelamento | cancelarOcorrencia | CAD, central |
POST /ocorrencias/{ocorrenciaId}/despachos | despachar | CAD, |
GET /ocorrencias/{ocorrenciaId}/despachos | listarDespachos | leitura |
GET /ocorrencias/{ocorrenciaId}/registro | listarRegistro | leitura |
POST /ocorrencias/em-campo | registrarOcorrenciaEmCampo | equipe |
GET /despachos/{id} | obterDespacho | leitura |
POST /despachos/{id}/cancelamento | cancelarDespacho | CAD, central |
POST /despachos/{id}/aceite · /recusa | aceitarDespacho · recusarDespacho | equipe |
POST /despachos/{id}/deslocamento · /chegada | iniciarDeslocamento · registrarChegada | equipe |
POST /despachos/{despachoId}/acoes · /situacoes · /apoios | registrarAcao · atualizarSituacao · solicitarApoio | equipe |
POST /despachos/{id}/encerramento | encerrarDespacho | equipe |
GET /guarnicoes/{guarnicaoId}/despachos | listarDespachosDaGuarnicao | equipe, CAD |
| Jornada | verbo | quem |
|---|---|---|
POST /policiais/{usuario}/apresentacao | registrarApresentacao | policial, CAD |
POST /jornadas/{id}/inicio · /encerramento | iniciarJornada · encerrarJornada | policial, CAD |
POST /jornadas/{id}/liberacao | liberarPolicial | supervisor |
POST /jornadas/{jornadaId}/pausas | iniciarPausa | policial, supervisor |
POST /pausas/{id}/encerramento · /interrupcao | encerrarPausa · interromperPausa | policial, supervisor |
POST /guarnicoes | constituirGuarnicao | supervisor, CAD |
GET /guarnicoes | listarGuarnicoesDisponiveis | leitura |
POST /guarnicoes/{id}/substituicoes · /dissolucao | substituirIntegrante · dissolverGuarnicao | supervisor, CAD |
POST /guarnicoes/{id}/comando | assumirComando | comandante, CAD |
POST /guarnicoes/{id}/prontidao · /saida-de-prontidao | declararProntidao · retirarDeProntidao | comandante, CAD |
POST /guarnicoes/{id}/pausas · /desmobilizacao · /desmobilizacao-concluida | iniciarPausaDaGuarnicao · solicitarDesmobilizacao · concluirDesmobilizacao | comandante, supervisor |
GET /jornadas/{id} · /pausas/{id} · /guarnicoes/{id} | obterJornada · obterPausa · obterGuarnicao | leitura |
GET /policiais/{usuario}/jornada-ativa · /guarnicao · /guarnicao-disponivel | obterJornadaAtiva · obterGuarnicaoDoUsuario · guarnicaoDisponivelDoUsuario | policial, leitura |
GET /viaturas/{viatura}/guarnicao · /guarnicao-disponivel | obterGuarnicaoDaViatura · guarnicaoDisponivelNaViatura | central, CAD |
As tabelas ALCANCE_DO_INTEGRADOR_NA_OCORRENCIA e ALCANCE_DO_INTEGRADOR_NA_JORNADA da exposição são a fonte do que o integrador alcança. Entre os papéis humanos, o despachante despacha; o operador de central registra e consulta mas não despacha; o supervisor operacional não tem capacidade de ocorrência.
Todos os eventos
tipo | quando | payload | quem recebe no webhook |
|---|---|---|---|
ocorrencia:registrada | a ocorrência nasceu | { ocorrencia }, o agregado inteiro | o integrador originador |
ocorrencia:atualizada | dados de negócio mudaram | { id, alteracoes, versao } | o integrador originador |
ocorrencia:mudou-status | a ocorrência mudou de status | { id, de, para, motivo?, versao } | o integrador originador |
ocorrencia:despachada | um foi empenhado | { despacho } | o integrador originador |
ocorrencia:despacho-mudou-status | um despacho mudou: aceito, em , no local, encerrado | { id, ocorrenciaId, de, para, motivo?, resultado? } | o integrador originador |
ocorrencia:registro-adicionado | ação, situação ou pedido de apoio na narrativa | { ocorrenciaId, entrada } | o integrador originador |
jornada:registrada | policial se apresentou | { jornada } | todo integrador ativo |
jornada:mudou-status | entrou em serviço, pausou, encerrou | { id, de, para, posto?, versao } | todo integrador ativo |
jornada:guarnicao-constituida | guarnição montada numa viatura | { guarnicao } | todo integrador ativo |
jornada:guarnicao-composicao-mudou | de integrante | a composição nova | todo integrador ativo |
jornada:comando-assumido | comandante assumiu | { id, comandante, versao } | todo integrador ativo |
jornada:guarnicao-mudou-status | entrou no pool, foi designada, chegou | { id, de, para, despachoId?, versao } | todo integrador ativo |
jornada:pausa-registrada · jornada:pausa-mudou-status | pausa de pessoa ou de equipe | { pausa } · { id, de, para, motivo? } | todo integrador ativo |
integracao:solicitacao-aceita · -rejeitada | o desfecho de cada comando, pelo segundo caminho | { solicitacaoId, ocorrenciaId?, despachoId? } · { solicitacaoId, codigo, motivo? } | o integrador que mandou o comando |
Os três ids
| id | quem cunha | para quê |
|---|---|---|
solicitacaoId | o cliente, um por comando (UUIDv7) | ; vai em x-solicitacao-id |
origem.solicitacao | o , copiando o seu | correlacionar o evento com o comando que o causou |
id do | o Geohub, um por evento | deduplicação na entrega; vai no corpo e em X-Geohub-Evento-Id |
Uma solicitação em andamento expira em 5 min; se o comando explodiu, a chave é liberada e volta a valer para o mesmo comando. A deduplicação pelo protocolo do integrador (referenciaExterna) é outra camada, do domínio.
Erros
Recusa de protocolo — defeito do cliente. Trate como .
| código | status | o que é |
|---|---|---|
NAO_AUTENTICADO | 401 | token ausente ou inválido |
SEM_CAPACIDADE | 403 | o papel não alcança o verbo (faltando[]) |
AUTORIA_FORJADA | 403 | o x-autoria não é o da sessão |
CORPO_INVALIDO | 400 | a entrada não cumpre o contrato (detalhes[]); campo desconhecido também |
SOLICITACAO_AUSENTE | 400 | comando de integrador sem x-solicitacao-id |
SOLICITACAO_INVALIDA | 400 | o x-solicitacao-id não é um UUID |
SOLICITACAO_EM_ANDAMENTO | 409 | repita depois do Retry-After, com a mesma chave |
SOLICITACAO_REUSADA | 422 | a chave já foi de outro comando |
VERBO_DESCONHECIDO | 404 | verbo fora da tabela de exposição |
Falha de negócio — resposta normal. Trate na tela.
| código | status | o que é |
|---|---|---|
ocorrencia-inexistente · despacho-inexistente · jornada-inexistente · guarnicao-inexistente · pausa-inexistente | 404 | o id não existe |
transicao-invalida | 409 | o verbo não vale no status atual |
referencia-externa-ja-registrada | 409 | o id da existente vem em contexto.ocorrenciaId |
jornada-ja-ativa · viatura-ja-tem-guarnicao | 409 | |
comando-nao-assumido · jornada-nao-iniciada · sem-posto-de-comandante | 409 | a ordem da jornada |
viatura-sem-guarnicao-disponivel · integrante-ausente · qualquer outro | 422 | a requisição valia; o domínio recusou |
GUARDA_DE_DOMINIO | 403 | o objeto não é seu (o despacho é de outra guarnição), guarnição não disponível, integrador sem referenciaExterna: é resposta, não incidente, e o exemplo a trata como desfecho |
Cadastro do integrador e tradução de ids
Configuração do ambiente, feita pelo com o admin.
Usuário de serviço com o papel Integração - Sistema de despacho, token estático configurado por deployment (INTEGRADOR_DESPACHO_STATIC_TOKEN).
Coleção integrador:
usuario: o usuário de serviço (único). A sessão só assina comointegradorse esta linha existir; sem ela, assina comousuario.nome,ativo(inativo não recebe: o outbox nem grava a linha para ele).callback_url: HTTPS público, porta 443 salvo quando a allowlist traz a porta.hosts_permitidos: hosts exatos, porta opcional, sem curinga. O validador recusa loopback, link-local, faixas privadas, CGNAT e host sem DNS, no cadastro e a cada envio.GEOHUB_WEBHOOK_PERMITE_REDE_LOCAL=trueé só para teste.segredo_do_webhook: o segredo do HMAC, mascarado no painel.
Coleção integrador_identidade, uma linha por policial:
integrador: o id do usuário de serviço.tipo:policial(o único que o tradutor usa).id_externo: a matrícula no sistema do CAD.id_geohub: oUsuarioId.
A tradução roda na exposição, nas posições marcadas meta({ id: 'UsuarioId' }) nos contratos. Só o admin escreve; o integrador lê a própria tabela. Empate: vence a primeira cadastrada. Sem a linha, o comando que cita policial volta integrante-ausente. A viatura viaja pelo prefixo (RP-1207), sem tradução; ocorrência e despacho pelos ids do Geohub, com referenciaExterna para o CAD reconhecer a sua.
Outbox e log de entrega: integrador_evento (status pendente, entregue, falhou, descartado; tentativas, próxima tentativa, último HTTP status). Idempotência: integrador_solicitacao. O isolamento entre integradores é de permissão de leitura: originador = $CURRENT_USER.