Guia de testes no sandbox

Toda a estrutura de testes do sandbox em um só lugar: chaves PIX de teste, helpers de ciclo de vida de conversão e forçamento de KYC.

O sandbox simula os sistemas externos com os quais a BlendFi se integra: PIX DICT, a exchange e custódia. Esta página documenta todos os dados de teste fixos e endpoints de controle que você pode usar para avançar sua integração sem esperar por eventos externos reais.

A capability `sandbox:control`

Todo endpoint POST /v1/test_helpers/* requer a capability sandbox:control. As chaves de sandbox emitidas durante o onboarding incluem essa capability por padrão. Se você receber um erro missing_capability, entre em contato com o suporte para adicioná-la à sua chave.

A capability não existe em produção. Qualquer chamada a um endpoint test_helpers com uma chave sk_live_… retorna 404.

Chaves PIX de teste

O sandbox não consulta o DICT PIX real. Use as chaves abaixo no campo pix_key da sua requisição de cotação de offramp para obter resultados de consulta determinísticos.

Chaves que funcionam

Essas chaves se resolvem com sucesso e retornam um titular sintético.

Tipo de chave	Valor
`cpf`	Qualquer CPF válido (ex.: `52998224725`)
`cnpj`	Qualquer CNPJ válido (ex.: `11222333000181`)
`email`	`sandbox@blendfi.com.br`
`phone`	`+5511999990001`
`evp`	`00000000-0000-0000-0000-000000000001`

Chaves CPF e CNPJ se resolvem automaticamente: o próprio número do documento vira o documento do titular, então qualquer CPF ou CNPJ válido funciona sem precisar de um valor fixo.

Chaves não encontradas

Essas chaves sempre retornam o erro pix_key_not_found (HTTP 422). Use-as para verificar o tratamento de erro da sua integração.

Tipo de chave	Valor
`email`	`notfound@blendfi.com.br`
`phone`	`+5511000000000`
`evp`	`00000000-0000-0000-0000-000000000000`

Qualquer chave fora das duas tabelas acima também retorna pix_key_not_found.

Helpers de ciclo de vida de conversão

Esses endpoints permitem avançar uma conversão pelo seu ciclo de vida sem esperar por pagamentos PIX reais ou depósitos on-chain. Todos exigem a capability sandbox:control e um header Idempotency-Key.

Endpoint	O que faz
`POST /v1/test_helpers/conversions/{id}/simulate-onramp-pix-paid`	Simula a chegada do pagamento PIX em uma conversão de onramp. Avança para `funded` e cria o registro da transação.
`POST /v1/test_helpers/conversions/{id}/simulate-offramp-deposit`	Simula o depósito de USDT em uma conversão de offramp. O valor cheio avança para `funded` e dispara o pagamento via PIX; um valor a menor ou a maior leva a `standby`.
`POST /v1/test_helpers/conversions/{id}/expire`	Expira uma conversão aguardando depósito
`POST /v1/test_helpers/conversions/{id}/fail`	Falha uma conversão com um motivo específico

Todos os endpoints retornam o objeto de conversão atualizado. Os schemas completos de request e response estão na referência da API.

Simular PIX recebido (onramp)

Campos do body:

Campo	Tipo	Obrigatório	Descrição
`amount`	string	Não	Valor decimal a creditar (ex.: `"500.00"`). Omita para usar o valor cotado. Passe um valor diferente para testar depósitos a menor ou a maior.

Simular depósito (offramp)

Campos do body:

Campo	Tipo	Obrigatório	Descrição
`amount`	string	Não	Valor decimal a creditar (ex.: `"500.00"`). Omita para usar o valor cotado. Passe um valor diferente para levar a conversão a `standby` (a menor ou a maior).

Expire

Campos do body:

Campo	Tipo	Obrigatório	Descrição
`occurred_at`	datetime ISO 8601	Não	Retrodata o evento. Padrão: agora.

Fail

Campos do body:

Campo	Tipo	Obrigatório	Descrição
`reason`	string	Sim	Um de: `pix_expired`, `pix_rejected`, `crypto_deposit_expired`, `crypto_deposit_rejected`, `settlement_failed`, `compliance_rejected`
`occurred_at`	datetime ISO 8601	Não	Retrodata o evento. Padrão: agora.

Helper de KYC

Força um resultado de revisão KYC para um usuário que já tem uma submissão KYC em andamento. Requer a capability sandbox:control.

POST /v1/test_helpers/users/{id}/kyc

Campos do body:

Campo	Tipo	Obrigatório	Descrição
`status`	string	Sim	Um de: `approved`, `rejected`, `in_review`

Retorna o status KYC atualizado do usuário. O schema completo está na referência da API.

Submissão necessária

O usuário precisa ter uma submissão KYC existente antes de você chamar este endpoint. Inicie uma pelo fluxo KYC padrão primeiro; depois use este helper para forçar o resultado em vez de esperar pelo pipeline de revisão.

Relacionados

Sandbox e chaves, visão geral do ambiente e como obter uma chave
Coleção do Postman, requisições prontas para cada test helper
Catálogo de erros, códigos de erro que você pode encontrar durante os testes

Nesta página