Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com
Start typing to search…

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

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

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


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.

EventoDescrição
bill-registrationNotificação que é enviada para o solicitante no momento que temos a resposta final do registro do boleto na Núclea
bill-paymentO 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-settlementO 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": []
    }
  }

Updated 2 days ago