Ambientes e limites de requisições
URLs base sandbox vs produção, prefixos de chave, limites de chamadas por chave de API e como pedir aumento.
Dois ambientes. Duas URLs base. Dois prefixos de chave. As regras são simples e não se cruzam.
Ambientes
| Ambiente | URL base | Prefixo da chave | O que faz |
|---|---|---|---|
| Sandbox | https://api.sandbox.blendfi.com.br | sk_test_… | Espelho funcional da API. Os pagamentos Pix são simulados; as transferências de USDT ficam em carteiras de teste. Sem dinheiro real. |
| Produção | https://api.blendfi.com.br | sk_live_… | Dinheiro real. Pix real. Liquidação on-chain real. Emitida na reunião de liberação de produção, depois que sua integração no sandbox estiver pronta. |
Uma chave de sandbox contra api.blendfi.com.br retorna 401 authentication_failed. Uma chave de produção contra api.sandbox.blendfi.com.br retorna o mesmo. Os dois ambientes não compartilham nada: nem dados, nem chaves, nem registros de idempotência, nem assinaturas de webhook.
Separação rígida
Quando você for para produção, você recria as suas assinaturas de webhook e qualquer estado persistido no ambiente de produção. O estado do sandbox não vai junto. Isso é intencional, força você a verificar a fiação de produção antes que parceiros possam transacionar.
Diferenças que você vai sentir
Pix é simulado no sandbox
No sandbox, você dispara eventos de payment-received com `POST /v1/test_helpers/transactions/{id}/pay`. Em produção, o banco do Pix entrega quando o usuário final realmente paga.
Test helpers não existem em produção
O namespace `/v1/test_helpers/*` é só do sandbox. Chamadas em produção retornam `404`. Os seus caminhos de código que chamam isso precisam ser marcados como test-only.
A liberação de produção é uma reunião
Quando sua integração no sandbox estiver pronta, agende uma reunião de 30 minutos com o time da BlendFi. A reunião cobre a integração (idempotência, retentativas em erros, verificação de assinatura de webhook) e termina com a emissão da sua chave `sk_live_…`.
Limites de transação são uma página separada
Esta página cobre limites de chamadas à API (requisições por minuto por chave). Para os limites de volume de transação (BRL por dia e por mês, em três camadas: plataforma, parceiro e cliente), veja Limites de transação.
Limites de uso
| Endpoint | Limite | Janela | Notas |
|---|---|---|---|
POST /v1/quotes | 60 | por minuto | Por chave de API. Padrão; pode ser aumentado para parceiros de produção sob solicitação. |
| Todos os outros endpoints | (sem limite explícito) | , | Sujeitos a proteções globais contra abuso. Menos de 10 req/s por chave de forma sustentada está tranquilo no sandbox. |
Quando você excede um limite, a resposta é:
{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded for POST /v1/quotes (60/min).",
"request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}A resposta inclui um cabeçalho Retry-After em segundos. Respeite. Se ausente, faça backoff exponencial começando em 1 segundo, com teto de 30 segundos.
Quando pedir aumento
Os limites padrão foram dimensionados para desenvolvimento e lançamento de baixo volume. Se você espera:
- Mais de 60 cotações por minuto em uma única chave em produção: envie um email antes do lançamento, não durante o incidente.
- Mais de 10 req/s sustentado agregando todos os endpoints: idem.
- Padrões de pico (lançamento de campanha, jobs de reconciliação em batch), sinalize antes para podermos pré-aquecer.
Envie um email com: a sua taxa esperada em regime, a sua taxa de pico e a duração dos picos esperados. Aumentamos o limite ou sugerimos um padrão de integração diferente (por exemplo, cache de cotação para o mesmo usuário e valor).
Particularidades do sandbox que vale saber
O estado é resetado periodicamente. Os dados do sandbox são apagados a cada cerca de 30 dias, então qualquer usuário, transação ou assinatura de webhook que você criou pode sumir. Não construa testes de integração de longa duração contra dados do sandbox, recrie fixtures no começo de cada suite.
O sandbox da verificação também é um espelho. Quando você chegar no fluxo de KYC, o sandbox da verificação responde para applicants de teste que provisionamos. CPFs reais no sandbox são criptografados e nunca enviados para um backend de KYC de produção.
Entrega de webhook para localhost funciona. Suportamos ferramentas de túnel (ngrok, cloudflared, tailscale funnel) para teste de webhook no sandbox. Os webhooks de produção precisam terminar em um endpoint HTTPS publicamente alcançável.
Os cabeçalhos de rate limit estão presentes no sandbox também. Use o sandbox para verificar a sua lógica de controle de taxa no cliente antes de bater nos limites de produção.
Domínios customizados e allowlist de IP
O tráfego de produção da BlendFi vem de uma faixa de egress publicada. Compartilhamos a lista atual sob solicitação, útil se o seu receiver de webhook estiver atrás de uma allowlist de IP.
A BlendFi não oferece domínios customizados para tráfego de entrada hoje; toda chamada vai para api.blendfi.com.br. Se o seu modelo de segurança exigir um endpoint específico por tenant, entre em contato com o time comercial.
O que ler em seguida
Primeiros passos
Chave de sandbox, primeira requisição, primeiro usuário, o caminho mais rápido pelos dois ambientes.
Erros e retentativas
Política completa de retry, incluindo o que fazer quando você bate em `rate_limit_exceeded`.
Referência da API
Especificidades por endpoint. Limites de uso aparecem inline onde se aplicam.
FAQ
Por que a URL base de produção não é prod.api.blendfi.com.br ou algo parecido?
Produção é o padrão sem marca, api.blendfi.com.br, então a URL não anuncia "é o ambiente seguro e chato" para qualquer um lendo o seu código. O sandbox é o subdomínio qualificado.
Posso ter uma chave de sandbox e uma de produção na mesma conta? Sim, são emitidas de forma independente, ambas atreladas à mesma organização. A maioria dos parceiros roda lado a lado: sandbox para testes de staging, produção para tráfego real.
O que acontece se eu usar uma chave de sandbox no meu app de produção sem querer?
A chave de sandbox falha contra api.blendfi.com.br com 401 authentication_failed. Nenhum dinheiro real corre risco; a chamada simplesmente falha. Fique de olho nos seus dashboards de taxa de erro, um pico súbito de authentication_failed depois de um deploy é o sinal canônico de que uma variável de ambiente foi trocada.
Os limites de uso são checados antes ou depois da autenticação? Depois. Autenticamos primeiro e depois contamos contra o orçamento por chave. O tráfego anônimo é rejeitado antes de tocar no limiter.
O limiter usa janela deslizante ou janela fixa? Janela deslizante de 60 segundos. Ou seja: 60 requisições no começo do minuto 1 seguidas de 60 no começo do minuto 2 não vão tropeçar no limiter, mas 60 nos últimos 30 segundos do minuto 1 seguidas de mais 60 nos primeiros 30 segundos do minuto 2 vão.