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

Contas a receber

Lista, cria, altera e apaga as contas a receber do seller.

Listar contas a receber

Uma conta a receber é um valor que um cliente deve ao seller, com vencimento. Esta lista ordena pelo vencimento mais próximo.

GET/api/v1/vendor/erp/financeiro/receivablesSeller

Lista as contas a receber

Parâmetros de consulta

statusstring
openpartialoverduereceivedcancelled
Estado, incluindo os derivados: open é só o que está a vencer e sem baixa parcial; partial é o que já teve baixa e ainda deve; overdue é o vencido e ainda aberto (inclui parciais). Os outros valores filtram o estado gravado.
fromstring
Vencimento a partir de YYYY-MM-DD, inclusivo.
tostring
Vencimento até YYYY-MM-DD, inclusivo.
categorystring
Categoria exata.
customerstring
Busca parcial, sem diferenciar maiúsculas, em customer_ref.
customer_user_iduuid
Só títulos deste cliente cadastrado.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 100. Acima disso vale 100.

Exemplo de requisição: Listar contas a receber

bash
curl "$BASE_URL/api/v1/vendor/erp/financeiro/receivables?status=overdue&from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar contas a receber

200Títulos retornados
json
{
  "receivables": [
    {
      "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"
    }
  ],
  "total": 1
}

Campos da resposta

receivablesarray

Títulos da página.

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.
totalinteger
Total que atende ao filtro.

Erros: Listar contas a receber

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list receivables","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
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"}

Criar conta a receber

POST/api/v1/vendor/erp/financeiro/receivablesSeller

Cria uma conta a receber

Corpo da requisição

customer_refstring
Referência livre ao cliente.
customer_user_iduuid
Cliente cadastrado.
descriptionstringobrigatório
Descrição. Obrigatória.
amount_centsintegerobrigatório
Valor em centavos, zero ou mais.
due_datestringobrigatório
Vencimento YYYY-MM-DD. Obrigatório.
categorystring
Categoria livre.
cost_centerstring
Centro de custo livre.
bank_account_iduuid
Conta bancária padrão.
attachment_urlstring
URL do comprovante.
attachment_namestring
Nome do comprovante.

Exemplo de requisição: Criar conta a receber

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/financeiro/receivables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_ref": "Mercadinho Pinheiros",
  "description": "Venda a prazo 1043",
  "amount_cents": 20000,
  "category": "Vendas",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "due_date": "2026-11-15"
}'

Resposta: Criar conta a receber

201Título criado 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": 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: Criar conta a receber

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400description em branco.{"error":"vendorerp: description required"}
400amount_cents negativo.{"error":"vendorerp: amount_cents must be >= 0"}
400due_date em branco.{"error":"vendorerp: due_date required"}
400due_date em outro formato.{"error":"vendorerp: due_date must be YYYY-MM-DD"}
400Um campo de id (customer_user_id ou bank_account_id) não é um UUID válido; a mensagem em português diz qual valor.{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
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"}
Valor zero é aceito

amount_cents pode ser 0. Um título de valor zero nasce open e não pode ser baixado (já está quitado: título já quitado).

Alterar conta a receber

Substitui todos os campos editáveis do título. Campos de texto omitidos são apagados. Estado, valor já baixado e baixas não mudam por aqui.

PUT/api/v1/vendor/erp/financeiro/receivables/{id}Seller

Altera uma conta a receber

Parâmetros de caminho

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

Corpo da requisição

customer_refstring
Referência livre ao cliente.
customer_user_iduuid
Cliente cadastrado.
descriptionstringobrigatório
Descrição. Obrigatória.
amount_centsintegerobrigatório
Valor em centavos, zero ou mais.
due_datestringobrigatório
Vencimento YYYY-MM-DD. Obrigatório.
categorystring
Categoria livre.
cost_centerstring
Centro de custo livre.
bank_account_iduuid
Conta bancária padrão.
attachment_urlstring
URL do comprovante.
attachment_namestring
Nome do comprovante.

Exemplo de requisição: Alterar conta a receber

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/financeiro/receivables/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_ref": "Mercadinho Pinheiros",
  "description": "Venda a prazo 1043",
  "amount_cents": 20000,
  "category": "Vendas",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "due_date": "2026-11-15"
}'

Resposta: Alterar conta a receber

200Título alterado
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: Alterar conta a receber

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400description em branco.{"error":"vendorerp: description required"}
400amount_cents negativo.{"error":"vendorerp: amount_cents must be >= 0"}
400due_date em branco.{"error":"vendorerp: due_date required"}
400due_date em outro formato.{"error":"vendorerp: due_date must be YYYY-MM-DD"}
400Um campo de id (customer_user_id ou bank_account_id) não é um UUID válido; a mensagem em português diz qual valor.{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
404A conta a receber não existe ou é de outro seller.{"error":"receivable 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"}
Nada impede reduzir o valor abaixo do que já foi baixado

A rota não compara amount_cents com paid_amount_cents. Reduzir o valor de um título parcialmente baixado deixa o título inconsistente. Reabra o título antes de mudar valores.

Apagar conta a receber

Exclusão lógica do título, em qualquer estado. As baixas já feitas não são apagadas e continuam contando nos saldos bancários e no fluxo de caixa diário.

DELETE/api/v1/vendor/erp/financeiro/receivables/{id}Seller

Apaga uma conta a receber

Parâmetros de caminho

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

Exemplo de requisição: Apagar conta a receber

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

Resposta: Apagar conta a receber

200Título apagado
json
{
  "message": "receivable deleted"
}

Campos da resposta

messagestring
receivable deleted ou payable deleted.

Erros: Apagar conta a receber

StatusQuandoCorpo
404A conta a receber não existe ou é de outro seller.{"error":"receivable 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"}
Prefira reabrir a apagar

Apagar um título quitado deixa as baixas dele soltas. Para desfazer um pagamento errado use reabrir, que estorna as baixas.

Veja também

  • Baixa de contas a receber
  • Régua de cobrança
Anterior
Baixa de contas a pagar
Próxima
Baixa de contas a receber
Nesta página
  • Listar contas a receber
  • Exemplo de requisição: Listar contas a receber
  • Resposta: Listar contas a receber
  • Erros: Listar contas a receber
  • Criar conta a receber
  • Exemplo de requisição: Criar conta a receber
  • Resposta: Criar conta a receber
  • Erros: Criar conta a receber
  • Alterar conta a receber
  • Exemplo de requisição: Alterar conta a receber
  • Resposta: Alterar conta a receber
  • Erros: Alterar conta a receber
  • Apagar conta a receber
  • Exemplo de requisição: Apagar conta a receber
  • Resposta: Apagar conta a receber
  • Erros: Apagar conta a receber
  • Veja também