Sandbox e chaves
Sandbox vs produção, como pedir chaves e o que muda quando você sobe para produção.
O sandbox é um espelho vivo da API da BlendFi onde os mesmos endpoints, formatos de resposta e códigos de erro se aplicam, mas os pagamentos Pix são simulados, as transferências USDT ficam numa carteira de teste e os endpoints test_helpers deixam você avançar o ciclo de vida programaticamente. Construa aqui primeiro; analisamos a sua integração sandbox antes de emitir uma chave sk_live_….
O que é igual
- Formatos de request e response idênticos. Todo payload, todo nome de campo, todo código de erro.
- Semântica de webhook idêntica. Assinatura, retentativas, janela de replay e tipos de evento.
- Fluxo KYC idêntico. A verificação hospedada pela BlendFi funciona no sandbox.
- Catálogo de erros idêntico. Mesmos
codes, mesmo formato de resposta.
O que é diferente
- O Pix é simulado. Um app de banco real apontado para um QR Pix de sandbox não paga nada; o sandbox usa
test_helperspara avançar de estado. - O DICT PIX é simulado. O sandbox não consulta o DICT real. Veja o Guia de testes no sandbox para as chaves fixas a usar.
- A exchange é mockada. Nenhum trade real BRL → USDT é executado.
- O USDT fica em uma conta de custódia de sandbox. Sem transferências on-chain para carteiras na mainnet.
- Endpoints exclusivos do sandbox.
/v1/test_helpers/*existe apenas no sandbox; em produção retorna 404. - Sem dinheiro real. Nunca.
URLs base
| Ambiente | URL base |
|---|---|
| Sandbox | https://api.sandbox.blendfi.com.br |
| Produção | https://api.blendfi.com.br |
Para os limites atuais de uso por endpoint, veja Ambientes e limites.
Como pedir uma chave de sandbox
Agende uma reunião de 30 minutos com o nosso time. Nessa conversa, entendemos o seu caso de uso e emitimos a sua chave de sandbox na hora, escopada com um conjunto padrão de capabilities que você pode refinar depois.
As chaves de sandbox nunca expiram sozinhas e podem ser revogadas ou rotacionadas sob demanda.
Subindo para produção
Quando a sua integração sandbox estiver pronta para dinheiro real, agende a reunião de liberação de produção. Nessa conversa, vamos:
- Percorrer a sua integração sandbox (idempotência, verificação de assinatura, tratamento de erro, logging de
request_id). - Emitir a chave
sk_live_…com as capabilities apropriadas. O escopo padrão é o mesmo da sua chave sandbox, menossandbox:control.
A maioria dos parceiros sai dessa reunião com a chave de produção em mãos.
Construa no sandbox primeiro
O sandbox é uma cópia viva da BlendFi onde os mesmos endpoints, formatos de resposta e códigos de erro se aplicam, mas os pagamentos PIX são simulados e as transferências USDT ficam numa carteira de teste. Analisamos a sua integração sandbox de ponta a ponta antes de emitir uma chave sk_live_….
FAQ
Onde pego uma chave de sandbox? Agende uma reunião de 30 minutos. Você sai dessa conversa com a sua chave de sandbox.
Posso ter mais de uma chave? Sim. Podemos emitir chaves escopadas por capability (read-only, transactions-only, etc.) para você compartimentar integrações. Peça durante a sua reunião de onboarding.
Como rotaciono uma chave?
Você mesmo faz. Uma única chamada a POST /v1/api-keys/{id}/rotate emite uma chave nova com as mesmas capabilities e revoga a antiga imediatamente, sem precisar abrir chamado de suporte. O novo segredo é retornado uma única vez. Veja Autenticação.
Por que ainda não tenho uma chave sk_live_…?
As chaves de produção são emitidas durante a reunião de liberação de produção. Construa no sandbox primeiro e depois agende aqui.
Onde reporto um bug?
Envie um email ao suporte com o request_id da resposta. Com ele, encontramos o seu request em segundos.
Leia em seguida
- Início rápido, sua primeira chamada autenticada
- Autenticação, Bearer e capabilities
- Webhooks → Testes no sandbox, listener local + configuração de túnel
- Guia de testes no sandbox, chaves PIX de teste, helpers de conversão, forçamento de KYC