Autenticação
Como autenticar suas chamadas à API DirectLuz e verificar webhooks recebidos.
A DirectLuz adota exclusivamente autenticação por chave de API em ambos os sentidos da integração e em ambos os modos de operação (Webhook e Polling). Outros mecanismos — OAuth, JWT emitido por terceiros, certificados client-side — não são suportados nesta versão.
1. Obter credenciais
Para integrar à API DirectLuz, o parceiro precisa de uma ExternalSystem cadastrada — entidade que representa o sistema integrador perante a DirectLuz. Cada ExternalSystem é vinculada a:
- Um tenant (município ou contrato operacional).
- Um conjunto de escopos que define quais endpoints podem ser invocados (ex.:
CanCreateServiceOrders,CanReadCityData). - Opcionalmente, uma
webhookUrl+webhookSecretpara receber eventos via Webhook.
O cadastro é solicitado pelo canal de suporte e gera uma chave de API rotativa que será usada em todas as requisições inbound do parceiro.
2. Inbound — chamadas do parceiro à DirectLuz
A autenticação inbound é feita por chave de API rotativa, transmitida no cabeçalho X-Api-Key.
| Item | Especificação |
|---|---|
| Protocolo | HTTPS, TLS 1.2 ou superior |
| Cabeçalho | X-Api-Key: <chave> |
| Armazenamento | A chave completa é armazenada como hash SHA-256. Apenas os 8 primeiros caracteres (prefixo) ficam legíveis na interface administrativa, para identificação |
| Rotação | A chave pode ser rotacionada a qualquer momento pelo painel administrativo da DirectLuz. A chave anterior é invalidada imediatamente |
Exemplo de chamada autenticada
GET /api/external/health HTTP/1.1
Host: api-sandbox.directluz.com.br
X-Api-Key: dlz_sandbox_8f2c4a1b9e7d3a5c6b8e1f9d2c4a7b5eA resposta diz a qual cidade a chave pertence, para o parceiro conferir antes de ler qualquer dado:
{ "status": "ok", "externalSystemCode": "GUARDCITY", "environment": "Production",
"tenantId": "RGS", "ibgeCode": "3544103", "serverTime": "2026-09-25T12:00:00Z" }ibgeCode é o código IBGE do município (7 dígitos), ou null quando a cidade ainda não tem o código cadastrado.
Respostas relevantes para erros de autenticação:
| Código | Causa |
|---|---|
401 Unauthorized | Chave ausente, inválida ou expirada |
403 Forbidden | Chave válida mas sem escopo para o endpoint chamado |
3. Outbound — webhooks da DirectLuz ao parceiro
A autenticidade e integridade de cada Webhook enviado pela DirectLuz são asseguradas por assinatura HMAC-SHA256 do corpo da requisição, calculada com um segredo compartilhado (webhookSecret) informado pelo parceiro no cadastro.
| Item | Especificação |
|---|---|
| Protocolo | HTTPS, TLS 1.2 ou superior |
| Cabeçalho | X-Directluz-Signature: sha256=<hex_lowercase> |
| Cálculo | HMAC_SHA256(webhook_secret, raw_request_body) |
| Codificação | Hexadecimal minúsculo |
| Comparação | O receptor deve usar comparação de tempo constante (hmac.compare_digest / crypto.timingSafeEqual) |
Verificação da assinatura HMAC
O sistema externo valida cada Webhook recebido seguindo o procedimento:
expected = hex_lowercase( HMAC_SHA256( webhook_secret, raw_request_body ) )
received = header "X-Directluz-Signature".replace("sha256=", "")
valid = constant_time_equal( expected, received )Pontos críticos:
- A assinatura é calculada sobre o corpo cru, exatamente como recebido. Qualquer reserialização do JSON antes da verificação invalida o resultado.
- A comparação deve usar função de tempo constante para evitar ataques de timing.
- Falha de verificação implica resposta
401 Unauthorizede descarte do evento.
Próximos passos
- Convenções — formatos, datas, idempotência.
- Ambientes — onde testar (sandbox) e onde produzir (prod).
- Ordens de Serviço — primeiro módulo público da API.
- Leitura de Dados da Cidade — postes, telegestores e ordens de serviço em lote.