Clickfin

Referência da API
Portal oficial

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 copiada

2. 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.pdf

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