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

# Criar Pedido

> Cria um pedido com produtos do catálogo usando a API key (escopo transaction.create) e retorna o QR Code Pix e o Copia e Cola.

Cria um pedido com produtos do seu catálogo e gera a cobrança Pix.

**Método:** `POST /api/v1/orders`

**Autenticação:** Obrigatória — inclua o header `Authorization: Bearer sk_live_sua_api_key`. A loja é identificada pela API key; **não envie** `X-Store-ID`. Escopo necessário: `transaction.create`.

<Note>
  Para o checkout público no seu frontend (sem API key), use `POST /api/v1/orders/public`, que identifica a loja pelo header `X-Store-ID` — os campos do corpo são os mesmos. Não use o endpoint público em integrações de backend autenticadas.
</Note>

## Parâmetros do corpo

<ParamField body="customerName" type="string" required>
  Nome de quem está comprando.
</ParamField>

<ParamField body="customerEmail" type="string" required>
  E-mail do cliente. É por onde a entrega é enviada.
</ParamField>

<ParamField body="paymentMethod" type="string" required>
  Use `PIX`.
</ParamField>

<ParamField body="items" type="object[]" required>
  Itens do pedido. Precisa ter ao menos um.
</ParamField>

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

<ParamField body="items[].quantity" type="number" required>
  Quantidade, inteiro maior que zero.
</ParamField>

<ParamField body="items[].variantId" type="string">
  UUID da variação. Obrigatório quando o produto é `variable`.
</ParamField>

<Warning>
  O preço não é enviado na requisição: vale sempre o preço cadastrado no produto. Isso impede que o valor seja alterado pelo lado do cliente.
</Warning>

## Exemplo de requisição

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/orders' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order_2026_0001' \
  --data '{
    "customerName": "Maria Silva",
    "customerEmail": "maria@exemplo.com",
    "paymentMethod": "PIX",
    "items": [
      {
        "productId": "9d40e409-28e6-481f-aafc-83f97b831f07",
        "quantity": 1
      }
    ]
  }'
```

## Resposta

```json theme={null}
{
  "order": {
    "id": "8159fbe2-fd7d-4b28-8028-1257210b32d0",
    "order_code": "2IH180IE7K3M9P4Q6R",
    "customer_name": "Maria Silva",
    "customer_email": "maria@exemplo.com",
    "financial": {
      "currency": "BRL",
      "price": 149.9
    },
    "status": {
      "code": "pending",
      "display": "Pendente"
    },
    "items": [
      {
        "product_id": "9d40e409-28e6-481f-aafc-83f97b831f07",
        "variant_id": null,
        "name": "Produto Exemplo",
        "quantity": 1,
        "price": 149.9
      }
    ],
    "pix": {
      "qr_code": "data:image/png;base64,iVBORw0KGgo...",
      "copy_paste": "00020126580014BR.GOV.BCB.PIX...",
      "expires_at": "2026-08-26T12:28:00.000Z"
    },
    "created_at": "2026-08-26T11:58:00.000Z"
  }
}
```

Exiba `pix.qr_code` como imagem e `pix.copy_paste` como texto copiável.

## Idempotência

Envie o header `Idempotency-Key` para poder repetir a requisição com segurança. Uma repetição com a mesma chave devolve o mesmo pedido e o mesmo Pix, sem cobrar o cliente duas vezes.

## Pagamento indisponível

Se o pedido for criado mas a cobrança falhar, a resposta traz `pix: null` e um campo `warning`. O pedido existe, mas não há como pagá-lo — crie outro.

## Confirmar o pagamento

Assine o webhook `payment.paid`, ou consulte `GET /api/v1/orders/:id` com a mesma API key (escopo `transaction.verify`). Só libere o produto após a confirmação.


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