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

# Pedidos e Checkout Público

> Estrutura dos pedidos, checkout público com Pix, valores em reais, idempotência e confirmação por webhook.

Os pedidos da BukioPay conectam o catálogo de produtos ao checkout com pagamento PIX.

Quando o cliente inicia uma compra, a API valida os produtos e as variações diretamente no catálogo da loja, calcula o valor do pedido e gera uma cobrança PIX associada ao pedido.

## Estrutura de um pedido

A resposta da criação pública contém os seguintes campos principais:

| Campo | Tipo | Descrição |
| - | - | - |
| `order.id` | `string` | UUID interno do pedido. |
| `order.order_code` | `string` | Código público do pedido. |
| `order.store_id` | `string` | UUID da loja responsável pelo pedido. |
| `order.customer_name` | `string` | Nome do cliente. |
| `order.customer_email` | `string` | E-mail do cliente. |
| `order.customer_document` | `string` | CPF ou CNPJ do cliente, quando informado. |
| `order.financial.currency` | `string` | Moeda do pedido. Sempre `BRL`. |
| `order.financial.price` | `number` | Valor total do pedido em reais. |
| `order.gateway.type` | `string` | Método de pagamento utilizado. Para PIX, o valor é `PIX`. |
| `order.gateway.external_id` | `string` | Identificador externo da cobrança associada ao pedido. |
| `order.status.code` | `string` | Código atual do status do pedido. |
| `order.status.display` | `string` | Descrição legível do status. |
| `order.items` | `array` | Itens validados e associados ao pedido. |
| `order.pix` | `object` | Dados do pagamento PIX. Pode ser `null` se a cobrança ainda não tiver sido confirmada. |
| `order.created_at` | `string` | Data e hora de criação no formato ISO 8601. |
| `order.updated_at` | `string` | Data e hora da última atualização no formato ISO 8601. |

<Warning>
  Os valores financeiros dos pedidos são representados em reais, e não em centavos. Por exemplo, `49.90` representa R\$ 49,90.
</Warning>

<Warning>
  Não envie o preço dos produtos como fonte de verdade. A BukioPay consulta os produtos e as variações cadastradas na loja e calcula o total do pedido no servidor.
</Warning>

## Status dos pedidos

Os principais estados do pedido são:

| Status | Descrição |
| - | - |
| `pending` | Pedido criado e aguardando a confirmação do pagamento. |
| `paid` | Pagamento confirmado. O pedido pode ser processado e entregue. |
| `cancelled` | Pedido encerrado sem pagamento, cancelado ou expirado. |
| `refunded` | Pagamento do pedido estornado. |

O fluxo mais comum é:

```text theme={null}
pending → paid
```

Quando o pagamento não é concluído:

```text theme={null}
pending → cancelled
```

<Warning>
  Nunca libere produtos, arquivos, links, serviços ou acessos apenas porque o pedido foi criado. Aguarde o evento `payment.paid` ou confirme que o pedido está com status `paid`.
</Warning>

## Fluxo de checkout

<Steps>
  <Step title="Cliente seleciona os produtos">
    O cliente escolhe os produtos e as variações desejadas e informa seus dados pessoais.
  </Step>

  <Step title="Sua aplicação cria o pedido">
    O frontend envia uma requisição para `POST /api/v1/orders/public`, incluindo o header `X-Store-ID`, os dados do cliente e os identificadores dos produtos.
  </Step>

  <Step title="A BukioPay valida o catálogo">
    A API consulta os produtos e as variações cadastradas, valida estoque e disponibilidade e calcula o valor final do pedido no servidor.
  </Step>

  <Step title="A API gera o pagamento PIX">
    A resposta contém `order.pix.qr_code`, `order.pix.copy_paste` e `order.pix.expires_at` quando a cobrança PIX é criada com sucesso.
  </Step>

  <Step title="Cliente realiza o pagamento">
    O cliente escaneia o QR Code ou utiliza o código Copia e Cola no aplicativo bancário.
  </Step>

  <Step title="Sua aplicação recebe a confirmação">
    Utilize o webhook `payment.paid` como mecanismo principal para confirmar o pagamento e liberar o pedido.
  </Step>
</Steps>

## Criando um checkout público

O checkout público utiliza o seguinte endpoint:

```text theme={null}
POST /api/v1/orders/public
```

Esse endpoint não exige Bearer Token. Entretanto, o UUID da loja deve ser enviado no header `X-Store-ID`.

```http theme={null}
X-Store-ID: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
```

<Warning>
  Nunca envie uma API Key para o navegador. O checkout público foi criado para ser usado sem expor credenciais privadas.
</Warning>

## Corpo da requisição

<ParamField body="customerName" type="string" required>
  Nome completo do cliente.
</ParamField>

<ParamField body="customerEmail" type="string" required>
  E-mail válido do cliente.
</ParamField>

<ParamField body="customerPhone" type="string">
  Telefone do cliente.
</ParamField>

<ParamField body="customerDocument" type="string">
  CPF ou CNPJ do cliente. A API remove automaticamente caracteres de formatação.
</ParamField>

<ParamField body="items" type="array" required>
  Lista dos produtos incluídos no pedido. O pedido deve possuir pelo menos um item.
</ParamField>

<ParamField body="items[].productId" type="string" required>
  UUID do produto cadastrado na loja.
</ParamField>

<ParamField body="items[].variantId" type="string">
  UUID da variação selecionada, quando o produto possuir variações.
</ParamField>

<ParamField body="items[].quantity" type="number" required>
  Quantidade desejada. Deve ser maior que zero.
</ParamField>

<ParamField body="paymentMethod" type="string">
  Método de pagamento. Para checkout PIX, envie `pix`. Quando omitido, o padrão é PIX.
</ParamField>

<ParamField body="couponCode" type="string">
  Código de cupom que deverá ser aplicado ao pedido.
</ParamField>

<ParamField body="salesAffiliateCode" type="string">
  Código de atribuição de afiliado, quando aplicável.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Alternativa para enviar a chave de idempotência no corpo. O header `Idempotency-Key` tem prioridade.
</ParamField>

## Exemplo de requisição

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/orders/public' \
  --header 'X-Store-ID: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Idempotency-Key: checkout_ORDER_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerName": "João Silva",
    "customerEmail": "joao@example.com",
    "customerPhone": "5511999999999",
    "customerDocument": "12345678900",
    "paymentMethod": "pix",
    "items": [
      {
        "productId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
        "variantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "quantity": 1
      }
    ]
  }'
```

## Exemplo de resposta

Uma criação pública bem-sucedida retorna `200 OK`.

```json theme={null}
{
  "message": "Pedido criado com sucesso",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "order_code": "ABC123DEF456GHI789",
    "store_id": "8f14e45f-ea2f-4a9d-bc52-3d19c9ea6d42",
    "customer_name": "João Silva",
    "customer_email": "joao@example.com",
    "customer_document": "12345678900",
    "financial": {
      "currency": "BRL",
      "price": 49.90
    },
    "gateway": {
      "type": "PIX",
      "external_id": "pix-reference"
    },
    "status": {
      "code": "pending",
      "display": "Pendente"
    },
    "items": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "product_id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
        "variant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Produto Exemplo",
        "quantity": 1,
        "price": 49.90
      }
    ],
    "pix": {
      "qr_code": "data:image/png;base64,iVBORw0KGgo...",
      "copy_paste": "00020101021226820014br.gov.bcb.pix...",
      "expires_at": "2026-08-15T15:30:00.000Z"
    },
    "created_at": "2026-08-15T14:30:00.000Z",
    "updated_at": "2026-08-15T14:30:00.000Z"
  }
}
```

<Note>
  O campo `order.pix` pode ser `null` quando não for possível confirmar a criação do pagamento. A resposta também pode incluir `warning`. Nesse caso, não crie outro pedido imediatamente usando uma chave diferente.
</Note>

## Idempotência do checkout

Envie uma chave de idempotência em todas as criações:

```http theme={null}
Idempotency-Key: checkout_ORDER_123
```

A chave também pode ser enviada como `idempotencyKey` no corpo, mas o header tem prioridade.

* A API retorna a chave efetiva no header `Idempotency-Key`.
* Um replay seguro preserva o mesmo pedido.
* Um replay é indicado por `Idempotency-Replayed: true`.
* Se a mesma chave for reutilizada com dados diferentes, a API retorna `409 Conflict`.
* Se o pedido ainda estiver sendo processado, a API pode retornar `409 Conflict` e `Retry-After`.
* Se a criação do PIX estiver incerta, a API retorna `PaymentCreationUnknown` e não repete automaticamente o envio.

<Warning>
  Se receber `PaymentCreationUnknown`, não crie outro pedido imediatamente. Utilize a mesma `Idempotency-Key` e reconcilie o pedido existente.
</Warning>

## Exibindo o QR Code

Quando `order.pix.qr_code` contiver uma Data URL, ela poderá ser utilizada diretamente:

```html theme={null}
<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>
```

Para o código Copia e Cola:

```html theme={null}
<input
  type="text"
  value="00020101021226820014br.gov.bcb.pix..."
  readonly
  id="pix-copy-paste"
/>

<button
  type="button"
  onclick="navigator.clipboard.writeText(document.getElementById('pix-copy-paste').value)"
>
  Copiar código PIX
</button>
```

## Confirmando o pagamento

Use o webhook `payment.paid` como mecanismo principal para confirmar o pagamento.

O webhook informa a transição financeira em tempo real e deve ser processado de forma idempotente.

```json theme={null}
{
  "event": "payment.paid",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_IN",
    "status": "paid",
    "amount": 49.90,
    "currency": "BRL"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-15T14:35:00.000Z"
}
```

<Note>
  A consulta do pedido pode ser utilizada como fallback ou para reconciliação. Evite depender de polling contínuo quando os webhooks estiverem configurados.
</Note>

## Consultando um pedido autenticado

Para consultar os dados completos de um pedido pelo backend, utilize:

```text theme={null}
GET /api/v1/orders/:id
```

Esse endpoint requer Bearer Token com o escopo `transaction.verify`.

O parâmetro `:id` aceita:

* UUID interno do pedido;
* `order_code` de 18 caracteres.

```bash theme={null}
curl -X GET 'https://api.bukiopay.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer sk_live_sua_api_key'
```

## Listando pedidos

Para listar os pedidos da loja autenticada, utilize:

```text theme={null}
GET /api/v1/orders
```

Esse endpoint exige o escopo `transaction.verify`.

Filtros disponíveis:

| Parâmetro | Descrição |
| - | - |
| `status` | Filtra pelo status do pedido. |
| `limit` | Quantidade por página. Padrão `50`, máximo `100`. |
| `offset` | Quantidade de registros ignorados. Padrão `0`. |
| `search` | Busca por UUID, código do pedido, cliente, pagador ou e-mail. |
| `dateFrom` | Início inclusivo do período no formato ISO 8601. |
| `dateTo` | Fim exclusivo do período no formato ISO 8601. |
| `productIds` | Lista de UUIDs de produtos separados por vírgula. |
| `onlyAutoApproved` | Use `true` para filtrar pedidos não aprovados manualmente. |

## Boas práticas

<AccordionGroup>
  <Accordion title="Nunca confie nos preços enviados pelo frontend" icon="shield">
    Envie apenas os identificadores dos produtos, das variações e as quantidades. A BukioPay consulta o catálogo e calcula os valores no servidor.
  </Accordion>

  <Accordion title="Use uma chave de idempotência" icon="key">
    Gere uma `Idempotency-Key` para cada tentativa lógica de checkout e reutilize a mesma chave em retries.
  </Accordion>

  <Accordion title="Confirme o pagamento por webhook" icon="circle-check">
    Utilize `payment.paid` como mecanismo principal de confirmação antes de entregar produtos ou liberar acessos.
  </Accordion>

  <Accordion title="Não exponha sua API Key" icon="lock">
    Utilize `POST /api/v1/orders/public` no frontend com `X-Store-ID`. Endpoints autenticados e API Keys devem permanecer no backend.
  </Accordion>

  <Accordion title="Não entregue o pedido apenas pelo retorno da criação" icon="triangle-exclamation">
    O retorno da criação confirma que o pedido foi registrado, não que o pagamento foi concluído. Aguarde o status `paid`.
  </Accordion>
</AccordionGroup>

***

Pronto para integrar pedidos na sua loja? Consulte a referência completa dos endpoints.

[Ver endpoints de Pedidos →](/api-reference/orders/list)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.