A API de Financeiro tem como objetivo oferecer um conjunto de recursos para gerenciar de forma programática os principais aspectos financeiros de uma empresa, desde a criação de eventos de contas a receber ou pagar, passando pela gestão de contas financeiras, centros de custo, categorias, até a cons
openapi: 3.0.1
info:
title: Financeiro
version: v1
description: >
A API de Financeiro tem como objetivo oferecer um conjunto de recursos para
gerenciar de forma programática os principais aspectos financeiros de uma
empresa, desde a criação de eventos de contas a receber ou pagar, passando
pela gestão de contas financeiras, centros de custo, categorias, até a
consulta de saldos. Com esta API, sistemas podem integrar de forma fluida
com o módulo financeiro da Conta Azul, garantindo que lançamentos, saldos,
classificações e relatórios estejam sempre sincronizados.
Se desejar aprofundar o entendimento das regras de negócio aplicadas pelo
ERP, recomendamos, de forma opcional a consulta à nossa Central de Ajuda:
**Contas a pagar e receber:**
[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)
**Cadastro e gestão de contas financeiras:**
[https://ajuda.contaazul.com/hc/pt-br/sections/20546846147981-Cadastro-e-gest%C3%A3o-de-contas-financeiras](https://ajuda.contaazul.com/hc/pt-br/sections/20546846147981-Cadastro-e-gest%C3%A3o-de-contas-financeiras)
**Categorias financeiras e centro de custos:**
[https://ajuda.contaazul.com/hc/pt-br/sections/28553633338765-Categorias-financeiras-e-centros-de-custo](https://ajuda.contaazul.com/hc/pt-br/sections/28553633338765-Categorias-financeiras-e-centros-de-custo)
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 as finanças da empresa
- esses recursos incluem centros de custo, parcelas, categorias,
categorias dre, contas financeiras e movimentações (contas a pagar e a
receber)
paths:
/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: Banco do Brasil
destino:
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: 7d1b2c34-8a5e-4f6d-b9c2-3e4f5a6b7c8d
nome: Conta Poupança
instituicao_bancaria:
codigo: 1
nome: Banco do Brasil
- id: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
descricao: Transferência para investimento
valor: 5000
data: '2026-02-20'
origem:
data: '2026-02-20'
composicao_valor:
valor_bruto: 5000
juros: 0
multa: 0
valor_liquido: 5000
desconto: 0
taxa: 0
conta_financeira:
id: 8f2a3e45-1c9d-4b3a-a7f1-9e8d7c6b5a4f
nome: Conta Corrente Principal
instituicao_bancaria:
codigo: 341
nome: Itaú
destino:
data: '2026-02-20'
composicao_valor:
valor_bruto: 5000
juros: 0
multa: 0
valor_liquido: 5000
desconto: 0
taxa: 0
conta_financeira:
id: 6c5d4e3f-2a1b-9c8d-7e6f-5a4b3c2d1e0f
nome: Conta Investimento
instituicao_bancaria:
codigo: 341
nome: Itaú
exemplo_vazio:
summary: Exemplo de resposta sem transferências
value:
itens_totais: 0
itens: []
'400':
description: Bad Request - Parâmetros inválidos na requisição
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: A data de início não pode ser posterior à data de fim.
examples:
data_invalida:
summary: Erro de validação de datas
value:
code: 400
message: A data de início não pode ser posterior à data de fim.
uuid_invalido:
summary: Erro de UUID inválido
value:
code: 400
message: >-
O valor fornecido no parâmetro 'ids_conta_financeira' não
é um identificador (uuid) válido.
'401':
description: Unauthorized - Token de autenticação inválido ou expirado
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 - Limite de requisições excedido
'500':
description: Internal Server Error - Erro interno no servidor
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/eventos-financeiros/contas-a-receber:
post:
summary: Criar um novo evento financeiro de contas a receber
operationId: createReceivableFinancialEvent
description: >-
Permite criar um novo evento financeiro de contas a receber, passando
dados como data de competência, valor, descrição, conta financeira,
condições de pagamento, entre outros. Facilita o registro de receitas
previstas ou realizadas.
tags:
- v1
requestBody:
description: Dados do evento financeiro de contas a receber
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventoFinanceiroRequest'
responses:
'202':
description: Evento financeiro de contas a receber criado com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/ProtocolResponseDTO'
'400':
description: Bad Request
'401':
description: Unauthorized
'429':
description: Too Many Requests
'500':
description: Internal Server Error
/v1/financeiro/eventos-financeiros/contas-a-receber/buscar:
summary: Endpoint de Contas a Receber
get:
summary: Retornar as receitas por filtro
operationId: searchInstallmentsToReceiveByFilter
description: >-
Permite consultar as parcelas de receitas (contas a receber) mediante
filtros como data de vencimento, data de competência, data de pagamento,
data de alteração, valor, status, dentre outros. Essa funcionalidade
ajuda no controle e análise de entradas financeiras com base nas
condições definidas.
tags:
- v1
parameters:
- name: pagina
in: query
description: Página
example: 1
required: true
schema:
type: integer
default: 1
minimum: 1
- name: tamanho_pagina
in: query
description: Tamanho da página
example: 10
schema:
enum:
- 10
- 20
- 50
- 100
- 200
- 500
- 1000
type: integer
minimum: 1
required: true
- name: campo_ordenado_ascendente
in: query
description: >-
Campo para ordenação ascendente. Se informado ele desconsidera o
valor do campo_ordenado_descendente. É possível ordenar por nome
required: false
example: nome
schema:
type: string
- name: campo_ordenado_descendente
in: query
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
example: nome
required: false
schema:
type: string
- name: descricao
in: query
description: Descrição da conta
example: Conta Corrente
required: false
schema:
type: string
- name: data_vencimento_de
in: query
description: Data de vencimento de (ISO date format)
example: '2027-08-15'
required: true
schema:
type: string
format: date
- name: data_vencimento_ate
in: query
description: Data de vencimento até (ISO date format)
example: '2027-08-20'
required: true
schema:
type: string
format: date
- name: data_competencia_de
in: query
description: Data de competência de (ISO date format)
example: '2025-08-15'
required: false
schema:
type: string
format: date
- name: data_competencia_ate
in: query
description: Data de competência até (ISO date format)
example: '2025-08-20'
required: false
schema:
type: string
format: date
- name: data_pagamento_de
in: query
description: Data de pagamento de (ISO date format)
example: '2025-08-15'
required: false
schema:
type: string
format: date
- name: data_pagamento_ate
in: query
description: Data de pagamento até (ISO date format)
example: '2025-08-20'
required: false
schema:
type: string
format: date
- name: data_alteracao_de
in: query
description: Data de alteração de (ISO 8601, São Paulo/GMT-3)
example: '2025-10-20T07:00:00'
required: false
schema:
type: string
format: date-time
- name: data_alteracao_ate
in: query
description: Data de alteração até (ISO 8601, São Paulo/GMT-3)
example: '2025-10-20T07:59:59'
required: false
schema:
type: string
format: date-time
- name: valor_de
in: query
description: Valor de
example: '100'
required: false
schema:
type: string
pattern: ^[0-9]+(\.[0-9]{1,2})?$
example: '999.99'
- name: valor_ate
in: query
description: Valor até
example: '500'
required: false
schema:
type:
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/conta-azul/refs/heads/main/openapi/conta-azul-financial-openapi.yml