Antecipação por valor

📘

O que você irá aprender nesse artigo

  • Antecipação na iugu
  • Como funciona a antecipação de valores
  • Como realizar uma antecipação de valor via API

Caso de uso

“Cliente entra no sistema e gostaria de sacar R$ 1.000,00 que está no saldo a receber”.

Diagrama de sequência:

Antecipação na iugu

Para saber o que é uma antecipação, basta acessar aqui. A antecipação na iugu não é habilitada de forma automática, existe uma análise que deve ser feita, veja quais os critérios aqui.

Considerando que a análise foi feita e a antecipação foi habilitada, há duas formas de antecipar valores na iugu: manualmente ou automaticamente.

Para saber como antecipar o saldo automaticamente, consulte aqui.

A antecipação manual pode ser feita por antecipação de parcelas ou por antecipação de valor. Para saber como antecipar parcelas, acesse aqui.

A antecipação por valor é feita através da chamada de Antecipação por valor

🚧

Atenção!

  • Horário: só pode antecipar das 9:00 da manhã até 16:00 em dias úteis (segunda a sexta, exceto feriados)
  • Parcelas antecipáveis: só pode antecipar parcelas criadas há mais de 24 horas e não pode antecipar parcelas que vão ser liquidadas em menos de 2 dias.

Como funciona a antecipação de valores

Para realizar a antecipação por valor, via API, é necessário que antes seja realizada uma simulação de antecipação. Isso porque a antecipação não pode quebrar o valor de uma parcela. Dessa maneira, é necessário saber qual o valor mais próximo do solicitado que poderá ser antecipado. Ou seja, suponha que você precise antecipar um valor de R$ 100,00 e na sua lista de recebíveis tenha uma parcela de R$ 50,00, outra de R$ 40,00 e outra de R$ 80,00. Nesse cenário, não é possível quebrar o valor de qualquer uma dessas parcelas para antecipar exatamente R$ 100,00. Sendo assim, o simulador vai retornar dados de antecipação de R$ 90,00 que é o mais próximo do valor desejado.

OBS: O simulador sempre vai mostrar um valor igual ou inferior ao solicitado. Isso significa que, no exemplo acima, não há possibilidade de retornar antecipação de R$ 120,00 (Soma da parcela de R$ 80,00 com a parcela de R$ 40,00).

O simulador de antecipação retornará dois arrays, o nearest e o farthest.

Nearest e Farthest

Nearest = Simulação de antecipação considerando as parcelas mais próximas de liquidação. Exemplo: Considerando que uma simulação seja feita no mês de janeiro, o primeiro array vai retornar as parcelas que liquidam em fevereiro, por exemplo.

Farthest = Simulação de antecipação considerando as parcelas mais distantes de liquidação.

Exemplo: Considerando que uma simulação seja feita no mês de janeiro, o segundo array vai retornar as parcelas que liquidam em dezembro, por exemplo.

Como realizar uma antecipação de valor via API

Primeiramente, faça uma simulação de antecipação realizando um GET na API de Simular antecipação por valor, informando o valor que deseja antecipar no campo total_cents. Ou seja, se a simulação for de R$ 1.000,00, informe o total_cents = 100000. Além disso, coloque o api_token e o id da conta (saiba aqui como acessar essa informação).

Modelo de request

curl --location --request GET 'https://api.iugu.com/v1/financial_transaction_requests/simulate_by_amount?total_cents=500' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=de5125641a3d2fefe94f5662f89812f490930a6b-1642512068'

Modelo de response de sucesso

O campo advanceable_amount_cents indica o valor que pode ser antecipado de acordo com o valor solicitado, o advancement_fee_cents aponta o valor que será pago para antecipar as parcelas, o advanceable_installments diz quantas parcelas serão antecipadas e o simulation_id é o identificador da simulação realizada. Esse id deve ser informado na chamada de antecipação para que o processo seja feito efetivamente.

OBS: A taxa de antecipação é retirada do montante que será antecipado, ou seja, caso a antecipação seja de R$ 100,00 e a taxa for de R$ 5,00, então no final você receberá R$ 95,00.

🚧

Atenção!

Outro ponto importante é que o id da simulação só é válido por 10 minutos. Após esse tempo, ele fica inválido e uma nova chamada deverá ser realizada.

📘

Saiba que:

A antecipação por valor tem um limite de 1.000 parcelas. Se caso o valor desejado para antecipação ultrapasse esse número de parcelas, antecipe um valor próximo e depois solicite mais uma antecipação do restante.

Modelos de response em casos de erro

Caso o valor de antecipação solicitado seja menor que o valor da primeira parcela que poderia ser antecipada.

Caso o valor solicitado seja maior que o limite de antecipação da conta.

Inicialmente, não há uma forma de consultar o limite de valor de antecipação. Desse modo, pode ser feita uma simulação com um valor alto para retornar o limite da sua conta.

Depois que a simulação for feita, o passo seguinte é solicitar a antecipação. Para isso, realize um POST na API de Antecipação por valor, informando o id da simulação anterior e o api_token.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/financial_transaction_requests/advance_by_amount?advancement_order=9269fa30-5a90-013a-d8f5-0ec08399a2c6' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=de5125641a3d2fefe94f5662f89812f490930a6b-1642512068'

Modelo de response em caso de sucesso

Modelo de response em caso de erro

Caso solicite a antecipação fora do horário padrão (9hs às 16hs) e em dias não úteis, a API retornará erro.

Modelo de response caso tente antecipar parcelas recentes


Did this page help you?