API de Integração

Como funciona

A comunicação é feita por requisições HTTP no formato JSON. O sistema da loja envia os dados da entrega e a plataforma responde na hora com o número da corrida. O acompanhamento pode ser feito por consulta ou por webhook.

1. A central gera as credenciais. No painel, em Integrações, cria a chave da loja e entrega o Código do cliente e os tokens.
2. O sistema da loja envia a corrida. Um POST para o endpoint de criar corrida com os pontos de coleta e entrega.
3. A plataforma responde. Retorna o número da corrida (a OS) e o link de rastreio.
4. Acompanhamento. Consulte o status quando precisar ou configure um webhook para receber os avisos de cada etapa.

Credenciais e autenticação

Cada integração pertence a uma loja. As credenciais são geradas pela central em Integrações, Nova integração, e aparecem uma única vez. Guarde em local seguro.

As duas informações vão dentro do corpo (o JSON) de cada requisição. Use o token correspondente à operação chamada.

URL base e formato

Todas as chamadas são POST com cabeçalho Content-Type: application/json:

# Base
https://logix-production-61ae.up.railway.app/api/v1/integracao

# Endpoints
POST  /gravar     criar corrida
POST  /status     consultar andamento
POST  /cancelar   cancelar corrida
POST  /calcular   previa de distancia e valor

Regras da operação

A plataforma aplica automaticamente as configurações que a central definiu para cada loja. A API respeita essas regras sem exigir nada do seu lado.

Preço

O valor de toda corrida criada pela API é calculado pela tabela de preço configurada para a loja do codCliente (incluindo eventuais regras de preço dinâmico). A API não aceita valores manuais.

Limite de corridas por profissional

Cada loja pode ter um limite de corridas simultâneas por profissional. A API não fura esse limite: se você enviar mais corridas do que o profissional pode assumir, as excedentes ficam na fila aguardando um profissional disponível ou o despacho da central. Exemplo: se o limite for 5 e você enviar 7, o profissional assume 5 e as outras 2 aguardam.

Cancelamento

O cancelamento pela API respeita a permissão de cancelamento configurada para a loja:

Detalhes e exemplos no endpoint de cancelar corrida.

POST Criar corrida

/api/v1/integracao/gravar

Cria uma nova corrida. O array pontos deve ter no mínimo 2 e no máximo 80 itens. O primeiro ponto é a coleta e os demais são as entregas.

Campos do corpo (JSON)

Exemplo de requisição

POST https://logix-production-61ae.up.railway.app/api/v1/integracao/gravar
Content-Type: application/json

{
  "token": "<segredo>-gravar",
  "codCliente": "<codigo da loja>",
  "numeroPedido": "1234",
  "semProfissional": "N",
  "ordenar": "true",
  "centroCusto": "MATRIZ",
  "categoria": "Moto",
  "codigoProf": 12,
  "pontos": [
    {
      "rua": "Av. Tancredo Neves", "numero": "620",
      "bairro": "Caminho das Arvores", "cidade": "Salvador", "uf": "BA",
      "cep": "41820-020", "la": "-12.978", "lo": "-38.458"
    },
    {
      "rua": "R. das Flores", "numero": "100", "bairro": "Pituba",
      "cidade": "Salvador", "uf": "BA", "la": "-12.995", "lo": "-38.451",
      "procurarPor": "Maria", "telefone": "71 90000-0000",
      "numeroNota": "998", "obs": "Deixar na portaria"
    }
  ]
}

Resposta de sucesso

{
  "Sucesso": "LX-1287",
  "detalhes": {
    "distancia": 8.7,
    "duracao": "00:21:00",
    "valor": "25.50",
    "obs": "",
    "urlRastreamento": "https://painel.suaempresa.com.br/rastreio.html?t=a1b2c3d4e5f6"
  }
}

"detalhes": {
  "distancia": 8.7, "duracao": "00:21:00", "valor": "25.50",
  "urlRastreamento": "...",
  "profissionalNaoAlocado": true,
  "codigoProfInformado": 12,
  "mensagem": "Você já está com 5 corrida(s) em andamento, o limite para este cliente é 5. A corrida foi criada sem profissional definido."
}

Respostas de erro

{ "Erro": "Favor, informar 2 ou mais pontos!" }
{ "Erro": "Endereço do ponto 1 obrigatório!" }
{ "Erro": "Limite de endereços excedido. Favor informar um número igual ou menor que 80 pontos." }
{ "Erro": "Token inválido" }
{ "Erro": "Só é permitido solicitar 2 serviços por segundo." }

Veja a lista completa de erros.

POST Consultar status

/api/v1/integracao/status

Consulta o andamento de uma ou mais corridas. Informe um destes: servico (uma OS), servicos (lista de OS, até 50) ou numeroNota.

Campos do corpo (JSON)

Exemplo de requisição

{
  "token": "<segredo>-status",
  "codCliente": "<codigo da loja>",
  "servico": "LX-1287"
}

Resposta de sucesso (uma OS)

{
  "Sucesso": {
    "status": "A",
    "urlRastreamento": "https://painel.suaempresa.com.br/rastreio.html?t=a1b2c3d4e5f6",
    "pontos": [
      {
        "ponto": "1",
        "IDponto": "3f2a9c10-...",
        "obs": "Deixar na portaria",
        "numeroNota": "998",
        "statusPonto": {
          "chegada": "2026-08-24 14:05:10",
          "saida": "2026-08-24 14:12:33",
          "ocorrencia": "Sucesso",
          "motivo": "",
          "protocoloAssinatura": [], "assinatura": [], "protocolo": [],
          "linkRastreamento": ""
        },
        "coordernadasPonto": { "la": "-12.995", "lo": "-38.451" },
        "codigo": "", "codigoCompleto": "", "descricao": "", "codigoFinalizarEnd": ""
      }
    ],
    "dadosProfissional": { "nome": "João Silva", "cpf": "", "placa": "" },
    "valorServico": 25.5,
    "valorProfissional": 18.0
  }
}

Resposta de sucesso (várias OS)

Com servicos ou numeroNota, o retorno vem indexado pela OS:

{
  "Sucesso": {
    "LX-1287": { "status": "F", "pontos": [ ... ], "valorServico": 25.5, "valorProfissional": 18.0 },
    "LX-1288": { "status": "A", "pontos": [ ... ], "valorServico": 30.0, "valorProfissional": 20.0 }
  }
}

Significado do campo status

{ "Erro": "Código do serviço não informado." }
{ "Erro": "Serviço não encontrado." }
{ "Erro": "É permitido realizar uma consulta a cada 30 segundos." }

POST Cancelar corrida

/api/v1/integracao/cancelar

Cancela uma corrida pela OS. O resultado segue a regra de cancelamento configurada para a loja. Uma corrida ainda na fila pode ser cancelada normalmente. Uma corrida já associada a um profissional só é cancelada se a loja tiver essa permissão. Uma corrida já finalizada não pode ser cancelada.

Campos do corpo (JSON)

Exemplo de requisição

{
  "token": "<segredo>-cancelar",
  "codCliente": "<codigo da loja>",
  "OS": "LX-1287",
  "descricaoMotivo": "Cliente desistiu antes da coleta"
}

Respostas

{ "Sucesso": "Cancelado" }

{ "Erro": "Alocado" }              // ja associada e a loja nao pode cancelar associadas, ou ja finalizada
{ "Erro": "Serviço não encontrado." }

POST Calcular preço

/api/v1/integracao/calcular

Retorna uma prévia de distância, tempo e valor sem criar a corrida. Útil para mostrar o frete antes de confirmar. O valor usa a tabela de preço da loja.

Exemplo de requisição

{
  "token": "<segredo>-calcular",
  "codCliente": "<codigo da loja>",
  "pontos": [
    { "rua": "Av. Tancredo Neves", "cidade": "Salvador", "uf": "BA", "la": "-12.978", "lo": "-38.458" },
    { "rua": "R. das Flores", "cidade": "Salvador", "uf": "BA", "la": "-12.995", "lo": "-38.451" }
  ]
}

{
  "Sucesso": { "distancia": 8.7, "duracao": "00:21:00", "valor": "25.50" }
}

POST Centros de custo disponíveis

/api/v1/integracao/centros

Lista os centros de custo disponíveis para a loja. Use para saber quais valores aceitar no campo centroCusto ao criar a corrida. Esta é uma consulta e usa o token de status.

Exemplo de requisição

{
  "token": "<segredo>-status",
  "codCliente": "<codigo da loja>"
}

{
  "Sucesso": [
    { "codigo": "MATRIZ", "nome": "Matriz Centro" },
    { "codigo": "FIL01", "nome": "Filial Pituba" }
  ]
}

Para gerar a corrida em um desses centros, envie o codigo (ou o nome) no campo centroCusto do gravar. Se o valor não corresponder a um centro da loja, a criação retorna Centro de custo não encontrado para esta loja.

POST Categorias disponíveis

/api/v1/integracao/categorias

Lista as categorias (modalidades) disponíveis para a loja. Use para saber quais valores aceitar no campo categoria ao criar a corrida. Usa o token de status.

Exemplo de requisição

{
  "token": "<segredo>-status",
  "codCliente": "<codigo da loja>"
}

{
  "Sucesso": [
    { "nome": "Moto" },
    { "nome": "Carro" }
  ]
}

Se o valor enviado em categoria não existir para a loja, a criação retorna Categoria não encontrada para esta loja.

POST Profissionais disponíveis

/api/v1/integracao/profissionais

Lista os profissionais vinculados à loja, com o código de cada um. Use para saber qual valor enviar em codigoProf ao criar a corrida e direcionar a um profissional específico. Usa o token de status.

Exemplo de requisição

{
  "token": "<segredo>-status",
  "codCliente": "<codigo da loja>"
}

{
  "Sucesso": [
    { "codigoProf": 12, "nome": "João Silva" },
    { "codigoProf": 27, "nome": "Maria Souza" }
  ]
}

Link de rastreio

Toda corrida recebe um link público de rastreio (campo urlRastreamento nas respostas e nas notificações). Ele abre uma página com o mapa, a posição do entregador em tempo real e o andamento de cada ponto, pronta para repassar ao cliente final.

Webhook de notificação

Em vez de consultar o status, a loja pode receber os avisos automaticamente. Informe uma URL de notificação ao criar a integração (ou depois, no painel) e a plataforma enviará um POST para o sistema da loja a cada etapa da corrida, com as coordenadas do entregador.

Quando a notificação é enviada

Formato do aviso

POST  <sua URL de notificacao>
x-lx-signature: sha256=<assinatura>
Content-Type: application/json

{
  "ID": "LX-1287",
  "Status": { "ID": 2, "Nome": "João Silva", "telefone": "71 90000-0000", "dataHora": "2026-08-24 14:30:00" },
  "UrlRastreamento": "https://painel.suaempresa.com.br/rastreio.html?t=a1b2c3d4e5f6",
  "coordenadasMotoboy": { "lat": -12.995, "lng": -38.451, "em": "2026-08-24 14:29:50" },
  "valorServico": 25.5,
  "valorProfissional": 18.0,
  "referenciaExterna": "1234"
}

No momento 1 (ponto finalizado) vem também o bloco statusEndereco:

"statusEndereco": {
  "codigo": "FIN", "codigoCompleto": "FINALIZADO", "descricao": "Endereço finalizado",
  "criadoEm": "2026-08-24 14:12:33",
  "endereco": {
    "ponto": 2, "enderecoCompleto": "R. das Flores, 100, Pituba, Salvador - BA",
    "dataColetado": "2026-08-24 14:12:33", "lat": -12.995, "lng": -38.451,
    "motivo": { "tipo": "sucesso", "descricao": "Entregue com sucesso" },
    "obs": "Deixar na portaria", "numeroNota": "998"
  }
}

No momento 3 (cancelamento) vem o bloco cancelamento:

"cancelamento": { "descricaoMotivo": "Cliente desistiu antes da coleta", "temMulta": false }

Validando a assinatura

Cada aviso vem com o cabeçalho x-lx-signature, um HMAC-SHA256 do corpo exato da mensagem usando o segredo do webhook (mostrado na criação da integração). Para validar, calcule o HMAC do corpo recebido e compare com o cabeçalho.

# Node.js
const crypto = require('crypto');
const esperado = 'sha256=' + crypto.createHmac('sha256', SEGREDO_WEBHOOK)
  .update(corpoBrutoDaRequisicao).digest('hex');
if (esperado !== req.headers['x-lx-signature']) { /* rejeitar */ }

Referência: campos do ponto

Cada item do array pontos aceita os campos abaixo. O primeiro ponto é a coleta. Cada ponto precisa de um endereço identificável: informe o endereço em texto (rua, cidade e afins) ou as coordenadas (la e lo). Quando as coordenadas vêm, elas são usadas diretamente.

Condicional: informe o endereço em texto ou as coordenadas. Ao menos um dos dois é obrigatório por ponto.

Lista completa de erros

Todos os erros chegam com HTTP 200 e o corpo { "Erro": "mensagem" }.