Openi DeveloperDeveloper

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.

.env
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:

CPFResultado
111.444.777-35Tela 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-25auth_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"

Veja Como receber webhooks e Listar transações.

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.md

No 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.md

A 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

On this page