VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Repasses e dívidas

Antecipações

Antecipação de recebíveis do seller: aprovar o pedido, registrar o envio e definir a política da loja.

A antecipação ("Antecipa Venddor") deixa o seller receber agora parte do saldo que só liberaria no ciclo normal, pagando uma taxa. O seller pede pelo painel dele e a plataforma calcula a taxa e confere se ele é elegível. O administrador então aprova (o que lança uma dívida igual ao valor pedido), registra o envio do dinheiro e a dívida vai sendo abatida dos saques seguintes até quitar.

pending > approved > disbursed > settling > settled. Um pedido pode ser canceled pelo seller antes do envio.

Listar antecipações

Lista as antecipações de todos os sellers, da mais recente para a mais antiga, até 500. Não há paginação.

GET/api/v1/admin/vendor-advancesAdmin

Lista as antecipações dos sellers

Autenticação: Authorization: Bearer <token> de um administrador. Não depende de módulo; a antecipação precisa estar habilitada pela rota de configuração (abaixo) para o seller conseguir pedir.

Parâmetros de consulta

statusstring
pendingapproveddisbursedsettlingsettledcanceled
Filtra pelo estado, na palavra exata.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-advances?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipações devolvidas
json
{
  "items": [
    {
      "id": "810384e7-ec30-4141-a993-238da66a7fac",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "pending",
      "requested_cents": 100000,
      "fee_cents": 2900,
      "net_cents": 97100,
      "fee_bps": 300,
      "estimated_days": 29,
      "created_at": "2026-07-19T00:52:54.145008Z"
    }
  ]
}

Campos da resposta

itemsarray
Antecipações.
items[].iduuid
Identificador da antecipação.
items[].vendor_iduuid
Seller que pediu.
items[].statusstring
pendingapproveddisbursedsettlingsettledcanceled
pending (pedida), approved (aprovada, dívida lançada), disbursed (dinheiro enviado), settling (dívida parcialmente abatida), settled (dívida quitada), canceled.
items[].requested_centsinteger
Valor antecipado, em centavos. É também o valor da dívida.
items[].fee_centsinteger
Taxa cobrada, em centavos.
items[].net_centsinteger
Valor líquido enviado ao seller: requested_cents - fee_cents.
items[].fee_bpsinteger
Taxa por 30 dias, em pontos-base, vigente no pedido.
items[].estimated_daysinteger
Prazo estimado até a liquidação, em dias, usado no cálculo da taxa.
items[].debt_iduuid
Dívida criada na aprovação. Omitido antes disso.
items[].created_atstring
Quando foi pedida.
items[].disbursed_atstring
Quando o envio foi registrado. Omitido antes.
items[].settled_atstring
Quando a dívida quitou. Omitido antes.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
500Falha na consulta{"error":"failed to list advances","detail":"..."}

Aprovar antecipação

Passa de pending para approved e lança uma dívida do seller no valor pedido (requested_cents), com motivo advance. Essa dívida será abatida dos saques seguintes. Publica o evento vendor.advance.approved.

POST/api/v1/admin/vendor-advances/{id}/approveAdmin

Aprova uma antecipação pedida

Autenticação: Authorization: Bearer <token> de um administrador. Não depende de módulo; a antecipação precisa estar habilitada pela rota de configuração (abaixo) para o seller conseguir pedir.

Parâmetros de caminho

iduuidobrigatório
Identificador da antecipação.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-advances/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipação aprovada
json
{
  "id": "810384e7-ec30-4141-a993-238da66a7fac",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "approved",
  "requested_cents": 100000,
  "fee_cents": 2900,
  "net_cents": 97100,
  "fee_bps": 300,
  "estimated_days": 29,
  "created_at": "2026-07-19T00:52:54.145008Z",
  "debt_id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d"
}

Campos da resposta

iduuid
Identificador da antecipação.
vendor_iduuid
Seller que pediu.
statusstring
pendingapproveddisbursedsettlingsettledcanceled
pending (pedida), approved (aprovada, dívida lançada), disbursed (dinheiro enviado), settling (dívida parcialmente abatida), settled (dívida quitada), canceled.
requested_centsinteger
Valor antecipado, em centavos. É também o valor da dívida.
fee_centsinteger
Taxa cobrada, em centavos.
net_centsinteger
Valor líquido enviado ao seller: requested_cents - fee_cents.
fee_bpsinteger
Taxa por 30 dias, em pontos-base, vigente no pedido.
estimated_daysinteger
Prazo estimado até a liquidação, em dias, usado no cálculo da taxa.
debt_iduuid
Dívida criada na aprovação. Omitido antes disso.
created_atstring
Quando foi pedida.
disbursed_atstring
Quando o envio foi registrado. Omitido antes.
settled_atstring
Quando a dívida quitou. Omitido antes.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
400Antecipação inexistente, id inválido ou fora de pending{"error":"failed to approve advance","detail":"advance is not pending"} / {"error":"failed to approve advance","detail":"sql: no rows in result set"}
A dívida é do valor bruto

O seller recebe o líquido (net_cents), mas a dívida lançada é o valor cheio pedido. A diferença é a taxa. O abatimento segue as regras de dívidas.

Registrar o envio

Passa de approved para disbursed e grava a data. Use depois de transferir o valor líquido ao seller. A plataforma não envia o dinheiro: só registra.

POST/api/v1/admin/vendor-advances/{id}/disburseAdmin

Registra que o valor da antecipação foi enviado

Autenticação: Authorization: Bearer <token> de um administrador. Não depende de módulo; a antecipação precisa estar habilitada pela rota de configuração (abaixo) para o seller conseguir pedir.

Parâmetros de caminho

iduuidobrigatório
Identificador da antecipação.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-advances/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/disburse" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Envio registrado
json
{
  "id": "810384e7-ec30-4141-a993-238da66a7fac",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "disbursed",
  "requested_cents": 100000,
  "fee_cents": 2900,
  "net_cents": 97100,
  "fee_bps": 300,
  "estimated_days": 29,
  "created_at": "2026-07-19T00:52:54.145008Z",
  "debt_id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
  "disbursed_at": "2026-07-20T10:00:00Z"
}

Campos da resposta

iduuid
Identificador da antecipação.
vendor_iduuid
Seller que pediu.
statusstring
pendingapproveddisbursedsettlingsettledcanceled
pending (pedida), approved (aprovada, dívida lançada), disbursed (dinheiro enviado), settling (dívida parcialmente abatida), settled (dívida quitada), canceled.
requested_centsinteger
Valor antecipado, em centavos. É também o valor da dívida.
fee_centsinteger
Taxa cobrada, em centavos.
net_centsinteger
Valor líquido enviado ao seller: requested_cents - fee_cents.
fee_bpsinteger
Taxa por 30 dias, em pontos-base, vigente no pedido.
estimated_daysinteger
Prazo estimado até a liquidação, em dias, usado no cálculo da taxa.
debt_iduuid
Dívida criada na aprovação. Omitido antes disso.
created_atstring
Quando foi pedida.
disbursed_atstring
Quando o envio foi registrado. Omitido antes.
settled_atstring
Quando a dívida quitou. Omitido antes.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
400Antecipação inexistente ou fora de approved{"error":"failed to disburse advance","detail":"advance not in approved state"}

Configurar

Grava a política de antecipação da loja: se está ligada, a taxa, o teto por pedido e os critérios para o seller ser elegível. O corpo substitui a política inteira.

PUT/api/v1/admin/vendor-advances/settingsAdmin

Define a política de antecipação da loja

Autenticação: Authorization: Bearer <token> de um administrador. Não depende de módulo; a antecipação precisa estar habilitada pela rota de configuração (abaixo) para o seller conseguir pedir.

Corpo da requisição

enabledbooleanpadrão: false
Liga a antecipação. Omitido vale false: a antecipação é desligada.
fee_bpsintegerpadrão: 250
Taxa por 30 dias, em pontos-base (250 = 2,5%). Zero ou negativo volta para 250.
max_pctintegerpadrão: 80
Percentual máximo do saldo (disponível + em retenção) que pode ser antecipado, de 1 a 100. Zero volta para 80.
max_cents_capintegerpadrão: 0
Teto absoluto por antecipação, em centavos. 0 = sem teto.
exposure_cap_centsintegerpadrão: 0
Teto da soma das antecipações em aberto na loja inteira, em centavos. 0 = sem teto.
min_days_activeinteger
Dias mínimos de cadastro do seller. Omitido vale 0 (sem mínimo). O padrão de uma loja nunca configurada é 90.
min_delivered_ordersinteger
Pedidos entregues mínimos do seller. Omitido vale 0 (sem mínimo). O padrão de uma loja nunca configurada é 20.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/vendor-advances/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "fee_bps": 250,
    "max_pct": 80,
    "max_cents_cap": 500000,
    "exposure_cap_cents": 5000000,
    "min_days_active": 90,
    "min_delivered_orders": 20
  }'

Resposta

200Política gravada
json
{
  "enabled": true,
  "fee_bps": 250,
  "max_pct": 80,
  "max_cents_cap": 500000,
  "exposure_cap_cents": 5000000,
  "min_days_active": 90,
  "min_delivered_orders": 20
}

A resposta ecoa o corpo recebido, com todos os campos. Não existe uma rota de leitura da política: guarde o que você enviou.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
400Corpo que não é JSON válido{"error":"invalid request body","detail":"..."}
500Falha ao gravar{"error":"failed to save settings","detail":"..."}
Envie sempre todos os campos

Como o corpo substitui a política, um PUT com só fee_bps desliga a antecipação (enabled vira false) e zera os critérios mínimos. Envie o objeto completo.

Como a taxa é calculada

taxa = arredonda_para_cima(valor * fee_bps * dias / (10000 * 30)), onde dias é a média dos últimos ciclos de repasse da loja, com mínimo de 7. Com fee_bps 300, 29 dias e R$ 1.000,00, a taxa é R$ 29,00.

Veja também

  • Dívidas de sellers
  • Pedidos de saque
Anterior
Dívidas de sellers
Próxima
Pagamentos
Nesta página
  • Listar antecipações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Aprovar antecipação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Registrar o envio
  • Exemplo de requisição
  • Resposta
  • Erros
  • Configurar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também