Introdução
Boleto bancário
Um boleto bancário geralmente está relacionado a cobranças. São caracterizados por terem linhas digitáveis que não são iniciadas com dígito 8. Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
Carteira de cobrança
De antemão, vale ressaltar que, nessa documentação, as carteiras de cobrança são chamadas de requester_profile. A carteira de cobrança está necessariamente relacionada a uma conta e carrega configurações padrão específicas (de juros, multa, protesto etc.) no que diz respeito ao registro de boletos. Uma vez atribuídas tais configurações padrão --- na criação ou edição da carteira de cobrança ---, sempre que o usuário registrar um boleto, sem mandar alguma dessas configurações, será utilizada a configuração padrão para o parâmetro em questão.
Ao criar a carteira de cobrança, o usuário enviou uma configuração de multa para a carteira que faz com que, caso o pagador atrase o pagamento em 5 dias ou mais, será cobrado R$10,00 de multa. Ao registrar o boleto, essa configuração pode ser sobrescrita; por exemplo, pode-se optar por cobrar uma multa de R$15,00, ou até mesmo não cobrar multa nenhuma. No entanto, caso tal configuração não seja sobrescrita no momento do registro do boleto, valerá a configuração padrão da carteira (a aplicação dos R$10,00 de multa, caso o pagador atrase mais de 5 dias no pagamento).
É possível criar várias carteiras de cobrança para uma mesma conta, e uma carteira inicial --- sem nenhuma configuração padrão ---, é criada juntamente com a abertura de conta na QI Tech. A possibilidade de se criar várias carteiras de cobrança permite a criação de diferentes carteiras com diferentes configurações padrão; e as configurações padrão, por sua vez, facilitam o registro de vários boletos com configurações em comum, uma vez que configurações de multa, juros etc. não precisam ser enviadas sempre que se deseja registrar um boleto.
Máquina de estados do boleto
Os boletos, ao longo de seu ciclo de vida, podem passar pelos seguintes status:
| Enumerador | Tradução | Descrição |
|---|---|---|
| accepted | aceito | Boleto aceito e pendente de confirmação junto à CIP/Nuclea |
| rejected | rejeitado | O registro do boleto não foi aceito |
| registered | registrado | Boleto registrado junto à CIP/Nuclea |
| payment_blocked | bloqueado para pagamento | Boleto bloqueado para pagamento na CIP/Nuclea por estar em fluxo de protesto |
| written_off | baixado | Boleto baixado (não está mais disponível para pagamento) |
| payment_notice | pagamento notificado | O boleto pago e baixado, mas ainda sem liquidação financeira |
| paid | pago | Boleto pago, baixado e liquidado financeiramente |
Transições de estado
accepted->rejected: registro do boleto não foi aceito junto à CIP/Nuclea;accepted->registered: registro do boleto aceito junto à CIP/Nuclea;registered->written_off: boleto foi baixado sem ser pago;registered->payment_notice: boleto foi pago e baixado, mas ainda não foi liquidado financeiramente;payment_notice->paid: após o pagamento, boleto foi liquidado financeiramente;registered->payment_blocked: pagamento do boleto foi bloqueado, devido ao início de um fluxo de protesto;payment_blocked->notary_office_payment_notice: boleto foi pago em cartório e baixado, mas ainda não foi liquidado financeiramente;notary_office_payment_notice->paid: após o pagamento em cartório, boleto foi liquidado financeiramente;payment_blocked->written_off: boleto foi protestado.
Registro de boletos
Via API
Fluxo de registro padrãoCaso o sistema receba uma requisição de registro de boleto pelo fluxo de registro padrão, e tal requisição seja aceita --- isto é, caso não haja nenhuma inconsistência com as informações enviadas ---, será devolvido como resposta um boleto com o status accepted, mas ainda não é certeza de que o mesmo será de fato registrado. Após o envio do boleto para a CIP/Nuclea e o recebimento da resposta, o boleto passa para o status rejected ou para o status accepted.
Há também uma outra opção para o registro de boletos: o fluxo de registro instantâneo. Nesse fluxo, o registro do boleto é processado de maneira síncrona e a resposta da API já retorna a informação se o boleto foi aceito ou rejeitado; ou seja, é devolvido como resposta um boleto que já possui status accepted ou rejected. O tempo de confirmação/rejeição da Nuclea/CIP, a respeito do registro do boleto, está incluso no tempo de resposta desse endpoint.
Via arquivo de remessa
A solicitação de registro de boletos via arquivo surte exatamente o mesmo resultado final do registro via API. A diferença é que, quando registrando via arquivo, deve-se considerar o tempo de processamento do arquivo no tempo total para registro do boleto. Portanto, geralmente trata-se de um registro mais demorado do que o registro via API.
Em contrapartida, ao registrar via arquivo, é possível registrar um volume muito alto de boletos de uma vez só.