Convenções
Encoding, formatos de data, identificadores, idempotência e limites aplicados em toda a API.
Convenções aplicadas em toda a API DirectLuz, independente do módulo ou modo de transporte.
| Item | Convenção |
|---|---|
| Codificação | UTF-8 |
| Formato | JSON (Content-Type: application/json) |
| Datas e horários | ISO 8601 em UTC, sufixo Z. Exemplo: 2026-05-20T13:42:00Z |
| Identificadores internos | UUID v4 |
| Telefones | E.164 (+5583999998888) |
| Coordenadas | Decimais em WGS-84 (latitude, longitude) — opcionais salvo indicação em contrário |
| Limite de tamanho da requisição | 5 MB |
| Timeout de resposta esperado | 30 segundos |
Para as URLs base de cada ambiente, ver Ambientes.
Idempotência
O cabeçalho Idempotency-Key permite que uma mesma requisição inbound seja repetida com segurança em caso de falha de rede ou timeout, sem produzir efeitos duplicados.
- O valor deve ser um UUID v4 único por requisição lógica.
- A janela de retenção é de 24 horas.
- Requisições recebidas com a mesma chave dentro da janela retornam o resultado original com
200 OK, independentemente do payload enviado.
A semântica da resposta repetida depende do módulo. Ver a documentação do módulo específico para detalhes.