Construa uma integração de PIX para USDT do sandbox até produção em cinco minutos.

Comece aqui

Construa uma integração PIX para USDT

Receba BRL via Pix dos seus usuários finais; liquide USDT em uma carteira que você controla. Este guia leva você de "acabei de receber uma chave de API" até "fiz uma chamada autenticada de verdade" em cerca de cinco minutos.

O que você vai fazer

Pegue sua chave de sandbox

Receba sua chave `sk_test_…` por e-mail. O sandbox é uma cópia funcional da BlendFi onde nenhum dinheiro real se move.

Autentique cada requisição

Toda chamada para `/v1/*` envia sua chave como Bearer token. Sem login, sem sessão — a chave é a sessão.

Crie seu primeiro usuário

Envie um `external_id`, nome e CPF. Recebe um ID de usuário BlendFi para usar em toda transação.

Tutorial rápido

1. Configure o ambiente

Coloque sua chave de sandbox numa variável de shell para os exemplos a seguir ficarem prontos para copiar e colar.

export BLENDFI_KEY=sk_test_substitua_pela_sua_chave_real
export BLENDFI_BASE=https://api.sandbox.blendfi.com.br

Você sabe em qual ambiente está pelo prefixo da chave:

Prefixo	Ambiente	O que ela faz
`sk_test_…`	Sandbox	Qualquer coisa. Sem dinheiro real.
`sk_live_…`	Produção	Dinheiro real. Liberada só após revisão de compliance.

Uma chave de sandbox não consegue atingir produção por engano, e uma chave de produção não consegue atingir o sandbox — ambas são rejeitadas com 401 authentication_failed.

2. Autentique cada requisição

Toda chamada para /v1/* envia sua chave no cabeçalho Authorization como um Bearer token:

Authorization: Bearer sk_test_…

Três coisas para saber:

A palavra Bearer é obrigatória. Só Authorization: sk_test_… retorna 401 authentication_required.
A chave vai em toda requisição. Não tem login, não tem cookie de sessão, não tem refresh de token. A chave é a sessão.
Capacidades são por chave. Cada chave tem uma lista de capacidades (por exemplo, users:create, transactions:create). Se a chave tentar um endpoint para o qual não tem permissão, vem 403 missing_capability. A maioria dos parceiros começa com uma chave de sandbox com permissão total; chaves de produção são mais restritas.

3. Faça sua primeira chamada

Crie um usuário de teste. Essa é a "primeira chamada" canônica porque a maioria dos outros endpoints precisa de um ID de usuário.

curl -X POST $BLENDFI_BASE/v1/users \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "external_id": "id-interno-do-seu-usuario-001",
    "name": "Ada Lovelace",
    "cpf": "52998224725"
  }'

Se tudo estiver ligado:

{
  "id": "01J…",
  "external_id": "id-interno-do-seu-usuario-001",
  "name": "Ada Lovelace",
  "kyc_status": "not_started",
  "created_at": "2026-04-29T13:00:00Z"
}

É isso. Você está autenticado.

Formato do CPF

Use 11 dígitos, sem pontos ou traços. O exemplo acima (52998224725) é um CPF de teste válido que você pode reusar no sandbox. CPFs reais no sandbox são criptografados igual em produção — nunca cole dados pessoais reais nos docs.

Para que serve `Idempotency-Key`

Versão curta: é uma string única (recomendamos um UUID) que torna a requisição segura para retentativas. Se sua conexão cair no meio da chamada e você tentar de novo com a mesma chave, você recebe a mesma resposta de volta em vez de criar um usuário duplicado. Todo POST e PATCH na BlendFi exige esse cabeçalho — veja o guia dedicado de Idempotência para o contrato completo.

Sandbox vs produção

Construa primeiro no sandbox

Sandbox é uma cópia funcional da BlendFi onde valem os mesmos endpoints, formatos de resposta e códigos de erro — só que os pagamentos Pix são simulados e as transferências de USDT ficam numa carteira de teste. Construa sua integração aqui primeiro; a gente revisa antes de emitir uma chave sk_live_….

Quando você estiver pronto, peça uma chave de produção. A gente revisa sua integração no sandbox de ponta a ponta (tratamento de idempotência, retentativas em erros, verificação de assinatura de webhooks) antes de emitir.

Quando algo dá errado

Toda resposta de erro tem o mesmo formato:

{
  "code": "authentication_required",
  "message": "Authorization header missing.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}

Campo	O que fazer com ele
`code`	Estável, legível por máquina. Programe sua lógica em cima dele.
`message`	Legível por humanos. Não faça `match` em cima dele; a gente pode reescrever.
`request_id`	Cole esse ID quando pedir ajuda pra gente. Localiza sua requisição nos logs em segundos.

Os dois erros que você mais vai ver no começo:

Código	Por quê	Como resolver
`401 authentication_required`	Cabeçalho `Authorization` ausente ou sem `Bearer`	Adicione o cabeçalho; preste atenção no espaço depois de `Bearer`
`401 authentication_failed`	Chave desconhecida, revogada ou colada com erro de digitação	Copie a chave de novo do e-mail de onboarding
`403 missing_capability`	Chave válida, mas sem permissão para esse endpoint	Manda e-mail pra gente; ampliamos as capacidades da chave

O catálogo completo de erros está no guia de Erros.

O que ler em seguida

Você está autenticado. A partir daqui:

Idempotência

POSTs e PATCHes seguros para retentativas. Leia antes da sua segunda chamada que escreve dado.

Erros e retentativas

Cada `code` mapeado para significado claro, quem causou, se deve retentar e como.

Ciclo de vida da transação

Cotação → execução → liquidação. O fluxo central de movimentação, com diagramas de estado.

Fluxo de KYC

Verifique a identidade do usuário com a Sumsub antes que ele transacione.

Referência da API

Cada endpoint, cada parâmetro, cada formato de resposta — gerada automaticamente do spec ao vivo.

Ambientes e limites

Sandbox vs produção, URLs base, limites atuais, como pedir aumento.

FAQ

Onde eu pego uma chave de sandbox? Manda e-mail pra gente. A gente envia em até um dia útil com um conjunto padrão de capacidades que você pode refinar depois.

Posso ter mais de uma chave? Pode. A gente pode emitir chaves com capacidades restritas (por exemplo, somente leitura, ou somente transações) para você compartimentar integrações. Pede no onboarding.

Como eu rotaciono uma chave? Manda e-mail pra gente; emitimos uma chave nova e revogamos a antiga depois que você migrar. Não tem self-service de rotação na v1.

Por que ainda não tenho uma chave sk_live_…? Chaves de produção são emitidas depois da gente revisar sua integração no sandbox e a documentação de compliance. Construa no sandbox primeiro; a gente avisa quando você estiver pronto.

Onde eu reporto um bug? Manda e-mail pra gente com o request_id da resposta. A gente acha sua requisição em segundos com isso.

Primeiros passos