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

Pedidos de saque

A fila de saques que os sellers pedem: aprovar, recusar, acompanhar o processamento e concluir com o comprovante.

Um pedido de saque nasce quando o seller, no painel dele, pede para sacar parte do saldo confirmado (cada seller tem um único pedido ativo por vez). Daí em diante o financeiro conduz o pedido por aberto > aprovado > em processamento > pago, ou o recusa enquanto está aberto. As rotas abaixo são o lado do administrador.

Listar pedidos de saque

Lista os pedidos de saque, do mais recente ao mais antigo. É a fila de trabalho do financeiro: cada linha é um seller pedindo para receber parte do saldo confirmado.

GET/api/v1/admin/payout-requestsAdmin

Lista os pedidos de saque dos sellers

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo commissions ativo.

Parâmetros de consulta

vendor_iduuid
Filtra por seller. Precisa ser UUID completo; outro valor responde 500.
statusstring
pendingapprovedprocessingcompletedrejectedOAPCR
pending (ou open), approved, processing, completed (ou paid), rejected, ou a letra O, A, P, C, R.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.

Exemplo de requisição

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

Resposta

200Pedidos devolvidos
json
{
  "requests": [
    {
      "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "amount_cents": 10000,
      "status": "O",
      "bank_info": {
        "method": "pix",
        "pix_key": "financeiro@lojaotavio.example.com",
        "pix_type": "email",
        "holder_name": "Loja Otávio LTDA",
        "holder_doc": "12.345.678/0001-95"
      },
      "admin_notes": "",
      "transaction_ref": "",
      "requested_at": "2026-07-19T11:00:20.216784Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

requestsarray
Pedidos da página.
requests[].iduuid
Identificador do pedido de saque.
requests[].vendor_iduuid
Seller que pediu.
requests[].amount_centsinteger
Valor pedido, em centavos.
requests[].statusstring
OAPCR
Letra do estado: O aberto, A aprovado, P em processamento, C pago, R recusado.
requests[].bank_infoobject | null
Destino informado pelo seller: method (pix ou bank_transfer), pix_key, pix_type (cpf, cnpj, email, phone, random), bank_code, agency, account, holder_name, holder_doc. Os campos vazios são omitidos.
requests[].admin_notesstring
Observação do administrador (aprovação ou recusa).
requests[].transaction_refstring
Comprovante da transferência (código PIX, número do TED). Preenchido ao concluir.
requests[].requested_atstring
Quando o seller pediu, RFC 3339 em UTC.
requests[].approved_atstring
Quando foi aprovado. Só depois da aprovação.
requests[].paid_atstring
Quando foi concluído. Só depois de pago.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
500vendor_id que não é UUID ou falha na consulta{"error":"failed to list payout requests","detail":"..."}
O seller tem um pedido aberto por vez

Um seller só pode ter um pedido nos estados aberto, aprovado ou em processamento. Um segundo pedido do mesmo seller é recusado até o primeiro terminar (pago ou recusado).

Aprovar pedido

Passa o pedido de O (aberto) para A (aprovado) e registra a data. O corpo é opcional. Aprovar não paga nem reserva saldo novo: o valor já estava reservado desde que o seller pediu.

POST/api/v1/admin/payout-requests/{id}/approveAdmin

Aprova um pedido de saque

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo commissions ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do pedido de saque.

Corpo da requisição

admin_notesstring
Observação interna. Opcional.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/payout-requests/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_notes": "Conferido com o financeiro"
  }'

Resposta

200Pedido aprovado
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 10000,
  "status": "A",
  "bank_info": {
    "method": "pix",
    "pix_key": "financeiro@lojaotavio.example.com",
    "pix_type": "email",
    "holder_name": "Loja Otávio LTDA",
    "holder_doc": "12.345.678/0001-95"
  },
  "admin_notes": "Conferido com o financeiro",
  "transaction_ref": "",
  "requested_at": "2026-07-19T11:00:20.216784Z",
  "approved_at": "2026-07-19T18:40:20.833988Z"
}

Campos da resposta

iduuid
Identificador do pedido de saque.
vendor_iduuid
Seller que pediu.
amount_centsinteger
Valor pedido, em centavos.
statusstring
OAPCR
Letra do estado: O aberto, A aprovado, P em processamento, C pago, R recusado.
bank_infoobject | null
Destino informado pelo seller: method (pix ou bank_transfer), pix_key, pix_type (cpf, cnpj, email, phone, random), bank_code, agency, account, holder_name, holder_doc. Os campos vazios são omitidos.
admin_notesstring
Observação do administrador (aprovação ou recusa).
transaction_refstring
Comprovante da transferência (código PIX, número do TED). Preenchido ao concluir.
requested_atstring
Quando o seller pediu, RFC 3339 em UTC.
approved_atstring
Quando foi aprovado. Só depois da aprovação.
paid_atstring
Quando foi concluído. Só depois de pago.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Pedido inexistente, id que não é UUID, ou pedido que não está aberto{"error":"failed to approve payout request","detail":"payout request ... not found or not in pending status"}

Recusar pedido

Passa o pedido de O (aberto) para R (recusado). Só pedidos abertos podem ser recusados; um já aprovado precisa seguir até o fim. O saldo reservado volta a ficar disponível para o seller.

POST/api/v1/admin/payout-requests/{id}/rejectAdmin

Recusa um pedido de saque

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo commissions ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do pedido de saque.

Corpo da requisição

admin_notesstring
Motivo da recusa. Opcional, mas o seller só o vê se você preencher.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/payout-requests/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_notes": "Dados bancários divergentes do cadastro"
  }'

Resposta

200Pedido recusado
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 10000,
  "status": "R",
  "bank_info": {
    "method": "pix",
    "pix_key": "financeiro@lojaotavio.example.com",
    "pix_type": "email",
    "holder_name": "Loja Otávio LTDA",
    "holder_doc": "12.345.678/0001-95"
  },
  "admin_notes": "Dados bancários divergentes do cadastro",
  "transaction_ref": "",
  "requested_at": "2026-07-19T11:00:20.216784Z"
}

Campos da resposta

iduuid
Identificador do pedido de saque.
vendor_iduuid
Seller que pediu.
amount_centsinteger
Valor pedido, em centavos.
statusstring
OAPCR
Letra do estado: O aberto, A aprovado, P em processamento, C pago, R recusado.
bank_infoobject | null
Destino informado pelo seller: method (pix ou bank_transfer), pix_key, pix_type (cpf, cnpj, email, phone, random), bank_code, agency, account, holder_name, holder_doc. Os campos vazios são omitidos.
admin_notesstring
Observação do administrador (aprovação ou recusa).
transaction_refstring
Comprovante da transferência (código PIX, número do TED). Preenchido ao concluir.
requested_atstring
Quando o seller pediu, RFC 3339 em UTC.
approved_atstring
Quando foi aprovado. Só depois da aprovação.
paid_atstring
Quando foi concluído. Só depois de pago.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Pedido inexistente, id inválido ou pedido que não está aberto{"error":"failed to reject payout request","detail":"payout request ... not found or not in pending status"}

Marcar como em processamento

Passa de A (aprovado) para P (em processamento). Use quando a transferência foi enviada ao banco e ainda não confirmada. Não tem corpo.

POST/api/v1/admin/payout-requests/{id}/processAdmin

Marca um pedido aprovado como em processamento

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo commissions ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do pedido de saque.

Exemplo de requisição

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

Resposta

200Pedido em processamento
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 10000,
  "status": "P",
  "bank_info": {
    "method": "pix",
    "pix_key": "financeiro@lojaotavio.example.com",
    "pix_type": "email",
    "holder_name": "Loja Otávio LTDA",
    "holder_doc": "12.345.678/0001-95"
  },
  "admin_notes": "",
  "transaction_ref": "",
  "requested_at": "2026-07-19T11:00:20.216784Z",
  "approved_at": "2026-07-19T18:40:20.833988Z"
}

Campos da resposta

iduuid
Identificador do pedido de saque.
vendor_iduuid
Seller que pediu.
amount_centsinteger
Valor pedido, em centavos.
statusstring
OAPCR
Letra do estado: O aberto, A aprovado, P em processamento, C pago, R recusado.
bank_infoobject | null
Destino informado pelo seller: method (pix ou bank_transfer), pix_key, pix_type (cpf, cnpj, email, phone, random), bank_code, agency, account, holder_name, holder_doc. Os campos vazios são omitidos.
admin_notesstring
Observação do administrador (aprovação ou recusa).
transaction_refstring
Comprovante da transferência (código PIX, número do TED). Preenchido ao concluir.
requested_atstring
Quando o seller pediu, RFC 3339 em UTC.
approved_atstring
Quando foi aprovado. Só depois da aprovação.
paid_atstring
Quando foi concluído. Só depois de pago.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Pedido inexistente, id inválido ou fora do estado aprovado{"error":"failed to process payout request","detail":"payout request ... not found or not in approved status"}

Concluir pedido

Fecha o ciclo: passa de P (em processamento) para C (pago), grava o comprovante e liquida o saldo do seller. Tudo ocorre numa única transação: as entradas confirmadas mais antigas do seller são marcadas como liquidadas até cobrir o valor do pedido, e um registro imutável entra no histórico de repasses. Se faltar saldo confirmado, nada é gravado.

POST/api/v1/admin/payout-requests/{id}/completeAdmin

Conclui um pedido de saque em processamento

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo commissions ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do pedido de saque.

Corpo da requisição

transaction_refstringobrigatório
Comprovante da transferência (código PIX, número do TED). Obrigatório.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/payout-requests/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_ref": "E00038166202610111200abc123"
  }'

Resposta

200Pedido pago
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 10000,
  "status": "C",
  "bank_info": {
    "method": "pix",
    "pix_key": "financeiro@lojaotavio.example.com",
    "pix_type": "email",
    "holder_name": "Loja Otávio LTDA",
    "holder_doc": "12.345.678/0001-95"
  },
  "admin_notes": "",
  "transaction_ref": "E00038166202610111200abc123",
  "requested_at": "2026-07-19T11:00:20.216784Z",
  "approved_at": "2026-07-19T18:40:20.833988Z",
  "paid_at": "2026-07-19T21:11:24.855283Z"
}

Campos da resposta

iduuid
Identificador do pedido de saque.
vendor_iduuid
Seller que pediu.
amount_centsinteger
Valor pedido, em centavos.
statusstring
OAPCR
Letra do estado: O aberto, A aprovado, P em processamento, C pago, R recusado.
bank_infoobject | null
Destino informado pelo seller: method (pix ou bank_transfer), pix_key, pix_type (cpf, cnpj, email, phone, random), bank_code, agency, account, holder_name, holder_doc. Os campos vazios são omitidos.
admin_notesstring
Observação do administrador (aprovação ou recusa).
transaction_refstring
Comprovante da transferência (código PIX, número do TED). Preenchido ao concluir.
requested_atstring
Quando o seller pediu, RFC 3339 em UTC.
approved_atstring
Quando foi aprovado. Só depois da aprovação.
paid_atstring
Quando foi concluído. Só depois de pago.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400transaction_ref ausente, pedido inexistente ou fora de processamento, ou saldo confirmado insuficiente{"error":"transaction_ref is required"} / {"error":"failed to complete payout request","detail":"insufficient available commission entries to settle payout: have 8000, need 10000"}
Dívidas do seller são descontadas aqui

Se o seller tiver dívidas ativas, cada uma retém a sua deduction_rate do valor pedido, limitada ao saldo restante da dívida. O valor efetivamente transferido é o líquido, gravado no repasse do histórico (amount). As entradas do razão são liquidadas pelo valor cheio. Transfira o líquido, não o valor pedido.

Irreversível

Não há rota para desfazer a conclusão. Confirme a transferência no banco antes de chamar.

Veja também

  • Repasses
  • Dívidas de sellers
  • Razão de comissões
Anterior
Repasses e dívidas
Próxima
Repasses
Nesta página
  • Listar pedidos de saque
  • Exemplo de requisição
  • Resposta
  • Erros
  • Aprovar pedido
  • Exemplo de requisição
  • Resposta
  • Erros
  • Recusar pedido
  • Exemplo de requisição
  • Resposta
  • Erros
  • Marcar como em processamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Concluir pedido
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também