Quickstart
Da conta criada à primeira chamada da API em 5 minutos, no ambiente sandbox.
Este guia leva você da conta nova até as transações de uma conta de teste, usando o ambiente sandbox. Nenhum dado real é tocado.
Integre com IA
Cole o prompt abaixo no seu agente de código (Cursor, Claude Code, Copilot, etc.). Ele contém a base URL, as fontes da documentação, os CPFs de sandbox e um critério de pronto. Antes, defina a variável OPENI_API_KEY com a sua chave.
Você vai integrar a API Openi Open Finance neste projeto. Meta: primeira chamada com resposta 200 em menos de 5 minutos, no ambiente sandbox.
## Contexto
- API REST. Base URL: https://of.openi.com.br/v1 (os caminhos abaixo são relativos a ela)
- Autenticação: header `Authorization: Bearer $OPENI_API_KEY`.
- Chaves `of_test_…` (sandbox) ou `of_live_…` (produção). O ambiente é fixo por aplicação: a chave já define qual ambiente você acessa.
- A chave é criada no console: https://of-console.openi.com.br → Aplicações → Sandbox → Chaves.
- Respostas de sucesso: `{ "status": "success", "data": ... }`. Erros: `{ "status": "error", "message": "..." }`.
## Fontes (consulte antes de escrever código; não invente campos)
- Índice da doc: https://developer.openi.com.br/docs/openfinance/llms.txt
- Quickstart: https://developer.openi.com.br/docs/openfinance/quickstart.md
- Autenticação: https://developer.openi.com.br/docs/openfinance/autenticacao.md
- Connect (widget): https://developer.openi.com.br/docs/openfinance/connect/overview.md
- Webhooks: https://developer.openi.com.br/docs/openfinance/webhooks/receiving-webhooks.md
- Sandbox: https://developer.openi.com.br/docs/openfinance/sandbox.md
- Regras para agentes: https://developer.openi.com.br/openfinance/AGENTS.md
## Tarefa
1. Leia a chave da variável de ambiente `OPENI_API_KEY` (adicione ao `.env` e garanta que `.env` está no `.gitignore`). Se ela não estiver definida, pare e me peça para defini-la. Use a chave só no backend: nunca no frontend, em logs ou em commits.
2. Crie um cliente HTTP mínimo no backend com `fetch` nativo (Node 18+), apontando para a base URL acima e enviando o header `Authorization`.
3. Chame `GET /connectors` e imprima a resposta. No sandbox ela traz "Instituição de Teste" (CPF) e "Instituição de Teste Empresas" (CPF + CNPJ).
4. Crie um endpoint no backend que chama `POST /connect-sessions` com `{ "redirectUrl": "<url de retorno do app>" }` e devolve ao frontend apenas a `connectUrl`. O frontend redireciona o usuário para ela; no retorno, o widget acrescenta `?itemId=...&status=success|error`.
5. Crie um endpoint `POST` para webhooks que compara o header `Authorization` com `OPENI_WEBHOOK_SECRET` (comparação em tempo constante; se diferente, 401), responde 2xx rápido e processa de forma idempotente. Eventos relevantes: `ITEM_CREATED`, `ITEM_WAITING_USER_INPUT`, `ITEM_LOGIN_SUCCEEDED`, `ITEM_UPDATED`, `ITEM_ERROR`, `TRANSACTIONS_CREATED`. Cadastre a URL (HTTPS; em desenvolvimento use um túnel) com `POST /webhooks` e `{ "url": "...", "secret": "<OPENI_WEBHOOK_SECRET>" }`, ou pelo console em Aplicações → Webhooks.
6. Quando o item estiver `synced`, liste as contas com `GET /items/{itemId}/accounts` e as transações com `GET /items/{itemId}/accounts/{accountId}/transactions?page=1&limit=50`.
## Sandbox
- CPF `111.444.777-35`: abre a tela de consentimento; em "Autorizar", o item vai a `synced` com 2 contas bancárias, 1 cartão de crédito, 90 dias de transações e 2 investimentos.
- CPF `529.982.247-25`: `auth_error` com `INVALID_CREDENTIALS`, sem tela de consentimento.
- Qualquer outro CPF: `422` com `fields: ["cpf"]`.
## Critério de pronto
Rode o passo 3 e me mostre a resposta real da API. Depois conecte a conta de teste com o CPF `111.444.777-35` e me mostre as contas retornadas no passo 6.
Crie sua conta e sua chave
Crie a conta em of-console.openi.com.br. Cada conta nasce com uma aplicação Sandbox (ambiente test).
No console, abra Aplicações → Sandbox → Chaves e crie uma chave. Ela começa com of_test_ e é exibida uma única vez: copie e guarde em um cofre de segredos ou no .env do backend.
OPENI_API_KEY=of_test_...Detalhes em Autenticação.
Faça a primeira chamada
Todas as rotas ficam em https://of.openi.com.br/v1 e recebem a chave no header Authorization.
curl https://of.openi.com.br/v1/connectors \
-H "Authorization: Bearer $OPENI_API_KEY"No sandbox, a resposta traz dois conectores de teste: Instituição de Teste (pessoa física, CPF) e Instituição de Teste Empresas (pessoa jurídica, CPF + CNPJ).
{
"status": "success",
"data": [
{ "id": "0198...", "name": "Instituição de Teste", "rules": [{ "field": "cpf", "required": true }] },
{ "id": "0198...", "name": "Instituição de Teste Empresas", "rules": [{ "field": "cpf" }, { "field": "cnpj" }] }
]
}Recebeu 401? A chave está ausente, incompleta ou revogada; veja Autenticação.
Cadastre o webhook
Cadastre um endpoint HTTPS (em desenvolvimento, use um túnel) antes de conectar a conta: eventos de itens criados antes do cadastro não são reenviados. A Openi envia o secret cadastrado no header Authorization; compare antes de processar.
curl -X POST https://of.openi.com.br/v1/webhooks \
-H "Authorization: Bearer $OPENI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://seu-tunel.exemplo/webhooks/openi", "secret": "um-segredo-forte"}'Crie uma sessão do Connect
O Connect é a tela pronta em que o usuário escolhe a instituição e autoriza o acesso. Seu backend cria a sessão e entrega só a connectUrl ao frontend.
curl -X POST https://of.openi.com.br/v1/connect-sessions \
-H "Authorization: Bearer $OPENI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"redirectUrl": "http://localhost:3000/callback"}'{
"status": "success",
"data": {
"id": "0198...",
"key": "of_connect_...",
"connectUrl": "https://...",
"expiresAt": "2026-01-01T12:30:00.000Z"
}
}Abra a connectUrl no navegador. Ao final, o usuário volta para redirectUrl?itemId=...&status=success.
Conecte a conta de teste
No widget, escolha Instituição de Teste e um dos CPFs de sandbox:
| CPF | Resultado |
|---|---|
111.444.777-35 | Tela de consentimento; em Autorizar, o item vai a synced com 2 contas, 1 cartão, 90 dias de transações e 2 investimentos |
529.982.247-25 | auth_error com INVALID_CREDENTIALS, sem tela de consentimento |
Guarde o itemId recebido no redirectUrl. Outros cenários em Sandbox.
Receba os eventos e leia as transações
Com o CPF de sucesso, os eventos chegam nesta ordem: ITEM_CREATED, ITEM_WAITING_USER_INPUT, ITEM_LOGIN_SUCCEEDED, TRANSACTIONS_CREATED (um por conta, 3 no total), INVESTMENTS_UPDATED e ITEM_UPDATED. Ao receber ITEM_UPDATED com status: "synced", leia os dados:
curl https://of.openi.com.br/v1/items/$ITEM_ID/accounts \
-H "Authorization: Bearer $OPENI_API_KEY"
curl "https://of.openi.com.br/v1/items/$ITEM_ID/accounts/$ACCOUNT_ID/transactions?page=1&limit=50" \
-H "Authorization: Bearer $OPENI_API_KEY"Use com seu agente
Acrescente as regras de integração ao AGENTS.md na raiz do seu projeto (o arquivo é criado se não existir; um AGENTS.md existente é preservado). Cursor, Claude Code, Codex e outros agentes leem o AGENTS.md automaticamente.
curl https://developer.openi.com.br/openfinance/AGENTS.md >> AGENTS.mdNo Claude Code, você também pode instalar como skill:
mkdir -p .claude/skills/openi-openfinance
curl -o .claude/skills/openi-openfinance/SKILL.md https://developer.openi.com.br/openfinance/SKILL.mdA documentação inteira também está em formato para LLMs: /docs/openfinance/llms.txt (índice) e a versão .md de cada página (adicione .md à URL).
Próximos passos
- Fluxo de conexão: integração direta via API, sem o widget.
- Itens: status, consentimentos e ressincronização.
- Collection Postman: todos os endpoints prontos para testar.

