Documentação
Guias de ImplementaçãoReferência da APIAPI StatusAjuda

Antecipação sob demanda

Suggest Edits

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.

ChaveValores
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_date
string		($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_date
string		($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_date
string		($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_date
string		($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.
receivables
string		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.
transactions
string		Lista de IDs de transações cujos recebíveis deverão ser incluídos na solicitação de antecipação

example: 4290f3c2d2787e8c28d4c96c451d9aee]
target_amount
integer		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.
margin
number		($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.
order
string		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_fee
number		($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_commit
boolean		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_invalid
boolean		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.

ChaveValores
percent_amount
number		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_customer
string		example: 8a70ac5fba13472a8b23171c62e244b4

Seller para qual a taxa da antecipação será aplicada

Verificando Recebíveis Aptos a Antecipação

ChaveValores
prepayable_for
string		($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_commit for passado com valor true), 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.

Para solicitar essa liberação, clique aqui

Updated 10 months ago