Quickstart
Do zero ao primeiro boleto
Em poucas chamadas: listar clientes, criar um cliente, criar um recebível, emitir um boleto, baixar o PDF e cancelar o boleto de teste, com uma chave cf_live_ da sua empresa.
As chamadas são reais
A API trabalha direto nos dados da sua empresa: o cliente e o recebível ficam no app e o boleto é registrado no Banco Inter. Comece pelas leituras (passo 2) para conferir a chave e só depois faça as escritas, com dados de um cliente real. Se emitir um boleto só para testar, cancele-o no último passo.
1. Crie a chave
No app ClickFin, entre como Administrador, abra Configurações → Integrações e crie uma chave para a empresa com os escopos bank_slips:read, bank_slips:write, clients:read, clients:write, market_segments:read, receivables:write, services:read. Para só explorar, crie antes uma chave com escopos read. Copie a chave na hora: ela não aparece de novo.
export CLICKFIN_API_URL="https://api.clickfin.com.br"export CLICKFIN_API_KEY="cf_live_..." # cole a chave copiada2. Listar clientes
Primeira chamada autenticada. Confira os cabeçalhos X-RateLimit-* da resposta.
Escopo: clients:read.
curl --request GET \ --url "$CLICKFIN_API_URL/client?page=1&limit=10" \ --header "Authorization: Bearer $CLICKFIN_API_KEY"3. Criar um cliente
A chave age só na empresa em que foi criada: o cliente nasce nela. Os dados abaixo são ilustrativos: use os do cliente real que vai receber o boleto, ou pule este passo e use o _id de um cliente que já existe. marketSegment é um segmento da empresa (GET /market-segment, escopo market_segments:read). Guarde o _id devolvido.
Escopo: clients:write.
curl --request POST \ --url "$CLICKFIN_API_URL/client" \ --header "Authorization: Bearer $CLICKFIN_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Padaria Pão Quente LTDA", "cpfCnpj": "12345678000199", "address": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postalCode": "30130000", "city": "Belo Horizonte", "state": "MG", "mobilePhone": "31998765432", "emails": [ "financeiro@paoquente.com" ], "companySize": "Microempresa", "taxRegime": "Simples Nacional", "marketSegment": "<id do segmento de mercado>", "origin": "Indicação de Cliente"}'4. Criar um recebível
Use o _id do cliente e um serviço já cadastrado na empresa (GET /service, escopo services:read).
Escopo: receivables:write.
curl --request POST \ --url "$CLICKFIN_API_URL/account-receivable" \ --header "Authorization: Bearer $CLICKFIN_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "clientId": "<id do cliente>", "serviceId": "<id do serviço>", "value": 150, "receivableDate": "2027-01-15T12:00:00.000Z", "observation": "Mensalidade de janeiro"}'5. Emitir um boleto com Idempotency-Key
O boleto é registrado de verdade no Banco Inter da empresa (que precisa estar configurado). Com sendBankSlipEmailToCustomer: false, o cliente não recebe e-mail. Envie uma Idempotency-Key nova por boleto e repita a mesma chave com o mesmo corpo se a resposta não chegar: a API não emite duas vezes.
Escopo: bank_slips:write.
curl --request POST \ --url "$CLICKFIN_API_URL/bank-slips" \ --header "Authorization: Bearer $CLICKFIN_API_KEY" \ --header "Idempotency-Key: boleto-cliente-123-2027-01" \ --header "Content-Type: application/json" \ --data '{ "companyId": "<id da empresa da chave>", "clientId": "<id do cliente>", "amount": 150, "dueDate": "2027-01-15T12:00:00.000Z", "agendaDays": 30, "sendBankSlipEmailToIssuer": false, "sendBankSlipEmailToCustomer": false, "discount": { "type": "NONE" }, "fine": { "type": "PERCENT", "amountOrPercent": 2 }, "interest": { "type": "MONTHLY_PERCENT", "amountOrPercent": 1.5 }}'6. Baixar o PDF do boleto
Com o _id do boleto devolvido na emissão.
Escopo: bank_slips:read.
curl --request GET \ --url "$CLICKFIN_API_URL/bank-slips/<id do boleto>/pdf" \ --header "Authorization: Bearer $CLICKFIN_API_KEY" \ --output boleto.pdf7. Cancelar o boleto de teste
Se o boleto foi só um teste, cancele-o no Banco Inter (status issued). Ninguém pode pagá-lo depois disso.
Escopo: bank_slips:write.
curl --request POST \ --url "$CLICKFIN_API_URL/bank-slips/<id do boleto>/cancel" \ --header "Authorization: Bearer $CLICKFIN_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "cancelReason": "Boleto de teste da integração"}'Próximos passos
Guarde a chave num cofre de segredos do servidor, peça só os escopos que a integração usa e trate os erros por category. Os limites de requisição e a política de compatibilidade estão nas páginas abaixo.