Envie um evento de entrega
curl --request POST \
--url https://api.dev.connect.onbeefapp.com.br/v1/logistics/deliveryUpdate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-App-Id: <x-app-id>' \
--header 'X-App-MerchantId: <x-app-merchantid>' \
--header 'X-App-Signature: <x-app-signature>' \
--data '
{
"deliveryId": {},
"orderId": {},
"orderDisplayId": "<string>",
"merchant": {},
"event": {},
"customerName": "<string>"
}
'Logística
Envie um evento de entrega
Atualize o estado de uma entrega.
POST
/
v1
/
logistics
/
deliveryUpdate
Envie um evento de entrega
curl --request POST \
--url https://api.dev.connect.onbeefapp.com.br/v1/logistics/deliveryUpdate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-App-Id: <x-app-id>' \
--header 'X-App-MerchantId: <x-app-merchantid>' \
--header 'X-App-Signature: <x-app-signature>' \
--data '
{
"deliveryId": {},
"orderId": {},
"orderDisplayId": "<string>",
"merchant": {},
"event": {},
"customerName": "<string>"
}
'Envie uma atualização quando o estado da entrega mudar. A Onbeef usa esses eventos para manter o rastreamento sincronizado.
Os demais valores (por exemplo,
Autenticação
Os endpoints de logística não usam o Bearer token OAuth. Eles são autenticados por três headers HTTP, validados a cada requisição:string (uuid)
required
Identificador da sua aplicação de logística (UUID v4).
string
required
UUID do merchant na plataforma Onbeef (entre 36 e 100 caracteres).
string
required
Assinatura HMAC-SHA256 (hex, 64 caracteres) do corpo cru da requisição. A chave é o
client_secret fornecido no provisionamento da sua integração de logística. Não use o client_secret OAuth do merchant: são credenciais diferentes.X-App-Signature = hex( hmac_sha256( corpo_cru_da_requisicao, client_secret ) )
A assinatura é calculada sobre o corpo exato enviado. Gere o JSON, calcule o HMAC-SHA256 desse mesmo texto e só então envie a requisição. Qualquer diferença de formatação invalida a assinatura.
Corpo da requisição
O corpo da requisição deve ser enviado comoapplication/json.
string (uuid)
required
Identificador único da entrega, gerado pelo seu serviço de logística.
string (uuid)
required
Identificador do pedido, gerado pela Onbeef. Associa o evento de entrega ao pedido correto na plataforma.
string
required
Identificador legível do pedido exibido na interface da Onbeef.
object
required
Informações sobre o merchant associado ao pedido. Contém
id (uuid) e name (string).object
required
Detalhes do evento atual da entrega. Contém:
type(string): Tipo do evento. Veja Tipos de evento abaixo.message(string): Descrição legível do evento.datetime(string, date-time): Timestamp ISO 8601 de quando o evento ocorreu.rejectionInfo(object, opcional): Presente quandotypeéREJECTED, com um camporeason.
string
required
Nome do cliente que receberá a entrega.
object
Informações do veículo:
type, container, containerSize, instruction.object
Informações de preço da entrega:
price (value, currency), pricingList, additionalPricePercentual.object
Dados de tempo estimado de chegada:
pickupEtaInMinutes, pickupEtaDatetime, deliveryEtaInMinutes, deliveryEtaDatetime, maxDeliveryTime, entre outros.object
Informações do entregador:
id (uuid), name, pictureURL, phone.object
Localização em tempo real do entregador:
latitude, longitude, lastAddress.string (uri)
URL externa do seu serviço de logística para acompanhamento em tempo real.
array of strings (uuid)
IDs adicionais de pedidos do mesmo merchant na mesma rota (mesmo
deliveryId).Este endpoint não valida os campos do corpo com um schema estrito. Envie o payload completo conforme descrito acima; campos ausentes usados pelo processamento podem causar erro no servidor.
Resposta
204: Sem conteúdo
O evento foi recebido e processado com sucesso. Nenhum corpo de resposta é retornado.400: Requisição inválida
Um dos headersX-App-Id, X-App-MerchantId ou X-App-Signature está ausente ou malformado.
401: Não autorizado
OX-App-Id ou o X-App-MerchantId não foi reconhecido, a integração não está ativa, ou a assinatura X-App-Signature não confere.
404: Não encontrado
Nenhum pedido foi encontrado com oorderId informado para este merchant. Corpo: { "title": "Order not found", "status": 404 }.
429: Limite de requisições
A rota aceita até 120 requisições por minuto por endereço IP, num limite compartilhado comPOST /v1/logistics/confirmationCode. Acima disso, a API responde { "title": "Too Many Requests", "status": 429 }. Aguarde e reenvie. Veja Limite de requisições.
Tipos de evento
O campoevent.type sinaliza o estágio atual da entrega. Dois valores transicionam o status do pedido na Onbeef:
| Tipo | Efeito no pedido |
|---|---|
DELIVERY_ONGOING | Marca o pedido como despachado (a caminho do cliente). |
DELIVERY_FINISHED | Marca o pedido como entregue. |
PENDING, REJECTED, CANCELLED, e outros estados de retirada/atribuição) são registrados para rastreamento, mas não alteram o status do pedido. Para REJECTED, inclua event.rejectionInfo.reason.
Exemplo de requisição
curl --request POST \
--url "https://api.dev.connect.onbeefapp.com.br/v1/logistics/deliveryUpdate" \
--header "Content-Type: application/json" \
--header "X-App-Id: <app_uuid>" \
--header "X-App-MerchantId: <merchant_id>" \
--header "X-App-Signature: <hmac_sha256_do_corpo>" \
--data '{
"deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
"orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",
"orderDisplayId": "ORD-0042",
"merchant": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Açougue do João"
},
"event": {
"type": "DELIVERY_ONGOING",
"message": "Pedido a caminho do cliente.",
"datetime": "2024-08-24T14:15:22Z"
},
"customerName": "Maria Silva"
}'
Este endpoint é chamado pela sua integração de logística atuando como remetente de webhook. Não é um endpoint de polling: seu sistema envia atualizações à Onbeef a cada mudança de status da entrega.