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

# Solicite um cancelamento

> Solicite o cancelamento de um pedido.

Chame este endpoint quando sua loja não puder cumprir um pedido. Informe o código, o motivo e o modo exigidos pelo payload.

## Parâmetros de rota

<ParamField path="orderId" type="string (uuid)" required>
  Identificador único do pedido para o qual você está solicitando o cancelamento. Gerado pela Onbeef e retornado no evento do pedido.
</ParamField>

## Corpo da requisição

<ParamField body="reason" type="string" required>
  Descrição em texto livre explicando por que o pedido está sendo cancelado. Pode ser compartilhada com o cliente.
</ParamField>

<ParamField body="code" type="string" required>
  Código padronizado de motivo do cancelamento. Deve ser um dos valores a seguir:

  | Código                                    | Descrição                                                       |
  | ----------------------------------------- | --------------------------------------------------------------- |
  | `SYSTEMIC_ISSUES`                         | Problemas técnicos ou de sistema.                               |
  | `DUPLICATE_APPLICATION`                   | O pedido foi realizado mais de uma vez.                         |
  | `UNAVAILABLE_ITEM`                        | Um ou mais itens estão sem estoque.                             |
  | `RESTAURANT_WITHOUT_DELIVERY_PERSON`      | Não há entregador disponível.                                   |
  | `OUTDATED_MENU`                           | O cardápio não está atualizado e o item não pode ser preparado. |
  | `ORDER_OUTSIDE_THE_DELIVERY_AREA`         | O endereço de entrega está fora da área atendida.               |
  | `BLOCKED_CUSTOMER`                        | O cliente está bloqueado para fazer pedidos.                    |
  | `OUTSIDE_DELIVERY_HOURS`                  | O pedido foi feito fora do horário de operação.                 |
  | `INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT` | Problemas internos que impedem o cumprimento.                   |
  | `RISK_AREA`                               | O endereço de entrega está em área de risco restrita.           |
  | `DELIVERY_PROBLEM`                        | Ocorreu um problema no processo de entrega.                     |
</ParamField>

<ParamField body="mode" type="string" required>
  Indica como o cancelamento foi iniciado.

  * `AUTO`: Disparado automaticamente pelo seu PDV ou sistema de integração.
  * `MANUAL`: Disparado manualmente por um funcionário.
</ParamField>

<ParamField body="outOfStockItems" type="array of strings (uuid)">
  Lista opcional de UUIDs de itens sem estoque. Recomendado quando o `code` é `UNAVAILABLE_ITEM`. Cada entrada deve ser um UUID válido.
</ParamField>

<ParamField body="invalidItems" type="array of strings (uuid)">
  Lista opcional de UUIDs de itens que não existem no seu estoque. Cada entrada deve ser um UUID válido.
</ParamField>

## Resposta

### 202: Aceito

A solicitação de cancelamento foi aceita para processamento. A Onbeef se encarregará de notificar o cliente.

### 401: Não autorizado

Retornado quando a requisição não inclui credenciais de autenticação válidas.

### 404: Não encontrado

Nenhum pedido foi encontrado com o `orderId` informado.

### 400: Requisição inválida

O pedido já está no estado solicitado (por exemplo, já cancelado). Corpo: `{ "title": "Order has already same event type", "status": 400 }`.

## Exemplo de requisição

<CodeGroup>
  ```bash Sandbox theme={null}
  curl --request POST \
    --url "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/requestCancellation" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
      "reason": "O corte solicitado não está disponível hoje.",
      "code": "UNAVAILABLE_ITEM",
      "mode": "MANUAL",
      "outOfStockItems": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
      "invalidItems": []
    }'
  ```

  ```bash Produção theme={null}
  curl --request POST \
    --url "https://api.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/requestCancellation" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
      "reason": "O corte solicitado não está disponível hoje.",
      "code": "UNAVAILABLE_ITEM",
      "mode": "MANUAL",
      "outOfStockItems": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
      "invalidItems": []
    }'
  ```
</CodeGroup>

## Exemplo de corpo da requisição

```json theme={null}
{
  "reason": "O corte solicitado não está disponível hoje.",
  "code": "UNAVAILABLE_ITEM",
  "mode": "MANUAL",
  "outOfStockItems": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "invalidItems": []
}
```

<Warning>
  Solicitar um cancelamento não cancela o pedido imediatamente: a Onbeef processa a solicitação e pode exigir ações adicionais. Monitore sua fila de eventos por um evento `CANCELLED` para confirmar que o cancelamento foi concluído.
</Warning>

<Tip>
  Use o código `SYSTEMIC_ISSUES` para cancelamentos automatizados disparados por falhas de integração ou indisponibilidade inesperada e, nesses casos, defina `mode` como `AUTO` para uma reportagem precisa.
</Tip>