Início rápido

De "acabei de receber uma API key" a "fiz uma chamada autenticada" em cerca de cinco minutos.

O caminho de cinco minutos. No final, você vai estar autenticado na BlendFi e criado seu primeiro usuário de teste.

1. Configure seu ambiente

Ainda não tem chave de sandbox?

As chaves são emitidas após uma reunião curta com o time da BlendFi. Agende sua reunião e você sai dela com a chave em mãos. Detalhes do fluxo em Sandbox e chaves.

Coloque sua chave de sandbox em uma variável de shell para que os exemplos fiquem prontos para colar.

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

Você identifica o ambiente de uma chave pelo prefixo:

Prefixo	Ambiente	O que pode fazer
`sk_test_…`	Sandbox	Tudo. Sem dinheiro real.
`sk_live_…`	Produção	Dinheiro real. Emitida na reunião de liberação de produção.

Chaves de sandbox não atingem produção por acidente, e vice-versa, as duas são rejeitadas com 401 authentication_failed. Veja Autenticação para o contrato completo.

2. Autentique todo request

Toda chamada em /v1/* envia sua chave no header Authorization como Bearer token:

Authorization: Bearer sk_test_…

Três coisas que você precisa saber:

A palavra Bearer é obrigatória. Apenas Authorization: sk_test_… retorna 401 authentication_required.
A chave vai em todo request. Sem login, sem cookie de sessão, sem refresh de token. A chave é a sessão.
Capabilities são por chave. Cada chave tem capabilities escopadas (ex.: users:create, transactions:create). Se uma chave chamar um endpoint fora do seu escopo, você recebe 403 missing_capability.

3. Faça sua primeira chamada

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

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

import crypto from "node:crypto";

const res = await fetch(`${process.env.BLENDFI_BASE}/v1/users`, {
  method: "POST",
  headers: {
    "authorization": `Bearer ${process.env.BLENDFI_KEY}`,
    "idempotency-key": crypto.randomUUID(),
    "content-type": "application/json",
  },
  body: JSON.stringify({
    external_id: "your-internal-user-id-001",
    name: "Ada Lovelace",
    document_type: "cpf",
    document_number: "52998224725",
  }),
});
console.log(await res.json());

import os, uuid, requests

res = requests.post(
    f"{os.environ['BLENDFI_BASE']}/v1/users",
    headers={
        "authorization": f"Bearer {os.environ['BLENDFI_KEY']}",
        "idempotency-key": str(uuid.uuid4()),
        "content-type": "application/json",
    },
    json={
        "external_id": "your-internal-user-id-001",
        "name": "Ada Lovelace",
        "document_type": "cpf",
        "document_number": "52998224725",
    },
)
print(res.json())

Se tudo estiver certo:

{
  "id": "usr_01J…",
  "external_id": "your-internal-user-id-001",
  "name": "Ada Lovelace",
  "document_type": "cpf",
  "document_masked": "***.224.725-**",
  "kyc_status": "not_started",
  "created_at": "2026-04-29T13:00:00Z"
}

Pronto. 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 reutilizar no sandbox. CPFs reais no sandbox são criptografados da mesma forma que em produção, nunca cole dados pessoais reais nos docs.

O que `Idempotency-Key` faz

Versão curta: é uma string única (recomendamos UUID) que torna o request seguro para retentar. Se sua rede cair no meio da chamada e você retentar com a mesma chave, recebe a mesma resposta de volta, sem usuário duplicado. Todo POST e PATCH da BlendFi exige a chave; veja Idempotência.

Quando algo dá errado

Toda resposta de erro segue o mesmo formato de resposta:

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

Decida com base no code (que é estável). Os dois erros que você mais vai ver no início:

Código	Por quê	Correção
`401 authentication_required`	Header ausente ou não começa com `Bearer`	Adicione o header; atenção ao espaço após `Bearer`
`401 authentication_failed`	Chave desconhecida, revogada ou colada com typo	Copie de novo a partir do email de onboarding
`403 missing_capability`	Chave válida, mas sem escopo para este endpoint	Entre em contato; ampliamos as capabilities

O catálogo alfabético completo está no catálogo de erros.

O que ler em seguida

Autenticação, Bearer e capabilities em detalhe
Sandbox e chaves, sandbox vs produção
Construa um onramp, sua primeira integração que move dinheiro
Conceitos → Idempotência, por que retentar é seguro