Visão Geral

A BukioPay é uma plataforma de e-commerce. Use a API para gerenciar o catálogo da sua loja, criar pedidos, receber pagamentos e acompanhar tudo pelo seu sistema. Os endpoints ficam sob /api/v1 e trocam dados em JSON.

URL Base

https://api.bukiopay.com/api/v1

Exemplo de URL completa:

https://api.bukiopay.com/api/v1/transactions

Autenticação

Os endpoints protegidos utilizam uma API Key enviada como Bearer Token no header Authorization:

Authorization: Bearer sk_live_sua_api_key

A API não utiliza o header X-API-Key. Envie a credencial exclusivamente no formato Authorization: Bearer <API_KEY>.

A API Key deve possuir o escopo exigido pelo endpoint:

Escopo	Permissão
`transaction.create`	Criar e cancelar transações PIX e pedidos.
`transaction.verify`	Listar e consultar transações e pedidos.
`balance.read`	Consultar saldo e acompanhar saques.
`withdrawal.create`	Criar saques Pix.
`*`	Acesso total aos recursos permitidos para a credencial.

Consulte a página de Autenticação para saber como utilizar e proteger sua API Key.

Endpoints públicos

Alguns endpoints são públicos e não exigem Bearer Token. O checkout público de pedidos utiliza:

POST /api/v1/orders/public

Nesse endpoint, a loja deve ser identificada pelo header:

X-Store-ID: UUID_DA_LOJA

O header X-Store-ID não substitui a autenticação nos endpoints protegidos. Utilize-o somente nos endpoints que documentam explicitamente esse header.

Formato das requisições

Envie corpos de requisição no formato JSON. Para requisições POST, PUT e PATCH com corpo JSON, inclua:

Content-Type: application/json

Exemplo:

curl -X POST 'https://api.bukiopay.com/api/v1/transactions' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "PIX_IN",
    "amount": 49.90,
    "has_products": false,
    "description": "Pagamento de serviço",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com"
    }
  }'

Valores monetários

Os valores financeiros da API são representados em reais, utilizando números decimais.

Valor enviado	Valor representado
`1.00`	R$ 1,00
`49.90`	R$ 49,90
`100.00`	R$ 100,00

Esse formato vale para cobranças, pedidos, produtos, taxas e saques.

Não converta valores para centavos antes de enviá-los. Por exemplo, para representar R$ 100,00, envie 100.00, e não 10000.

Cobranças Pix

As cobranças Pix usam os endpoints de transações:

POST   /api/v1/transactions
GET    /api/v1/transactions
GET    /api/v1/transactions/:id
DELETE /api/v1/transactions/:id

Para criar uma cobrança Pix, envie:

{
  "type": "PIX_IN",
  "amount": 49.90,
  "has_products": false
}

Saques Pix

A cotação e a criação de saques usam:

GET  /api/v1/wallet/withdrawals/quote
POST /api/v1/wallet/withdrawals

Para acompanhar seus saques:

GET /api/v1/wallet/activity?view=withdrawals&limit=20&offset=0

O campo amount representa o valor líquido que o destinatário receberá. A taxa da loja é somada ao débito da carteira. Exemplo: com taxa de R$ 1,00, um saque de R$ 100,00 entrega R$ 100,00 ao destinatário e debita R$ 101,00 da carteira.

Datas

Os campos de data e hora utilizam o formato ISO 8601, normalmente em UTC. Exemplo:

2026-08-15T14:30:00.000Z

Filtros de período também utilizam ISO 8601:

GET /api/v1/transactions?dateFrom=2026-08-01T00:00:00.000Z&dateTo=2026-09-01T00:00:00.000Z

Nos filtros de transações e pedidos:

dateFrom representa o início inclusivo;
dateTo representa o fim exclusivo;
dateFrom deve ser anterior a dateTo.

Paginação

Os endpoints de listagem utilizam os parâmetros limit e offset.

Parâmetro	Tipo	Descrição
`limit`	`number`	Quantidade máxima de registros retornados.
`offset`	`number`	Quantidade de registros ignorados antes do início da página.

Exemplo:

GET /api/v1/transactions?limit=20&offset=0

Paginação de transações

A listagem de transações retorna:

{
  "success": true,
  "data": {
    "transactions": [],
    "pagination": {
      "total": 0,
      "page": 1,
      "pageSize": 20,
      "totalPages": 0
    }
  },
  "requestId": "req_A1B2C3D4"
}

Paginação de pedidos e carteira

Algumas listagens retornam o formato baseado diretamente em limit e offset:

{
  "orders": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 0
  }
}

Consulte a referência de cada endpoint para verificar o formato exato do objeto pagination.

Idempotência

Endpoints financeiros de criação podem aceitar o header Idempotency-Key. Exemplo:

Idempotency-Key: order_ABC123

A idempotência impede que uma repetição crie cobrança, pedido ou saque duplicado. Quando suportado pelo endpoint:

a chave deve identificar uma única operação lógica;
o header tem prioridade sobre idempotencyKey enviado no JSON;
a API devolve a chave efetiva no header Idempotency-Key;
um replay pode retornar Idempotency-Replayed: true;
reutilizar a chave com dados diferentes pode retornar 409 Conflict.

Em timeouts ou resultados incertos, não crie outra operação imediatamente com uma chave diferente. Reutilize a mesma chave e reconcilie o recurso existente.

Formato das respostas

Uma resposta bem-sucedida pode utilizar um envelope como:

{
  "success": true,
  "message": "Transação PIX criada com sucesso",
  "data": {},
  "requestId": "req_A1B2C3D4"
}

Alguns recursos possuem envelopes próprios:

{
  "message": "Pedido criado com sucesso",
  "order": {}
}

Em caso de erro, o formato comum é:

{
  "success": false,
  "error": "Bad Request",
  "message": "Parâmetros inválidos",
  "requestId": "req_A1B2C3D4"
}

Nem todos os middlewares incluem success ou requestId. Utilize o status HTTP como a fonte principal para determinar se a requisição foi bem-sucedida.

Códigos de status HTTP

Código	Status	Descrição
`200`	OK	Requisição processada com sucesso.
`201`	Created	Recurso criado com sucesso.
`400`	Bad Request	Parâmetros ausentes, inválidos ou operação não permitida.
`401`	Unauthorized	Bearer Token ausente, vazio, inválido ou revogado.
`403`	Forbidden	Credencial sem escopo ou sem acesso ao recurso.
`404`	Not Found	Recurso não encontrado ou não pertencente à loja.
`409`	Conflict	Conflito de idempotência ou recurso ainda em processamento.
`410`	Gone	Registro idempotente original removido e chave indisponível para reutilização.
`429`	Too Many Requests	Limite de requisições excedido.
`500`	Internal Server Error	Erro interno ou de persistência.
`501`	Not Implemented	Tipo de operação ainda não implementado no endpoint.
`502`	Bad Gateway	Falha definitiva ou resultado incerto de uma operação financeira.
`503`	Service Unavailable	Serviço, lock ou infraestrutura temporariamente indisponível.

Webhooks

Utilize webhooks para receber atualizações financeiras em tempo real. Eventos principais:

Evento	Descrição
`payment.created`	Cobrança Pix criada.
`payment.paid`	Pagamento Pix confirmado.
`payment.failed`	Criação ou processamento definitivamente não concluído.
`payment.pix.expired`	Cobrança Pix expirada.
`refund.requested`	Estorno solicitado.
`refund.completed`	Estorno concluído.
`refund.failed`	Estorno não concluído.
`transfer.created`	Saque criado e enviado para processamento.
`transfer.completed`	Saque concluído.
`transfer.failed`	Saque não concluído.

Nunca libere produtos, serviços ou acessos apenas com base em informações recebidas pelo frontend. Utilize o webhook payment.paid ou confirme o estado atual pela API.

Endpoints disponíveis

Cobranças Pix

Crie, liste, consulte e cancele cobranças Pix com QR Code e Copia e Cola.

Pedidos

Crie checkouts, acompanhe pagamentos e consulte os pedidos da loja.

Saques Pix

Consulte a taxa, envie Pix e acompanhe seus saques.

Produtos

Cadastre e gerencie os produtos disponíveis para venda.

Categorias

Organize os produtos da loja em categorias.

Cupons

Crie e gerencie cupons de desconto.

Loja

Consulte os dados e as configurações da loja.

Webhooks

Receba e valide notificações de pagamentos, estornos e saques.

Boas práticas

Mantenha a API Key somente no backend.
Utilize apenas os escopos necessários.
Envie valores monetários em reais.
Use Idempotency-Key em operações financeiras que suportam esse header.
Processe webhooks de forma idempotente.
Respeite o header Retry-After quando estiver presente.
Use retry com backoff somente em falhas transitórias.
Não repita automaticamente operações com resultado incerto.
Registre IDs, referências e requestId para rastreabilidade.

Introdução

Conceitos

URL Base

Autenticação

Endpoints públicos

Formato das requisições

Valores monetários

Cobranças Pix

Saques Pix

Datas

Paginação

Paginação de transações

Paginação de pedidos e carteira

Idempotência

Formato das respostas

Códigos de status HTTP

Webhooks

Endpoints disponíveis

Cobranças Pix

Pedidos

Saques Pix

Produtos

Categorias

Cupons

Loja

Webhooks

Boas práticas

​URL Base

​Autenticação

​Endpoints públicos

​Formato das requisições

​Valores monetários

​Cobranças Pix

​Saques Pix

​Datas

​Paginação

​Paginação de transações

​Paginação de pedidos e carteira

​Idempotência

​Formato das respostas

​Códigos de status HTTP

​Webhooks

​Endpoints disponíveis

Cobranças Pix

Pedidos

Saques Pix

Produtos

Categorias

Cupons

Loja

Webhooks

​Boas práticas

URL Base

Autenticação

Endpoints públicos

Formato das requisições

Valores monetários

Cobranças Pix

Saques Pix

Datas

Paginação

Paginação de transações

Paginação de pedidos e carteira

Idempotência

Formato das respostas

Códigos de status HTTP

Webhooks

Endpoints disponíveis

Boas práticas