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.returnUrlprecisa ser HTTPS, com o domínio em Domínios de retorno.- O Inter responde
422 credentials_on_authorization_pagecom umauthorizationUrl: mande o usuário para a página de autorização. - Já existe uma conexão viva com o mesmo banco:
409 connection_existscom oconnectionId. Renove comPOST /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.
| Estado | O que significa |
|---|---|
connecting | Preparando a autorização. |
waiting_oauth | Esperando o usuário autorizar no banco. |
succeeded | Autorizado. Os dados começam a chegar. |
pending_approval | A conta tem mais de um aprovador; o banco só libera depois de todos. |
document_mismatch | A conta autorizada é de outro CNPJ ou CPF. Nada foi lido. |
failed | A 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.