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_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_ascending), 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_ascending

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.

Chave

Valores

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

Chave

Valores

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 26 days ago


Antecipação sob demanda


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.