Realizar antecipação de parcelas via API

📘

O que você irá aprender com esse artigo?

  • O que é antecipação
  • Como funciona a antecipação de parcelas na iugu
  • Como realizar uma antecipação manual via API
  • Como realizar um saque via API

Caso de uso

“Cliente entra no sistema e gostaria de sacar parte do valor que está no saldo a receber”

Diagrama de sequência

968

O que é antecipação

A antecipação consiste em adiantar o recebimento de valores pagos por cartão de crédito em recursos líquidos e imediatos. Quando a antecipação é realizada, o valor sai do "saldo a receber" e passa para o "saldo disponível para saque".

🚧

Atenção!

A antecipação tem um custo de juros compostos ao mês. Para mais detalhes consulte sua negociação comercial.

Como funciona a antecipação de parcelas na iugu

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 via API através da chamada de Antecipar Recebíveis.

Como realizar uma antecipação manual de parcelas via API

É possível solicitar a antecipação de determinada parcela através da API. O processo tem uma limitação de 200 parcelas que podem ser antecipadas. Supondo que há 3 faturas criadas na conta que foram pagas por cartão: uma em 12 parcelas, outra em 7 parcelas e a última em 3 parcelas. Na antecipação por parcelas é possível selecionar 3 parcelas da primeira fatura, uma da segunda e todas as 3 da última fatura, por exemplo. Isso significa que a antecipação por parcelas não fica limitada a um valor, mas é possível definir exatamente quais são as parcelas que deseja antecipar, independente se são parcelas de uma mesma fatura ou não. Essa seria a principal diferença da antecipação por parcela e por valores.

🚧

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.

O primeiro passo para a antecipação seria listar todas os recebíveis da conta. Essa chamada retornará uma lista separada por parcelas com seus devidos valores. Nesse passo é necessário que seja capturado do callback da requisição todos os ids das parcelas que deseja antecipar (no máximo 200).

Modelo de request

curl --location --request GET 'https://api.iugu.com/v1/financial_transaction_requests' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012'

Modelo de response

748

Simular Antecipação

Antes de realizar a antecipação propriamente dita, pode ser feita uma simulação de como ficaria a antecipação das parcelas selecionadas.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/financial_transaction_requests/advance_simulation?transactions=33666790,33666791' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012'

Modelo de response

703

O campo taxes, que é mostrado no retorno da requisição, se refere a taxa paga pela transação no cartão, o advance_fee representa a taxa de antecipação dessa parcela, já o received_value apresenta o valor da parcela que será recebida após o processo de antecipação.

Antecipar Parcelas

Depois de definido quais são as parcelas que deseja antecipar, o próximo passo é a requisição de antecipação. Nessa chamada é enviado todos os identificadores das parceladas selecionadas e o valor somado dessas parcelas ficarão como saldo disponível na conta.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/financial_transaction_requests/advance' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012' \ 
--data-raw '{ 
    "transactions": [33666790,33666791] 
}'

Modelo de response

424

Como realizar um saque via API

O saque é uma transferência do saldo que está na conta digital iugu para uma conta bancária de mesmo titular. O saque na iugu pode ser feito de maneira automática ou manual. Confira a API de Pedido de Saque aqui.

Só é possível sacar um valor que está no saldo disponível, o valor que estiver em saldo futuro precisa ser antecipado. Importante ressaltar que a operação de saque pode ter um custo, para mais detalhes consultar negociação comercial realizada.

Depois de antecipar os recebíveis o valor fica em saldo disponível para saque. A transferência para a conta bancária pode ser solicitada via API através da requisição de pedido de saque. Nessa chamada é necessário informar o identificador da conta e o api-token.

Modelo de response caso tente antecipar fora do horário

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

1113

Modelo de response caso tente antecipar parcelas recentes

1004