Crie rotas via API a partir de pedidos que já existem

A novidade em uma frase

Antes, pra criar uma rota via API você usava POST /v2/orders/route, que criava os pedidos e a rota no mesmo request. Funciona, mas se você já tinha cadastrado os pedidos via outro caminho (webhook, integração, dashboard), precisava reenviar tudo.

Agora tem POST /v2/routes: você manda só os order_ids que já existem + os dados da rota, e a gente monta a rota apontando pra eles.

📖 Referência completa com schema, exemplos e códigos de erro: Create Route from Orders.

Quando usar

• Pedido já está na Abbiamo. Se o pedido já entrou pelo seu fluxo normal (integração, webhook, dashboard, outro endpoint), use o endpoint novo. Mais simples, menos payload.
• Pedido ainda não existe. Se quer criar pedido + rota no mesmo request, continue usando POST /v2/orders/route. Nada muda nele.

Payload

POST /v2/routes
x-abbiamo-seller-group-key: <sua-chave>
Content-Type: application/json

{
  "order_ids": [
    "22222222-2222-2222-2222-222222222222",
    "33333333-3333-3333-3333-333333333333"
  ],
  "route": {
    "driver_document": "11038299033",
    "cost": 1000,
    "start": {
      "type": "WAREHOUSE_SELLER_IDENTIFIER",
      "value": "minha-loja-01"
    },
    "end": {
      "type": "WAREHOUSE_SELLER_IDENTIFIER",
      "value": "minha-loja-01"
    },
    "orders_sequenced": false
  }
}

Campos da rota

• start (obrigatório) — local de partida. type é sempre WAREHOUSE_SELLER_IDENTIFIER e value é o identifier do seller cujo local será usado.
• end (opcional) — local de chegada (se a rota terminar em outro lugar).
• driver_document (opcional) — CPF do motorista. Quando informado, tem que pertencer a algum seller do seu seller group. Veja a seção abaixo pra entender o papel desse campo.
• cost (opcional) — custo da rota, em centavos.
• expected_duration / expected_distance (opcionais) — duração estimada em minutos e distância em metros.
• orders_sequenced (opcional, default false) — se true, a ordem do array order_ids define a sequência da rota.
• external_name (opcional) — nome externo pra identificar a rota nos seus sistemas.

O papel do driver_document

driver_document é opcional de propósito — e isso muda como você pode operar a rota:

• Passou o driver_document → a rota já nasce com motorista atribuído, pronta pra ser despachada com a sua frota.
• Não passou → a rota fica criada e "parada" (sem motorista). Aí você decide depois, pelo dashboard, o que fazer com ela:
  • Atribuir um motorista próprio e despachar normalmente, ou
  • Despachar pra uma transportadora (TRP) que suporte esse tipo de operação, e quem faz a entrega é a TRP.

Ou seja, dá pra usar o endpoint só pra agrupar pedidos numa rota e deixar a decisão de quem entrega pra um segundo momento, sem precisar ter um motorista na mão na hora de criar.

Validações

Antes de criar a rota, a gente valida — e devolve erro claro se algo não bater:

• Cada order_id existe e pertence ao seu seller group → senão, INVOICE_NOT_FOUND_OR_NOT_IN_SELLER_GROUP (404).
• Cada pedido está roteirizável → senão, INVOICE_NOT_ROUTEABLE (400). Detalhe abaixo.
• O seller_identifier do start/end tem um local ativo associado → senão, WAREHOUSE_NOT_FOUND (404).
• O motorista (quando informado) pertence a algum seller do seller group → senão, DRIVER_NOT_FOUND (404).

O erro INVOICE_NOT_ROUTEABLE em detalhe

Esse é o erro que mais aparece na prática. Um pedido deixa de ser roteirizável quando ele já foi despachado em outro lugar — ou seja:

• Já foi incluído em outra rota (mesmo que ainda não tenha saído pra entrega), ou
• Já foi despachado como envio individual pra uma transportadora (TRP).

O motivo é simples: cada pedido só pode estar em um despacho ativo. Se ele já tá em rota A, não dá pra colocar em rota B sem antes cancelar a A.

A resposta vem assim:

{
  "status_code": 400,
  "timestamp": "2026-05-18T19:20:35.397Z",
  "message": "Orders are not routeable: b235ada8-54ca-454e-8800-e64ecefa28a2",
  "code": "INVOICE_NOT_ROUTEABLE",
  "error_id": "f6c4b159-e94e-41b6-92c4-da29d3cc0580",
  "params": {
    "order_ids": [
      "b235ada8-54ca-454e-8800-e64ecefa28a2"
    ]
  }
}

Como tratar: olhe a lista params.order_ids — esses são os culpados. Você pode:

1. Remover os ids problemáticos da chamada e refazer com o restante, ou
2. Cancelar o despacho anterior do pedido (rota antiga ou envio pra transportadora) e tentar de novo, ou
3. Conferir no dashboard onde aquele pedido foi parar — geralmente o histórico do pedido mostra a rota/envio que travou.