Ciclo da entrega

Todas as rotas ficam sob /integrations/opendelivery/v1/logistics e usam o deliveryId retornado na criação (não o seu orderId).

1. Criar a entrega

POST /integrations/opendelivery/v1/logistics/delivery → 202

{
  "orderId": "pedido-84321",
  "orderDisplayId": "4321",
  "merchant": { "id": "loja-001", "name": "Pizzaria Exemplo" },
  "pickupAddress": { "street": "Rua das Flores", "number": "100", "district": "Centro" },
  "deliveryAddress": {
    "street": "Avenida Brasil",
    "number": "250",
    "district": "Jardim América",
    "city": "Campinas",
    "latitude": -22.9099,
    "longitude": -47.0626
  },
  "customerName": "Maria Souza",
  "customerPhone": "+5519999990000",
  "totalOrderPrice": { "value": 89.9, "currency": "BRL" },
  "payments": {
    "method": "OFFLINE",
    "offlineMethod": [{ "type": "CASH", "amount": { "value": 89.9, "currency": "BRL" } }],
    "change": { "value": 10.1, "currency": "BRL" }
  }
}

Resposta:

{
  "deliveryId": "0b6f9f0e-3c9a-4f0e-9c1e-2f6a8b1d7c55",
  "event": "PENDING",
  "completion": {
    "estimate": "2026-10-07T14:02:00.000Z",
    "rejectAfter": "2026-10-07T15:00:00.000Z"
  }
}

Pontos de atenção:

Idempotência: reenviar o mesmo orderId da mesma loja retorna a entrega já criada, sem duplicar. É seguro repetir em caso de timeout.
Telefone obrigatório: o destinatário precisa ter telefone, em customerPhone, metadata.customer.phone.number ou metadata.phone. Sem ele, a resposta é 422.
Coleta: a coleta é feita sempre no endereço da unidade cadastrada na RaptorX para a loja. O pickupAddress é exigido pelo padrão, mas não é usado para roteirizar.
Coordenadas: envie latitude e longitude do endereço de entrega. Se informadas e a até 150 km da coleta, são usadas diretamente, sem geocodificar o endereço.
Código de confirmação: pickupCode é usado como código de confirmação da entrega.
Observações: specialInstructions é repassado ao entregador.
Taxa de entrega: vale a tabela de preços da RaptorX para a loja. orderDeliveryFee só é considerada se a loja estiver configurada para isso.
Campos extras do padrão Open Delivery são aceitos e ignorados.
rejectAfter é o prazo para um entregador aceitar (SLA da loja; 60 minutos se não houver SLA configurado). Veja REJECTED.

Pagamentos

`payments`	Tratamento
`method: ONLINE`	Pedido já pago
`OFFLINE` com `PIX`	Pix
`OFFLINE` com `CASH`	Dinheiro
`OFFLINE` com `MEAL_VOUCHER` ou `FOOD_VOUCHER`	Vale
`OFFLINE` com `CREDIT`, `DEBIT` ou `CREDIT_DEBIT`	Cartão
`OFFLINE` com `OTHER` ou sem `offlineMethod`	Dinheiro

O tipo é definido pelo primeiro item de offlineMethod.
O entregador leva maquininha quando method é OFFLINE e wirelessPos é true, ou quando algum item de offlineMethod é cartão ou vale.
Em dinheiro, change.value é o troco a devolver: o entregador leva troco para (total do pedido + change.value).

2. Marcar como pronta

POST /integrations/opendelivery/v1/logistics/readyForPickup/{deliveryId} → 200 com {}. Sem corpo.

Por padrão, a entrega só é oferecida aos entregadores depois desta chamada. Lojas configuradas para despacho imediato entram em despacho na criação, e a chamada continua aceita. É idempotente. Se o deliveryId não existir (ou não for da sua integração), a resposta é 404.

3. Consultar

GET /integrations/opendelivery/v1/logistics/delivery/{deliveryId} → 200

{
  "deliveryId": "0b6f9f0e-3c9a-4f0e-9c1e-2f6a8b1d7c55",
  "orderId": "pedido-84321",
  "event": "ORDER_PICKED",
  "updatedAt": "2026-10-07T14:21:08.000Z"
}

Prefira os eventos de webhook e use a consulta para conferência.

4. Cancelar

POST /integrations/opendelivery/v1/logistics/cancel/{deliveryId} → 200 com { "additionalCharges": false }

{ "reason": "CONSUMER_CANCELLATION_REQUESTED", "message": "Cliente desistiu do pedido" }

reason é obrigatório, com um dos valores: CONSUMER_CANCELLATION_REQUESTED, NO_SHOW, PROBLEM_AT_MERCHANT, HIGH_ACCEPTANCE_TIME, INCORRECT_ORDER_OR_PRODUCT_PICKUP, PROBLEM_RESOLUTION, DISCOMBINE_ORDER, OTHER. message é opcional e action é aceito, mas ignorado.

Situação	Resposta
Entrega cancelada com sucesso, ou já estava cancelada	`200` (idempotente)
Loja sem permissão de cancelamento (vem desabilitada por padrão; a RaptorX habilita)	`403` “Empresa sem permissão para cancelar pedidos”
Entregador já retirou o pedido (a caminho ou no destino)	`422` “O pedido já está a caminho…” Fale com a operação da RaptorX
Entrega concluída	`409` “Pedido já finalizado”
Entrega em devolução ou devolvida	`409` “Pedido #… está em devolução…”
Entrega inexistente	`404` “Pedido não encontrado”

A RaptorX também envia o evento CANCELLED ao seu webhook após o cancelamento.

Status da entrega

Valores retornados pela consulta:

`event`	Significado
`PENDING`	Aguardando o pedido ficar pronto ou um entregador aceitar
`ACCEPTED`	Entregador aceitou
`ORDER_PICKED`	Pedido retirado na loja
`DELIVERY_ONGOING`	A caminho do cliente
`ARRIVED_AT_CUSTOMER`	Entregador no endereço do cliente
`DELIVERY_FINISHED`	Entregue
`RETURNING_TO_MERCHANT`	Voltando para a loja
`RETURNED_TO_MERCHANT`	Devolvido à loja
`CANCELLED`	Cancelada