> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onbeef.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Envie um evento de entrega

> Atualize o estado de uma 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:

<ParamField header="X-App-Id" type="string (uuid)" required>
  Identificador da sua aplicação de logística (UUID v4).
</ParamField>

<ParamField header="X-App-MerchantId" type="string" required>
  Identificador do merchant no contexto da sua integração (entre 36 e 100 caracteres).
</ParamField>

<ParamField header="X-App-Signature" type="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.
</ParamField>

```text theme={null}
X-App-Signature = hex( hmac_sha256( corpo_cru_da_requisicao, client_secret ) )
```

<Warning>
  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.
</Warning>

## Corpo da requisição

O corpo da requisição deve ser enviado como `application/json`.

<ParamField body="deliveryId" type="string (uuid)" required>
  Identificador único da entrega, gerado pelo seu serviço de logística.
</ParamField>

<ParamField body="orderId" type="string (uuid)" required>
  Identificador do pedido, gerado pela Onbeef. Associa o evento de entrega ao pedido correto na plataforma.
</ParamField>

<ParamField body="orderDisplayId" type="string" required>
  Identificador legível do pedido exibido na interface da Onbeef.
</ParamField>

<ParamField body="merchant" type="object" required>
  Informações sobre o merchant associado ao pedido. Contém `id` (uuid) e `name` (string).
</ParamField>

<ParamField body="event" type="object" required>
  Detalhes do evento atual da entrega. Contém:

  * `type` (string): Tipo do evento. Veja [Tipos de evento](#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`.
</ParamField>

<ParamField body="customerName" type="string" required>
  Nome do cliente que receberá a entrega.
</ParamField>

<ParamField body="vehicle" type="object">
  Informações do veículo: `type`, `container`, `containerSize`, `instruction`.
</ParamField>

<ParamField body="deliveryPrice" type="object">
  Informações de preço da entrega: `price` (`value`, `currency`), `pricingList`, `additionalPricePercentual`.
</ParamField>

<ParamField body="eta" type="object">
  Dados de tempo estimado de chegada: `pickupEtaInMinutes`, `pickupEtaDatetime`, `deliveryEtaInMinutes`, `deliveryEtaDatetime`, `maxDeliveryTime`, entre outros.
</ParamField>

<ParamField body="deliveryPerson" type="object">
  Informações do entregador: `id` (uuid), `name`, `pictureURL`, `phone`.
</ParamField>

<ParamField body="geoLocalization" type="object">
  Localização em tempo real do entregador: `latitude`, `longitude`, `lastAddress`.
</ParamField>

<ParamField body="externalTrackingURL" type="string (uri)">
  URL externa do seu serviço de logística para acompanhamento em tempo real.
</ParamField>

<ParamField body="combinedOrdersIds" type="array of strings (uuid)">
  IDs adicionais de pedidos do mesmo merchant na mesma rota (mesmo `deliveryId`).
</ParamField>

<Note>
  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.
</Note>

## 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:

| Tipo                | Efeito no pedido                                       |
| ------------------- | ------------------------------------------------------ |
| `DELIVERY_ONGOING`  | Marca o pedido como despachado (a caminho do cliente). |
| `DELIVERY_FINISHED` | Marca o pedido como entregue.                          |

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

```bash theme={null}
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"
  }'
```

<Note>
  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.
</Note>