Inbound API

Endpoint

POST /api/external/service-orders

URL completa em produção: https://app-directluz-v2-backend-prod.azurewebsites.net/api/api/external/service-orders

Cada solicitação recebida vira um Alerta no DirectLuz. Dependendo da política da cidade, esse alerta pode virar uma Ordem de Serviço (OS) imediatamente ou aguardar triagem manual da equipe operacional. O sistema externo sempre recebe 201 quando o alerta é aceito — a existência (ou não) de OS é refletida na resposta.

Cabeçalhos

Estrutura do payload

Sobre o motivo do alerta (reasonCode)

O parceiro envia o código que ele já usa internamente (ex.: LAMP_OUT, POLE_DAMAGED). A operação da cidade cadastra no painel administrativo um mapeamento DE/PARA entre esses códigos e os motivos internos do DirectLuz — assim, o parceiro não precisa conhecer ou conformar-se à taxonomia interna. Quando um código novo (ainda não mapeado) chega, o alerta é criado com o motivo padrão EXTERNAL_OTHER para não bloquear a integração; o operador pode reclassificar manualmente e o administrador cadastra o mapeamento para os próximos.

Sobre o nível de detalhe do endereço

O sistema externo recebe solicitações de cidadãos com nível de detalhe variável. A DirectLuz aceita ambos os extremos: o único campo de endereço obrigatório é address.street.

Sobre coordenadas geográficas

Quando o payload não contém address.latitude e address.longitude, a DirectLuz realiza geocodificação interna a partir dos campos textuais. Se a geocodificação falhar (provider indisponível, endereço ambíguo), a solicitação continua sendo aceita (201) — o alerta fica visível na caixa de entrada operacional do DirectLuz com a marcação "endereço não geolocalizado", e um operador resolve manualmente, ou um job periódico re-tenta a geocodificação automaticamente. O sistema externo não precisa fazer nada diferente nesse cenário.

Exemplo de requisição — payload completo

POST /api/external/service-orders HTTP/1.1
Host: api.directluz.com.br
Content-Type: application/json
X-Api-Key: dlz_live_8f2c4a1b9e7d3a5c6b8e1f9d2c4a7b5e
Idempotency-Key: 9f4d2c1a-7b6e-4a8d-9c1f-2e5b8d3a4c7f

{
  "protocolNumber": "EXT-2026-001234",
  "assetType": "POLE",
  "requestedAt": "2026-05-20T13:42:00Z",
  "requester": {
    "name": "Maria da Silva",
    "phone": "+5583999998888"
  },
  "lampType": "LED",
  "reasonCode": "LAMP_OUT",
  "address": {
    "street": "Av. Exemplo",
    "number": "1320",
    "neighborhood": "Centro",
    "reference": "Em frente ao mercadinho",
    "latitude": -7.114,
    "longitude": -34.831
  },
  "problem": {
    "description": "Poste apagado há três dias",
    "additionalNotes": "À noite a rua fica muito escura"
  },
  "attachments": [
    {
      "type": "photo",
      "url": "https://parceiro.exemplo.gov.br/files/abc123.jpg",
      "filename": "logradouro.jpg",
      "contentType": "image/jpeg"
    }
  ]
}

Exemplo de payload com endereço parcial

{
  "protocolNumber": "EXT-2026-001235",
  "assetType": "POLE",
  "requestedAt": "2026-05-20T14:10:00Z",
  "requester": { "name": "João Pereira" },
  "address": { "street": "Rua das Trincheiras" },
  "problem": { "description": "Lâmpada queimada" }
}

Resposta de sucesso

201 Created — solicitação registrada. O conteúdo da resposta depende da política de intake configurada pela cidade.

A resposta sempre inclui um objeto alert com os dados do alerta criado a partir das informações da requisição.

Modo automático (OS gerada imediatamente)

Quando a cidade está configurada para abrir OS automaticamente, o alerta é criado e já vinculado a uma OS. O campo internalProtocol traz o número humano-legível da OS gerada. O id raiz refere-se à OS; o alerta fica em alert.

{
  "id": "8c2b4a1f-3d6e-4b9a-bc2f-5a7d8e1c9b3a",
  "internalProtocol": "OS-00042",
  "protocolNumber": "EXT-2026-001234",
  "assetType": "POLE",
  "status": "OPEN",
  "priority": "Medium",
  "createdAt": "2026-05-20T13:42:05Z",
  "alert": {
    "id": "3e7f1a2b-9c4d-4e8a-b1f2-6d5c8a9b0e1f",
    "alertNumber": 42,
    "alertReasonCode": "LAMP_OUT",
    "alertReasonName": "Lâmpada apagada",
    "requesterName": "Maria da Silva",
    "requesterPhone": "+5583999998888",
    "description": "Poste apagado há três dias",
    "additionalNotes": "À noite a rua fica muito escura",
    "lampType": "LED",
    "externalRequestedAt": "2026-05-20T13:42:00Z",
    "latitude": -7.114,
    "longitude": -34.831,
    "status": "Linked",
    "attachments": [
      {
        "success": true,
        "blobPath": "service-orders-external/cidade/3e7f1a2b.../f9d8e7c6...jpg",
        "filename": "logradouro.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 124500,
        "error": null
      }
    ]
  }
}

Modo manual (alerta aguardando triagem)

Quando a cidade exige triagem manual, o alerta é registrado e fica aguardando classificação operacional. A OS só é gerada depois — quando isso acontecer, o sistema externo recebe um webhook ServiceOrder.Created. O id raiz refere-se ao alerta nesse cenário; internalProtocol é omitido até o alerta virar OS.

{
  "id": "5a3d1c9f-2b4e-4a8d-9c1f-7e6b5d8a3c4f",
  "protocolNumber": "EXT-2026-001234",
  "assetType": "POLE",
  "status": "RECEIVED",
  "createdAt": "2026-05-20T13:42:05Z",
  "alert": {
    "id": "5a3d1c9f-2b4e-4a8d-9c1f-7e6b5d8a3c4f",
    "alertNumber": 42,
    "alertReasonCode": "LAMP_OUT",
    "alertReasonName": "Lâmpada apagada",
    "requesterName": "Maria da Silva",
    "requesterPhone": "+5583999998888",
    "description": "Poste apagado há três dias",
    "additionalNotes": "À noite a rua fica muito escura",
    "lampType": "LED",
    "externalRequestedAt": "2026-05-20T13:42:00Z",
    "latitude": -7.114,
    "longitude": -34.831,
    "status": "Pending",
    "attachments": [
      {
        "success": true,
        "blobPath": "service-orders-external/cidade/5a3d1c9f.../a1b2c3d4...jpg",
        "filename": "logradouro.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 124500,
        "error": null
      }
    ]
  }
}

200 OK — solicitação já havia sido registrada (idempotência ou reenvio com mesmo protocolNumber). Retorna o resultado original sem efeito colateral.

Campos da resposta

Valores de alert.status

O campo reflete o estado interno do alerta no DirectLuz no momento da resposta.

Anexos e fotografias

Cada item da lista attachments deve conter:

A DirectLuz baixa o conteúdo do anexo e mantém cópia em storage próprio. Anexos cuja URL retorne falha após três tentativas são descartados e registrados em log para reconsulta manual.

Atenção com contentBase64: envie apenas o conteúdo binário codificado em base64 puro — sem o prefixo data:image/jpeg;base64,. Exemplo correto: "/9j/4AAQSkZJRgAB...".

O resultado de cada anexo é retornado no array alert.attachments da resposta. Use o campo error para diagnosticar falhas sem precisar de acesso ao servidor.

Erros

Ver lista completa em Response Codes.