Esta página documenta mudanças importantes na API da Conta Azul, como novos endpoints, atualizações de comportamento, alterações de contrato e descontinuações. Siga este changelog para manter suas integrações atualizadas e compatíveis.
[Endpoint] Envia um documento para a captura e extração de dados
[O que?] Adicionado endpoint para envio de arquivos (PDF, JPEG, PNG ou BMP; máximo 10 MB) via multipart/form-data para extração automática de dados, retornando o ID do documento para acompanhamento do processamento.
[Por que?] Permitir a digitalização e extração automatizada de informações de documentos e comprovantes através de IA, reduzindo o trabalho manual.
[Exemplo]
[Endpoint] Consulta o status de documentos e das extrações (Captura)
[O que?] Adicionado endpoint para consulta assíncrona paginada do status de processamento de até 20 documentos por requisição e suas respectivas capturas extraídas.
[Por que?] Viabilizar o acompanhamento do fluxo assíncrono de processamento dos arquivos enviados até a conclusão da extração dos dados.
[Exemplo]
[Endpoint] Consulta os dados extraídos da captura do documento enviado
[O que?] Adicionado endpoint para obtenção dos dados extraídos pela IA e da sugestão de evento financeiro associada à captura no status PENDENTE.
[Por que?] Permitir a conferência e validação detalhada dos dados extraídos do documento antes da criação do lançamento no ERP.
[Exemplo]
[Endpoint] Aceita a prévia do evento financeiro da captura
[O que?] Adicionado endpoint para confirmação da prévia da captura e criação automática do evento financeiro correspondente na Conta Azul.
[Por que?] Automatizar a geração de contas a pagar e receber a partir de documentos digitalizados sem a necessidade de digitação manual.
[Exemplo]
[Endpoint] Recusa a captura (rejeita o evento financeiro sugerido)
[O que?] Adicionado endpoint para rejeição da sugestão de evento financeiro gerada pela IA, ocultando a captura do histórico de processamento.
[Por que?] Permitir o descarte de dados extraídos incorretamente ou de documentos que não devem gerar lançamentos no sistema financeiro.
[Exemplo]
[Endpoint] Atualizar uma venda por id
[O que?] Adicionado o campo id_vendedor no payload do método PUT.
[Por que?] Permite associar ou atualizar o vendedor responsável diretamente na edição da venda, garantindo a consistência das comissões e relatórios de vendas.
[Exemplo]
[Endpoint] Retornar empresa da conta conectada
[O que?] Inclusão do campo id_empresa na resposta do endpoint de empresa conectada.
[Por que?] Permite que os sistemas integrados identifiquem de forma direta a empresa que está conectada e operando na sessão atual, melhorando o controle de multi-empresas e a segurança na validação dos dados.
[Exemplo]
[Endpoint] Configuração de categorias padrão
[O que?] Disponibilizamos um novo endpoint que retorna o de-para entre as operações financeiras e as categorias configuradas na sua conta.
[Por que?] Permitir que sua integração consiga identificar de forma automática qual categoria está associada a cada tipo de operação (fretes, juros, multas, descontos, tarifas, etc.).
[Exemplo]
[Endpoint] Criar lançamento de contas a receber | Criar lançamento de contas a pagar
[O que?] Inclusão do campo metodo_pagamento dentro do objeto de parcelas.
[Por que?] Permitir que o usuário informe o método de pagamento do lançamento diretamente via API, o que antes não era possível, garantindo maior precisão no registro financeiro desde a sua criação.
[Exemplo]
[Endpoint] Criar uma nova venda
[O que?] Implementada a possibilidade de criar vendas com 100% de desconto, onde o valor do desconto pode ser igual ao somatório do valor total (quantidade x preço unitário) somado ao frete.
[Por que?] Permitir que a API suporte cenários de bonificação ou cortesias onde a parcela resulte em valor zerado, garantindo paridade de comportamento entre as integrações via API e a plataforma Web da Conta Azul.
[Exemplo]
[Endpoint] Criar um novo contrato
[O que?] Implementação de novas regras de validação para os campos de configuração do contrato:
- intervalo_frequencia: Deve estar entre 1 e 60. Valores 0 ou acima de 60 serão rejeitados.
- dia_emissao_venda: Valor máximo permitido: 31. Valores superiores serão rejeitados.
- primeira_data_vencimento e dia_vencimento: Os dois campos devem ser consistentes entre si. A primeira_data_vencimento não pode ser anterior à data atual.
- data_inicio e data_fim: A data_inicio não pode ser posterior à data_fim.
- frete: Apenas valores positivos serão aceitos. Valores negativos serão rejeitados.
- desconto: Não pode ser superior ao valor total dos itens do contrato.
[Por que?] Garantir a integridade dos dados e conformidade com as regras de negócio do ERP, evitando erros no processamento de vendas recorrentes e inconsistências financeiras.
[Endpoint] Listar orçamentos por filtros
[O que?] Implementação de novo endpoint para recuperação da listagem de orçamentos, permitindo o uso de múltiplos parâmetros de busca como período de datas (criação, alteração e orçamento), identificadores de clientes, vendedores, produtos, categorias e situações específicas.
[Por que?] Oferecer maior flexibilidade e performance na consulta de orçamentos, permitindo que sistemas externos construam visões personalizadas, relatórios e dashboards integrados ao fluxo de vendas da Conta Azul.
[Exemplo]
[Endpoint] Excluir orçamentos em lote
[O que?] Implementação de novo endpoint DELETE que permite a remoção de múltiplos orçamentos simultaneamente através do envio de uma lista de IDs no corpo da requisição.
[Por que?] Otimizar processos de limpeza de dados e sincronização entre sistemas, permitindo que o desenvolvedor remova grandes volumes de registros com uma única chamada, reduzindo o overhead de rede e processamento.
[Exemplo]
[Endpoint] Criar um novo orçamento
[O que?] Implementação de novo endpoint POST para criação de orçamentos no sistema, permitindo a definição de itens, clientes, vendedores, composição de valores (frete/desconto) e prazos.
[Por que?] Facilitar a automação comercial permitindo que sistemas externos registrem propostas e orçamentos diretamente no ERP, agilizando o fluxo de vendas e negociação.
[Exemplo]
[Endpoint] Retornar o orçamento por id
[O que?] Implementação de novo endpoint GET que permite a recuperação detalhada de um orçamento específico através do seu identificador único (UUID).
[Por que?] Facilita a integração de sistemas externos que necessitam exibir informações detalhadas, realizar auditorias ou sincronizar o status e itens de orçamentos específicos com a base de dados do ERP Conta Azul.
[Exemplo]
[Endpoint] Criar uma nova cobrança POST v1/financeiro/eventos-financeiros/contas-a-receber/gerar-cobranca
[O que?]
- Adição do campo maximo_parcelas no corpo da requisição.
[Por que?]
- Permitir que o integrador defina o limite máximo de parcelas permitidas para a geração de uma cobrança específica oferecendo maior controle sobre as condições de pagamento oferecidas ao cliente final.
[Exemplo]
[Endpoint] Retornar os contratos por filtro
[O que?]
- Adicionado os parâmetros 'tipo_pagamento' e 'status'.
- A resposta da API foi expandida para incluir o objeto 'conta_financeira' (id e tipo), o objeto 'termos' (data_fim, tipo_expiracao, vigencia_atual e vigencia_total), além dos campos 'tipo_pagamento', 'total' e 'total_proximo_vencimento'.
[Por que?] Amplia a capacidade de filtragem e detalhamento na consulta de contratos, permitindo uma gestão mais precisa do fluxo financeiro e das vigências contratuais diretamente via API.
[Exemplo]
[Endpoint] Encerrar um contrato
[O que ?] Adicionado novo endpoint para encerrar um contrato.
[Por que?] Permite encerrar um contrato ativo. O contrato que for encerrado não poderá gerar novas cobranças. Contratos que estão passando por reajuste de valor não podem ser encerrados.
[Exemplo]
[Endpoint] Remover um contrato
[O que ?] Adicionado novo endpoint para remover um contrato.
[Por que?] Permite remover um contrato de forma permanente, cancelando todas as vendas associadas (agendadas e efetivadas). Contratos em reajuste de valor não podem ser removidos.
[Exemplo]
[Endpoint] Retornar o contrato por id
[O que ?] Adicionado novo endpoint de retornar o contrato por ID.
[Por que?] Permite recuperar os detalhes de um contrato específico por ID. Útil quando quiser exibir ou sincronizar todos os dados de um contrato específico.
[Exemplo]
[Endpoint] Retornar a parcela por id
[O que ?] Adicionado novo campo codigo_referencia no retorno do endpoint.
[Por que?] Permitir a identificação e conciliação das parcelas.
[Exemplo]
[Endpoint] Retornar os saldos iniciais das contas financeiras
[O que ?] Adicionado o endpoint '/v1/financeiro/eventos-financeiros/saldo-inicial'.
[Por que?] Permite consultar os saldos iniciais das contas financeiras em um período definido por data de início e fim.
[Exemplo]
[Endpoint] Retornar os IDs dos eventos financeiros alterados em um período
[O que ?] Adicionado o endpoint '/v1/financeiro/eventos-financeiros/alteracoes'.
[Por que?] Permite consultar os IDs dos eventos financeiros para identificar quais eventos sofreram modificações recentes, facilitando a sincronização e o monitoramento de mudanças nos dados financeiros.
[Exemplo]
[Endpoint] Retornar dados da empresa conectada
[O que ?] Adicionado o endpoint '/v1/pessoas/conta-conectada'.
[Por que?] Permite consultar as informações cadastrais e de contato da empresa vinculada à sua integração.
[Exemplo]
[Endpoint]
[O que ?] Adicionado a possibilidade de fazer cadastro e alteração de itens que sejam kits em uma venda.
[Por que?] Permitir que parceiros desenvolvedores possam cadastrar e alterar itens que sejam kits em uma venda.
[Exemplo]
Criar uma nova venda
Atualizar uma venda por id
[Endpoint]
[O que ?] Adicionado o campo contato_cobranca_faturamento na atualização de pessoa.
[Por que?] Permitir que parceiros desenvolvedores possam garantir melhor governança de dados e suportar fluxos de cobrança.
[Exemplo]
Atualizar uma pessoa por id
Atualizar parcialmente uma pessoa por id
[Endpoint]
[O que ?] Adicionado o campo contato_cobranca_faturamento no retorno do endpoint.
[Por que?] Permitir que parceiros desenvolvedores possam garantir melhor governança de dados e suportar fluxos de cobrança.
[Exemplo]
Retornar a pessoa por id
Retornar a pessoa por legacyid
[Endpoint] Retornar as pessoas por filtro
[O que?] Adicionado intervalo máximo de 365 dias para consulta com data_alteracao_de e data_alteracao_ate
[Por que?]
Garantir que as consultas sejam eficientes, seguras, performáticas e dentro dos padrões de uso da plataforma, evitando indisponibilidades ou lentidão.
[Exemplo]
[Endpoint] Criar uma nova pessoa
[O que ?] Adicionado o campo contato_cobranca_faturamento para informar o contato responsável por cobrança e faturamento na criação de pessoa.
[Por que?] Permitir que parceiros desenvolvedores possam garantir melhor governança de dados e suportar fluxos de cobrança.
[Exemplo]
[Endpoint] Retornar transferências por período
[O que ?] Adicionado novo endpoint de consulta de transferências por período.
[Por que?] Viabilizar a conciliação financeira automática e sincronizar corretamente as movimentações.
[Exemplo]
[Endpoint] Retornar as receitas por filtro
[Endpoint] Retornar as despesas por filtro
[Endpoint] Retornar as vendas por filtro
[O que?] Adicionado intervalo máximo de 365 dias para consulta com data_alteracao_de e data_alteracao_ate
[Por que?]
Garantir que as consultas sejam eficientes, seguras, performáticas e dentro dos padrões de uso da plataforma, evitando indisponibilidades ou lentidão.
[Exemplo]
[Endpoint] Retornar os itens de uma venda pelo id da venda
[O que?]
- Filtrar por tamanho da página deve ser um dos seguintes valores: 10, 20, 50, 100, 200, 500 ou 1000.
- Adicionado o campo id_centro_custo no retorno dos itens de uma venda pelo id da venda.
[Por que?]
- Manter padrão de paginação entre os endpoints.
- Permitir que parceiros desenvolvedores identifiquem facilmente o centro de custo vinculado a cada item da venda.
[Exemplo]
Filtrar por tamanho da página:
Campo id_centro_custo no retorno do endpoint:
[Endpoint] Retornar o produto por id
[O que ?] Adicionado o campo url_imagem no retorno de produto por id.
[Por que?] Permitir que parceiros desenvolvedores possam realizar o download das imagens do produto.
[Exemplo]
[Endpoint] Retornar as receitas por filtro
[O que?] Adicionado o campo ids_clientes como filtro na requisição (aceita lista de IDs). Incluídos no retorno da API os campos data_competencia, centros_de_custo e categorias.
[Por que?] A inclusão do filtro ids_clientes permite correlacionar diretamente os lançamentos de receita ao cliente responsável. A disponibilização dos campos data_competencia, centros_de_custo e categorias no retorno possibilitará análises financeiras mais completas, automações contábeis, consolidações gerenciais e alinhamento entre critérios de filtro e dados retornados pela API.
[Exemplo] Filtro por ids_clientes e os campos data_competencia, centros_de_custo e categorias mapeados na resposta:
[Endpoint] Retornar as despesas por filtro
[O que?] Incluídos no retorno da API os campos data_competencia, centros_de_custo e categorias.
[Por que?] A disponibilização dos campos data_competencia, centros_de_custo e categorias no retorno possibilitará análises financeiras mais completas, automações contábeis, consolidações gerenciais e alinhamento entre critérios de filtro e dados retornados pela API.
[Exemplo] Campos data_competencia, centros_de_custo e categorias mapeados na resposta:
[Endpoint] Retornar notas fiscais de serviço por filtros
[O que?] Filtrar notas fiscais pelo ID (uuid) da NFS-e e receber esse identificador no retorno do endpoint.
[Por que?] Facilitar a conciliação, rastreabilidade e correlação das NFS-e entre sistemas internos e integrações externas.
[Exemplo]
Filtro por ids e id no retorno da request:
[Endpoint] Retornar a venda por id
[O que?] Alterado na resposta da request o enum tipo_pagamento de PAGAMENTO_INSTANTANEO para PIX_PAGAMENTO_INSTANTANEO
[Por que?] Para o método de pagamento PIX seja retornado e aceito de forma padronizada entre criação de venda, consulta por ID e criação de baixa
[Exemplo]
Método de pagamento (PIX_PAGAMENTO_INSTANTANEO):
[Endpoint] Retornar as vendas por filtro
[O que?] Adicionado o campo id_contrato no retorno das vendas por filtro.
[Por que?] Permitir que parceiros desenvolvedores identifiquem facilmente a origem de cada venda recorrente (contrato), suportando processos de conciliação, análise de recorrência.
[Exemplo]
Vendas do tipo contrato (SCHEDULED_SALE):
[Endpoint] Retornar a venda por id
[O que?] Adicionado objeto de contrato no retorno do endpoint.
[Por que?] Permitir que parceiros desenvolvedores identifiquem facilmente a origem de cada venda recorrente (contrato), suportando processos de conciliação, análise de recorrência.
[Exemplo]
Venda do tipo contrato (SCHEDULED_SALE):
Venda tipo venda avulsa (SALE) ou orçamento (SALE_PROPOSAL):
[Endpoint] Retornar as notas fiscais de serviço (NFS-e) por filtro
[O que?] Novo endpoint público para consulta e listagem de Notas Fiscais de Serviço (NFS-e).
[Por que?] Permitir que parceiros desenvolvedores realizem a listagem de NFS-e geradas no ERP, aplicando filtros para facilitar a busca, conciliação e acompanhamento fiscal.
[Exemplo]
Estamos realizando uma transição do canal de suporte aos desenvolvedores.
O atendimento que antes ocorria pelo e-mail api@contaazul.com passará a ser feito exclusivamente pelo Portal do Desenvolvedor.
O suporte por e-mail será gradativamente descontinuado até meados de janeiro/2026.
Após a descontinuação, o e-mail deixará de ser monitorado.
- Acesse o Portal do Desenvolvedor.
- Clique no ícone de suporte no canto inferior direito.
- Envie sua dúvida técnica ou abra um chamado diretamente pelo portal.
- A partir de meados de janeiro, não iremos mais dar suporte por e-mail.
- O Portal do Desenvolvedor passa a ser o canal oficial e exclusivo para suporte técnico.
- Melhor organização e rastreabilidade do atendimento.
- Centralização do histórico e mais agilidade na resolução.
- Experiência mais consistente para parceiros desenvolvedores.
[Configuração] Rate limit da API
[O que?] O limite de requisições foi atualizado para 600 por minuto e 10 por segundo, agora aplicado por conta conectada do ERP, e não mais por aplicação.
[Por que?] Com as recentes liberações dos filtros por data de atualização (Pessoas, Vendas, Receitas e Despesas), é possível consultar apenas os dados que foram alterados, reduzindo o volume desnecessário de requisições.
Essa mudança torna o consumo mais eficiente e permite ampliar o limite de contas conectadas do ERP em uma mesma aplicação, sem comprometer a estabilidade da API.
[Endpoint] Retornar as notas fiscais por filtro
[O que?] Novo filtro
[Por que?] Permitir a busca de notas fiscais por meio do ID de uma venda.
[Exemplo]
[Endpoint] Retornar os produtos por filtro
[O que?] Foram adicionados novos filtros aos parâmetros de consulta:
sku: permite busca exata por código de identificação do produto.data_alteracao_deedata_alteracao_ate: possibilitam filtrar produtos com base no período de alteração.
[Por que?] Esses filtros aumentam a precisão e a eficiência na consulta de produtos, facilitando a localização dos dados desejados conforme critérios específicos.
[Exemplo]
[Endpoint] Retornar o próximo número do contrato disponível
[O que?] Novo endpoint
[Por que?] Este endpoint tem como objetivo disponibilizar o próximo número do contrato para ser possível criar contratos de forma automatizada
[Exemplo]
[Endpoint] Retornar as parcelas pelo id do evento financeiro
[O que?]
Adicionado objeto de renegociação
Mapeado novos status:
- "RENEGOCIADO"
- "RECEBIDO_PARCIAL"
- "ATRASADO"
- "PERDIDO"
[Por que?] Necessidade de disponibilizar a informações de renegociação dentro da parcela. Exibir outras opções de status da parcela
[Exemplo]
Adicionado objeto de renegociação
Mapeado novos status
[Endpoint] Retornar a parcela por id
[O que?]
Adicionado objeto de renegociação
Mapeado novos status:
- "RENEGOCIADO"
- "RECEBIDO_PARCIAL"
- "ATRASADO"
- "PERDIDO"
[Por que?] Necessidade de disponibilizar a informações de renegociação dentro da parcela. Exibir outras opções de status da parcela
[Exemplo]
Adicionado objeto de renegociação
Mapeado novos status
[Endpoint] Retornar as receitas por filtro
[O que?] Adicionado objeto de renegociação
[Por que?] Necessidade de disponibilizar a informações de renegociação dentro da parcela
[Exemplo]
[Endpoint] Retornar as pessoas por filtro
[O que?] Novo filtro e novos campos retornados
[Por que?] Possibilitar a busca de pessoas pela data de/até da alteração da pessoa
[Exemplo]
[Endpoint] Retornar as vendas por filtro
[O que?] Novo filtro e novo campo retornado
[Por que?] Possibilitar a busca de vendas pela data de/até da alteração da venda
[Exemplo]
[Endpoint] Retorna receitas por filtro e Retorna despesas por filtro
[O que?] Novo filtro
[Por que?] Possibilitar a busca de receitas e despesas pela data de alteração da parcela
[Exemplo]
[Endpoint] Retornar os itens de uma venda pelo id da venda
[O que?] Novo campo retornado
[Por que?] Retornar o valor do custo do item da venda
[Exemplo]
[Endpoint] Buscar saldo atual da conta financeira
[O que?] Novo endpoint
[Por que?] Este endpoint tem como objetivo disponibilizar, de forma simples e direta, o saldo atual de uma conta financeira específica, identificada pelo id da conta financeira.
[Exemplo]
[Endpoint] Retorna a estrutura completa de categorias DRE
[O que?] Novo endpoint
[Por que?] Este endpoint tem como objetivo listar a estrutura completa de categorias da Demonstração do Resultado do Exercício (DRE), composta por categorias principais e subcategorias hierárquicas
[Exemplo]
[Endpoint] Retornar parcela por id
[O que?] Agora o endpoint passa a retornar também informações de rateio, centros de custo e categoria financeira associadas à parcela.
[Por que?] Para fornecer uma visão mais completa dos detalhamentos financeiros, permitindo análises mais precisas e integração mais rica por parte dos desenvolvedores.
[Exemplo]
[O que?] Inclusão de duas novas sessões no Portal do Desenvolvedor:
- FAQ, consolidando as dúvidas mais comuns dos desenvolvedores.
- Change Log, permitindo acompanhar facilmente todas as alterações, inclusões e evoluções das APIs e recursos da plataforma.
[Por que?] Para melhorar a navegação, facilitar a consulta e aumentar a autonomia dos desenvolvedores ao utilizar as APIs.