Postes, telegestores e ordens de serviço

Além de registrar solicitações (veja Ordens de Serviço), a DirectLuz expõe leitura em lote dos ativos e das ordens de serviço do tenant do parceiro — pensada para sistemas que mantêm um espelho local (ex.: um mapa da cidade) e precisam de pull incremental.

Escopo necessário

Ambos os endpoints exigem que a ExternalSystem do parceiro tenha o escopo canReadCityData habilitado. Sem ele, ambos retornam 403 Forbidden. É um escopo independente de canCreateServiceOrders/canCreateAlerts — pode ser concedido isoladamente.

Paginação e pull incremental

Os dois endpoints compartilham a mesma convenção:

Os itens vêm ordenados por updatedAt crescente e, no empate, por id — a ordem é estável: a mesma página, com o mesmo updatedSince, sempre devolve os mesmos itens na mesma ordem. Um pull incremental típico salva o maior updatedAt visto e o usa como updatedSince na próxima rodada.

GET /api/external/poles

GET /api/external/poles?page=1&pageSize=500 HTTP/1.1
Host: api-sandbox.directluz.com.br
X-Api-Key: <chave>

{
  "items": [
    {
      "id": "8c2b4a1f-3d6e-4b9a-bc2f-5a7d8e1c9b3a",
      "code": "P-0001",
      "address": "Rua X, 10",
      "neighborhood": "Centro",
      "latitude": -23.74,
      "longitude": -46.40,
      "active": true,
      "updatedAt": "2026-09-25T12:00:00Z",
      "device": {
        "id": "3f1e9c2a-7b4d-4a6e-9c1f-2d5b8a3e7c1f",
        "identifier": "TG-123",
        "online": true,
        "relayOn": false,
        "lastCommunicationAt": "2026-09-25T11:59:00Z"
      }
    }
  ],
  "page": 1,
  "pageSize": 500,
  "total": 1234
}

• device é null quando o poste não tem telegestor vinculado.
• online/relayOn são null quando o estado de comunicação não é conhecido (ex.: telegestor nunca reportou telemetria).
• updatedSince também considera a última comunicação do telegestor — um poste sem alteração própria reaparece no pull incremental se o telegestor dele acabou de reportar.

GET /api/external/service-orders

GET /api/external/service-orders?page=1&pageSize=500 HTTP/1.1
Host: api-sandbox.directluz.com.br
X-Api-Key: <chave>

{
  "items": [
    {
      "id": "8c2b4a1f-3d6e-4b9a-bc2f-5a7d8e1c9b3a",
      "number": "OS-2026-0001",
      "status": "OPEN",
      "priority": "Medium",
      "type": "Lâmpada queimada",
      "address": "Rua X, 10",
      "neighborhood": "Centro",
      "latitude": -23.74,
      "longitude": -46.40,
      "poleId": "3f1e9c2a-7b4d-4a6e-9c1f-2d5b8a3e7c1f",
      "team": { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Equipe 1" },
      "openedAt": "2026-09-24T09:00:00Z",
      "updatedAt": "2026-09-25T12:00:00Z",
      "closedAt": null
    }
  ],
  "page": 1,
  "pageSize": 500,
  "total": 10
}

• team é null quando a ordem de serviço não tem equipe atribuída.
• poleId é null quando a ordem de serviço não está vinculada a um poste.
• status/priority vêm como o valor bruto do enum interno (OPEN, ASSIGNED, Medium, …), estável entre chamadas.

Erros