> ## 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. # Visão Geral > URL base, autenticação, valores em reais e formato das respostas da API da BukioPay. 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 ```text theme={null} https://api.bukiopay.com/api/v1 ``` Exemplo de URL completa: ```text theme={null} https://api.bukiopay.com/api/v1/transactions ``` ## Autenticação Os endpoints protegidos utilizam uma API Key enviada como Bearer Token no header `Authorization`: ```http theme={null} 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 `. 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](/authentication) 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: ```text theme={null} POST /api/v1/orders/public ``` Nesse endpoint, a loja deve ser identificada pelo header: ```http theme={null} 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: ```http theme={null} Content-Type: application/json ``` Exemplo: ```bash theme={null} 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: ```text theme={null} 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: ```json theme={null} { "type": "PIX_IN", "amount": 49.90, "has_products": false } ``` ## Saques Pix A cotação e a criação de saques usam: ```text theme={null} GET /api/v1/wallet/withdrawals/quote POST /api/v1/wallet/withdrawals ``` Para acompanhar seus saques: ```text theme={null} 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: ```text theme={null} 2026-08-15T14:30:00.000Z ``` Filtros de período também utilizam ISO 8601: ```text theme={null} 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: ```text theme={null} GET /api/v1/transactions?limit=20&offset=0 ``` ### Paginação de transações A listagem de transações retorna: ```json theme={null} { "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`: ```json theme={null} { "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: ```http theme={null} 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: ```json theme={null} { "success": true, "message": "Transação PIX criada com sucesso", "data": {}, "requestId": "req_A1B2C3D4" } ``` Alguns recursos possuem envelopes próprios: ```json theme={null} { "message": "Pedido criado com sucesso", "order": {} } ``` Em caso de erro, o formato comum é: ```json theme={null} { "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 Crie, liste, consulte e cancele cobranças Pix com QR Code e Copia e Cola. Crie checkouts, acompanhe pagamentos e consulte os pedidos da loja. Consulte a taxa, envie Pix e acompanhe seus saques. Cadastre e gerencie os produtos disponíveis para venda. Organize os produtos da loja em categorias. Crie e gerencie cupons de desconto. Consulte os dados e as configurações da loja. 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.