Gestão de Emissão de Boletos

Esta funcionalidade permite que o cliente emita e gerencie um boleto, podendo atrelar ou não à uma Carteira (Wallet) criada anteriormente. Nesta API, poderá configurar parâmetros como: Beneficiário Original, Beneficiário Final, Pagador, valor nominal, data de vencimento, desconto, juros, multa, entre outros.

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com o padrão REST usando o protocolo OAuth 2.0.
Ter o produto/solução contratado e habilitado em produção.
- Caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.
Possuir uma conta no BaaS da Celcoin (Conta essa responsável por receber o valor da cobrança)

Passos para Integrar

Realizar autenticação na API - [API Reference]
Emitir um Boleto - [API Reference]
Cadastrar o Webhook para receber atualizações do boleto - Saiba Mais.

Caso seja necessário você pode consultar a cobrança manualmente.

Consultar um boleto com paginação- [API Reference]
Consultar um boleto por ID [API Reference]

2. Emitir um Boleto

cURL da chamada

curl --request POST \
     --url https://sandbox.openfinance.celcoin.dev/billissuance/v1/bill \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
{
  "beneficiary": {
    "documentType": "CPF",
    "name": "Nome ou Razão Social do beneficiário original",
    "document": "51236721000136"
  },
  "beneficiaryFinal": {
    "documentType": "CPF",
    "name": "Nome ou Razão Social do beneficiário final",
    "document": "51236721000136"
  },
  "payer": {
    "documentType": "CPF",
    "name": "Nome ou Razão Social do pagador",
    "document": "17910432000132",
    "address": "Logradouro do pagador",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "08675040"
  },
  "documentKind": "DUPLICATA_MERCANTIL",
  "paymentType": "PARCIAL",
  "discount": {
    "discountType": "DATA_FIXA",
    "discountOne": {
      "value": 100,
      "limitDate": "2023-05-12"
    }
  },
  "fine": {
    "percentage": 20,
    "daysAmount": 10
  },
  "walletCode": 1,
  "requestId": "9b37e3f9-c59e-4b47-a93e-41f66e89df88",
  "nominalValue": 2500,
  "dueDate": "2024-06-10",
  "maxValue": 2600,
  "minValue": 10,
  "partials": 12,
  "deductionValue": 32.5,
  "interestPercentage": 10,
  "settleDaysAmount": 10
}
'

Descrição dos campos

Campo	Descrição	Tipo Campo
walletCode	Código da carteira	int32
requestId	Identificador único da requisição	string
beneficiary.name	Nome ou Razão Social do beneficiário original	string
beneficiary.documentType	Tipo de documento. Valores Aceitos: CPF ou CNPJ	string
beneficiary.document	CPF ou CNPJ do beneficiário original	string
beneficiaryFinal.name	Nome ou Razão Social do beneficiário final	string
beneficiaryFinal.documentType	Tipo de documento. Valores Aceitos: CPF ou CNPJ	string
beneficiaryFinal.document	CPF ou CNPJ do beneficiário final	string
payer.name	Nome ou Razão Social do pagador	string
payer.documentType	Tipo de documento. Valores Aceitos: CPF ou CNPJ	string
payer.document	CPF ou CNPJ do pagador	string
payer.address	Rua, Número e Complemento do pagador	string
payer.city	Cidade do pagador	string
payer.state	Sigla da Unidade da Federação do pagador	string
payer.zipCode	CEP do pagador.	string
nominalValue	Valor nominal do boleto.	double
dueDate	Data de vencimento do boleto.	string
documentKind	Código Espécie da cobrança. Valores aceitos: DUPLICATA_MERCANTIL* - Duplicata Mercantil. DUPLICATA_SERVICO - Duplicata de Serviço. OUTROS* - Outros. DEPOSITO_APORTE* *- Boleto de Depósito e Aporte.	string
paymentType	Tipo de Pagamento do boleto. Valores aceitos: TOTAL - Aceita apenas um único pagamento no valor total do boleto, incluindo juros, multas e descontos. DIVERGENTE** - Aceita apenas um único pagamento no valor definido entre o intervalo dos campos maxValue e minValue. PARCIAL *- Aceite a quantidade de pagamentos estipulada no campo partials no valor definido entre o intervalo dos campos maxValue e minValue.	string
maxValue	Valor Máximo aceito para pagamento.	double
minValue	Valor Mínimo aceito para pagamento	double
partials	Quantidade de pagamento parcial	int32
discount.discountType	Código de Desconto do pagamento. Valores aceitos: DATA_FIXA - Valor Fixo até a data informada. Permite até 3 registros de desconto, sendo obrigatório especificar o valor e a data limite. DIA_CORRIDO* - Valor por antecipação dia corrido. Permite apenas um único registro de desconto (discountOne) e só o atributo value deve ser preenchido DIA_UTIL* *- Valor por antecipação dia útil. Permite apenas um único registro de desconto (discountOne) e só o atributo value deve ser preenchido	string
discount.discountOne.value	Valor de Desconto do pagamento.	double
discount.discountOne.limitDate	Data de Desconto do pagamento.	string
discount.discountTwo.value	Valor de Desconto do pagamento.	double
discount.discountTwo.limitDate	Data de Desconto do pagamento.	string
discount.discountThree.value	Valor de Desconto do pagamento.	double
discount.discountThree.limitDate	Data de Desconto do pagamento.	string
deductionValue	Valor de Abatimento do valor nominal por antecipação do pagamento.	double
fine.percentage	Percentual de Multa do pagamento	double
fine.daysAmount	Quantidade de Dias de Multa após vencimento do pagamento.	int32
interestPercentage	Percentual de Juros do pagamento.	double
settleDaysAmount	Quantidade de Dias de Baixa após vencimento	int32
tags		array of objects \| null

Exemplo de retorno

👍
Sucesso 201

{
  "detailMessage": "string",
  "id": "6659cffd92bdd93b23773661",
  "walletCode": 103,
  "requestId": "9b37e3f9-c59e-4b47-a93e-41f66e89df88",
  "bankNumber": 1,
  "billNumber": 3024061305151269000,
  "billReferenceNumber": 3024061305151269000,
  "beneficiary": {
    "name": "Nome ou Razão Social do beneficiário",
    "documentType": "CNPJ",
    "document": "51236721000136"
  },
  "beneficiaryFinal": {
    "name": "Nome ou Razão Social do beneficiário",
    "documentType": "CNPJ",
    "document": "51236721000136"
  },
  "payer": {
    "name": "Nome ou Razão Social do pagador",
    "documentType": "CNPJ",
    "document": "17910432000132",
    "address": "Logradouro do pagador",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "08675040"
  },
  "barcode": "50997000000000000000000000000000000000000019",
  "digitableLine": "50990000090000000000000000000191700000000000000",
  "nominalValue": 2500,
  "paidValue": 0,
  "issueDate": "2024-05-18",
  "dueDate": "2024-06-10",
  "documentKind": "DUPLICATA_MERCANTIL",
  "paymentType": "PARCIAL",
  "status": "PROCESSAMENTO",
  "maxValue": 1200,
  "minValue": 10,
  "partials": 12,
  "discount": {
    "discountType": "DATA_FIXA",
    "discountOne": {
      "value": 100,
      "limitDate": "2023-05-12"
    },
    "discountTwo": {
      "value": 100,
      "limitDate": "2023-05-12"
    },
    "discountThree": {
      "value": 100,
      "limitDate": "2023-05-12"
    }
  },
  "deductionValue": 32.5,
  "fine": {
    "percentage": 20,
    "daysAmount": 10
  },
  "interestPercentage": 10,
  "settleDaysAmount": 10,
  "receivableScheduleDelay": 0,
  "tags": [
    {
      "key": "IDSAP",
      "value": "125262"
    }
  ],
  "created": "2025-10-20T17:54:50.962Z",
  "updated": "2025-10-20T17:54:50.962Z"
}

Descrição dos campos

Campo	Descrição	Tipo Campo
detailMessage		string
id	Identificador único do boleto	string
walletCode	Código da carteira	int32
requestId	Identificador único da requisição	string
bankNumber	Identificador nosso número	int64
billNumber	Número de identificação do boleto	int64
billReferenceNumber	Número Referência Atual Cadastro Título	int64
beneficiary.name	Nome ou Razão Social do beneficiário original	string
beneficiary.documentType	Tipo de documento	string
beneficiary.document	CPF ou CNPJ do beneficiário original	string
beneficiaryFinal.name	Nome ou Razão Social do beneficiário final	string
beneficiaryFinal.documentType	Tipo de documento	string
beneficiaryFinal.document	CPF ou CNPJ do beneficiário final	string
payer.name	Nome ou Razão Social do pagador.	string
payer.documentType	Tipo de documento	string
payer.document	CPF ou CNPJ do pagador.	string
payer.address	Rua, Número e Complemento do pagador.	string
payer.city	Cidade do pagador.	string
payer.state	Sigla da Unidade da Federação do pagador.	string
payer.zipCode	CEP do pagador.	string
barcode	Número código de barras.	string
digitableLine	Número Linha Digitável.	string
nominalValue	Valor nominal do boleto.	double
paidValue	Valor pago do boleto.	double
issueDate	Data de emissão do boleto.	string
dueDate	Data de Vencimento do boleto.	string
documentKind	Código Espécie da cobrança. Valores Retornados: DUPLICATA_MERCANTIL* - Duplicata Mercantil. DUPLICATA_SERVICO - Duplicata de Serviço. OUTROS* - Outros. DEPOSITO_APORTE* *- Boleto de Depósito e Aporte.	string
paymentType	Tipo de Pagamento do boleto. Valores Retornados: TOTAL - Aceita apenas um único pagamento no valor total do boleto, incluindo juros, multas e descontos. DIVERGENTE* - Aceita apenas um único pagamento no valor definido entre o intervalo dos campos maxValue e minValue. PARCIAL* *- Aceite a quantidade de pagamentos estipulada no campo partials no valor definido entre o intervalo dos campos maxValue e minValue.	string
status	Situação do boleto. Valores Retornados: PROCESSAMENTO - Processamento. REJEITADO** - Rejeitado. REGISTRADO - Registrado. BAIXADO* - Baixado. LIQUIDADO_PARCIAL* - Liquidado parcial. LIQUIDADO_INTEGRAL** - Liquidado integral. CANCELADO - Cancelado. EXPIRADO* *- Expirado.	string
maxValue	Valor Máximo aceito para pagamento.	double
minValue	Valor Mínimo aceito para pagamento.	double
partials	Quantidade de pagamento parcial.	int32
discount.discountType	Código de Desconto do pagamento. Valores Retornados: DATA_FIXA - Valor Fixo até a data informada. Permite até 3 registros de desconto, sendo obrigatório especificar o valor e a data limite. DIA_CORRIDO* - Valor por antecipação dia corrido. Permite apenas um único registro de desconto (discountOne) e só o atributo value deve ser preenchido DIA_UTIL* *- Valor por antecipação dia útil. Permite apenas um único registro de desconto (discountOne) e só o atributo value deve ser preenchido	string
discount.discountOne.value	Valor de Desconto do pagamento.	double
discount.discountOne.limitDate	Data de Desconto do pagamento.	string
discount.discountTwo.value	Valor de Desconto do pagamento.	double
discount.discountTwo.limitDate	Data de Desconto do pagamento.	string
discount.discountThree.value	Valor de Desconto do pagamento.	double
discount.discountThree.limitDate	Data de Desconto do pagamento.	string
deductionValue	Valor de Abatimento do valor nominal por antecipação do pagamento.	double
fine.percentage	Percentual de Multa do pagamento	double
fine.daysAmount	Quantidade de Dias de Multa após vencimento do pagamento.	int32
interestPercentage	Percentual de Juros do pagamento.	double
settleDaysAmount	Quantidade de Dias de Baixa após vencimento	int32
receivableScheduleDelay	Atraso do agendamento do recebimento.	int32
tags		array of objects \| null
created	Data de inclusão.	date-time
updated	Data de alteração.	date-time

📘
A Emissão do Boleto é síncrona. Porém é necessário o registro do mesmo para ser possível efetuar o pagamento

❗
Error 400

{
  "code": "string",
  "statusCode": 0,
  "message": "string",
  "details": [
    {
      "field": "string",
      "description": [
        "string"
      ]
    }
  ]
}

Para validar os cenários de erro dessa API, acesse a tabela de erros.

3. Webhooks

Para ser possível receber todas as atualizações referente aos boletos emitidos, como por exemplo: Registro do Boleto na Núclea, Registro de Pagamento e Baixa Por cancelamento, é necessário cadastrar os eventos, para isso, acesse aqui a documentação.

Evento	Descrição
bill-registration	Notificação que é enviada para o solicitante no momento que temos a resposta final do registro do boleto na Núclea
bill-payment	O webhook de pagamento é a notificação que é enviada para o solicitante no momento em que a liberação de crédito é realizada na conta , após a identificação com sucesso da liquidação.
bill-settlement	O webhook de baixa por cancelamento é a notificação que é enviada para o solicitante no momento que temos a resposta final do registro da baixa por cancelamento do boleto na Núclea.

bill-registration

{
  "entity": "bill-registration",
  "createTimestamp": "2024-06-17T18:09:19.0406704",
  "status": "SUCCESS",
  "body": {
    "billId": "60c72b2f9f1b2c4d5f8d2e1a",
    "requestId": "401943ae-b9d8-4e35-9816-eeecc1678357",
    "tenantId": "35c12b2f9f1b2c4d5f8d2099",
    "walletCode": 003,
    "bankNumber": 12345,
    "barcode": "50997000000000000000000000000000000000000680",
    "beneficiaryDocument": "51236721000000",
    "tags": []
  }
}

bill-payment

{
  "entity": "bill-payment",
  "createTimestamp": "2024-06-17T18:09:19.0406704",
  "status": "SUCCESS",
  "body": {
    "billId": "60c72b2f9f1b2c4d5f8d2e1a",
    "billNumber": 2023092622222113254,
    "billRequestId": "401943ae-b9d8-4e35-9816-eeecc1678357",
    "tenantId": "35c12b2f9f1b2c4d5f8d2099",
    "walletCode": 004,
    "bankNumber": 12345,
    "barcode": "07799707771500000100000029170110202309261131",
    "digitableLine": "07799707771500000100000029170110202309261131",
    "settlementOrigin": "INTERBANCARIA",
    "settlementType": "INTEGRAL",
    "settlementNumber": 2310180310102620251,
    "settlementChannel": 3,
    "receiverISPB": 34829992,
    "value": 980.44,
    "tags": []
  }

bill-settlement

{
    "entity": "bill-settlement",
    "createTimestamp": "2024-06-17T18:09:19.0406704",
    "status": "SUCCESS",
    "body": {
      "billId": "60c72b2f9f1b2c4d5f8d2e1a",
      "billRequestId": "401943ae-b9d8-4e35-9816-eeecc1678357",
      "tenantId": "35c12b2f9f1b2c4d5f8d2099",
      "walletCode": 003,
      "bankNumber": 12345,
      "barcode": "50997000000000000000000000000000000000000680",
      "beneficiaryDocument": "51236721000136",
      "settlementId": "60c72b2f9f1b2c4d5f8d2e1a",
      "settlementRequestId": "401943ae-b9d8-4e35-9816-eeecc1678357",
      "settlementNumber": 3024090203158932726,
      "tags": []
    }
  }