Esse endpoint permite a realização de uma consulta detalhada dos dados de um boleto a partir de um código de barras.
Nos dados retornados é possível validar diversas informações sendo elas:
A categoria do pagamento é definida na propriedade type sendo, "1" para Concessionarias/Tributos e "2" para fichas de compensação. Nas consultas para fichas de compensação realizaremos a consulta CIP, retornando no agrupamento registerData todas as informações atualizadas. Para Concessionárias/Tributos extraímos as informações da linha digitável, sendo assim o mencionado agrupamento registerData não é retornado.
Para consultas de fichas de compensação, retornamos o valor atualizado para o pagamento no campo "totalUpdated". Apenas nas consultas onde o "AllowChangeValue" for true, será possível efetivar o pagamento com um valor diferente do retornado no totalUpdated, lembrando que é necessário respeitar o intervalo máximo(maxValue) e mínimo(minValue).
Disponibilizamos o intervalo que esse pagamento pode ser processado através nas propriedades initeHour e EndHour, desta forma é possível validar qual é a hora inicial e final do processamento do pagamento. Caso seja realizado a tentativa de pagamento fora desse horário de corte o pagamento será postergado para o próximo dia útil.
É possível validar a data em que será realizada a liquidação do boleto através da propriedade settleDate. Também pode ser validado se o título será, ou não liquidado no o dia, através da propriedade nextSettle, onde S mostra que será liquidado no próximo dia útil e N que a liquidação será no mesmo dia. As vezes em ambiente de sandbox, pode ser que a propriedade settleDate seja populada como null, então recomendamos que seja realizado um tratamento para esse cenário do lado da sua aplicação, ou seja ela entenda que uma vez que populado com N a data de liquidação será no dia da confirmação do pagamento.
O transactionId é o id da transação que foi criada para esse pagamento (billpaymentTxnIdAuth).
O documentPayer é o documento do pagador e o value é o valor do pagamento com descontos ou juros.
Para alguns convênios de concessionária, não será possível realizar a extração da data de vencimento por meio da linha digitável, nesses casos, retornaremos o campo "dueDate" com o valor "null", e no momento da efetivação (billpayments) deve ser enviado a data em que está sendo realizado tal pagamento. Em ambiente de homologação a data de vencimento é mockada para qualquer convênio de concessionária, por isso retornará sempre "null". Porém, em produção, podemos retornar a data de vencimento corretamente em casos que o convênio a informa na linha digitável.
Ou seja, em ambiente de produção, nós retornaremos no atributo "dueDate" o valor "null" quando o convênio não disponibiliza a data de vencimento, e retornaremos o valor correto da data de vencimento em formato de Datetime nos casos em que temos a informação por parte do convênio. Por isso na integração os dois cenários devem ser considerados em produção.
OBS:
- Para contas do tipo 1 (concessionárias/tributos), é necessário considerar sempre o atributo "dueDate", o qual refere-se a data de vencimento extraída na linha digitável do registro;
- Para contas do tipo 2 (ficha de compensação), é necessário considerar sempre o atributo "registerData.dueDateRegister", o qual refere-se a data de vencimento recuperada na consulta junto a CIP (Câmara Interbancária de Pagamentos).
Parâmetros da URL
bar_code(string): Código de barras para consulta.
Resposta
Se a requisição for processada com sucesso será retornado um código 200 e um JSON no seguinte formato:
assignor(string (100)): Cedente do pagamento consultado.
registerData(object): Objeto contendo os dados de registro.
settleDate(datetime): Informa a data em que o pagamento será enviado para liquidação.
dueDate(datetime): Retorna a data de vencimento extraída do código.
endHour(string (5)): Informa a Hora corte do convênio (HH:MM).
initeHour(string (5)): Informa a Hora recebimento Inicial do convênio (HH:MM).
nextSettle(string (1)): Informa se o título será liquidado no próximo dia útil. Pode ser N ou S.
digitable(string (48)): Define a linha digitável consultada.
transactionId(bigInt): Protocolo de identificação da operação (billpaymentTxnIdAuth).
type(int): Tipo de conta que está realizando a consulta.
value(float): Valor extraído do código.
errorCode(string (3)): Define o código status da operação.
message(string (100)): Informa descrição do erro.
status(string (30)): Define o status da operação.
Objeto 'registerData'
documentRecipient(string (18)): CPF ou CNPJ do beneficiário.
documentPayer(string (18)): CPF ou CNPJ do pagador.
payDueDate(datetime): Data de baixa do boleto.
nextBusinessDay(datetime): Próximo dia útil.
dueDateRegister(datetime): Data de vencimento do registro.
allowChangeValue(boolean): Indica que o Boleto permite alterar valor entre o range “maxValue” e “minValue”, sugerimos que caso seja retornado “True” libere que o usuário insira na efetivação (Billpayments) o valor desejado.
recipient(string (100)): Nome do beneficiário.
payer(string (100)): Nome do pagador.
discountValue(float): Valor do desconto calculado.
interestValueCalculated(float): Valor juros já calculado.
maxValue(float): Valor máximo permitido para pagamento do título. Utilizado nos cenários onde o “AllowChangeValue” for “True”.
minValue(float): Valor mínimo permitido para pagamento do título. Utilizado nos cenários onde o “AllowChangeValue” for “True”.
fineValueCalculated(float): Valor multa já calculado.
originalValue(float): Valor nominal do título.
totalUpdated(float): Valor atualizado a ser pago do título. Caso o campo “AllowChangeValue” retorne “False” apenas o valor retornado neste campo será aceito.
totalWithDiscount(float): Valor total de descontos e abatimentos.
totalWithAdditional(float): Valor total de juros e multa.
Exemplo de JSON:
{
"registerData": {
"documentRecipient": "<string>",
"documentPayer": "<string>",
"payDueDate": "<string>",
"nextBusinessDay": "<string>",
"dueDateRegister": "<string>",
"allowChangeValue": "<boolean>",
"recipient": "<string>",
"payer": "<string>",
"discountValue": "<number>",
"interestValueCalculated": "<number>",
"maxValue": "<number>",
"minValue": "<number>",
"fineValueCalculated": "<number>",
"originalValue": "<number>",
"totalUpdated": "<number>",
"totalWithDiscount": "<number>",
"totalWithAdditional": "<number>"
},
"assignor": "<string>",
"settleDate": "<string>",
"dueDate": "<string>",
"endHour": "<string>",
"initeHour": "<string>",
"nextSettle": "<string>",
"digitable": "<string>",
"billpaymentTxnIdAuth": "<number>",
"type": "<number>",
"value": "<number>",
"maxValue": "<number>",
"minValue": "<number>",
"errorCode": "<string>",
"message": "<string>",
"status": "<number>"
}