API: lançar pagamento e recebimento — obrigatórios, rateio e o que não muda depois

Atualizado em 22/10/2026

O QUE ESTA FONTE RESPONDE

Você liga o seu sistema ao ERP pelo aplicativo API e precisa lançar, consultar, alterar ou apagar uma conta a pagar ou a receber. Aqui estão o endereço certo, o que é obrigatório, como o rateio aparece, o que o ERP não deixa mudar depois e o que costuma dar errado. O que é conta a pagar, baixa, plano de contas, centro de custo e forma de pagamento é conceito do ERP e se responde pelas fontes do financeiro. Os nomes de campo trocados, os filtros e a paginação estão na fonte de campos e filtros da API.

O ENDEREÇO DECIDE SE É PAGAMENTO OU RECEBIMENTO

São dois endereços para o mesmo recurso: /api/pagamentos e /api/recebimentos. Os dois caem no mesmo lugar do financeiro. Pagamento é o tipo D, saída; recebimento é o tipo C, entrada. Esse tipo vem do endereço, não do corpo: se você mandar um campo tipo no JSON de criação, ele é sobrescrito pelo do endereço. Para lançar uma despesa, POST em /api/pagamentos. Para lançar uma entrada, POST em /api/recebimentos.

Na consulta de um lançamento pelo id o tipo não é conferido: GET /api/pagamentos/{id} devolve o registro mesmo que ele seja um recebimento. Quem manda ali é o id, não o endereço.

Na alteração o tipo também não muda: o ERP regrava o tipo do registro que já existe. Não existe converter pagamento em recebimento.

O QUE É OBRIGATÓRIO PARA CRIAR

São três campos: descricao, valor e forma_pagamento_id. Faltando qualquer um, a resposta é 400 com a frase exata:

"É necessário informar a descrição!"
"É necessário informar o valor!"
"É necessário informar a forma de pagamento!"

A terceira frase também aparece quando a forma de pagamento informada não pertence à empresa do token: o id é descartado antes e a recusa cai na mesma mensagem. Se você jurou que mandou a forma de pagamento, confira se o id é da mesma empresa.

Dois campos não são obrigatórios, mas, se você mandar um id que não existe na sua empresa, o lançamento para com 400: conta_bancaria_id, com "É necessário informar a conta bancária!", e plano_contas_id, com "É necessário informar o plano de contas!". A frase engana: o problema não é a falta, é o id.

Não mande id no corpo do POST. Com o campo id preenchido na criação, a resposta é 400 com "O parametro ID é inválido!".

O QUE O ERP PREENCHE SOZINHO

Sem data_competencia, entra a data de hoje. Sem data_vencimento, entra a data de hoje. Sem conta_bancaria_id, entra a conta bancária da forma de pagamento escolhida, quando ela tem uma. Sem nenhuma pessoa informada, o pagamento nasce como fornecedor e o recebimento nasce como cliente. O usuário vem do token. A loja vem do loja_id que você mandar; sem ele, entra a loja padrão do usuário do token. Um loja_id que não é uma das lojas desse usuário para a chamada com "Loja inválida!".

Datas vão em AAAA-MM-DD. Fora desse formato a resposta é 400 dizendo qual campo recusou, no formato "O campo (data_vencimento) não é uma data válida (31/12/2026)!". Atenção ao nome citado: a mensagem usa o nome interno do campo, então data_competencia aparece como data_emissao e data_liquidacao aparece como data_baixa.

Cada chamada cria UMA movimentação. Não há parcelamento neste endereço: doze parcelas são doze chamadas, ou nascem do pedido, que é outra fonte.

A QUEM O LANÇAMENTO PERTENCE

O campo entidade diz de quem é a conta: C de cliente, F de fornecedor, T de transportadora, U de funcionário. Você não envia esse campo: ele é definido pelo id de pessoa que você mandar, ou seja cliente_id, fornecedor_id, transportadora_id ou funcionario_id.

Mande só um. Se mandar mais de um, o rótulo fica com o último desta ordem: cliente, fornecedor, transportadora, funcionário. Ou seja, funcionário vence todos, e cliente é o mais fraco.

Funcionário aqui é usuário do ERP: funcionario_id é o id do usuário.

Id de pessoa que não pertence à empresa do token não gera erro. O campo é limpo e o lançamento é gravado sem a pessoa. Se a conta entrou sem cliente e ninguém entende por quê, foi isso.

LIQUIDADO E O MÊS EM QUE O LANÇAMENTO APARECE

Não existe endereço de baixa. A liquidação é um campo do próprio lançamento: liquidado e data_liquidacao, enviados no mesmo POST ou no PUT. Marcando liquidado sem informar data_liquidacao, entra a data de hoje.

Isso muda onde o lançamento é encontrado depois. Enquanto não está liquidado, ele é procurado pela data de vencimento. Depois de liquidado, pela data de liquidação. Um título que vencia em janeiro e foi liquidado em março some da consulta de janeiro e passa a aparecer na de março. Não sumiu do ERP: mudou de janela.

A LISTAGEM VEM DO MÊS CORRENTE

GET /api/pagamentos e GET /api/recebimentos sem data_inicio e sem data_fim devolvem apenas o mês corrente, do dia primeiro ao último dia do mês. É o padrão, não é falha. Informe data_inicio e data_fim para qualquer outro período. Quando nada bate com o filtro, a resposta é "Nenhuma movimentação foi encontrada!".

Alguns filtros trocam a janela de datas por um vínculo. Filtrando por codigo, conta-fixa, fixo, compra, venda, contrato, locacao, servico, nota, nfse ou nfse_id, a janela é ignorada por inteiro, inclusive a data_inicio e a data_fim que você mandou: a busca passa a ser pelo vínculo, em qualquer período. O mesmo acontece com caixa e com id. Por isso o mesmo lançamento aparece quando você busca pela venda e não aparece quando você busca pelo período.

A listagem também é recortada pela loja e pelo autor. Sem loja_id, ela traz só a loja padrão do usuário do token. E, se esse usuário não tem a permissão de ver lançamentos financeiros dos outros, a consulta traz apenas os lançamentos criados por ele mesmo — na listagem e também na consulta por id. É a causa mais comum de "lancei e não aparece" quando a data está certa.

RATEIO SÓ APARECE NA CONSULTA DE UM ID

O bloco rateios só existe na consulta de um lançamento, GET /api/pagamentos/{id} ou GET /api/recebimentos/{id}. Na listagem ele não vem, nem vazio. Cada item de rateios é um plano de contas do lançamento, e os centros de custo daquele plano vêm dentro dele, na chave centros_custo. Lançamento sem rateio devolve a chave vazia. Se você precisa do rateio de vários lançamentos, consulte um id de cada vez.

O QUE NÃO MUDA DEPOIS DE LANÇADO

A loja. Se o PUT levar um loja_id diferente do que está gravado, a resposta é 400 com esta frase, literal: O parâmetro "loja_id" enviado não corresponde à loja da movimentação financeira cadastrado. Alterações na loja da movimentação financeira não são permitidas.

Não há parâmetro, cabeçalho nem permissão que libere. E omitir o loja_id não é atalho: sem ele, a API assume a loja padrão do usuário do token e faz a mesma comparação — se a movimentação for de outra loja, você leva a mesma recusa sem ter mandado nada. Para alterar uma conta lançada em outra loja, mande o loja_id da própria movimentação. Para uma conta lançada na loja errada, o caminho é apagar e lançar de novo na loja certa.

O tipo também não muda, como já dito. E o codigo enviado no PUT é descartado.

O QUE COSTUMA DAR ERRADO

Erro ao salvar na alteração sem dizer o motivo. Este é o pior de todos. Na alteração, o motivo real da recusa não chega até você: a resposta vem 400 com "Erro ao salvar dados." ou com a mensagem vazia, mesmo quando o ERP sabe exatamente o que barrou, como uma situação que não permite edição. Não tente adivinhar pelo JSON. Faça a mesma alteração na tela do ERP, com o mesmo usuário: lá a recusa aparece escrita. Corrigido o motivo, o PUT passa. Na criação isso não acontece, o POST devolve a frase certa.

"Movimentação financeira não encontrada." com 404 no PUT. O id não existe, ou está fora do alcance do token: outra empresa, uma loja que o usuário não tem, ou um lançamento de outro usuário quando falta a permissão de ver os alheios.

"Você não possui permissão para acessar este registro!" com 400 na consulta de um id. Mesmas causas do 404 acima.

"Falha ao adicionar movimentação.", "Falha ao salvar movimentação.", "Falha ao listar movimentações.", "Falha ao visualizar movimentação." e "Falha ao deletar movimentação.", todas com 500. São genéricas: querem dizer que a chamada quebrou no meio, não que o dado está errado. Ao abrir chamado, mande o endereço, o horário e o corpo que você enviou, sem token e sem senha.

"Este usuário não possui permissão para acessar este método!" com 403 na listagem. É permissão do usuário do ERP que o token representa, não é a chave. Listar pagamentos e listar recebimentos são permissões separadas: pode acontecer de uma responder e a outra não.

"O parametro ID é inválido!" com 400. O id na URL precisa ser número.

Campo extra obrigatório não é cobrado aqui. Se você marcou um campo extra como obrigatório no ERP, o lançamento pela API passa sem ele. Essa checagem existe em outros cadastros da API — cliente, fornecedor, funcionário, produto e pedido —, mas no financeiro está desligada. Não conte com a API para garantir esse preenchimento. Já um campo extra com id que não existe dá 400 com "Falha ao salvar dados, campo extra inválido.".

Conta bancária não se cadastra pela API. Em /api/contas_bancarias existe só a listagem, e ela devolve apenas id e nome. Não há consulta por id, criação, alteração nem exclusão. Conta bancária se cadastra no ERP.

Apaguei um plano de contas e a resposta falou em conta. Em /api/planos_contas o DELETE responde "Conta removida com sucesso!". Esse texto é do plano de contas, que no ERP é a categoria de movimentação financeira. Não quer dizer que uma conta bancária ou uma movimentação foi apagada. O DELETE de um lançamento responde "Movimentação removida com sucesso!".

OS CADASTROS DE APOIO

Plano de contas: /api/planos_contas, com consulta, criação, alteração e exclusão. Por padrão a listagem traz só as contas que têm conta mãe; para trazer também as contas mãe, envie o parâmetro todos.

Centro de custo: /api/centros_custos, com consulta, criação, alteração e exclusão. A listagem traz id, nome e data de cadastro. Centro de custo inativo, ou de outra empresa, enviado no lançamento é descartado sem erro. A exclusão responde "CentrosCusto removido com sucesso!", que é o nome técnico do cadastro.

Forma de pagamento: /api/formas_pagamentos, com consulta, criação, alteração e exclusão. Dados de boleto são recusados: "Não é possível informar dados de boleto pela API!".

Conta bancária: só listagem, como dito acima.

ONDE ESTA FONTE NÃO RESPONDE

Nomes de campo trocados, filtros, paginação e envelope do retorno: fonte de campos e filtros da API. Mensagem de autenticação, limite de requisições e plano: fonte de erro por erro. Qual usuário e qual loja o token representa: fonte de identidade do token. Criar orçamento, venda, ordem de serviço e pedido, e as parcelas que nascem deles: fonte de criação de pedidos. Conceito de conta a pagar, baixa, plano de contas, centro de custo e forma de pagamento: fontes do financeiro do ERP.