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

Contas a pagar

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

Listar contas a pagar

Uma conta a pagar é um valor que o seller deve, com vencimento. Esta lista ordena pelo vencimento mais próximo. Contas geradas ao lançar uma NF-e de entrada aparecem aqui.

GET/api/v1/vendor/erp/financeiro/payablesSeller

Lista as contas a pagar

Parâmetros de consulta

statusstring
openpartialoverduepaidcancelled
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.
supplierstring
Busca parcial, sem diferenciar maiúsculas, em supplier_id (a referência em texto).
supplier_ref_iduuid
Só títulos deste fornecedor 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 pagar

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

Resposta: Listar contas a pagar

200Títulos retornados
json
{
  "payables": [
    {
      "id": "5f585c3c-68a2-4f88-b76c-e2465ab041d4",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "supplier_id": "",
      "supplier_ref_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
      "supplier_name": "Distribuidora Aurora Ltda",
      "description": "Duplicata 001 NF 48765",
      "amount_cents": 52400,
      "paid_amount_cents": 0,
      "category": "Mercadoria",
      "cost_center": "Loja online",
      "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
      "attachment_url": "",
      "attachment_name": "",
      "due_date": "2026-11-06",
      "paid_at": null,
      "status": "open",
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

payablesarray

Títulos da página.

iduuid
Id do título.
vendor_iduuid
Seller dono.
supplier_idstring
Referência livre ao fornecedor (texto). Vazio se não informada. Nas contas geradas por NF-e traz o id do fornecedor.
supplier_ref_iduuid
Fornecedor cadastrado (Fornecedores). Vazio se não informado.
supplier_namestring
Nome resolvido a partir de supplier_ref_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.
paid_atdatetime
Quando foi quitado por inteiro. null enquanto houver saldo.
statusstring
openpaidcancelled
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 pagar

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list payables","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 pagar

POST/api/v1/vendor/erp/financeiro/payablesSeller

Cria uma conta a pagar

Corpo da requisição

supplier_idstring
Referência livre ao fornecedor (texto).
supplier_ref_iduuid
Fornecedor 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 pagar

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/financeiro/payables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_ref_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "description": "Duplicata 001 NF 48765",
  "amount_cents": 52400,
  "category": "Mercadoria",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "due_date": "2026-11-06"
}'

Resposta: Criar conta a pagar

201Título criado em aberto
json
{
  "id": "5f585c3c-68a2-4f88-b76c-e2465ab041d4",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "supplier_id": "",
  "supplier_ref_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "supplier_name": "Distribuidora Aurora Ltda",
  "description": "Duplicata 001 NF 48765",
  "amount_cents": 52400,
  "paid_amount_cents": 0,
  "category": "Mercadoria",
  "cost_center": "Loja online",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "attachment_url": "",
  "attachment_name": "",
  "due_date": "2026-11-06",
  "paid_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.
supplier_idstring
Referência livre ao fornecedor (texto). Vazio se não informada. Nas contas geradas por NF-e traz o id do fornecedor.
supplier_ref_iduuid
Fornecedor cadastrado (Fornecedores). Vazio se não informado.
supplier_namestring
Nome resolvido a partir de supplier_ref_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.
paid_atdatetime
Quando foi quitado por inteiro. null enquanto houver saldo.
statusstring
openpaidcancelled
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 pagar

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 (supplier_ref_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 pagar

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/payables/{id}Seller

Altera uma conta a pagar

Parâmetros de caminho

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

Corpo da requisição

supplier_idstring
Referência livre ao fornecedor (texto).
supplier_ref_iduuid
Fornecedor 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 pagar

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/financeiro/payables/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_ref_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "description": "Duplicata 001 NF 48765",
  "amount_cents": 52400,
  "category": "Mercadoria",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "due_date": "2026-11-06"
}'

Resposta: Alterar conta a pagar

200Título alterado
json
{
  "id": "5f585c3c-68a2-4f88-b76c-e2465ab041d4",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "supplier_id": "",
  "supplier_ref_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "supplier_name": "Distribuidora Aurora Ltda",
  "description": "Duplicata 001 NF 48765",
  "amount_cents": 52400,
  "paid_amount_cents": 0,
  "category": "Mercadoria",
  "cost_center": "Loja online",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "attachment_url": "",
  "attachment_name": "",
  "due_date": "2026-11-06",
  "paid_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.
supplier_idstring
Referência livre ao fornecedor (texto). Vazio se não informada. Nas contas geradas por NF-e traz o id do fornecedor.
supplier_ref_iduuid
Fornecedor cadastrado (Fornecedores). Vazio se não informado.
supplier_namestring
Nome resolvido a partir de supplier_ref_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.
paid_atdatetime
Quando foi quitado por inteiro. null enquanto houver saldo.
statusstring
openpaidcancelled
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 pagar

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 (supplier_ref_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 pagar não existe ou é de outro seller.{"error":"payable 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 pagar

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/payables/{id}Seller

Apaga uma conta a pagar

Parâmetros de caminho

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

Exemplo de requisição: Apagar conta a pagar

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

Resposta: Apagar conta a pagar

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

Campos da resposta

messagestring
receivable deleted ou payable deleted.

Erros: Apagar conta a pagar

StatusQuandoCorpo
404A conta a pagar não existe ou é de outro seller.{"error":"payable 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 pagar
  • Fluxo de caixa
Anterior
ERP financeiro do seller
Próxima
Baixa de contas a pagar
Nesta página
  • Listar contas a pagar
  • Exemplo de requisição: Listar contas a pagar
  • Resposta: Listar contas a pagar
  • Erros: Listar contas a pagar
  • Criar conta a pagar
  • Exemplo de requisição: Criar conta a pagar
  • Resposta: Criar conta a pagar
  • Erros: Criar conta a pagar
  • Alterar conta a pagar
  • Exemplo de requisição: Alterar conta a pagar
  • Resposta: Alterar conta a pagar
  • Erros: Alterar conta a pagar
  • Apagar conta a pagar
  • Exemplo de requisição: Apagar conta a pagar
  • Resposta: Apagar conta a pagar
  • Erros: Apagar conta a pagar
  • Veja também