Skip to main content
POST
Envie um evento de entrega
Envie uma atualização quando o estado da entrega mudar. A Onbeef usa esses eventos para manter o rastreamento sincronizado.

​
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:
​
X-App-Id
string (uuid)
required
Identificador da sua aplicação de logística (UUID v4).
​
X-App-MerchantId
string
required
Identificador do merchant no contexto da sua integração (entre 36 e 100 caracteres).
​
X-App-Signature
string
required
Assinatura HMAC-SHA256 (hex, 64 caracteres) do corpo cru da requisição, calculada com o client_secret da sua integração de logística como chave.
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 como application/json.
​
deliveryId
string (uuid)
required
Identificador único da entrega, gerado pelo seu serviço de logística.
​
orderId
string (uuid)
required
Identificador do pedido, gerado pela Onbeef. Associa o evento de entrega ao pedido correto na plataforma.
​
orderDisplayId
string
required
Identificador legível do pedido exibido na interface da Onbeef.
​
merchant
object
required
Informações sobre o merchant associado ao pedido. Contém id (uuid) e name (string).
​
event
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 quando type é REJECTED, com um campo reason.
​
customerName
string
required
Nome do cliente que receberá a entrega.
​
vehicle
object
Informações do veículo: type, container, containerSize, instruction.
​
deliveryPrice
object
Informações de preço da entrega: price (value, currency), pricingList, additionalPricePercentual.
​
eta
object
Dados de tempo estimado de chegada: pickupEtaInMinutes, pickupEtaDatetime, deliveryEtaInMinutes, deliveryEtaDatetime, maxDeliveryTime, entre outros.
​
deliveryPerson
object
Informações do entregador: id (uuid), name, pictureURL, phone.
​
geoLocalization
object
Localização em tempo real do entregador: latitude, longitude, lastAddress.
​
externalTrackingURL
string (uri)
URL externa do seu serviço de logística para acompanhamento em tempo real.
​
combinedOrdersIds
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 headers X-App-Id, X-App-MerchantId ou X-App-Signature está ausente ou malformado.

​
401: Não autorizado

O X-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.

​
Tipos de evento

O campo event.type sinaliza o estágio atual da entrega. Dois valores transicionam o status do pedido na Onbeef: Os demais valores (por exemplo, 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

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.