Visão geral

Módulo de Ordens de Serviço — receber e atualizar OS via webhook ou polling.

O módulo de Ordens de Serviço permite que sistemas externos registrem solicitações operacionais na DirectLuz e recebam de volta notificações sobre o ciclo de vida das Ordens de Serviço (OS) geradas a partir dessas solicitações.

Fluxo bidirecional da API de Ordens de Serviço

Como funciona

A integração é bidirecional:

Inbound — o sistema externo envia um POST à API DirectLuz com os dados da solicitação. A DirectLuz registra, gera uma Ordem de Serviço interna e devolve o identificador.
Outbound — qualquer alteração realizada na Ordem de Serviço dentro do DirectLuz é notificada ao sistema externo: abertura, mudanças de status, conclusão e cancelamento.

Premissa contratual: toda transição relevante registrada na OS pela DirectLuz — sem exceção — é propagada ao sistema externo cadastrado. Cabe ao receptor decidir quais eventos consumir e quais ignorar.

Dois modos de transporte equivalentes

A escolha entre Webhook e Polling é feita pelo parceiro no momento do cadastro. Ambos cobrem o mesmo contrato de payload — apenas o mecanismo difere.

Modo	Mecanismo	Quando usar
Webhook (push)	A DirectLuz dispara `POST` HTTP no endpoint do parceiro a cada evento, em tempo real	Quando o parceiro expõe endpoint HTTPS público e prefere notificação imediata
Polling (pull)	A DirectLuz consulta o endpoint do parceiro e disponibiliza eventos para coleta em janelas recorrentes de até 3 minutos	Quando o parceiro prefere modelo de "puxar" ou não pode expor endpoint público

Comparação rápida

Critério	Webhook	Polling
Latência de entrega	Tempo real	Até 3 minutos
Endpoint público do parceiro	Obrigatório	Não necessário no sentido outbound
Quem inicia o tráfego	DirectLuz (push)	Parceiro / DirectLuz (pull)
Mecanismo de garantia	Retentativas com backoff	Re-consulta na próxima janela

Tipo de ativo (`assetType`)

Toda OS é declarada com um tipo de ativo — o bem físico sobre o qual a OS atua. O campo é obrigatório em toda solicitação inbound.

Valor	Descrição
`POLE`	Poste de iluminação pública

Novos tipos serão acrescentados de forma aditiva e retrocompatível. Solicitações com assetType ausente ou desconhecido recebem 422.

Identificadores: protocolo externo + protocolo interno

Como o sistema externo tem seu próprio protocolo (protocolNumber) e a DirectLuz tem o dela (internalProtocol), toda resposta e todo evento outbound contém os dois. Isso permite que o parceiro mantenha correlação em ambos os lados sem nenhum mapeamento auxiliar.

{
  "id": "8c2b4a1f-3d6e-4b9a-bc2f-5a7d8e1c9b3a",
  "internalProtocol": "OS-00042",
  "protocolNumber": "EXT-2026-001234"
}

Campo	Origem	Descrição
`id`	DirectLuz (interno)	UUID v4 da Ordem de Serviço — chave técnica imutável
`internalProtocol`	DirectLuz (interno)	Identificador humano-legível (`OS-NNNNN`)
`protocolNumber`	Sistema externo	Eco do protocolo informado na requisição

Páginas deste módulo

Inbound — POST /api/external/service-orders com payload, exemplos e idempotência.
Outbound Webhook — cabeçalhos, eventos, payloads JSON, retentativas.
Polling — inbound + outbound em modo pull.
Response Codes — códigos HTTP de resposta.