Polling
Modo de transporte alternativo ao Webhook — consulta e envio em janelas de até 3 minutos.
O modo Polling é a alternativa equivalente ao modo Webhook. Ambos cobrem o mesmo contrato de payload — a escolha entre Webhook (push) e Polling (pull) é definida pelo parceiro integrador no momento do cadastro do sistema externo.
No modo Polling, a DirectLuz consulta e envia dados em janelas recorrentes de até 3 minutos. Isto é, a cada intervalo de até 3 minutos:
- A DirectLuz consulta o endpoint do parceiro para coletar novas solicitações pendentes (inbound em modo pull).
- A DirectLuz disponibiliza os eventos acumulados desde a última coleta para o parceiro consultar (outbound em modo pull).
A janela máxima de 3 minutos é o teto — a frequência efetiva pode ser ajustada para ciclos mais curtos mediante acordo, respeitando esse limite superior.
Recebimento de solicitações (inbound em Polling)
A DirectLuz consulta um endpoint exposto pelo parceiro para coletar as solicitações registradas desde a última consulta.
GET {polling_inbound_endpoint}?since=<ISO 8601>&limit=<máximo 200>
X-Api-Key: <chave fornecida pelo parceiro à DirectLuz>Convenções esperadas do endpoint do parceiro:
| Item | Especificação |
|---|---|
| Método | GET sobre HTTPS, TLS 1.2 ou superior |
| Autenticação | Cabeçalho X-Api-Key com chave emitida pelo parceiro à DirectLuz |
| Paginação | Cursor temporal since (ISO 8601 UTC) — a DirectLuz preserva o cursor entre chamadas |
| Limite por chamada | Máximo de 200 itens por resposta |
| Formato da resposta | JSON com lista de solicitações no mesmo formato definido em Inbound |
| Idempotência | Garantida pelo protocolNumber — solicitações já existentes no DirectLuz não geram OS duplicadas |
| Frequência | Até a cada 3 minutos |
Envio de eventos (outbound em Polling)
A DirectLuz expõe um endpoint próprio do qual o parceiro consulta os eventos acumulados desde a última coleta. O parceiro chama:
GET https://app-directluz-v2-backend-prod.azurewebsites.net/api/api/external/events?since=<ISO 8601>&limit=<máximo 200>
X-Api-Key: <chave emitida pela DirectLuz ao parceiro>| Item | Especificação |
|---|---|
| Método | GET sobre HTTPS, TLS 1.2 ou superior |
| Autenticação | Cabeçalho X-Api-Key com a chave emitida pela DirectLuz |
| Paginação | Cursor temporal since. A resposta inclui nextSince para a próxima chamada |
| Limite por chamada | Máximo de 200 eventos |
| Formato | Lista de eventos com payloads idênticos aos definidos em Outbound Webhook |
| Frequência | Até a cada 3 minutos |
| Confirmação de processamento | Avançar o cursor since na próxima chamada equivale a confirmar processamento — eventos não retornarão |
Formato da resposta:
{
"events": [
{
"eventId": "...",
"eventType": "ServiceOrder.Created",
"occurredAt": "...",
"protocolNumber": "...",
"serviceOrder": {}
},
{
"eventId": "...",
"eventType": "ServiceOrder.Completed",
"occurredAt": "...",
"protocolNumber": "...",
"serviceOrder": {}
}
],
"nextSince": "2026-05-21T15:09:42Z",
"hasMore": false
}Escolha entre Webhook e Polling
| 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 |
| Endpoint público da DirectLuz | Sempre disponível | Sempre disponível |
| Quem inicia o tráfego | DirectLuz (push) | Parceiro / DirectLuz (pull) |
| Mecanismo de garantia | Retentativas com backoff | Re-consulta na próxima janela |