VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Financeiro

Baixa de contas a receber

Baixa total ou parcial de uma conta a receber, reabertura e histórico de baixas.

Baixar conta a receber

Baixa é o registro de que o dinheiro entrou (ou saiu). Cada chamada grava uma baixa e soma o principal em paid_amount_cents. O título só vira received quando o principal é totalmente quitado; até lá continua open e paid_amount_cents mostra o progresso.

POST/api/v1/vendor/erp/financeiro/receivables/{id}/settleSeller

Baixa uma conta a receber (total ou parcial)

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da conta a receber.

Corpo da requisição

amount_centsinteger
Principal a baixar, em centavos. 0 ou omitido baixa todo o saldo devedor.
interest_centsinteger
Juros pagos, em centavos, zero ou mais. Não reduzem o saldo do título.
penalty_centsinteger
Multa paga, em centavos, zero ou mais. Não reduz o saldo do título.
bank_account_iduuid
Conta bancária da baixa. Omitido, usa a conta padrão do título.
notesstring
Observação da baixa.
settled_atstring
Data da baixa YYYY-MM-DD. Padrão: hoje.

Exemplo de requisição: Baixar conta a receber

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/financeiro/receivables/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/settle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 10000,
  "interest_cents": 150,
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "settled_at": "2026-11-06",
  "notes": "Pago via PIX"
}'

Resposta: Baixar conta a receber

200Baixa registrada, título em aberto
json
{
  "id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "customer_ref": "Mercadinho Pinheiros",
  "customer_user_id": "",
  "customer_name": "",
  "description": "Venda a prazo 1043",
  "amount_cents": 20000,
  "paid_amount_cents": 10000,
  "category": "Vendas",
  "cost_center": "",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "attachment_url": "",
  "attachment_name": "",
  "due_date": "2026-11-15",
  "received_at": null,
  "status": "open",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}
200Baixa final, título quitado
json
{
  "id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "customer_ref": "Mercadinho Pinheiros",
  "customer_user_id": "",
  "customer_name": "",
  "description": "Venda a prazo 1043",
  "amount_cents": 20000,
  "paid_amount_cents": 20000,
  "category": "Vendas",
  "cost_center": "",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "attachment_url": "",
  "attachment_name": "",
  "due_date": "2026-11-15",
  "received_at": "2026-11-06T00:00:00Z",
  "status": "received",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id do título.
vendor_iduuid
Seller dono.
customer_refstring
Referência livre ao cliente (nome, apelido). Vazio se não informada.
customer_user_iduuid
Cliente cadastrado, quando houver. Vazio se não informado.
customer_namestring
Nome do cliente resolvido a partir de customer_user_id. Vazio se não há.
descriptionstring
Descrição do título.
amount_centsinteger
Valor total em centavos.
paid_amount_centsinteger
Quanto já foi baixado (soma das baixas, só o principal), em centavos.
categorystring
Categoria livre. Vazio se não informada.
cost_centerstring
Centro de custo livre. Vazio se não informado.
bank_account_iduuid
Conta bancária padrão do título. Vazio se não informada.
attachment_urlstring
URL do comprovante. Vazio se não informada.
attachment_namestring
Nome do comprovante.
due_datestring
Vencimento YYYY-MM-DD.
received_atdatetime
Quando foi quitado por inteiro. null enquanto houver saldo.
statusstring
openreceivedcancelled
Estado gravado. partial e overdue não existem aqui: um título parcial ou vencido continua open.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Baixar conta a receber

StatusQuandoCorpo
400Juros ou multa negativos.{"error":"vendorerp: juros/multa devem ser >= 0"}
400settled_at em outro formato.{"error":"vendorerp: settled_at must be YYYY-MM-DD"}
400O título está cancelled.{"error":"vendorerp: título cancelado não pode ser baixado"}
400Não há saldo a baixar.{"error":"vendorerp: título já quitado"}
400amount_cents maior que o saldo.{"error":"vendorerp: valor da baixa acima do saldo devedor"}
404O título não existe ou é de outro seller.{"error":"entry not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Corpo vazio baixa tudo

Um POST sem corpo (ou com corpo ilegível) baixa o saldo restante inteiro, com a data de hoje.

Juros e multa são só registro

Eles ficam na baixa, mas não entram em paid_amount_cents nem nos saldos bancários, que somam apenas o principal.

Reabrir título

Desfaz a baixa: estorna todas as baixas do título (exclusão lógica), zera paid_amount_cents e volta o estado para open. Funciona em qualquer estado, inclusive cancelled. Não há reabertura parcial.

POST/api/v1/vendor/erp/financeiro/receivables/{id}/reopenSeller

Reabre uma conta a receber

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da conta a receber.

Exemplo de requisição: Reabrir título

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/financeiro/receivables/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/reopen" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Reabrir título

200Título reaberto
json
{
  "id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "customer_ref": "Mercadinho Pinheiros",
  "customer_user_id": "",
  "customer_name": "",
  "description": "Venda a prazo 1043",
  "amount_cents": 20000,
  "paid_amount_cents": 0,
  "category": "Vendas",
  "cost_center": "",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "attachment_url": "",
  "attachment_name": "",
  "due_date": "2026-11-15",
  "received_at": null,
  "status": "open",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id do título.
vendor_iduuid
Seller dono.
customer_refstring
Referência livre ao cliente (nome, apelido). Vazio se não informada.
customer_user_iduuid
Cliente cadastrado, quando houver. Vazio se não informado.
customer_namestring
Nome do cliente resolvido a partir de customer_user_id. Vazio se não há.
descriptionstring
Descrição do título.
amount_centsinteger
Valor total em centavos.
paid_amount_centsinteger
Quanto já foi baixado (soma das baixas, só o principal), em centavos.
categorystring
Categoria livre. Vazio se não informada.
cost_centerstring
Centro de custo livre. Vazio se não informado.
bank_account_iduuid
Conta bancária padrão do título. Vazio se não informada.
attachment_urlstring
URL do comprovante. Vazio se não informada.
attachment_namestring
Nome do comprovante.
due_datestring
Vencimento YYYY-MM-DD.
received_atdatetime
Quando foi quitado por inteiro. null enquanto houver saldo.
statusstring
openreceivedcancelled
Estado gravado. partial e overdue não existem aqui: um título parcial ou vencido continua open.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Reabrir título

StatusQuandoCorpo
404O título não existe ou é de outro seller.{"error":"entry not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Não desfaz a conciliação bancária

Se o título foi quitado por uma conciliação, a transação do extrato continua matched. Desfaça por lá (unmatch) em vez de reabrir aqui.

Listar baixas

Mostra o histórico de baixas do título, da mais antiga para a mais nova. Um id inexistente devolve lista vazia (200), não 404.

GET/api/v1/vendor/erp/financeiro/receivables/{id}/settlementsSeller

Lista as baixas de um título

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da conta a receber.

Exemplo de requisição: Listar baixas

bash
curl "$BASE_URL/api/v1/vendor/erp/financeiro/receivables/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/settlements" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar baixas

200Baixas
json
{
  "settlements": [
    {
      "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
      "entry_kind": "R",
      "entry_id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
      "amount_cents": 20000,
      "interest_cents": 150,
      "penalty_cents": 0,
      "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
      "notes": "Pago via PIX",
      "settled_at": "2026-11-06T00:00:00Z",
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

settlementsarray

Baixas do título.

iduuid
Id da baixa.
entry_kindstring
PR
P conta a pagar, R conta a receber.
entry_iduuid
Título baixado.
amount_centsinteger
Principal baixado.
interest_centsinteger
Juros.
penalty_centsinteger
Multa.
bank_account_iduuid
Conta bancária. Vazio se nenhuma.
notesstring
Observação.
settled_atdatetime
Data da baixa.
created_atdatetime
Quando foi registrada.
totalinteger
Quantidade devolvida.

Erros: Listar baixas

StatusQuandoCorpo
400O id não é um UUID válido.{"error":"o valor \"zzz\" não é um uuid válido. ..."}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Veja também

  • Contas a receber
  • Contas bancárias
Anterior
Contas a receber
Próxima
Contas bancárias
Nesta página
  • Baixar conta a receber
  • Exemplo de requisição: Baixar conta a receber
  • Resposta: Baixar conta a receber
  • Erros: Baixar conta a receber
  • Reabrir título
  • Exemplo de requisição: Reabrir título
  • Resposta: Reabrir título
  • Erros: Reabrir título
  • Listar baixas
  • Exemplo de requisição: Listar baixas
  • Resposta: Listar baixas
  • Erros: Listar baixas
  • Veja também