Antecipação sob demanda
Antecipação sob demanda via API
O produto de antecipação, tem por objetivo, permitir que os parceiros possam antecipar suas transações (Crédito) que seriam liquidadas em uma data futura (D + Período acordado). Os parceiros tem disponível uma API, onde podem ser realizadas as antecipações.
Primeiro passo, é o parceiro (marketplace) estar habilitado para realizar antecipações. Uma vez que o Marketplace possa antecipar, fazendo uso da API, será realizado uma solicitação de criação da antecipação, na resposta da API, será devolvido um identificador (ID da Antecipação).
Uma vez que o processo de simulação da antecipação for concluído, o mesmo passará pelo processo de aprovação, etapa onde as áreas de controle da Zoop (Financeiro) irá autorizar ou recusar a simulação. Após as autorização das áreas de controle, os recebíveis simulados que seriam pagos em data futura, passarão a ter data pagamento de acordo com dia da antecipação. Uma vez que essas datas de pagamentos são alteradas, os recebíveis seguiram o fluxo de liquidação (O valor antecipado será creditado ao solicitante).
Solicitando Antecipação sob demanda
Cria um novo pedido de antecipação, que será posteriormente simulado e terá aprovação financeira para realizar a antecipação de fato.
| Chave | Valores |
|---|---|
customer* string | example: 28d4c96c451d93c2d2787e8caee4290f ID do Seller que terá seus recebíveis antecipáveis. |
prepayment_date* string | ($date) example: 2018-01-19 Data para a qual os recebíveis serão antecipados. Caso não seja preenchido, é considerado D0. |
min_transaction_datestring | ($date) example: 2018-01-19 Apenas considerar recebíveis de vendas realizadas após esta data (inclusive). Caso não seja preenchida, é considerada a data da venda mais antiga com recebíveis não liquidados. |
max_transaction_datestring | ($date) example: 2018-01-19 Apenas considerar recebíveis de vendas realizadas até esta data (inclusive). Caso não seja preenchida, é considerado D-1. Este também é o valor máximo para este campo. |
min_expected_datestring | ($date) example: 2018-01-19 Apenas considerar recebíveis cuja agenda original de liquidação seja após esta data (inclusive). Caso não seja preenchida, é considerado D+1 do campo "prepayment_date". Este também é o valor mínimo para este campo. |
max_expected_datestring | ($date) example: 2018-01-19 Apenas considerar recebíveis cuja agenda original de liquidação seja até esta data (inclusive). Caso não seja preenchida, é considerada a data de liquidação do recebível mais tardio. |
receivablesstring | Lista de IDs de recebíveis que deverão ser incluídos na solicitação de antecipação example: 6c451d93c2d278728d4c9e8caee4290f] Pode usar a informação que está no endpoint de Recebíveis Aptos a Antecipação para preencher essa lista. |
transactionsstring | Lista de IDs de transações cujos recebíveis deverão ser incluídos na solicitação de antecipação example: 4290f3c2d2787e8c28d4c96c451d9aee] |
target_amountinteger | example: 500000 Valor alvo, em centavos de Reais, para escolha dos recebíveis a antecipar mediante algoritmo de busca, que seleciona recebíveis de forma incremental até atingir este valor alvo, até o limite percentual da margem (campo "margin"). Recebíveis que façam o valor total de antecipação ultrapassar o valor alvo com a margem incluída não são incluídos na antecipação. Caso um recebível faça o valor da antecipação atingir o intervalo entre o valor alvo e a margem, o algoritmo é interrompido e a simulação é concluída com os recebíveis selecionados. |
marginnumber | ($float) example: 0.01 Margem para seleção de recebíveis caso seja solicitado o filtro de valor alvo (target_amount). Caso não seja preenchido, é considerado 0.01 (1%). Isto significa que no caso de uma antecipação solicitada com target_amount de 500000 (R$5.000,00) e sem margem definida, o algoritmo selecionará recebíveis até atingir o valor de R$5.000,00, porém nunca ultrapassando o valor de R$5.050,00 (recebíveis que ultrapassariam este valor são descartados - pulados). Mesmo que o valor final seja inferior ao valor alvo solicitado, a antecipação é considerada simulada e fica apta à aprovação. |
orderstring | Indica a prioridade de seleção dos recebíveis na antecipação por valor alvo. Como os recebíveis são selecionados um por um até atingir-se o valor alvo, pode-se utilizar este campo para forçar uma seleção dos recebíveis que estejam vencendo primeiro (expected_date_descending), vencendo por último (expected_date_descending) ou mesmo priorizar recebíveis de vendas mais antigas (transaction_date_ascending), o que na prática fará com que todos os recebíveis de uma venda sejam antecipados em conjunto antes de partir para os recebíveis da próxima venda (exceto se o somatório dos recebíveis de uma venda ultrapasse o limite da margem do valor alvo). Caso não seja preenchido, é considerada a ordenação expected_date_descending Enum: Array [ 3 ] |
partner_feenumber | ($float) example: 0.0094 Permite que o Marketplace cadastre, ou altere, sua taxa para ser aplicada em cima da antecipação requisitada pelo estabelecimento. Essa taxa não afeta a taxa da Zoop. Pode-se deixar pré-cadastrada um a cobrança do fee para um determinado seller. Valores maiores do que 1 irão resultar em Bad Request. |
auto_commitboolean | example: true|false Permite desativar o transito automático do status simulated para ready. Se a requisição enviar em seu payload auto_commit=false, o status permanecerá simulated aguardando a confirmação do usuário da API através da requisição /commit. A operação /commit transita somente do status simulated para o status ready. O valor default é true. |
fail_on_receivable_invalidboolean | example: true|false default: false Com o valor default false a solicitação retornará sucesso e adicionará a resposta a propriedade rejected_transactions que conterá uma lista detalhada dos erros que invalidam as transações e/ou seus recebíveis. Com valor true, a requisição falhará e não será criada a solicitação, a mensagem de error conterá os detalhes da invalidação para cada transação e/ou seus recebíveis. |
Pré-Cadastrando taxa de antecipação para o vendedor (seller)
É possível deixar uma taxa pré-cadastrada para um determinado vendedor (seller) e com isso, não necessitando passar a informação na chave {partner_fee} da requisição de antecipação sob demanda.
| Chave | Valores |
|---|---|
percent_amountnumber | example: 0.01 default: 0 Valor percentual que será aplicado. O valor mínimo é de 0(equivale a 0%), e o máximo de 0.9999(equivale a 99.99%). O percentual pode variar entre menor que 1 ou maior ou igual a 0. |
id_customerstring | example: 8a70ac5fba13472a8b23171c62e244b4 Seller para qual a taxa da antecipação será aplicada |
Verificando Recebíveis Aptos a Antecipação
| Chave | Valores |
|---|---|
prepayable_forstring | ($date) example: 2019-05-30 Retorna os recebíveis que estão aptos ao participar de uma antecipação, a parir da data informada. Ao passar o valor da data, não é necessario a utilização das aspas. Ex.: prepayable_for=2019-05-30 |
Para retornar os recebíveis aptos a antecipação para um determinado seller, disponibilizamos um endpoint específico.
Liberação de antecipação
Para que seja possível fazer uso da API de antecipação, o parceiro deverá entrar em contato com a pessoa do comercial (Zoop), responsável por sua conta.
Clique na imagem para aumentar.
Fluxo detalhado
-
Após a requisição da antecipação sob demanda, a mesma passa a ficar com status "solicitada" (requested), onde fica passível de simulação por rotina automática.
-
Após a simulação, entra no status "simulada" (simulated) (ou "pronta" (ready) se o parâmetro
auto_commitfor passado com valortrue), onde passam a ser preenchidos os campos de taxas aplicadas, valor total aplicado à antecipação de recebíveis selecionados. -
Fica então passível de aprovação do Financeiro da Zoop, que pode torná-la "aprovada" (approved) ou "rejeitada" (rejected) dependendo da análise.
-
Uma vez aprovada, fica passível de realização de fato da antecipação, após o qual fica com o status "realizada" (succeeded).
-
Não possível cancelar uma solicitação de antecipação sob demanda via API. O status de "cancelado" (canceled). ocorre quando houver qualquer tipo de alteração nos recebíveis ou não ter sido aprovado pela Zoop.
-
Caso a solicitação de antecipação não seja aprovada até a data selecionada para sua realização, a solicitação vai para o status "expirada" (expired).
-
Caso ocorra alguma situação no processo que impeça a antecipação de ser realizada, como por exemplo: Se algum de seus recebíveis tiver sido cancelado por motivo de estorno/chargeback ou mesmo se outra antecipação tiver sido realizada com recebíveis utilizados nesta simulação, esta vai para o status "inválida" (invalid).
Importante
Essa simulação não está disponível no ambiente de teste.
O split invalida uma antecipação solicitada anteriormente.
Antecipação sob demanda (suporte)
Para os parceiros que não fazem uso de API, disponibilizamos a solicitação da antecipação através do suporte.
Updated about 1 year ago