GuidesAPI ReferenceCommunity
GuidesCommunityLog In

Emitir um Boleto

Existem alguns provedores responsáveis ​​pela emissão de Boletos na plataforma Bit Capital. Alguns desses provedores foram preteridos e outros estão ativos.

Usado para

  • Emitir um Boleto para cobrança de terceiros, a ser pago por qualquer Instituição Financeira;
  • Emitir um Boleto para creditação em sua própria wallet (Boleto de recarga) , a ser pago por qualquer Instituição Financeira;

Provedores disponíveis

Provider

Status

provider name

CIP

Disponível em Beta version since 2.7.x

boleto-provider

BS2

Deprecated since 2.2.x

bs2

Dock

Deprecated since 2.2.x

dock


Emitindo um Boleto

Um Boleto pode ser emitido para ser pago a um terceiro como pagador.

Tecnicamente, você estará criando uma cobrança para uma terceira pessoa (física ou jurídica) pagar e, em seguida, o saldo deste Boleto será creditado na wallet especificada no body request.

Nesse caso, será necessário fornecer alguns dados do pagador do Boleto ao órgão requisitante.

Request

POST {{BASE_URL}}/boletos/emission/beneficiary/{{CNPJ}}/boleto

Body Request

{
    "destination": "{{walletId}}",
    "amount": "22.22",
    "yourNumber": "{string}", 
    "insuranceNumber": "{{string}}", 
    "billing": {
        "externalId": 1
    },
    "extra": {
        "expiresAt": "2022-04-30",
        "payer": {
            "name": "Pagador do Boleto",
            "consumer": {
                "taxId": "11122233344456",
                "type": "corporate",
                "phones": [
                    {
                        "countryCode": "+55",
                        "code": "19",
                        "number": "999666777"
                    }
                ],
                "addresses": [
                    {
                        "street": "Av. Paulista",
                        "number": "123",
                        "code": "12311234",
                        "neighborhood": "Bela Vista",
                        "state": "SP",
                        "city": "São Paulo",
                        "country": "BR"
                    }
                ]
            }
        }
    }
}
curl --location --request POST 'https://{{API_BASEURL}}/boletos/emission/beneficiary/{{TAXID}}/boleto' \
--header 'x-idempotence-key: {{uuid}}' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "destination": "bda727b4-69bd-4cd5-acaa-86f65addec1e",
    "amount": "222.21",
    "yourNumber": "2432967955", 
    "insuranceNumber": "2432967955insurance", 
    "billing": {
        "externalId": 6
    },
    "extra": {
        "expiresAt": "2022-04-30",
        "payer": {
            "name": "Pagador do Boleto",
            "consumer": {
                "taxId": "16035529000180",
                "type": "corporate",
                "phones": [
                    {
                        "countryCode": "+55",
                        "code": "19",
                        "number": "999666777"
                    }
                ],
                "addresses": [
                    {
                        "street": "Av. Paulista",
                        "number": "123",
                        "code": "12311234",
                        "neighborhood": "Bela Vista",
                        "state": "SP",
                        "city": "São Paulo",
                        "country": "BR"
                    }
                ]
            }
        }
    }
}'

campo

tipo

descrição

amount

string

  • Valor do boleto

destination

string(uuid)

  • Wallet no qual receberá o valor do boleto

billing.externalId

number

  • Campo obrigatório que identifica carteira de Cobrança na plataforma

extra.expiresAt

string

  • Data de vencimento do Boleto
  • Timestamp AAAA-MM-DD

yourNumber

string (max 10 chars)

  • Campo para personalização e identificação interna para o cliente da API;
  • Ao utilizar este atributo, obrigatoriamente você deve utilizar também o atributo insuranceNumber
  • Uso livre para o cliente da API

insuranceNumber

string

  • Campo para personalização e identificação interna para o cliente da API;
  • Ao utuilizar este atributo, obrigatoriamente você deve utilizar também o atributo yourNumber
  • Máximo de 10 caracteres
  • Valores não podem se repetir;
  • Uso livre para o cliente da API;

extra.payer.name

string

  • nome do pagador do Boleto;
  • caso o pagador do Boleto seja o mesmo emissor do Boleto, existe uma configuração mais simples descrita neste link

extra.payer.consumer.taxId

string

  • CPF se pessoa física
  • CNPJ se pessoa jurídica
  • este campo dependa da configuracao do campo extra.payer.consumer.taxId

extra.payer.consumer.type

enum ( corporate | personal )

  • define qual o tipo de pagador se pessoa jurídica ou pessoa física

extra.payer.phones[]

array

  • dados de telefone do pagador

extra.payer.addresses[]

array

  • dados de endereço do pagador

Neste momento o campo extra.payer.addresses[] ainda é um campo obrigatório para se declarar no body do requerimento. Esta sendo desenvolvido uma melhoria para a remoção deste dado.

📘

yourNumber e insuranceNumber

Os campos descritos abaixo são disponibilizados para o cliente da API. Possui registro saldo em banco de dados e está disponível para personalização de qualquer tipo de string (UUID, sequencial, BASE64...) caso o cliente da API queira personalizar internamente com uma identificação baseada em seu negócio.


Definindo a carteira de cobrança para o Boleto

Para deifnir uma carteira de cobrança o objeto billing.externalId deve ser definido com número da carteira de cobrança desejada.
Para saber qual carteira de cobrança está configurada em seu ambiente, entre em contato com o nosso Help Desk.
Sempre que estiver com dúvidas pode acessar a sessão de descrição do produto neste link

{
  ...
  

"billing": {
        "externalId": 5
      }

  ...
  
}

Response

{
    "id": "3172961d-118a-437a-b4c7-334a9b4b34b4",
    "beneficiary": {
        "taxId": "50272736000197",
        "name": "Randy Schuppe"
    },
    "payer": {
        "taxId": "50272736000197",
        "name": "Randy Schuppe"
    },
    "states": [
        {
            "id": "c44f9865-d95b-4924-8812-7a443e518354",
            "createdAt": "2022-03-11T18:13:02.912Z",
            "updatedAt": "2022-03-11T18:13:02.912Z",
            "deletedAt": null,
            "status": "pending_registration",
            "additionalData": null
        }
    ],
    "fineInterest": null,
    "fineValue": null,
    "fineDate": null,
    "discountValue": null,
    "discountPercentage": null,
    "discountLimit": null,
    "paymentDate": null,
    "settledAmount": null,
    "yourNumber": "0100",
    "amount": "75.71",
    "expiresAt": "2022-12-31T00:00:00.000Z",
    "digitableLine": "32690.00000   00175.550003   00360.380133   1   92150000007571",
    "documentNumber": "0100",
    "barCode": "32691921500000075710000000175550000036038013",
    "createdAt": "2022-03-11T18:13:02.908Z"
}

campo

tipo

descrição

id

string

  • boletoId
  • Identificador do Boleto criado com sucesso

beneficiary.taxid

string

  • CPF|CNPJ do pagador do boleto

beneficiary.name

string

  • Nome do beneficiário do boleto

payer.taxId

string

  • CPF|CNPJ do pagador do boleto

payer.name

string

  • Nome do pagador do boleto

states

array

  • States[0] exibe o último status do Boleto

digitableLine

string

  • Identificação do registro do boleto na CIP

barCode

  • Número para desenvolvimento do código de barras

amount

string

  • Campo para valor

expiresAt

  • Data de expiração do boleto

yourNumber

  • Identificação interna

🚧

barCode x digitableLine

  • barCode é diferente de digitableLine
  • as validações são baseadas em digitableLine

Emitindo um Boleto para recarga

Emitir um Boleto para recarga é uma forma de abreviar o body da requisição, ocultando dados que não precisariam ser declarados pois o emissor do boleto é o próprio beneficiário do valor pago do Boleto, dando assim a nomenclatura de recarregar sua própria wallet

O body da requisição se abrevia da seguinte forma

Pré requisitos para o uso desta facilidade;

  • o emissor do Boleto também deve ser o pagador do Boleto;
  • e beneficiário do boleto deve possuir um registro na plataforma ativo;
{
    "destination": "{{walletId}}",
    "amount": "30.03",
    "yourNumber": "4545454545",
    "insuranceNumber": "4545454545number",
    "billing": {
        "externalId": 1
    },
    "extra": {
        "expiresAt": "2022-12-31"
    }
}

Para este caso, necessariamente o campo destination deve conter a wallet do pŕoprio emissor do Boleto. No caso, o emissor é um Beneficiário já cadastrado na plataforma. A plataforma busca os dados do emissor a partir de seu vículo com a walletId especificada.


Configurando taxas e descontos

🚧

Taxas e descontos

  • Esta é uma feature em Alfa-test.
  • Esta configuração é opcional.

Para configuração de taxas e descontos para um Boleto é necessário acrescentar as propriedades abaixo dentro da propriedade extra

{....
"extra": {

... 

        "fine": {
            "date": "{{AAAA-MM-DD}}",
            "interest": "0.1",
            "value": "1.3"
        },
        "discount": {
            "limit": "{{AAAA-MM-DD}}",
            "value": "1.4"
        }

...
}

campo

tipo

descrição

fine.date

string

  • AAAA-MM-DD
  • Data limite para pagamento do boleto com juros após o vencimento.
  • Deve ser maior do que a data de vencimento do boleto.

fine.interest

string

  • Taxa de juros mensal para pagamento atrasado.
  • Valor em porcentagem. Ex: 1.0 (1%), 5.3 (5,3%)

fine.value

string

  • Valor de multa a ser aplicada ao valor do boleto após o vencimento.
  • Valor em reais. Ex: 1.0 (R$ 1,00), 10.50 (R$ 10,50)

discount.limit

string

  • AAAA-MM-DD
  • Data limite para pagamento do boleto com desconto.
  • Deve ser menor ou igual a data de vencimento do boleto.

discount.percentage

string

  • Porcentagem do desconto a ser aplicada ao valor do boleto antes do vencimento.
  • Valor em porcentagem. Ex: 1.0 (1%), 5.3 (5,3%)

discount.value

string

  • Valor do desconto a ser aplicado ao valor do boleto antes do vencimento.
  • Valor em reais. Ex: 1.0 (R$ 1,00), 10.50 (R$ 10,50)

Informações

  • Este procedimento apenas emite um Boleto.
  • Uma vez emitido o Boleto, ele aguarda registro na CIP.
  • CIP registra o Boleto;
  • O status do boleto evolui para pending_payment. Este status informa que o Boleto está cadastrado e já pode ser pago em qualquer Instituição Financeira.

📘

Limitação de valores para emissão

A limitação de valor mínimo e valor máximo a emitir é um acordo entre a Instituição Financeira e a CIP (principal órgão de registro de Boletos no Brasil).

Neste caso, temos as seguintes limitações:

  • 00,01 como valor mínimo para emitir um Boleto
  • 50.000,00 como valor máximo para emitir um Boleto.

Caso seja realmente necessário emitir um valor diferente no Boleto, por favor abra um ticket em nossa Central de Atendimento para solicitar.

Todas as solicitações serão analisadas pela equipe de Compliance correspondente.


Did this page help you?