powered by Nortcash
Testar grátis
documentação

API de conexão

Para montar o seu próprio conector, com a sua tela e a sua identidade. A autorização continua no site ou app do banco.

1. Cadastre o CNPJ ou CPF

curl -X POST "https://api.openfinancemcp.ai/v1/holders" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "document": "11222333000181", "reference": "cli_1042" }'

A resposta traz o titular e um authorizationUrl, que vale por 7 dias. Se preferir, mande o usuário para esse link: é a página de autorização pronta. Um documento que já está na conta responde 200 com o mesmo titular.

2. Mostre os bancos

curl "https://api.openfinancemcp.ai/v1/institutions?documentType=cnpj" \
  -H "Authorization: Bearer SUA_CHAVE"

Cada banco traz connectionMethod: oauth (autorização no site ou app do banco) ou credentials (o Inter, só para CNPJ). Bancos fora do ar não aparecem.

3. Crie a conexão

curl -X POST "https://api.openfinancemcp.ai/v1/connections" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "x-company-register: 11222333000181" \
  -H "Content-Type: application/json" \
  -d '{ "institutionId": 201, "cpf": "52998224725", "returnUrl": "https://app.suaplataforma.com.br/bancos/retorno", "reference": "cli_1042" }'
  • O CNPJ vem do cabeçalho x-company-register, nunca do corpo.
  • cpf é obrigatório para um CNPJ (é quem autoriza no banco) e é ignorado para um CPF.
  • returnUrl precisa ser HTTPS, com o domínio em Domínios de retorno.
  • O Inter responde 422 credentials_on_authorization_page com um authorizationUrl: mande o usuário para a página de autorização.
  • Já existe uma conexão viva com o mesmo banco: 409 connection_exists com o connectionId. Renove com POST /v1/connections/:id/reconnect.

4. Leve o usuário ao banco

Consulte GET /v1/connections/:id a cada 2 segundos enquanto o estado for connecting. Quando chegar o oauthUrl, redirecione o usuário para ele.

EstadoO que significa
connectingPreparando a autorização.
waiting_oauthEsperando o usuário autorizar no banco.
succeededAutorizado. Os dados começam a chegar.
pending_approvalA conta tem mais de um aprovador; o banco só libera depois de todos.
document_mismatchA conta autorizada é de outro CNPJ ou CPF. Nada foi lido.
failedA conexão parou. Renove a autorização.

5. Leia os dados

Com a conexão autorizada, as rotas de leitura respondem para aquele CNPJ ou CPF. Veja a lista em O que dá para consultar.