API atual/Referência completa/Financeiro do seller

Antecipação (Antecipa Venddor)

Simula, pede, lista e cancela a antecipação de saldo a receber do seller.

A antecipação deixa o seller receber agora parte do dinheiro que só liberaria nos próximos repasses, pagando uma taxa. Funciona como um adiantamento: a loja paga o líquido e depois desconta o valor cheio dos repasses futuros por meio de uma dívida. A função precisa estar ligada pela loja; senão a simulação responde not_enabled.

Simular antecipação

Diz se o seller pode antecipar parte do saldo a receber ("Antecipa Venddor"), quanto no máximo e, se você enviar amount_cents, quanto custa. Nunca responde erro por falta de configuração: devolve eligible: false com um reason_code.

GET/api/v1/vendor/advances/quoteSeller

Elegibilidade e simulação da antecipação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

amount_centsinteger

Valor que quer antecipar, em centavos. Se passar do máximo, é reduzido ao máximo. Texto que não é número vira 0 (sem simulação).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/advances/quote?amount_cents=100000" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Elegível

json

{
  "eligible": true,
  "max_cents": 200000,
  "fee_bps": 300,
  "estimated_days": 10,
  "quote": {
    "RequestedCents": 100000,
    "FeeCents": 1000,
    "NetCents": 99000,
    "FeeBps": 300,
    "EstimatedDays": 10
  },
  "expires_at": "2026-10-11T22:15:00Z"
}

200Não elegível

json

{
  "eligible": false,
  "reason_code": "overdue_debt",
  "max_cents": 0,
  "fee_bps": 300,
  "estimated_days": 0
}

Campos da resposta

eligibleboolean

Se pode pedir agora.

reason_codestring

not_enabledadvance_in_progressexposure_capmin_days_activemin_delivered_ordersreputation_redoverdue_debtinsufficient_balanceunavailable

Por que não pode. Omitido quando elegível.

max_centsinteger

Máximo antecipável, em centavos: um percentual (80% por padrão) do saldo disponível mais retido, limitado a um teto da loja.

fee_bpsinteger

Taxa por 30 dias, em pontos-base.

estimated_daysinteger

Dias estimados de liquidação (mínimo 7, média dos últimos ciclos de repasse).

quoteobject

Só com amount_cents válido. As chaves saem em PascalCase, como estão: RequestedCents, FeeCents, NetCents, FeeBps, EstimatedDays. Taxa = valor x bps x dias / (10000 x 30), arredondada para cima.

expires_atstring

Até quando esta simulação vale (15 minutos), RFC 3339. Só junto com quote.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Listar antecipações

Devolve as antecipações do seller, da mais recente para a mais antiga, sem paginação.

GET/api/v1/vendor/advancesSeller

Histórico de antecipações do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/advances" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipações

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-10-11T00:52:54Z"
    }
  ]
}

Campos da resposta

itemsobject[]

Antecipações.

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Pedir antecipação

Pede a antecipação de um valor. A plataforma repete a simulação; se o seller não for elegível, nada é criado. Um valor acima do máximo é reduzido ao máximo sem aviso, então confira requested_cents na resposta. Só uma antecipação ativa por seller. O pedido nasce pending; a loja aprova (o que cria uma dívida), paga e a dívida é descontada dos repasses seguintes.

POST/api/v1/vendor/advancesSeller

Pedir uma antecipação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

requested_centsintegerobrigatório

Valor a antecipar, em centavos. Envie positivo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/advances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requested_cents": 100000
}'

Resposta

201Antecipação criada

json

{
  "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-10-11T00:52:54Z"
}

Campos da resposta

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
400	JSON inválido, seller não elegível (`not eligible: <reason_code>`) ou já há antecipação ativa.	`{"error":"failed to request advance","detail":"not eligible: insufficient_balance"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Cancelar antecipação

Cancela uma antecipação que ainda não foi paga (pending ou approved). Se a loja já tinha criado a dívida, ela é cancelada junto. Depois de disbursed não há mais cancelamento.

POST/api/v1/vendor/advances/{id}/cancelSeller

Cancelar antes do desembolso

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da antecipação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/advances/810384e7-ec30-4141-a993-238da66a7fac/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipação cancelada

json

{
  "id": "810384e7-ec30-4141-a993-238da66a7fac",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "canceled",
  "requested_cents": 100000,
  "fee_cents": 2900,
  "net_cents": 97100,
  "fee_bps": 300,
  "estimated_days": 29,
  "created_at": "2026-10-11T00:52:54Z"
}

Campos da resposta

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
400	Antecipação inexistente, de outro seller ou já desembolsada, em liquidação ou liquidada.	`{"error":"failed to cancel advance","detail":"advance already disbursed; cannot cancel"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Veja também

API atual/Referência completa/Financeiro do seller

Antecipação (Antecipa Venddor)

Simula, pede, lista e cancela a antecipação de saldo a receber do seller.

Simular antecipação

GET/api/v1/vendor/advances/quoteSeller

Elegibilidade e simulação da antecipação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

amount_centsinteger

Valor que quer antecipar, em centavos. Se passar do máximo, é reduzido ao máximo. Texto que não é número vira 0 (sem simulação).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/advances/quote?amount_cents=100000" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Elegível

json

{
  "eligible": true,
  "max_cents": 200000,
  "fee_bps": 300,
  "estimated_days": 10,
  "quote": {
    "RequestedCents": 100000,
    "FeeCents": 1000,
    "NetCents": 99000,
    "FeeBps": 300,
    "EstimatedDays": 10
  },
  "expires_at": "2026-10-11T22:15:00Z"
}

200Não elegível

json

{
  "eligible": false,
  "reason_code": "overdue_debt",
  "max_cents": 0,
  "fee_bps": 300,
  "estimated_days": 0
}

Campos da resposta

eligibleboolean

Se pode pedir agora.

reason_codestring

not_enabledadvance_in_progressexposure_capmin_days_activemin_delivered_ordersreputation_redoverdue_debtinsufficient_balanceunavailable

Por que não pode. Omitido quando elegível.

max_centsinteger

Máximo antecipável, em centavos: um percentual (80% por padrão) do saldo disponível mais retido, limitado a um teto da loja.

fee_bpsinteger

Taxa por 30 dias, em pontos-base.

estimated_daysinteger

Dias estimados de liquidação (mínimo 7, média dos últimos ciclos de repasse).

quoteobject

expires_atstring

Até quando esta simulação vale (15 minutos), RFC 3339. Só junto com quote.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Listar antecipações

Devolve as antecipações do seller, da mais recente para a mais antiga, sem paginação.

GET/api/v1/vendor/advancesSeller

Histórico de antecipações do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/advances" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipações

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-10-11T00:52:54Z"
    }
  ]
}

Campos da resposta

itemsobject[]

Antecipações.

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Pedir antecipação

POST/api/v1/vendor/advancesSeller

Pedir uma antecipação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

requested_centsintegerobrigatório

Valor a antecipar, em centavos. Envie positivo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/advances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requested_cents": 100000
}'

Resposta

201Antecipação criada

json

{
  "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-10-11T00:52:54Z"
}

Campos da resposta

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
400	JSON inválido, seller não elegível (`not eligible: <reason_code>`) ou já há antecipação ativa.	`{"error":"failed to request advance","detail":"not eligible: insufficient_balance"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`

Cancelar antecipação

Cancela uma antecipação que ainda não foi paga (pending ou approved). Se a loja já tinha criado a dívida, ela é cancelada junto. Depois de disbursed não há mais cancelamento.

POST/api/v1/vendor/advances/{id}/cancelSeller

Cancelar antes do desembolso

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da antecipação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/advances/810384e7-ec30-4141-a993-238da66a7fac/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Antecipação cancelada

json

{
  "id": "810384e7-ec30-4141-a993-238da66a7fac",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "canceled",
  "requested_cents": 100000,
  "fee_cents": 2900,
  "net_cents": 97100,
  "fee_bps": 300,
  "estimated_days": 29,
  "created_at": "2026-10-11T00:52:54Z"
}

Campos da resposta

iduuid

Id da antecipação.

vendor_iduuid

Seller.

statusstring

pendingapprovedrejecteddisbursedsettlingsettledcanceled

Situação da antecipação.

requested_centsinteger

Valor antecipado, em centavos.

fee_centsinteger

Taxa cobrada, em centavos.

net_centsinteger

O que o seller recebe: valor menos taxa.

fee_bpsinteger

Taxa em pontos-base por 30 dias (300 = 3%).

estimated_daysinteger

Dias estimados até o saldo liquidar; entra no cálculo da taxa.

debt_iduuid

Dívida criada na aprovação, que será descontada dos próximos repasses. Omitido antes.

created_atstring

Pedido em, RFC 3339 em UTC.

disbursed_atstring

Quando a loja pagou o líquido. Omitido antes.

settled_atstring

Quando a dívida foi toda descontada. Omitido antes.

Erros

Status	Quando	Corpo de exemplo
400	Antecipação inexistente, de outro seller ou já desembolsada, em liquidação ou liquidada.	`{"error":"failed to cancel advance","detail":"advance already disbursed; cannot cancel"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em `privilege_required_any`; o exemplo está cortado). O dono da loja passa sempre.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}`