Financeiro

Lançamentos, cobranças, baixas e reenvio.

14 rotas. Todas exigem a chave de API no header Authorization, salvo quando marcadas como públicas. Abrir este módulo no Swagger.

Listar lançamentos por período e status

POST /companie/financial/filterAdvanced/{filter}/{date_start}/{date_end}

Lista receitas e despesas da empresa, paginada.

• filter: período (inclui next_month). Com other_period, informe date_start e date_end (YYYY-MM-DD).
• date: qual data o período filtra. V (ou vazio) vencimento, P data do pagamento, C crédito em conta.
• type (obrigatório): R, D ou Todos.
• status: Aberta, Vencida, Paga, Cancelada. Para todos, envie [] (não use Todos: nada casa com ele).
• Envie sempre client_id, contract_id, provider_id, pla_account_id, form_of_payment e status, mesmo que como []. Sem eles a rota responde 500.
• received: envie null para não filtrar. Se omitido, a rota traz só os não recebidos (received_value = 0). true só os recebidos.
• name: busca por nome do cliente/fornecedor (substitui os filtros client_id e status=Vencida; prefira não combinar).
• order: due_date_asc (padrão), due_date_desc, received_date_asc, received_date_desc.
• Paginação: skip e take obrigatórios. total é o total do filtro.
• Recorrências integradas mostram só a próxima parcela pendente. Para ver a série inteira, filtre por group, asaas_pay_id_subs ou asaas_pay_id_charges.

Em cada item:

• payment_link é o link de cobrança (fatura do Asaas) para mandar ao cliente. Só existe em cobranças integradas.
• nfe_id e nfe_status indicam a última NFS-e do lançamento. O PDF da nota sai em GET /companie/financial/serviceInvoiceCompany/{nfe_id}/pdf.
• O status já vem recalculado: Aberta com vencimento passado volta como Vencida.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
filter	URL	all · today · yesterday · this_week · last_week · this_month · last_month · next_month · …	sim
date_start	URL	string		Opcional na URL: pode ser omitido junto com os segmentos seguintes.
date_end	URL	string		Opcional na URL: pode ser omitido junto com os segmentos seguintes.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
name	string
galax_pay_id_subs	número ou null
asaas_pay_id_charges	string ou null
asaas_pay_id_subs	string ou null
group	número
client_id	número[]
provider_id	número[]
contract_id	número[]
product_id	número[]
pla_account_id	número[]
type	R · D · Todos	sim
form_of_payment	creditcard · boleto · pix · ted · dinheiro · check · voucher · app · …[]
method	in_sight · installments · recurrence[]
status_contract	Ativo · Ag.Pagamento · Cancelado · Inadimplente · Interrompido[]
status	Aberta · Paga · Vencida · Cancelada · Todos[]
received	boolean ou null
order	due_date_asc · due_date_desc · received_date_asc · received_date_desc
skip	número	sim
take	número	sim
date	string ou null

Respostas

Status	Descrição
200	Lançamentos da página.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Criar lançamento ou cobrança

POST /companie/financial

Cria uma receita (type: R) ou despesa (type: D).

Cobrança integrada x lançamento avulso. A receita vira cobrança no Asaas quando form_of_payment é boleto, pix ou creditcard e a empresa tem a integração Asaas ativa. Nesse caso:

• o vencimento não pode ser anterior a hoje (error_due_date_less_now);
• o Asaas gera a fatura e o payment_link de cada parcela (veja na listagem);
• a resposta traz as cobranças criadas no Asaas.

Nos demais casos (despesas, ted, dinheiro, check, voucher, app, ou empresa sem integração) o lançamento é só interno, sem link de cobrança, e a resposta é true.

Método:

• in_sight: à vista, installment: 1.
• installments: parcelado. value é o total; cada parcela recebe value / installment, com vencimentos mensais a partir de due_date. Para valores e datas próprios, envie installment_items (a soma precisa bater com value).
• recurrence: recorrente. Exige cycle. Use installment: 1 e value igual ao valor de cada cobrança. Sem integração, cria as duas primeiras parcelas (1/n, 2/n).

Regras:

• Receita exige client_id ou contract_id (error_required_contract_or_client). Despesa exige provider_id.
• pla_account_id: conta do plano de contas do mesmo tipo (R/D).
• Datas em YYYY-MM-DD.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_id	número ou null
client_id	número ou null
provider_id	número ou null
value	número	sim
due_date	string	sim
pla_account_id	número	sim
cycle	WEEKLY · BIWEEKLY · MONTHLY · BIMONTHLY · QUARTERLY · SEMIANNUALLY · YEARLY
bank_account_id	número ou null
form_of_payment	creditcard · boleto · pix · ted · dinheiro · check · voucher · app	sim
method	in_sight · installments · recurrence	sim
installment	número	sim
installment_items	object[]
installment_items[].number	número	sim
installment_items[].due_date	string	sim
installment_items[].value	número	sim
type	R · D	sim
obs	string
instructions	string

Respostas

Status	Descrição
200	true no lançamento avulso; na cobrança integrada, as cobranças criadas no Asaas.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_plan_account_not_exist, error_bank_account_not_exist, error_contract_not_exist, error_client_not_exist, error_provider_not_exist, error_required_contract_or_client, error_required_provider, error_due_date_less_now, error_installment_items_sum_mismatch (e demais error_installment_items_*), ou o erro devolvido pelo Asaas. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar lançamentos

PUT /companie/financial

O id não vai na URL: cada parcela a editar vai em items[] com o seu id.

• Os campos do topo (type, pla_account_id, form_of_payment, client_id/contract_id/provider_id, bank_account_id, cycle) valem para todos os itens.
• Valor e vencimento não mudam em lançamento Paga, Cancelada, Estornada ou Negada (error_financial_status_not_editable).
• Em cobrança integrada, a alteração é repassada ao Asaas; a forma de pagamento da cobrança é mantida.
• cycle só em recorrência (error_cycle_not_allowed_for_method).

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_id	número ou null
client_id	número ou null
provider_id	número ou null
pla_account_id	número	sim
bank_account_id	número ou null
form_of_payment	creditcard · boleto · pix · ted · dinheiro · check · voucher · app	sim
type	R · D	sim
cycle	WEEKLY · BIWEEKLY · MONTHLY · BIMONTHLY · QUARTERLY · SEMIANNUALLY · YEARLY
items	object[]	sim
items[].id	número	sim
items[].value	número	sim
items[].due_date	string	sim
items[].obs	string
items[].instructions	string

Respostas

Status	Descrição
200	Lançamentos atualizados.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_financial_not_exist, error_financial_status_not_editable, error_cycle_not_allowed_for_method, error_financial_shared_asaas_payment, error_plan_account_not_exist, error_provider_not_exist, error_bank_account_not_exist, ou a recusa do Asaas. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Dar baixa em um lançamento

PUT /companie/financial/payed/{id}

Marca o lançamento como Paga, com valor e data do recebimento (YYYY-MM-DD).

• Em cobrança integrada ao Asaas, registra no Asaas o recebimento em dinheiro.
• Não recusa lançamento já pago: chamar de novo sobrescreve a baixa e soma de novo nos totais do cliente.
• Resposta false quando o lançamento é de um gateway em que a baixa manual não se aplica.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
received_value	número	sim
received_date	string	sim
obs_received	string

Respostas

Status	Descrição
200	true quando baixado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_financial_not_exist, error_settings_not_galax_companie, error_ai_token_purchase_pay_not_allowed, ou o erro do gateway. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Dar baixa em lote

POST /companie/financial/bulk/payed

Baixa até 50 lançamentos. Cada um é baixado pelo próprio valor, com a data de hoje.

• Todos os ids precisam ser da empresa; senão o lote inteiro é recusado (409).
• Lançamento já pago falha só aquele item (error_financial_already_payed).
• A resposta traz o resultado por item.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
ids	número[]	sim

Respostas

Status	Descrição
200	Resultado por item.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	Lote recusado inteiro, nada foi processado: error_financial_bulk_ids_required, error_financial_bulk_limit_exceeded (com max_items), error_financial_bulk_ids_invalid ou error_financial_not_exist (com invalid_ids: ids que não existem ou são de outra empresa).
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Estornar a baixa de um lançamento

PUT /companie/financial/revertPayed/{id}

Desfaz uma baixa manual: o lançamento volta para Aberta (ou Vencida), sem data nem valor recebido. Só vale para lançamento Paga que não foi pago pelo gateway (cobrança integrada paga pelo Asaas não pode ser estornada aqui).

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Lançamento reaberto.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_financial_not_exist, error_financial_not_payed, error_integrated_financial_revert_not_allowed ou error_ai_token_purchase_pay_not_allowed. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Reenviar a cobrança por e-mail

POST /companie/financial/sendBillingEmail/{id}

Envia ao cliente um e-mail com o valor, o vencimento e o payment_link do lançamento.

• Só receitas Aberta, Vencida ou Aguardando pagamento com link de cobrança (cobrança integrada).
• Destinatário: email_override, se enviado; senão o e-mail do cliente ou do contrato.
• A empresa precisa ter logo, nome fantasia e documento cadastrados.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	número	sim	Id do lançamento.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
email_override	string		Envia para este e-mail em vez do e-mail do cliente.

Respostas

Status	Descrição
200	E-mail enviado.
400	Lançamento não é receita, status não permite reenvio, ou faltam dados (missing_fields: e-mail, link de pagamento, nome do cliente, logo, nome fantasia, documento da empresa).
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	"Lançamento não encontrado".
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Reenviar cobranças por e-mail em lote

POST /companie/financial/bulk/sendBillingEmail

Reenvia até 50 cobranças, para o e-mail cadastrado de cada cliente (sem email_override). Mesmas regras do reenvio individual; a falha de um item não para o lote.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
ids	número[]	sim

Respostas

Status	Descrição
200	Resultado por item.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	Lote recusado inteiro, nada foi processado: error_financial_bulk_ids_required, error_financial_bulk_limit_exceeded (com max_items), error_financial_bulk_ids_invalid ou error_financial_not_exist (com invalid_ids: ids que não existem ou são de outra empresa).
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Consultar o histórico do lançamento

GET /companie/financial/history/{id}

Linha do tempo do lançamento, do mais recente ao mais antigo: criação, mudanças de status (baixa, estorno, confirmações do gateway) e edições com os campos alterados.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	número	sim

Respostas

Status	Descrição
200	Eventos do lançamento.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	error_financial_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Excluir lançamento

DELETE /companie/financial/{id}/{is_delete_futures}

• is_delete_futures=false: exclui só este lançamento.
• is_delete_futures=true: exclui também as parcelas em aberto do mesmo grupo, parcelamento ou assinatura.
• Em cobrança integrada, a cobrança (ou a assinatura/parcelamento) é cancelada no Asaas.
• Cobrança integrada já paga não pode ser excluída.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim
is_delete_futures	URL	true · false	sim

Respostas

Status	Descrição
200	true quando excluído.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_financial_not_exist, error_financial_received_not_allowed ou o erro do Asaas. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Excluir lançamentos em lote

POST /companie/financial/bulk/delete

Exclui até 50 lançamentos, com a mesma regra da exclusão individual. is_delete_futures: true leva junto as parcelas em aberto de cada grupo. Item já removido pela cascata de um item anterior conta como sucesso.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
ids	número[]	sim
is_delete_futures	boolean

Respostas

Status	Descrição
200	Resultado por item.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	Lote recusado inteiro, nada foi processado: error_financial_bulk_ids_required, error_financial_bulk_limit_exceeded (com max_items), error_financial_bulk_ids_invalid ou error_financial_not_exist (com invalid_ids: ids que não existem ou são de outra empresa).
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Emitir NFS-e a partir do lançamento

POST /companie/financial/{financialId}/serviceInvoiceCompany/requestServiceInvoice

Emite uma nota fiscal de serviço vinculada à receita financialId.

Pré-requisitos:

• NFS-e configurada para a empresa e crédito de nota disponível. Cada nota emitida consome 1 crédito.
• Cliente com CPF/CNPJ, e-mail e endereço completos.
• customerServiceId: id do serviço do cliente, obtido em GET /companie/financial/serviceInvoiceCompany/clientEconomicActivity?client_id={id}&for_emission=true.

Regras:

• customerId deve ser o cliente do lançamento (ou o do contrato).
• Os valores retidos (*AmountWithheld) vão em reais, não em percentual. issRate é fração (0.05 = 5%).
• Os dados fiscais são repassados ao provedor (NFE.io); campos além dos listados também são aceitos.
• A rota espera alguns segundos pela autorização. Se a prefeitura demorar, responde ok: false com processing: true; acompanhe pelo nfe_status do lançamento.
• O PDF sai em GET /companie/financial/serviceInvoiceCompany/{nfe_id}/pdf.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
financialId	URL	número	sim	Id do lançamento (receita).

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
customerId	número	sim	Id do cliente tomador.
customerServiceId	número	sim	Id do serviço (atividade econômica) do cliente.
servicesAmount	número	sim	Valor dos serviços, em reais.
description	string		Discriminação do serviço na nota.
cityServiceCode	string		Código do serviço; normalmente o cityServiceCodeId do serviço escolhido.
issRate	número		Alíquota do ISS como fração.
issTaxAmount	número		Valor do ISS, em reais.
retentionType	NotWithheld · WithheldByBuyer		WithheldByBuyer quando o tomador retém o ISS.
issAmountWithheld	número		ISS retido, em reais (0 se não retido).
pisAmountWithheld	número
cofinsAmountWithheld	número
csllAmountWithheld	número
irAmountWithheld	número
inssAmountWithheld	número
additionalInformation	string		Informações complementares.
nbsCode	string		Código NBS (IBS/CBS), quando a empresa está no regime que exige.
ibsCbsClassCode	string ou null
ibsCbsOperationIndicator	string ou null
contractProductIds	número[]		Produtos do contrato do lançamento que entram na nota (opcional).
construction	object		Obrigatório para serviços de construção civil: CNO/CEI ou endereço da obra.
construction.workId	object
construction.workId.scheme	bra.cno · bra.cei
construction.workId.value	string		12 dígitos.
construction.siteAddress	object
construction.siteAddress.country	string
construction.siteAddress.postalCode	string
construction.siteAddress.street	string
construction.siteAddress.number	string
construction.siteAddress.district	string
construction.siteAddress.state	string
construction.siteAddress.city	object

Respostas

Status	Descrição
200	Nota emitida (ok: true) ou ainda em processamento (processing: true).
400	Pendências que impedem a emissão (lançamento não encontrado ou não é receita, cliente incompleto, serviço ausente, sem crédito de nota, recusa da prefeitura).
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Consultar indicadores do mês

POST /companie/financial/balanceIndicator/{columnDateFilter}/{month}/{year}

Totais de receitas e despesas do mês (exceto canceladas), com saldo anterior e saldo final. columnDateFilter: due_date (vencimento) ou received_date (pagamento). Usa o valor recebido quando houver; senão o valor do lançamento.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
columnDateFilter	URL	due_date · received_date	sim
month	URL	01 · 02 · 03 · 04 · 05 · 06 · 07 · 08 · …	sim
year	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
status_contract	Ativo · Ag.Pagamento · Cancelado · Inadimplente · Interrompido[]	sim	Filtra receitas pelo status do contrato. Obrigatório na prática: envie [] para não filtrar.

Respostas

Status	Descrição
200	Indicadores do mês.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Consultar o fluxo de caixa do mês

POST /companie/financial/cashFlow/{month}/{year}

Fluxo de caixa diário por conta do plano de contas. A data de cada lançamento é a do pagamento, se recebido; senão a do vencimento. Ignora lançamentos Vencida e Cancelada.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
month	URL	01 · 02 · 03 · 04 · 05 · 06 · 07 · 08 · …	sim
year	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
status_contract	Ativo · Ag.Pagamento · Cancelado · Inadimplente · Interrompido[]	sim	Filtra receitas pelo status do contrato. Obrigatório na prática: envie [] para não filtrar.

Respostas

Status	Descrição
200	Fluxo de caixa.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger