Pular para o conteúdo principal

Emitir Boleto/Cobrança

Essa funcionalidade permite que os clientes da Onnix consigam criar cobranças para seus clientes, essas cobranças são em Boleto Registrado e em Pix Cobrança (Bolepix)

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.
  • Possuir uma conta no BaaS da Celcoin (Conta essa responsável por receber o valor da cobrança)

cURL da chamada​

curl -X POST https://api.onnixpay.com/sdk/boleto \
  -H "X-API-Key: ox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "dueDate": "2025-10-15",
    "description": "Mensalidade outubro",
    "customerName": "João Silva",
    "customerDocument": "12345678901",
    "externalId": "order-123"
  }'

JSON de exemplo​

{
  "amount": 100.5,
  "dueDate": "2025-10-15",
  "description": "Pagamento de mensalidade - Outubro 2025",
  "customerId": "23e7a9ee-2cb4-4031-8649-698644a43934",
  "customerName": "João da Silva",
  "customerDocument": "12345678901",
  "customerEmail": "joao@exemplo.com",
  "customerPhone": "string",
  "customerAddress": {
    "postalCode": "01234-567",
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP"
  },
  "clientCode": "order-12345",
  "fine": {
    "type": "PERCENTAGE",
    "value": 2,
    "daysAfterDue": 1
  },
  "interest": {
    "type": "PERCENTAGE",
    "value": 1
  },
  "discountAmount": 10,
  "discount": {
    "type": "PERCENTAGE",
    "value": 5,
    "limitDate": "2025-07-25"
  },
  "billetType": "OUT",
  "instructions": [
    "Vencimento prorrogado",
    "Desconto de 10% até 25/07"
  ]
}

Descrição dos campos​

CampoDescriçãoTipo Campo
amountValor do boleto em reaisstring
exemplo: 100.50
Min: 5.00
Max: 100000
customerIdUUID do cliente cadastrado previamentestring
exemplo: '23e7a9ee-2cb4-4031-8649-698644a43934'
descriptionDescrição do boletostring
exemplo: 'Pagamento de mensalidade - Outubro 2025'
MaxLenght: 200
dueDateData de vencimento (formato: YYYY-MM-DD)string($date-time)
exemplo: '2025-10-15'
billetTypeTipo do boleto"DM","DS","NP","RC","FAT","ND","OUT"
discount.limitDateData limite para o descontostring($date-time)
exemplo:'2025-07-25'
discount.typeTipo do desconto"PERCENTAGE","FIXED"
discount.valueValor do descontonumber
exemplo: 5.0
Min: 1.00
expirationAfterPaymentDefine o período adicional permitido para pagamento após o vencimento da cobrança. Precisa ser entre 0 a 59. Não enviando o parâmetro, como default, assumirá o valor 0.""
clientCodeID externo para referência (seu sistema)string
exemplo: 'af39f77d-1bf5-4b4e-a814-14b9fe08d86b'
fine.daysAfterDueDias após vencimento para cobrança da multa
fine.typeTipo de multa"PERCENTAGE","FIXED"
fine.valueValor da multa10
instructionsInstruções do boletoArray de strings
exemplo: ['Vencimento prorrogado', 'Desconto de 10% até 25/07']
interest.typeTipo do juros"PERCENTAGE","FIXED"
interest.valueValor do juro (mensal para percentage, diário para fixed)10
customerNameNome completo do pagadorstring
exemplo: 'João da Silva'
customerDocumentCPF ou CNPJ do pagador (apenas números)string
exemplo: '12345678901'
customerEmailEmail do pagadorstring
exemplo: 'joao@exemplo.com'
customerPhoneTelefone do pagador
customerAddress.postalCodeCEP do pagador
customerAddress.streetEndereço do pagador
customerAddress.numberNúmero da casa do pagador
customerAddress.complementComplemento do endereço do pagador
customerAddress.neighbordhoodBairro do pagador
customerAddress.cityCidade do pagador
customerAddress.stateEstado do pagador
Atenção!
  1. Cálculo de Juros: A Aplicação dos juros é calculada com base no valor total (em percentual) dividido por 30 dias (prática adotada pelo mercado, vide diretrizes do Banco Central):
    • Ex: Cobrança de R$150 com multa de 1%. O cálculo do juros seria R$150 * (1 / 100 / 30), resultando em R$0,05 de juros por dia.
  2. Permitido emitir cobranças de até 50 milhões de reais. Entretanto, existem limites internos estabelecidos que podem variar de cliente para cliente. Em caso de dúvidas, entre em contato com o nosso time de Suporte.
Importante

O valor mínimo para geração do boleto é R$5,00.

Observação

Para boletos do tipo aporte/depósito, onde o pagador e o recebedor são a mesma pessoa, é obrigatório que o campo debtor.name seja exatamente igual ao nome informado no registro da conta.

Cliente da cobrança

Você deve enviar apenas uma das opções abaixo:

  • customerId → quando o cliente já está cadastrado
  • Dados de customer → quando você não quer ou não pode usar um cliente cadastrado

❗ Não envie os dois ao mesmo tempo.

Exemplo de retorno​

Sucesso 201
{
    "success": true,
    "boletoId": "b4f888c9-74c3-4b0b-a12d-2b0262c60124",
    "status": "PROCESSING",
    "message": "Boleto está sendo gerado e será processado em breve",
    "amount": 10,
    "dueDate": "2025-11-15",
    "clientCode": "e2a774dd-10c0-4dfa-9b3b-3d23e1ea627d",
    "createdAt": "2025-11-15T15:30:05.220Z"
}
Error 400
{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "OBE001",
    "message": "Ocorreu um erro interno durante a chamada da api."
  }
}

Tabela de errorCode​

CodeMessage
OBE001O identificador externo é obrigatório.
OBE002Informar os dias de pagamento permitidos após o vencimento é obrigatório.
OBE003Tempo de expiração após vencimento deve ser entre 0 e 59.
OBE004A data de vencimento é obrigatória.
OBE005A data de vencimento precisa ser maior ou igual a data atual
OBE006O valor é obrigatório.
OBE007O valor precisa ser maior que 5.
OBE008Valor para recebimento parcial deve ser menor ou igual ao valor com desconto aplicado.
OBE009Valor para recebimento parcial deve ser menor ou igual ao valor original.
OBE010Não pode haver contas iguais para recebedores parciais.
OBE011Máximo de 5 recebedores parciais por cobrança.
OBE012É obrigatório informar a cidade do pagador.
OBE013É obrigatório informar o CPF ou CNPJ do pagador.
OBE014É obrigatório informar o nome do pagador.
OBE015É obrigatório informar o CEP do pagador.
OBE016O Cep informado não é válido.
OBE017É obrigatório informar o logradouro do pagador.
OBE018É obrigatório informar o Número do endereço do pagador.
OBE019É obrigatório informar o Bairro do pagador.
OBE020É obrigatório informar o Estado do pagador.
OBE021É obrigatório informar o número da conta do recebedor.
OBE022É obrigatório informar o CPF ou CNPJ do recebedor.
OBE023Máximo de 20 caracteres permitido.
OBE024Máximo de 100 caracteres permitido.
OBE025Mínimo de 11 e máximo de 14 caracteres permitido.
OBE026Apenas 2 caracteres permitido.
OBE027Apenas 8 caracteres permitido.
OBE028Máximo de 200 caracteres permitido.
OBE029Documento recebedor não é válido.
OBE030Documento pagador não é válido.
OBE031O valor da multa deve estar entre 0.1 e 100.
OBE032O valor dos juros deve estar entre 0.1 e 100.
OBE033O valor de desconto precisa ser maior que 0.
OBE034O valor total, após o desconto por pagamento antecipado, não pode ser inferior a R$ 5,00.
OBE035É necessário informar a modalidade do desconto.
OBE036A modalidade do desconto deve ser fixed ou percent.
OBE037É necessário informar a data limite do desconto.
OBE038A data limite do desconto não pode ser menor que a data atual.
OBE039É obrigatório informar o número da conta de todos os recebedores parciais.
OBE040É obrigatório informar o número de documento de todos os recebedores parciais.
OBE041Porcentagem e valor devem ser preenchidos para caso de pagamento agregado.
OBE042Apenas um dos campos de porcentagem ou valor deve estar preenchido.
OBE043Quando valor é nulo, porcentagem deve ser preenchida.
OBE044A porcentagem deve estar entre 0.1 e 100.
OBE045Quando porcentagem é nula, valor deve ser preenchido.
OBE046A quantidade deve ser maior que 0.
OBE047Account não localizada para um dos recebedores parciais.
OBE048Obrigatório o preenchimento do documento para todos os recebedores parciais.
OBE049A data limite de desconto precisa ser menor ou igual a data de vencimento e não deve ultrapassar 20 dias.
OBE050Número da conta do recebedor não localizada ou inativa.
OBE051Chave pix não localizada para a conta informada.
OBE052Obrigatório o preenchimento dos dados do pagador.
OBE053Obrigatório o preenchimento dos dados do recebedor.
OBE054Serviço de consulta a chave pix está indisponível no momento. Tente mais tarde.
OBE055Serviço de consulta de contas está indisponível no momento. Tente mais tarde.
OBE056Só é permitido atribuir um valor de até 2 casas decimais ao juros.
OBE057Só é permitido atribuir um valor de até 2 casas decimais a multa.
OBE058Só é permitido atribuir um valor de até 2 casas decimais ao desconto.
OBE059Transação não foi localizada.
OBE060Não foi possível criar transação.
OBE061Cliente BaaS não localizado.
OBE062Não foi possível realizar crédito em conta bolsão.
OBE063Não foi possível localizar o recurso de lançamento.
OBE064Não foi encontrado registro para o identificador informado.
OBE065Podem ser gerados PDF apenas de cobranças com status PENDING.
OBE066Template não encontrado para a geração de PDF.
OBE067Sessão ServiceBus de SessionId expirada.
OBE068Não foi possivel realizar essa operação.
OBE069Erro em lançamento para conta beneficiária.
OBE070Erro em cancelamento de boleto.
OBE071Erro em cancelamento de pix.
OBE072Não foi possível identificar o evento.
OBE073O hash de confirmação é obrigatório.
OBE074Não foi possível validar o hash de confirmação.
OBE075Transação é obrigatório.
OBE076Status de transação é obrigatório.
OBE077Não foi possível identificar o status.
OBE078O evento é obrigatório.
OBE099Máximo de 200 caracteres permitido para o logradouro.
OBE100Inclusão ou alteração de split não permitida para Virtual BaaS.
OBE102Erro tratado em cel_cash
OBE101Falha durante geração de boleto
OBE103Nome do pagador só deve conter caracteres válidos.
OBE104Invoice number só deve conter caracteres válidos.
OBE106Boleto não foi criado.
OBE107Número de casas decimais não deve ser maior do que 2.
OBE999Falha em geração de boleto, favor tente novamente.

Webhooks de Cobranças​

EventoDescrição
charge-createApós uma cobrança ser registrada, você receberá esse evento com os detalhes da cobrança
charge-inQuando uma cobrança é paga
charge-canceled.Quando uma cobrança é cancelada
charge-expiredQuando uma cobrança é gerada e não é paga
charge-create 
{
   "body":{
      "transactionId":"e7302f6b-7188-4379-8316-6c537d288596",
      "clientCode":"EXT00001",
      "amount":10,
      "duedate":"2023-07-20 00:00:00",
      "status":"PENDING",
      "debtor":{
         "name":"Josea Joaquina veira",
         "document":"1234568909",
         "postalCode":"15000000",
         "publicArea":"Rua Cinco",
         "number":"123",
         "complement":"",
         "neighborhood":"Centro",
         "city":"São Paulo",
         "state":"SP"
      },
      "receiver":{
         "name":"Monue Krajcik",
         "document":"1234568909",
         "postalCode":"08827434",
         "publicArea":"Rua Nove",
         "city":"São Paulo",
         "state":"SP",
         "account":"30053913745629"
      },
      "instructions":{
         "fine":10.0,
         "interest":1.0,
         "discount":{
            "amount":3.1,
            "modality":"fixed",
            "limitDate":"2023-07-15T03:00:00Z"
         }
      },
      "boleto":{
         "transactionId":"31881",
         "status":"PENDING",
         "bankEmissor":"santander",
         "bankNumber":"4000176322",
         "bankAgency":"1004",
         "bankAccount":"0220060",
         "barCode":"03393941700000010009022006000040001763220101",
         "bankLine":"03399022070600004000317632201012394170000001000",
         "bankAssignor":"CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA"
      },
      "pix":{
         "transactionId":"816145081",
         "transactionIdentification":"kk6g232xel65a0daee4dd13kk816145081",
         "status":"PENDING",
         "key":"teste@chavepix.com.br",
         "emv":"00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/cobv/bf53a874ef9d4a0cb2e1226b5c2d5ed05204000053039865802BR5915Monique Krajcik6015West Marianabor61080882743462070503***630441FF"
      }
   }
}
Importante

O recebimento do webhook de charge-create não significa que o boleto foi registrado na Nuclea, pois o processo de registro é realizado de forma paralela.

charge-canceled 
{
 "entity": "charge-canceled",
 "createTimestamp": "2024-01-18T12:43:04.7091436",
 "status": "CANCELED",
 "body": {
     "amount": 140,
     "boleto": {
         "bankAccount": "12345",
         "bankAgency": "123",
         "bankAssignor": "CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA",
         "bankEmissor": "BancoTeste",
         "bankLine": "",
         "bankNumber": "1234",
         "barCode": "",
         "status": "CANCELED",
         "transactionId": "1234"
     },
     "debtor": {
         "city": "Blumenau",
         "document": "123456789",
         "name": "Fulano de Tal",
         "neighborhood": "Garcia",
         "number": "123",
         "postalCode": "123456789",
         "publicArea": "Rua Por ai",
         "state": "SP"
     },
     "duedate": "2024-01-11 00:00:00",
     "clientCode": "12345678External",
     "pix": {
         "emv": "",
         "key": "",
         "status": "CANCELED",
         "transactionId": "12345",
         "transactionIdentification": "abcdefghijklmnopqrstuvwxyz"
     },
     "reasonCancellation": "Cancelado.",
     "receiver": {
         "account": "123456",
         "city": "Blumenau",
         "document": "123456789",
         "name": "Teste",
         "postalCode": "123456781",
         "publicArea": "Rua",
         "state": "SP"
     },
     "status": "CANCELED",
     "transactionId": "2asdg604a-0124-4poic-95f7-6b12345a3995"
 }
}
charge-expired 
{
  "entity": "charge-expired",
  "createTimestamp": "2025-10-07T14:36:57.676242",
  "status": "EXPIRED",
  "body": {
      "transactionId": "9b7cdabe-ad7d-464f-9fcf-a80d240bc112",
      "clientCode": "9f3fd57b-3df8-45fa-81f9-dc5d37270784",
      "barCode": "50997125100000009560000001000000000000001725",
      "bankLine": "50990000010100000000800000017251712510000000956",
      "dueDate": "2025-10-31 00:00:00",
      "expirationAfterPayment": 59,
      "amount": 9.56,
      "creditParty": {
      "taxId": "12349123000189",
      "account": "123817361"
    }
  }
}