Ambientes e limites
URLs base sandbox vs produção, prefixos de chave, limites de taxa atuais e como pedir aumento.
Ambientes e limites
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. Pagamentos Pix são simulados, transferências de USDT ficam em carteiras de teste. Sem dinheiro real. |
| Produção | https://api.blendfi.com | sk_live_… | Dinheiro real. Pix real. Liquidação on-chain real. Emitida só após revisão de compliance da sua integração no sandbox. |
Uma chave de sandbox contra api.blendfi.com 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ê re-cria 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 sua 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`. Seus caminhos de código que chamam isso precisam ser marcados como test-only.
Revisão de compliance é o gate de produção
A gente revisa sua integração no sandbox de ponta a ponta (idempotência, retentativas em erros, verificação de assinatura de webhook) antes de emitir sua chave `sk_live_…`.
Limites de taxa
| 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
Limites padrão foram dimensionados para desenvolvimento e lançamento de baixo volume. Se você espera:
- Mais de 60 cotações/min numa única chave em produção — manda e-mail 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 a gente pré-aquecer.
Manda e-mail com: sua taxa esperada de regime, sua taxa de pico e a duração dos picos esperados. A gente aumenta o limite ou sugere um padrão de integração diferente (por exemplo, cache de cotação para o mesmo usuário/valor).
Particularidades do sandbox que vale saber
O estado é resetado periodicamente. Dados do sandbox são apagados a cada uns 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 Sumsub também é um espelho. Quando você chegar no fluxo de KYC, o sandbox da Sumsub 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. A gente suporta ferramentas de tunneling (ngrok, cloudflared, tailscale funnel) para teste de webhook no sandbox. Webhooks de produção precisam terminar num endpoint HTTPS publicamente alcançável.
Cabeçalhos de rate limit estão presentes no sandbox também. Use o sandbox para verificar sua lógica de throttling no cliente antes de bater nos limites de produção.
Domínios customizados e allowlist de IP
Tráfego de produção da BlendFi vem de uma faixa de egress publicada. A gente compartilha a lista atual sob solicitação — útil se seu receiver de webhook estiver atrás de uma allowlist de IP.
Atualmente não oferecemos domínios customizados para tráfego de entrada (você chama api.blendfi.com, ponto). Se seu modelo de segurança exige um endpoint específico por tenant, fala com a gente.
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 taxa surgem inline onde se aplicam.
FAQ
Por que a URL base de produção não é prod.api.blendfi.com ou parecido?
Produção é o padrão sem marca — api.blendfi.com — então a URL não anuncia "é o ambiente seguro e chato" para qualquer um lendo seu código. Sandbox é o subdomínio qualificado.
Posso ter uma chave de sandbox e uma de produção na mesma conta? Sim — são emitidas independentes, 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 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 taxa são checados antes ou depois da autenticação? Depois. A gente autentica primeiro, depois conta contra o orçamento por chave. Tráfego anônimo é rejeitado antes de tocar no limiter.
O limiter usa janela deslizante ou janela fixa? Janela deslizante de 60 segundos. Então 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.