Conjunto de recursos para acompanhar e administrar operações relacionadas ao gerenciamento de baixas - esses recursos incluem criar uma nova baixa, retornar as baixas pelo id da parcela, atualizar parcialmente uma baixa por id, deletar baixa por id e retornar a baixa por id
openapi: 3.0.1
info:
title: Baixas v1 API
version: v1
description: "A API de Baixas tem como objetivo automatizar e simplificar o processo de conciliação financeira, permitindo o registro e o acompanhamento de pagamentos recebidos. Com ela, é possível criar uma nova baixa, retornar as baixas pelo id da parcela, atualizar parcialmente uma baixa, deletar uma baixa e retornar a baixa, garantindo que o status financeiro das cobranças seja atualizado de maneira precisa e em tempo real, reduzindo o retrabalho e evitando inconsistências entre sistemas.\n\nSe desejar aprofundar o entendimento das regras de negócio aplicadas pelo ERP, recomendamos, de forma opcional a consulta à nossa Central de Ajuda:\n\n**Lançamentos Financeiros:** \n[https://ajuda.contaazul.com/hc/pt-br/sections/20564397198989-Lan%C3%A7amentos-financeiros-contas-a-receber-e-a-pagar](https://ajuda.contaazul.com/hc/pt-br/sections/20564397198989-Lan%C3%A7amentos-financeiros-contas-a-receber-e-a-pagar)\n"
servers:
- url: https://api-v2.contaazul.com
description: Servidor de produção
security:
- BearerAuth: []
tags:
- name: v1
description: Conjunto de recursos para acompanhar e administrar operações relacionadas ao gerenciamento de baixas - esses recursos incluem criar uma nova baixa, retornar as baixas pelo id da parcela, atualizar parcialmente uma baixa por id, deletar baixa por id e retornar a baixa por id
paths:
/v1/financeiro/eventos-financeiros/parcelas/{parcela_id}/baixa:
post:
summary: Criar uma nova baixa
operationId: criarBaixa
description: Permite registrar uma nova baixa vinculada a uma parcela específica. Por meio desse endpoint, é possível informar os dados do pagamento, como data, valor, juros, multa, descontos e método de pagamento. Ao registrar a baixa, o sistema atualiza automaticamente o status da parcela refletindo a quitação realizada.
tags:
- v1
parameters:
- name: parcela_id
in: path
required: true
schema:
type: string
format: uuid
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BaixaCriacaoRequestDTO'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaixaCriacaoResponseDTO'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
get:
summary: Retornar as baixas pelo id da parcela
operationId: listarBaixas
description: Permite consultar todas as baixas associadas a uma determinada parcela. Essa funcionalidade possibilita o acompanhamento detalhado de pagamentos realizados, facilitando a auditoria e o controle financeiro.
tags:
- v1
parameters:
- name: parcela_id
in: path
required: true
schema:
type: string
format: uuid
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BaixaResponseDTO'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/eventos-financeiros/parcelas/baixa/{baixa_id}:
patch:
summary: Atualizar parcialmente uma baixa por id
operationId: atualizarBaixa
description: Permite atualizar parcialmente as informações de uma baixa. Use a baixa parcial quando houver pagamento ou recebimento parcial de uma fatura, seja por negociação com cliente/fornecedor ou em situações de inadimplência parcial. Por meio desse endpoint, é possível corrigir dados como valor, conta financeira, data de pagamento ou observações, mantendo o controle de versão para evitar conflitos de atualização.
tags:
- v1
parameters:
- name: baixa_id
in: path
required: true
schema:
type: string
format: uuid
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BaixaAtualizacaoRequestDTO'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaixaCriacaoResponseDTO'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
delete:
summary: Deletar baixa por id
operationId: deletarBaixa
description: Permite excluir uma baixa existente do sistema. Esse endpoint deve ser utilizado com cautela, pois a exclusão impacta diretamente o saldo e o histórico financeiro da parcela associada.
tags:
- v1
parameters:
- name: baixa_id
in: path
required: true
schema:
type: string
format: uuid
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
responses:
'200':
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
get:
summary: Retornar a baixa por id
operationId: buscarBaixa
description: Permite consultar os detalhes de uma baixa específica a partir do seu identificador único (baixa_id). O retorno inclui informações completas sobre a baixa, como data de pagamento, valores envolvidos, conta financeira utilizada, método de pagamento e observações registradas.
tags:
- v1
parameters:
- name: baixa_id
in: path
required: true
schema:
type: string
format: uuid
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaixaResponseDTO'
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/eventos-financeiros/contas-a-receber/cobranca/{id_cobranca}:
get:
summary: Retornar a cobrança por id
operationId: buscarCobrancaPorId
description: Permite consultar os detalhes de uma cobrança específica utilizando seu identificador único (id_cobranca).
tags:
- v1
parameters:
- name: id_cobranca
in: path
required: true
schema:
type: string
format: uuid
description: Identificador único da cobrança
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GerarCobrancaResponseDto'
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
delete:
summary: Deletar cobrança por id
operationId: deletarCobrancaPorId
description: Permite cancelar uma cobrança existente identificada por id_cobranca. É recomendada apenas quando a cobrança foi gerada incorretamente ou precisa ser invalidada antes de seu pagamento.
tags:
- v1
parameters:
- name: id_cobranca
in: path
required: true
schema:
type: string
format: uuid
description: Identificador único da cobrança
responses:
'200':
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/eventos-financeiros/contas-a-receber/gerar-cobranca:
post:
summary: Criar uma nova cobrança
operationId: criarCobranca
description: Permite criar uma nova cobrança, por meio desse endpoint, é possível informar o valor, data de vencimento, descrição da fatura e demais parâmetros que definem a cobrança. Essa funcionalidade facilita a geração automatizada de cobranças.
tags:
- v1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GerarCobrancaRequestDto'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GerarCobrancaResponseDto'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/contratos:
post:
summary: Criar um novo contrato
operationId: criarContrato
description: Permite criar um novo contrato, definindo as informações necessárias para configuração da recorrência, como período, produtos/serviços vinculados e demais parâmetros do contrato.
tags:
- v1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContratoToCreateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContratoToCreateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
get:
summary: Retornar os contratos por filtro
operationId: listarContratos
description: Permite consultar contratos existentes, com suporte a filtros que facilitam a busca e a gestão dos contratos criados (ex. por cliente, data, status, entre outros).
tags:
- v1
parameters:
- in: query
name: pagina
description: Página
example: 1
schema:
type: number
default: 1
- in: query
name: tamanho_pagina
description: Tamanho da página (máximo 50)
example: 10
schema:
type: number
default: 10
- in: query
name: campo_ordenado_ascendente
description: Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente.
schema:
type: string
enum:
- DATA_INICIO
- DATA_FIM
example: DATA_INICIO
- in: query
name: campo_ordenado_descendente
description: Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado.
schema:
type: string
enum:
- DATA_INICIO
- DATA_FIM
example: DATA_INICIO
- in: query
name: busca_textual
description: Busca textual por nome
example: Contrato 1
schema:
type: string
required: false
- in: query
name: cliente_id
description: id do cliente
schema:
type: string
format: uuid
- in: query
name: data_inicio
description: Data inicio do intervalo de busca
example: '2026-08-15'
required: true
schema:
type: string
format: date
- in: query
name: data_fim
description: Data fim do intervalo de busca
example: '2027-08-15'
required: true
schema:
type: string
format: date
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListagemContratoResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/contratos/proximo-numero:
get:
summary: Retornar o próximo número do contrato disponível
operationId: getNextContractNumber
description: Permite consultar o próximo número de contrato a ser utilizado no momento da criação.
tags:
- v1
responses:
'200':
description: OK
content:
application/json:
schema:
type: integer
format: int64
nullable: true
example: 4512645
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/centro-de-custo:
summary: Endpoint de Centros de Custo
get:
summary: Retornar os centros de custo por filtro
operationId: searchCostCenters
tags:
- v1
description: Permite consultar os centros de custo cadastrados. Suporta filtros como página, tamanho de página, busca por texto, status (ativo/inativo/todos) e ordenação. Utilizado para consultar lançamentos financeiros e facilitar análise orçamentária.
parameters:
- in: query
name: pagina
description: Página
example: 1
schema:
type: number
required: true
- in: query
name: tamanho_pagina
description: Tamanho da página
example: 10
schema:
enum:
- 10
- 20
- 50
- 100
- 200
- 500
- 1000
type: number
required: true
- in: query
name: busca
description: Busca textual por nome ou código
example: '010'
schema:
type: string
required: false
- in: query
name: filtro_rapido
description: Filtro rápido para itens ativos, inativos ou todos
example: ATIVO
schema:
type: string
enum:
- ATIVO
- INATIVO
- TODOS
required: false
- in: query
name: campo_ordenado_ascendente
description: Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente. É possível ordenar por nome ou por código
example: nome
schema:
type: string
required: false
- in: query
name: campo_ordenado_descendente
description: Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado. É possível ordenar por nome ou por código
example: nome
schema:
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CentroDeCustoResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
post:
summary: Criar um novo centro de custo
operationId: createCostCenter
tags:
- v1
description: Permite criar um novo centro de custo, definindo campos como código, nome, parâmetros que ajudam a organizar os custos da empresa de forma estruturada.
requestBody:
description: Dados do centro de custo a ser criado
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CriacaoCentroDeCustoRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CentroDeCusto'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/eventos-financeiros/{id_evento}/parcelas:
summary: Endpoint de parcelas por evento financeiro
get:
summary: Retornar as parcelas pelo id do evento financeiro
operationId: getInstallmentsByEventId
description: Permite listar as parcelas vinculadas a um evento financeiro específico (id_evento). Útil para acompanhar cada parcela de um lançamento de contas a pagar ou receber, com seus valores, vencimentos e status e outras informações pertinentes.
tags:
- v1
parameters:
- name: id_evento
in: path
description: uuid ou id legado do evento
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Parcela'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/categorias:
summary: Endpoint de Categorias
get:
summary: Retornar as categorias por filtro
operationId: searchCategories
tags:
- v1
description: Permite listar as categorias utilizadas para classificação de receitas ou despesas. Auxilia no controle, agrupamento e geração de relatórios financeiros baseados em categorias.
parameters:
- in: query
name: pagina
description: Página
example: 1
schema:
type: number
required: true
- in: query
name: tamanho_pagina
description: Tamanho da página
example: 10
schema:
enum:
- 10
- 20
- 50
- 100
- 200
- 500
- 1000
type: number
required: true
- in: query
name: campo_ordenado_ascendente
description: Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente. É possível ordenar por 'NOME' ou 'TIPO'
example: NOME
schema:
type: string
enum:
- NOME
- TIPO
required: false
- in: query
name: campo_ordenado_descendente
description: Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado. É possível ordenar por 'NOME' ou 'TIPO'
example: TIPO
schema:
type: string
enum:
- NOME
- TIPO
required: false
- in: query
name: busca
description: Busca textual por nome ou código
example: '010'
schema:
type: string
required: false
- in: query
name: tipo
description: Tipo da categoria
example: RECEITA
schema:
type: string
enum:
- RECEITA
- DESPESA
required: false
- in: query
name: apenas_filhos
description: Filtrar apenas categorias filhas
example: true
schema:
type: boolean
required: false
- in: query
name: nome
description: Nome da categoria
example: Eletrônicos
schema:
type: string
required: false
- in: query
name: permite_apenas_filhos
description: Permite apenas categorias filhas
example: true
schema:
type: boolean
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
itens_totais:
type: integer
example: 6
itens:
type: array
items:
$ref: '#/components/schemas/Categoria'
totais:
$ref: '#/components/schemas/Totais'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/categorias/configuracao-padrao:
summary: Configuração padrão de categorias
get:
summary: Retornar a configuração de de-para de categorias
operationId: getDefaultCategoryConfig
tags:
- v1
description: Retorna o de-para entre as operações financeiras e as categorias configuradas para o tenant, incluindo opcionalmente a sugestão padrão de categoria para cada operação.
parameters:
- in: query
name: sugestao_padrao
description: Quando verdadeiro (padrão), inclui o objeto `sugestao_padrao` em cada item. Quando falso, o campo `sugestao_padrao` é retornado como `null`.
example: true
schema:
type: boolean
default: true
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConfiguracaoPadraoCategoria'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/categorias-dre:
get:
summary: Retornar as categorias DRE
operationId: searchDreCategories
description: Permite listar as categorias de DRE (Demonstração do Resultado do Exercício) usadas para a estrutura contábil-financeira da empresa, facilitando o fechamento financeiro e contábil.
tags:
- v1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EstruturaDRE'
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/conta-financeira:
summary: Endpoint de Contas Financeiras
get:
summary: Retornar as contas financeiras por filtro
operationId: searchFinancialAccounts
tags:
- v1
description: Permite consultar as contas financeiras existentes no sistema (contas bancárias, cartões, poupança, etc.). Suporta filtros como tipo de conta, nome, se estão ativas, entre outros.
parameters:
- name: pagina
in: query
description: Página
required: false
example: 1
schema:
type: integer
default: 1
- name: tamanho_pagina
in: query
description: Tamanho da página
example: 10
schema:
enum:
- 10
- 20
- 50
- 100
- 200
- 500
- 1000
type: integer
required: false
- name: tipos
in: query
description: Lista de tipos de conta
example: APLICACAO
required: false
schema:
type: array
items:
type: string
enum:
- APLICACAO
- CAIXINHA
- CONTA_CORRENTE
- CARTAO_CREDITO
- INVESTIMENTO
- OUTROS
- MEIOS_RECEBIMENTO
- POUPANCA
- COBRANCAS_CONTA_AZUL
- RECEBA_FACIL_CARTAO
- name: nome
in: query
description: Nome da conta
example: Conta corrente
required: false
schema:
type: string
- name: apenas_ativo
in: query
description: Filtrar apenas contas ativas
example: true
required: false
schema:
type: boolean
- name: esconde_conta_digital
in: query
description: Esconder contas digitais
example: true
required: false
schema:
type: boolean
- name: mostrar_caixinha
in: query
description: Mostrar contas de caixinha
example: true
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
itens_totais:
type: integer
example: 6
itens:
type: array
items:
$ref: '#/components/schemas/ContaFinanceira'
totais:
$ref: '#/components/schemas/Totais'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/conta-financeira/{id_conta_financeira}/saldo-atual:
summary: Endpoint de saldo atual da conta financeira
get:
summary: Retornar o saldo atual pelo id da conta financeira
operationId: searchBalanceByFinancialAccountId
tags:
- v1
description: Permite obter o saldo atual de uma conta financeira específica identificada por id_conta_financeira. Útil para monitoramento em tempo real de saldos das contas da empresa.
parameters:
- name: id_conta_financeira
in: path
description: uuid da conta financeira
example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SaldoAtualResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: O valor 'fbbccb85-a71a-4dfdb699-56ac1b5f1115' fornecido no parâmetro 'id_conta_financeira' não é um identificador (uuid) válido.
example:
code: 400
message: O valor 'fbbccb85-a71a-4dfdb699-56ac1b5f1115' fornecido no parâmetro 'id_conta_financeira' não é um identificador (uuid) válido.
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: The Token has expired.
example:
code: 401
message: The Token has expired.
'429':
description: Too Many Requests
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: Ocorreu um erro inesperado no servidor. Tente novamente mais tarde.
example:
code: 500
message: Ocorreu um erro inesperado no servidor. Tente novamente mais tarde.
/v1/financeiro/transferencias:
summary: Endpoint de Transferências entre Contas Financeiras
get:
summary: Retornar as transferências entre contas financeiras por filtro
operationId: searchAccountingExportTransfers
tags:
- v1
description: Permite consultar as transferências realizadas entre contas financeiras mediante filtros como período de datas e contas financeiras específicas. Para viabilizar a conciliação financeira automática e sincronizar corretamente as movimentações no meu sistema.
parameters:
- name: pagina
in: query
description: Número da página para paginação dos resultados
example: 1
required: false
schema:
type: integer
default: 1
minimum: 1
- name: tamanho_pagina
in: query
description: Quantidade de itens por página
example: 10
required: false
schema:
type: integer
default: 10
enum:
- 10
- 20
- 50
- 100
- 200
- 500
- 1000
- name: ids_conta_financeira
in: query
description: Lista de identificadores (UUIDs) das contas financeiras para filtrar as transferências. Retorna transferências onde as contas especificadas sejam origem ou destino.
example:
- 35473eec-4e74-11ee-b500-9f61de8a8b8b
- 8f2a3e45-1c9d-4b3a-a7f1-9e8d7c6b5a4f
required: false
schema:
type: array
items:
type: string
format: uuid
- name: data_inicio
in: query
description: Data inicial do período para filtrar as transferências (formato ISO date)
example: '2026-01-01'
required: false
schema:
type: string
format: date
- name: data_fim
in: query
description: Data final do período para filtrar as transferências (formato ISO date)
example: '2026-12-31'
required: false
schema:
type: string
format: date
responses:
'200':
description: OK - Retorna a lista paginada de transferências entre contas financeiras
content:
application/json:
schema:
$ref: '#/components/schemas/TransferenciaContaFinanceiraResponse'
examples:
exemplo_sucesso:
summary: Exemplo de resposta com transferências
value:
itens_totais: 2
itens:
- id: 35473eec-4e74-11ee-b500-9f61de8a8b8b
descricao: Transferência para conta poupança
valor: 1500.5
data: '2026-02-15'
origem:
data: '2026-02-15'
composicao_valor:
valor_bruto: 1500.5
juros: 0
multa: 0
valor_liquido: 1500.5
desconto: 0
taxa: 0
conta_financeira:
id: 8f2a3e45-1c9d-4b3a-a7f1-9e8d7c6b5a4f
nome: Conta Corrente Principal
instituicao_bancaria:
codigo: 1
nome: Ban
# --- truncated at 32 KB (230 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/conta-azul/refs/heads/main/openapi/conta-azul-v1-api-openapi.yml