Financeiro

A rota permite consultar, criar e atualizar movimentações financeiras, incluindo lançamentos únicos e parcelados.

Introdução

Nesta documentação, detalhamos os campos que você pode esperar manipular ao interagir com a API. Cada campo é descrito para esclarecer sua função e o tipo de dado esperado, garantindo que você possa fornecer ou obter informações precisas.

Veja abaixo:

URLs

Método	URL	Ação	Descrição
GET	/api/v1/financial	Listar	Lista todos as movimentações
GET	/api/v1/financial/`{id}`	Visualizar	Exibe uma determinada movimentação pelo ID
POST	/api/v1/financial	Criar	Cria uma nova movimentação financeira
PUT	/api/v1/financial/`{id}`	Editar	Atualiza uma movimentação financeira pelo ID

Campos

Abaixo estão os campos disponíveis na API:

Campo	Tipo	Descrição
datahoraupdate	datetime	Data e hora da última edição no formato `Y-m-d H:i:s`. Retornado nos endpoints GET
datapagamento	date	Data do pagamento
datacompetencia	date	Data de competência
tipocobranca	string	Tipo da movimentação (Despesa/Receita)
idrecebidode	integer	ID do pagador/recebedor
recebidode	string	Nome do pagador/recebedor
informede	string	Informações adicionais do pagador/recebedor
descricao	string	Descrição da movimentação
valor	decimal	Valor da movimentação
juros	decimal	Valor de juros
multa	decimal	Valor da multa
desconto	decimal	Valor do desconto
pago	string	Status do pagamento (sim/nao/pen)
idconta	integer	ID da conta
conta	string	Nome da conta
idcategoria	integer	ID da categoria
categoria	string	Nome da categoria
idcentrodecusto	integer	ID do centro de custo
centrodecusto	string	Nome do centro de custo
mododepagamento	string	Forma de pagamento
parcelas	array ou null	Demais parcelas do parcelamento, sem a movimentação retornada. Cada item traz `id`, `numeroparcela`, `datapagamento`, `valor`, `descricao` e `pago`, ordenados por `numeroparcela`. Retorna `null` quando a movimentação não faz parte de um parcelamento
idevento	integer	ID do evento relacionado
evento	string	Nome do evento

Listar

Endpoint: /api/v1/financial

Método: GET

Retorna uma lista de todos as movimentações financeiras. Suporta busca e paginação para gerenciar grandes volumes de dados.

Ordenação

Para melhorar a experiência de visualização dos dados, oferecemos suporte à ordenação de registros. Você pode especificar a ordenação dos dados através de dois parâmetros:

Parâmetros:

sort: Define a direção da ordenação. Valores permitidos: asc para ascendente, desc para descendente.
field_sort: Especifica o campo pelo qual os registros devem ser ordenados.

Exemplo de Uso: Para ordenar as movimentações pelo ID em ordem ascendente: /api/v1/financial?field_sort=id&sort=asc

O parâmetro field_sort aceita somente os campos abaixo. Qualquer outro valor retorna 400:

id, datahoraupdate, numeroparcela, datapagamento, datacompetencia, tipocobranca, idrecebidode, recebidode, informede, descricao, valor, juros, multa, desconto, pago, idconta, conta, idcategoria, categoria, classificacao_categoria, idcentrodecusto, centrodecusto, classificacao_centrodecusto, mododepagamento, idevento e evento.

Paginação

A paginação é essencial para o gerenciamento eficiente dos dados, especialmente quando lidamos com grandes volumes. Cada página pode conter um número definido de registros, reduzindo o tempo de carregamento e melhorando a usabilidade.

Parâmetro:

page: Número da página desejada.
limit (opcional): Número de registros por página, o limite e de até 200 registros.

Exemplo de Uso: Para acessar a segunda página de registros: /api/v1/financial?page=2&limit=10

Resumo

Utilizar as funcionalidades de Ordenação, Paginação em conjunto permite uma manipulação eficiente e precisa dos dados na nossa API. Por exemplo, para listar movimentações ordenados pelo ID, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:

/api/v1/financial?field_sort=id&sort=desc&page=1&limit=10

Esta combinação otimiza suas consultas, permitindo que você obtenha dados específicos de forma rápida e organizada.

Response:

json

{
  "data": [
    {
      "id": "2673",
      "datahoraupdate": "2026-07-15 15:42:10",
      "datapagamento": "2024-06-23",
      "datacompetencia": "2024-06-23",
      "tipocobranca": "Despesa",
      "idrecebidode": "4",
      "recebidode": "Fornecedores/Parceiros",
      "informede": "Jonathan Moreira",
      "descricao": "Pagamento fornecedor",
      "valor": "150.00",
      "juros": "0.00",
      "multa": "0.00",
      "desconto": "0.00",
      "pago": "nao",
      "idconta": "7",
      "conta": "Nubank",
      "idcategoria": "11",
      "categoria": "Não Informado",
      "idcentrodecusto": "12",
      "centrodecusto": "Não Informado",
      "mododepagamento": "Não Informado",
      "parcelas": [
        {
          "id": 288,
          "numeroparcela": 2,
          "datahoraupdate": "2026-07-15 15:42:10",
          "pago": "nao",
          "valor": 2500,
          "descricao": "Entrada Parcela 2",
          "datapagamento": "2020-10-16"
        }
      ],
      "idevento": "2673",
      "evento": "Green Gold Plaza"
    }
  ],
  "pagination": {
    "page": 1, // Página atual
    "page_size": 200, // Quantidade de resgistros exibida por pagina
    "total_page": 1, // Quantidade de paginas no total
    "total_data": 1 // Quantidade total de registros encontrados
  }
}

Visualizar

Endpoint: /api/v1/financial/{id}

Método: GET

Para visualizar as informações de uma movimentação, você pode fazer uma solicitação GET para endpoint acima. Não é necessário fornecer informações no corpo da solicitação, já que você estará apenas recuperando dados. O ID do cliente a ser consultado deve ser especificado no endpoint.

Response:

json

{
  "id": "2673",
  "datahoraupdate": "2026-07-15 15:42:10",
  "datapagamento": "2024-06-23",
  "datacompetencia": "2024-06-23",
  "tipocobranca": "Despesa",
  "idrecebidode": "4",
  "recebidode": "Fornecedores/Parceiros",
  "informede": "Jonathan Moreira",
  "descricao": "Pagamento fornecedor",
  "valor": "150.00",
  "juros": "0.00",
  "multa": "0.00",
  "desconto": "0.00",
  "pago": "nao",
  "idconta": "7",
  "conta": "Nubank",
  "idcategoria": "11",
  "categoria": "Não Informado",
  "idcentrodecusto": "12",
  "centrodecusto": "Não Informado",
  "mododepagamento": "Não Informado",
  "parcelas": [
    {
      "id": 288,
      "numeroparcela": 1,
      "datahoraupdate": "2026-07-15 15:42:10",
      "pago": "nao",
      "valor": 2500,
      "descricao": "Entrada",
      "datapagamento": "2020-10-16"
    },
    {
      "id": 290,
      "numeroparcela": 3,
      "datahoraupdate": "2026-07-15 15:42:10",
      "pago": "nao",
      "valor": 2500,
      "descricao": "Parcela 3",
      "datapagamento": "2020-12-16"
    }
  ],
  "idevento": "2673",
  "evento": "Green Gold Plaza"
}

O campo parcelas traz as demais parcelas do parcelamento, sem a movimentação consultada — no exemplo acima, a consulta foi feita na parcela 2, por isso ela não aparece na lista. A primeira parcela é incluída normalmente. Quando a movimentação não faz parte de um parcelamento, o campo retorna null.

O campo datahoraupdate é preenchido automaticamente quando o lançamento é editado pelo sistema ou pela API. Registros antigos que ainda não possuem esse histórico podem retornar 0000-00-00 00:00:00.

Criar

Endpoint: /api/v1/financial

Método: POST

Para criar uma nova movimentação financeira, você deve fazer uma solicitação POST. Suporta criação de movimentações únicas ou parceladas.

Campos Obrigatórios:

datapagamento: Data do pagamento (formato Y-m-d)
valor: Valor da movimentação (número > 0)
pago: Status do pagamento ("sim", "nao", "pen")
tipocobranca: Tipo de cobrança (1=Receita, 2=Despesa)

Campos Opcionais:

datacompetencia: Data de competência (padrão: mesma data do pagamento)
recebidode: ID de quem recebeu/pagou (padrão: 1)
idconta: ID da conta (padrão: 1)
idcategoria: ID da categoria (padrão: 1)
mododepagamento: ID do modo de pagamento (padrão: 1)
idcartao: ID do cartão (obrigatório se modo de pagamento for cartão)
informede: ID da entidade relacionada
idevento: ID do evento relacionado
idcentrodecusto: ID do centro de custo
descricao: Descrição da movimentação
juros, multa, desconto: Valores adicionais
numerodocumento: Número do documento
parcelas: Array de parcelas para parcelamento

Exemplo de Requisição Simples:

json

{
  "datapagamento": "2024-01-15",
  "valor": 1500.00,
  "pago": "sim",
  "tipocobranca": 1,
  "descricao": "Pagamento de evento",
  "idconta": 1,
  "idcategoria": 2,
  "mododepagamento": 3,
  "idevento": 123
}

Exemplo de Requisição com Parcelamento:

json

{
  "datapagamento": "2024-01-15",
  "valor": 5000.00,
  "pago": "sim",
  "tipocobranca": 1,
  "descricao": "Pagamento evento casamento",
  "idconta": 1,
  "idcategoria": 1,
  "mododepagamento": 1,
  "idevento": 123,
  "parcelas": [
    {
      "datapagamento": "2024-02-15",
      "valor": 2500.00,
      "pago": "nao",
      "descricao": "2ª parcela do casamento"
    },
    {
      "datapagamento": "2024-03-15",
      "valor": 2500.00,
      "pago": "nao",
      "descricao": "3ª parcela do casamento"
    }
  ]
}

Response de Sucesso:

json

{
  "status": "success",
  "message": "Movimentação financeira com 3 parcelas cadastrada com sucesso.",
  "data": [
    {
      "idevento": "123",
      "idmovimentacao": "15",
      "datapagamento": "2024-01-15",
      "tipocobranca": "Receita",
      "valor": "5000.00",
      "pago": "sim",
      "descricao": "Pagamento evento casamento",
      "numeroparcela": "1",
      "vinculoparcela": "abc123def456"
    },
    {
      "idevento": "123",
      "idmovimentacao": "16",
      "datapagamento": "2024-02-15",
      "tipocobranca": "Receita",
      "valor": "2500.00",
      "pago": "nao",
      "descricao": "2ª parcela do casamento",
      "numeroparcela": "2",
      "vinculoparcela": "abc123def456"
    },
    {
      "idevento": "123",
      "idmovimentacao": "17",
      "datapagamento": "2024-03-15",
      "tipocobranca": "Receita",
      "valor": "2500.00",
      "pago": "nao",
      "descricao": "3ª parcela do casamento",
      "numeroparcela": "3",
      "vinculoparcela": "abc123def456"
    }
  ],
  "vinculoparcela": "abc123def456",
  "total_parcelas": 3
}

Observações Importantes:

Para pagamentos com cartão de crédito, o campo idcartao é obrigatório
A API verifica se contas, categorias, eventos e outras entidades existem
Parcelas são vinculadas através do campo vinculoparcela
Valores padrão são aplicados automaticamente quando campos opcionais não são informados
A validação do campo informede varia conforme o valor de recebidode

Editar

Endpoint: /api/v1/financial/{id}

Método: PUT

Atualiza parcialmente uma movimentação financeira existente. O parâmetro {id} deve ser o ID numérico da movimentação e o corpo da solicitação deve conter pelo menos um campo válido para atualização. Os campos que não forem enviados permanecem inalterados.

Campos aceitos

Todos os campos são opcionais, mas pelo menos um campo de atualização além de tipoeditar deve ser informado.

Campo	Tipo	Descrição
tipoeditar	integer	Escopo da edição no parcelamento: `1` = somente este lançamento, `2` = este e as parcelas futuras, `3` = todas as parcelas. Padrão: `1`
data_vencimento	date	Data de vencimento no formato `Y-m-d`. Se não for enviada junto com `datapagamento`, recebe automaticamente o mesmo valor
datapagamento	date	Data de pagamento no formato `Y-m-d`. Atualiza também `data_vencimento`, salvo se `data_vencimento` for enviada explicitamente
datacompetencia	date	Data de competência no formato `Y-m-d`
data_faturamento	date ou null	Data de faturamento no formato `Y-m-d`. Envie `null` ou uma string vazia para remover a data
valor	decimal	Valor da movimentação. Deve ser maior que zero. Não pode ser alterado em movimentações com rateio ou com cobrança em aberto
pago	string	Status do pagamento: `sim`, `nao` ou `pen`. Não pode ser alterado quando a movimentação já possui cobrança emitida
tipocobranca	integer	Tipo da movimentação: `1` = Receita, `2` = Despesa
recebidode	integer	ID do tipo de pagador/recebedor. Deve ser maior que zero
informede	integer	ID da entidade relacionada ao campo `recebidode`
idconta	integer	ID de uma conta existente. Deve ser maior que zero
idcategoria	integer	ID de uma categoria existente. Deve ser maior que zero
idcentrodecusto	integer	ID do centro de custo. Use `0` para remover o vínculo
mododepagamento	integer	ID de um modo de pagamento existente. Deve ser maior que zero
idcartao	integer	ID do cartão relacionado. Obrigatório quando o `mododepagamento` resultante for um cartão de crédito
idevento	integer	ID de um evento existente. Use `0` para remover o vínculo. Não pode ser alterado em movimentações com rateio
descricao	string	Descrição da movimentação
juros	decimal	Valor dos juros
multa	decimal	Valor da multa
desconto	decimal	Valor do desconto. O valor é armazenado como negativo pela API
numerodocumento	string	Número do documento
detalhes	string	Detalhes da movimentação
tipo_integracao	string	Tipo da integração relacionada à movimentação
tipo_cobranca	string	Tipo de cobrança utilizado pela integração
juros_cobranca	decimal	Valor ou percentual de juros da cobrança
multa_cobranca	decimal	Valor ou percentual da multa da cobrança
idpedido	integer	ID do pedido relacionado. Aceita `0` para remover o vínculo
idvenda	integer	ID da venda relacionada. Aceita `0` para remover o vínculo
tags	array ou string	Lista de IDs positivos de tags ou uma string com as tags
anotacoesinternas	string	Anotações internas da movimentação
iduser	integer	ID do usuário responsável pela atualização. O usuário deve estar ativo e possuir permissão no financeiro

Atualização de parcelamentos

O campo tipoeditar controla o alcance da alteração quando a movimentação pertence a um parcelamento:

Valor	Escopo	Comportamento
`1`	Somente este lançamento	Atualiza apenas a movimentação indicada no endpoint. Este é o comportamento padrão
`2`	Este e as parcelas futuras	Atualiza a movimentação indicada e as parcelas vinculadas com data posterior à data original do lançamento
`3`	Todas as parcelas	Atualiza a movimentação indicada e todas as demais parcelas vinculadas

Nos escopos 2 e 3, somente os campos compartilhados do parcelamento são propagados: recebidode, informede, idevento, valor, idconta, idcategoria, idcentrodecusto, numerodocumento, mododepagamento, detalhes, tipo_integracao, tipo_cobranca, juros_cobranca, multa_cobranca, idpedido, idcartao, tags e idvenda.

Campos próprios de cada parcela, como descricao, pago, tipocobranca, juros, multa, desconto e anotacoesinternas, são alterados somente na movimentação indicada pelo {id}.

As datas datapagamento, data_vencimento, datacompetencia e data_faturamento são alteradas somente na movimentação indicada pelo {id}, independentemente do valor de tipoeditar. As datas das demais parcelas permanecem inalteradas.

No lançamento indicado pelo {id}, envie somente as datas que realmente deseja alterar. datacompetencia e data_faturamento são sempre independentes entre si.

datapagamento e data_vencimento, por outro lado, são mantidas espelhadas, como acontece no cadastro e na edição pela tela do sistema:

enviar apenas datapagamento grava o mesmo valor nas duas;
enviar as duas grava exatamente o que foi enviado, permitindo datas diferentes;
enviar apenas data_vencimento altera somente ela.

Movimentações com cobrança emitida

Quando a movimentação já possui uma cobrança gerada em um gateway (Mezy, Asaas ou Banco Inter), parte dos campos não pode ser alterada pela API e a resposta é 409.

O motivo é que a tela do sistema reenvia a alteração para o gateway logo após salvar, mantendo o boleto e o sistema iguais. A API não faz esse reenvio, então permitir a edição deixaria o boleto que já está com o pagador diferente do que está registrado. No Banco Inter não há sequer como corrigir depois: a API do banco não permite editar um boleto já emitido, apenas cancelar e gerar outro.

Campos bloqueados enquanto a cobrança estiver em aberto: valor, datapagamento, descricao, juros_cobranca, multa_cobranca, tipo_cobranca, tipo_integracao, informede e recebidode.

A regra vale também para a propagação: se tipoeditar for 2 ou 3 e alguma das parcelas atingidas tiver cobrança em aberto, a requisição é recusada por inteiro, sem alterar nenhum registro.

Movimentações já quitadas (pago: "sim") não entram nessa regra — a cobrança está encerrada e esses campos voltam a ser editáveis.

O campo pago segue uma regra própria: é bloqueado sempre que existir cobrança emitida, inclusive nas já quitadas, porque o status é atualizado automaticamente pelo retorno do gateway. Reenviar o mesmo valor que já está gravado não é considerado alteração e não gera erro.

Os demais campos — categoria, conta, centro de custo, modo de pagamento, tags, detalhes, anotações internas, evento, entre outros — continuam editáveis normalmente.

json

{
  "status": "error",
  "message": "Não é possível alterar valor porque este lançamento já possui cobrança emitida (asaas). Cancele a cobrança e gere novamente pela tela do sistema.",
  "campos_bloqueados": ["valor"]
}

Movimentações com rateio

Em um lançamento rateado, o valor é dividido entre eventos e centros de custo, e o idevento do próprio lançamento fica zerado — a atribuição por evento passa a existir apenas nas linhas do rateio. A tela do sistema recalcula essas linhas a cada edição e recusa salvar quando a soma do rateio não corresponde ao valor do lançamento.

Como a API não altera o rateio, os campos valor e idevento não podem ser editados nessas movimentações e a resposta é 409. Alterar o valor deixaria a soma do rateio incorreta, e alterar o evento deixaria o lançamento com evento próprio e rateio ao mesmo tempo. Em ambos os casos, os relatórios por evento, o DRE e o relatório por centro de custo passariam a apresentar valores que não correspondem ao financeiro geral.

A regra também vale para a propagação: se tipoeditar for 2 ou 3 e alguma das parcelas atingidas possuir rateio, a requisição é recusada por inteiro, sem alterar nenhum registro.

Os demais campos continuam editáveis normalmente. Para alterar valor ou evento de um lançamento rateado, use a tela do sistema, onde o rateio é recalculado junto.

json

{
  "status": "error",
  "message": "Não é possível alterar valor porque este lançamento possui rateio. Edite pela tela do sistema, onde o rateio é recalculado junto.",
  "campos_bloqueados": ["valor"]
}

Registro no histórico

Toda atualização feita por este endpoint é registrada no histórico do sistema, com o valor anterior e o novo, as parcelas afetadas e o IP de origem. Quando o campo iduser é informado, o histórico exibe o nome do usuário responsável; quando não é, o registro aparece como "Sistema".

Exemplo de requisição simples

json

{
  "valor": 1750.00,
  "pago": "sim",
  "datapagamento": "2024-02-20",
  "descricao": "Pagamento de evento atualizado"
}

Exemplo de requisição com parcelas futuras

json

{
  "tipoeditar": 2,
  "datapagamento": "2024-02-29",
  "data_vencimento": "2024-02-29",
  "datacompetencia": "2024-02-29",
  "valor": 1800.00,
  "idconta": 7,
  "iduser": 15
}

Nesse exemplo, a movimentação informada no endpoint recebe as novas datas, enquanto as parcelas futuras recebem somente o novo valor e a nova idconta. Todas as datas das parcelas futuras permanecem inalteradas.

Response de sucesso

json

{
  "status": "success",
  "message": "Movimentação financeira atualizada com sucesso, incluindo 2 parcela(s) vinculada(s).",
  "data": {
    "idevento": "123",
    "idmovimentacao": "2673",
    "datapagamento": "2024-02-29",
    "data_vencimento": "2024-02-29",
    "datacompetencia": "2024-02-29",
    "data_faturamento": null,
    "tipocobranca": "Receita",
    "idrecebidode": "3",
    "recebidode": "Clientes",
    "informede": "Maria Silva",
    "descricao": "Pagamento de evento atualizado",
    "valor": "1800.00",
    "juros": "0.00",
    "multa": "0.00",
    "desconto": "0.00",
    "pago": "sim",
    "numerodocumento": "DOC-123",
    "detalhes": "",
    "tags": "",
    "idpedido": "0",
    "idvenda": "0",
    "tipo_integracao": "",
    "tipo_cobranca": "",
    "juros_cobranca": "0.00",
    "multa_cobranca": "0.00",
    "idconta": "7",
    "conta": "Nubank",
    "idcategoria": "11",
    "categoria": "Eventos",
    "classificacao_categoria": "Receita",
    "idcentrodecusto": "12",
    "centrodecusto": "Eventos",
    "classificacao_centrodecusto": "Receita",
    "mododepagamento": "Pix",
    "parcelas": [
      {
        "id": 2674,
        "numeroparcela": "2",
        "datapagamento": "2024-03-29",
        "valor": 1800,
        "descricao": "2ª parcela",
        "pago": "nao"
      },
      {
        "id": 2675,
        "numeroparcela": "3",
        "datapagamento": "2024-04-29",
        "valor": 1800,
        "descricao": "3ª parcela",
        "pago": "nao"
      }
    ],
    "evento": "Casamento Maria e João"
  },
  "parcelas_atualizadas": 2,
  "ids_parcelas_atualizadas": [2674, 2675]
}

parcelas_atualizadas informa a quantidade de parcelas alteradas além da movimentação indicada. ids_parcelas_atualizadas retorna os respectivos IDs. Quando apenas a movimentação indicada for atualizada, esses campos retornam, respectivamente, 0 e [], e a mensagem será Movimentação financeira atualizada com sucesso.

Possíveis erros

Status HTTP	Situação
`400`	ID inválido, corpo sem campos válidos, algum campo fora do formato aceito ou `idcartao` ausente quando o modo de pagamento for cartão de crédito
`403`	O usuário informado em `iduser` não possui permissão no financeiro
`404`	Movimentação, usuário ou entidade relacionada não encontrada
`409`	A movimentação, ou alguma parcela atingida pela propagação, possui cobrança emitida ou rateio, e um dos campos enviados alteraria esses dados. A resposta traz `campos_bloqueados` com os campos recusados
`500`	Erro interno ao executar a atualização

Financeiro ​

Introdução ​

URLs ​

Campos ​

Listar ​

Ordenação ​

Paginação ​

Resumo ​

Visualizar ​

Criar ​

Editar ​

Campos aceitos ​

Atualização de parcelamentos ​

Movimentações com cobrança emitida ​

Movimentações com rateio ​

Registro no histórico ​

Exemplo de requisição simples ​

Exemplo de requisição com parcelas futuras ​

Response de sucesso ​

Possíveis erros ​

Financeiro

Introdução

URLs

Campos

Listar

Ordenação

Paginação

Resumo

Visualizar

Criar

Editar

Campos aceitos

Atualização de parcelamentos

Movimentações com cobrança emitida

Movimentações com rateio

Registro no histórico

Exemplo de requisição simples

Exemplo de requisição com parcelas futuras

Response de sucesso

Possíveis erros