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.

Emitir um Boleto

Usado para

Provedores disponíveis

Emitindo um Boleto

Request

Body Request

📘
yourNumber e insuranceNumber

Definindo a carteira de cobrança para o Boleto

Response

🚧
barCode x digitableLine

Emitindo um Boleto para recarga

Configurando taxas e descontos

🚧
Taxas e descontos

Informações

📘
Limitação de valores para emissão

Usado para

Provedores disponíveis

Emitindo um Boleto

Request

Body Request

📘yourNumber e insuranceNumber

Definindo a carteira de cobrança para o Boleto

Response

🚧barCode x digitableLine

Emitindo um Boleto para recarga

Configurando taxas e descontos

🚧Taxas e descontos

Informações

📘Limitação de valores para emissão

📘
yourNumber e insuranceNumber

🚧
barCode x digitableLine

🚧
Taxas e descontos

📘
Limitação de valores para emissão