Referência da API de Parceiros — vale para os dois modelos

# Autenticação

Toda chamada exige sua API key no header — server-to-server apenas, nunca exponha a key no front-end ou no app. A key é gerada (e revogada) por você mesmo no painel do parceiro e exibida uma única vez na emissão.

copiarAuthorization: Bearer rl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key ausente ou inválida → 401. Limite de requisições excedido → 429 (padrão 60 req/min, ajustável por contrato). Período de teste encerrado → 402 (500 pedidos grátis / 30 dias — depois disso, liberação de produção via contrato).

# Teste de conexão

GET/v1/ping

copiarcurl -H "Authorization: Bearer rl_live_SUA_KEY" https://rotapro.net.br/v1/ping

{ "success": true, "message": "pong", "partner": { "nome": "Sua Plataforma", "slug": "sua-plataforma" }, "ts": "..." }

# Gerar rota

POST/v1/resolve

Recebe até 25 pedidos por chamada e devolve endereços geocodificados, ordem otimizada de entrega e link do Google Maps. Stateless: nada fica gravado — quem guarda o resultado é você.

Requisição

copiar{
  "origin": { "lat": -26.4851, "lng": -49.0713, "city": "Guaramirim", "uf": "SC" },
  "orders": [
    {
      "external_id": "pedido-8841",
      "structured": {
        "numero_pedido": "8841",
        "cliente_nome": "Maria Silva",
        "telefone": "47999990000",
        "localizador": "ABC123",
        "valor_total": 54.90,
        "forma_pagamento": "PIX",
        "endereco": {
          "logradouro": "Rua 28 de Agosto", "numero": "2200",
          "bairro": "Centro", "cidade": "Guaramirim",
          "uf": "SC", "cep": "89270-000",
          "complemento": "Apto 32", "referencia": "Próximo ao mercado"
        }
      }
    },
    { "external_id": "pedido-8842", "text": "texto integral da comanda..." },
    { "external_id": "pedido-8843", "image": { "fileName": "comanda.jpg", "data": "<base64>" } }
  ]
}

Formas de entrada (exatamente uma por pedido)

Resposta 200

copiar{
  "success": true,
  "mapsLink": "https://www.google.com/maps/dir/?api=1&travelmode=driving&waypoints=...&destination=...",
  "mapsAppLink": "https://www.google.com/maps/dir/?api=1&...",
  "orders": [
    {
      "external_id": "pedido-8841",
      "order": 1,
      "numero_pedido": "8841",
      "cliente_nome": "Maria Silva",
      "telefone": "47999990000",
      "valor_total": 54.90,
      "forma_pagamento": "PIX",
      "troco": null,
      "endereco": { "logradouro": "Rua 28 de Agosto", "numero": "2200", "bairro": "Centro", "cidade": "Guaramirim", "uf": "SC" },
      "lat": -26.4702,
      "lng": -49.0028,
      "number_not_confirmed": false,
      "city_mismatch": false
    }
  ],
  "rejected": [
    { "external_id": "pedido-8842", "reason": "NO_GOOGLE_RESULTS" }
  ]
}

# Sessões — App do Entregador (recurso do Modelo 2)

Mesmo payload do /v1/resolve — mas em vez de devolver só os dados, a RotaLink cria uma sessão de entrega e devolve a URL que o seu app abre no webview do entregador (com a sua marca). Guia completo com código Android/iOS, acompanhamento e segurança: baixe no painel do parceiro.

# Webhooks (Modelo 2 · tempo real)

Configure a URL no painel (card Webhooks, com botão "Enviar teste"). Todo POST vem assinado — valide antes de processar.

Esperamos 2xx em até 8s. Falhou? Retry com backoff exponencial (30s → 1h), até 8 tentativas.

# Erros

Específicos de sessões