Tutorial de uso da API

Comece a integrar rapidamente com a Open Finance API da Celcoin

📘

Para iniciar na Celcoin API

Tenha em mãos sua chave de acesso à API. Caso não tenha uma, solicitamos que contate a nossa área comercial. Recomendamos iniciar os testes com a URL de sandbox, facilitando os testes de integração sem gerar nenhum impacto em produção.

Bem-vindo ao repositório de documentação da Celcoin Open Finance API. Para simplificar o processo de integração, vamos ilustrar uma integração passo-a-passo com a nossa API.

Iniciando o login

Toda a autenticação será feita por meio da apresentação de um access_token obtido em uma autenticação do tipo OAuth 2.0. Vamos começar -- tenha em mãos:

SECRET

A sua chave de acesso fornecida pela CELCOIN.

CLIENT_ID

O seu identificador único na CELCOIN.

GRANT

Tipo de acesso fornecido pela CELCOIN.

curl -X POST "https://sandbox.openfinance.celcoin.com.br/v5/token" -H "accept: /" -H "Content-Type: multipart/form-data" -F "client_id=$CLIENT_ID" -F "grant_type=$GRANT" -F "client_secret=$SECRET"
{
  "access_token": "AAABBBCCCDDD",
  "expires_in": 999,
  "token_type": "bearer"
}

Você passará a utilizar o token devolvido em "access_token" para todos os demais pedidos.

Obtendo consentimento do usuário

Agora é hora de solicitar o consentimento do seu usuário para utilizarmos a credencial de acesso e realizar a extração da informação bancária ou da concessionária de serviços. Utilize a URL específica do widget para iniciar a captura:

curl https://api.openfinance.celcoin.com.br/widget/?client_id=$CLIENT_ID&user_id=$USER_ID&r
edirect_url=$CALLBACK_URL&token=$TOKEN

Considerando:

CLIENT_ID

O mesmo identificador único de Cliente na CELCOIN.

USER_ID

Um identificador único gerado e gerido por você, para identificação do usuário.

CALLBACK_URL

A sua URL que irá receber a informação sobre a o status do consentimento.

TOKEN

Token especial de consentimento obtido a partir da CELCOIN (não é o mesmo que o access_token).

{
    "userId": 999,
    "consentId": 9999,
    "partner": "CAIXA"
}

Retorno do Widget inclui:

userId

Identificador do usuário que você passou na variável USER_ID (livre escolha).

consentId

Identificador de consentimento (a ser utilizado como referência nas próximas chamadas).

partner

Identificador (string) do parceiro escolhido (Banco ou Concessionária).

Obtendo as informações bancárias do usuário

Utilizando o consentimento obtido por meio do retorno do Secure Widget, você pode iniciar a solicitação da extração de informações do usuário. Vamos iniciar com uma consulta de saldo (lembre-se de substituir o ACCESS_TOKEN pela credencial obtida no login):

curl -X GET "https://sandbox.openfinance.celcoin.com.br/v1/bank/balance/{consentId}" -H "accept: /" -H "Authorization: Bearer $ACCESS_TOKEN"
{ "informationId": 9999 }

Agora é só esperar a chamada na sua URL registrada como webhook durante o processo de cadastro de acesso à API:

{
    "event": "INFORMATION_OUTPUT_READY",
    "informationId": 9999,
    "informationTypeId": 999,
    "type": "balanceStatement",
    "status": "OK",
    "infomationData": [ { "versao": "1.0", "balance": 3500.00 }]
}

Nesse caso, a informação relevante a ser extraída é o saldo, no valor de R$ 3.500, referente ao informationId 9999, obtido a partir das credenciais do userId 999.

Obtendo dados de concessionária

A mesma lógica se aplica para as informações de concessionária. Após a coleta do consentimento por meio do Secure Widget, vamos solicitar um extrato de utilização de 90 dias da concessionária:

curl -X POST "https://sandbox.openfinance.celcoin.com.br/v1/utility/usage-statement" -H "accept: /" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: multipart/form-data" -F "consentId=$CONSENT_ID" -F "limit=90"
{
    "event": "INFORMATION_OUTPUT_READY",
    "informationId": 999,
    "informationTypeId": 8,
    "type": "usageStatement",
    "status": "OK",
    "infomationData": [ { "versao": "1.0", "amount": 300.00, date": "2020-06-30T00:00:00.000Z", "dueDate": "2020-06-01T00:00:00.000Z",  "unitMeasurement": "Watts", "consumptionValue": 125 }]
}

Neste caso, apesar de solicitado 90 dias, foi detectado apenas o extrato de consumo de energia elétrica do usuário relativo ao mês de Junho/20.


What’s Next

Próximos passos