📚 DICIONÁRIO COMPLETO CONTA AZUL. Consulte para ver payloads, limites, cURLs e regras das rotas de OAuth, Pessoas, Produtos, Vendas, Financeiro, Notas Fiscais e Contratos.
⚠️ DOCUMENTO MESTRE — Atualizado em Mar/2026 com toda a documentação oficial do Portal do Desenvolvedor Conta Azul. Organizado por área: Autenticação | Pessoas/Clientes | Produtos | Vendas | Financeiro | |
| Item | Valor |
|---|---|
| Base URL | https://api-v2.contaazul.com |
| Auth URL | https://auth.contaazul.com |
| Estilo | REST |
| Formato | JSON |
| Autenticação | OAuth 2.0 (Bearer JWT) |
| Header | Authorization: Bearer <access_token> |
| Rate Limit | 600 req/min e 10 req/seg por conta conectada do ERP |
| Paginação | pagina (int) + tamanho_pagina (int) |
| Datas | ISO 8601 — YYYY-MM-DDTHH:mm:ss (sem Z, fuso SP/GMT-3 salvo indicação) |
| Sandbox | ❌ Não existe. Use App de Desenvolvimento (conta fictícia por 30 dias) |
| Webhooks | ❌ Não existem. Use polling periódico |
| SDKs | ❌ Não existem. Use chamadas HTTP diretas |
| Suporte | Portal do Desenvolvedor → ícone chat inferior direito |
| Código | Significado |
|---|---|
200 | Sucesso |
202 | Aceito (processamento assíncrono em Financeiro) |
400 | Payload inválido / campos faltando |
401 | Token expirado ou inválido |
404 | Recurso não encontrado |
429 | Rate limit excedido — implemente backoff exponencial |
500 | Erro interno CA — tente novamente em alguns segundos |
O Conta Azul usa o fluxo Authorization Code do OAuth 2.0.
Redirecione o usuário para o portal Conta Azul para conceder permissão à sua aplicação. O CA retornará um code (válido por 3 minutos) na redirect_uri.
curl --location 'https://auth.contaazul.com/oauth2/token' \
--header 'Authorization: Basic BASE64(SEU_CLIENT_ID:SEU_CLIENT_SECRET)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=CODIGO_AUTORIZACAO' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=SUA_URL_REDIRECIONAMENTO'
Como gerar o Base64:
- Linux/mac:
echo -n "client_id:client_secret" | base64- Windows PowerShell:
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("client_id:client_secret"))
{
"access_token": "ACCESS_TOKEN_GERADO",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN_GERADO",
"token_type": "Bearer"
}
| Token | Validade | Uso |
|---|---|---|
access_token | 3600 seg (1 hora) | Header de todas as requisições à API |
refresh_token | 5 anos ou até próxima renovação | Renovar o access_token quando expira |
⚠️ CRÍTICO: Salve o
refresh_tokena cada renovação — ele muda a cada uso.
Quando o access_token expirar, use o refresh_token para obter um novo par de tokens sem re-autenticar o usuário.
Todas as chamadas à API devem incluir:
Authorization: Bearer <access_token>
NUNCA use
axios.get()ouaxios.post()diretamente. UsecontaAzulService._axiosGet(url, 'LOG_NAME')para GETs, pois ele intercepta erros401e renova o token automaticamente. Para POST/PUT, capture o token comcontaAzulService.getAccessToken()e em caso de401force renovação comgetAccessToken(true).
Base URL: https://api-v2.contaazul.com/v1/pessoas
⚠️ O filtro de data (
data_alteracao_de/data_alteracao_ate) exige ambos os campos e formato sem milissegundos e sem Z (YYYY-MM-DDTHH:mm:ss), caso contrário retorna erro 500.
Consulta pessoas cadastradas com suporte a filtros.
| Parâmetro | Tipo | Obrig.? | Descrição |
|---|---|---|---|
pagina | integer | Sim | Número da página |
tamanho_pagina | integer | Sim | Itens por página |
tipo_perfil | string | Sim | Cliente, Fornecedor, Transportadora |
busca | string | Não | Busca por documento ou nome |
ids | string | Não | UUIDs separados por vírgula |
documentos | string | Não | CPF/CNPJ |
emails | string | Não | Emails |
nomes | string | Não | Nomes |
telefones | string | Não | Telefones |
tipos_pessoa | string | Não | Fisica, Juridica, Estrangeira |
ufs | string | Não | Siglas de estados |
cidades | string | Não | Cidades |
paises | string | Não | Países |
codigos_pessoa | string | Não | Códigos internos |
data_criacao_inicio | string | Não | Data inicial de criação |
data_criacao_fim | string | Não | Data final de criação |
data_alteracao_de | string | Cond. | ISO YYYY-MM-DDTHH:mm:ss — obrig. junto com ate |
data_alteracao_ate | string | Cond. | ISO YYYY-MM-DDTHH:mm:ss — obrig. junto com de |
com_endereco | boolean | Não | Incluir endereços na resposta |
tipo_ordenacao | string | Não | nome, email, documento, ativo |
ordem_ordenacao | string | Não | ASC, DESC |
curl -X GET \
'https://api-v2.contaazul.com/v1/pessoas?pagina=1&tamanho_pagina=50&tipo_perfil=Cliente&data_alteracao_de=2024-01-01T00:00:00&data_alteracao_ate=2024-01-31T23:59:59' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X POST 'https://api-v2.contaazul.com/v1/pessoas' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{...}'
{
"nome": "João Silva",
"tipo_pessoa": "Juridica",
"cnpj": "12.345.678/0001-90",
"nome_fantasia": "Empresa LTDA",
"email": "[email protected]",
"ativo": true,
"agencia_publica": false,
"optante_simples": false,
"codigo": "CLI001",
"data_nascimento": "1990-01-01",
"observacao": "Cliente preferencial",
"perfis": [
{ "tipo_perfil": "Cliente" }
],
"enderecos": [
{
"logradouro": "Rua das Flores",
"numero": "123",
"complemento": "Apto 45",
"bairro": "Centro",
"cidade": "São Paulo",
"estado": "SP",
"cep": "12345-678",
"pais": "Brasil"
}
],
"inscricoes": [
{
"indicador_inscricao_estadual": "NAO CONTRIBUINTE",
"inscricao_estadual": "ISENTO"
}
],
"outros_contatos": []
}
Substitui integralmente o cadastro. Todos os campos obrigatórios devem ser enviados.
curl -X PUT 'https://api-v2.contaazul.com/v1/pessoas/UUID-DA-PESSOA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ ...payload_completo... }'
Atualiza apenas os campos enviados.
curl -X PATCH 'https://api-v2.contaazul.com/v1/pessoas/UUID-DA-PESSOA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"telefones": [{ "numero": "11999999999", "tipo": "CELULAR" }]
}'
curl -X GET 'https://api-v2.contaazul.com/v1/pessoas/UUID-DA-PESSOA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Para compatibilidade com sistemas que guardam o ID numérico antigo da API V1.
curl -X GET 'https://api-v2.contaazul.com/v1/pessoas/legado/123456' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X POST 'https://api-v2.contaazul.com/v1/pessoas/ativar' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "uuids": ["UUID-1", "UUID-2"] }'
curl -X POST 'https://api-v2.contaazul.com/v1/pessoas/inativar' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "uuids": ["UUID-1", "UUID-2"] }'
curl -X POST 'https://api-v2.contaazul.com/v1/pessoas/excluir' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "uuids": ["UUID-1", "UUID-2"] }'
Além dos campos padrão do CA, a tabela clientes local possui:
| Campo | Tipo | Descrição |
|---|---|---|
id_vendedor | String | ID do Vendedor responsável (FK vendedores) |
Dia_de_entrega | String | Dia da semana fixo para entrega |
Dia_de_venda | String | Dia da semana fixo para visita/contato |
Condicao_de_pagamento | String | ID da tabela de preços (1000, BOL_7, etc.) |
Formas_Atendimento | String[] | Array de canais (WHATSAPP, VISITA, etc.) |
Base URL: https://api-v2.contaazul.com/v1/produtos
| Parâmetro | Tipo | Descrição |
|---|---|---|
pagina | integer | Número da página |
tamanho_pagina | integer | Itens por página |
busca | string | Busca textual (Nome, EAN, SKU) |
status | string | ATIVO ou INATIVO |
sku | string | Filtro exato por SKU (adicionado Nov/2025) |
data_alteracao_de | string | ISO 8601 — Data inicial de alteração (adicionado Nov/2025) |
data_alteracao_ate | string | ISO 8601 — Data final de alteração (adicionado Nov/2025) |
integracao_ecommerce_ativo | boolean | Filtrar integrados via e-commerce |
produtos_kit_ativo | boolean | Filtrar kits |
valor_venda_inicial | number | Range de preço inicial |
valor_venda_final | number | Range de preço final |
campo_ordenacao | string | Campo para ordenar |
direcao_ordenacao | string | ASC ou DESC |
curl -X GET \
'https://api-v2.contaazul.com/v1/produtos?pagina=1&tamanho_pagina=50&status=ATIVO&data_alteracao_de=2024-01-01T00:00:00&data_alteracao_ate=2024-01-31T23:59:59' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
{
"items": [
{
"id": "030bfa5e-e7b4-434d-aaab-bd1833056c74",
"nome": "COXINHA TRADICIONAL FRANGO C/20 130GR",
"codigo_sku": "3059",
"codigo_ean": "7898620330224",
"status": "ATIVO",
"categoria": {
"id": 61589260,
"descricao": "Produto Acabado",
"uuid": "b96ad226-588e-49b2-bdc7-9c97d97ffa22"
},
"ultima_atualizacao": "2026-01-20T10:51:05.706929Z"
}
],
"totalItems": 232
}
⚠️ IMPORTANTE: A listagem retorna estrutura simplificada. Para dados completos (estoque, custos), use o endpoint de detalhes
GET /v1/produtos/{id}.
curl -X GET 'https://api-v2.contaazul.com/v1/produtos/UUID-DO-PRODUTO' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
{
"id": "030bfa5e-e7b4-434d-aaab-bd1833056c74",
"id_legado": 462908994,
"ativo": true,
"nome": "COXINHA TRADICIONAL FRANGO C/20 130GR",
"codigo_sku": "3059",
"codigo_ean": "7898620330224",
"status": "ATIVO",
"formato": "SIMPLES",
"categoria": {
"id": 61589260,
"descricao": "Produto Acabado",
"uuid": "b96ad226-588e-49b2-bdc7-9c97d97ffa22"
},
"estoque": {
"quantidade_total": 120,
"quantidade_disponivel": 120,
"quantidade_reservada": 0,
"minimumStock": 180,
"valor_venda": 54.5,
"custo_medio": 3.35
},
"fiscal": {
"origem": "NACIONAL",
"tipo_produto": "PRODUTO_ACABADO",
"ncm": {
"id": 617762,
"codigo": "19022000",
"descricao": "Massas aliments.recheadas"
},
"cest": {},
"unidade_medida": { "id": 51617379, "descricao": "PT" }
},
"pesos_dimensoes": {
"peso_liquido": 1.25,
"peso_bruto": 1.35
},
"url_imagem": "https://...",
"ultima_atualizacao": "2026-01-20T10:51:05.706929Z"
}
⚠️ Campos críticos:
estoque.valor_venda— Preço está dentro do objetoestoque, não na raizestoque.custo_medio— Custo está dentro deestoque, não na raizestoque.minimumStock— camelCase! (nãoestoque_minimo)url_imagem— adicionado em Dez/2025 para download de imagens
curl -X POST 'https://api-v2.contaazul.com/v1/produtos' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{...}'
{
"nome": "Nome do Produto",
"codigo_sku": "SKU123",
"codigo_ean": "EAN123",
"valor_venda": 100.00,
"ativo": true,
"unidade_medida": { "id": 51617379 },
"categoria": { "id": 61589260 },
"fiscal": {
"ncm": { "id": 617762 },
"cest": { "id": 1 },
"origem": "NACIONAL",
"tipo_produto": "MERCADORIA_PARA_REVENDA"
},
"estoque": {
"estoque_disponivel": 50,
"estoque_minimo": 10
},
"pesos_dimensoes": {
"peso_liquido": 1.0,
"peso_bruto": 1.1
}
}
⚠️ IDs de NCM, Categoria e Unidade devem ser buscados previamente nos endpoints auxiliares. Não é possível enviar strings diretamente.
Atualiza apenas os campos enviados (nome, EAN, SKU, NCM, peso, valor_venda, unidade_medida, etc.).
curl -X PATCH 'https://api-v2.contaazul.com/v1/produtos/UUID-DO-PRODUTO' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "valor_venda": 59.90, "nome": "Novo Nome" }'
curl -X DELETE 'https://api-v2.contaazul.com/v1/produtos/UUID-DO-PRODUTO' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
| Endpoint | Descrição | Filtros |
|---|---|---|
GET /v1/produtos/categorias | Categorias de produto | busca_textual, pagina, tamanho_pagina |
GET /v1/produtos/unidades-medida | Unidades de medida | busca_textual |
GET /v1/produtos/ncm | Códigos NCM fiscais | busca_textual (por código ou descrição) |
GET /v1/produtos/cest | Códigos CEST fiscais | busca_textual |
GET /v1/produtos/ecommerce-categorias | Categorias e-commerce | descricao |
GET /v1/produtos/ecommerce-marcas | Marcas e-commerce | nome, pagina |
# Exemplo: buscar unidades de medida
curl -X GET 'https://api-v2.contaazul.com/v1/produtos/unidades-medida?busca_textual=PT' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Base URL: https://api-v2.contaazul.com/v1/venda
⚠️ CRÍTICO [FEV/2026]: Use exclusivamente
api-v2.contaazul.com. A antigaapi.contaazul.comrejeita os novos tokens Cognito com401 Unauthorized.
curl -X GET 'https://api-v2.contaazul.com/v1/venda/vendedores' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
[
{
"id": "cd3dff75-91e1-4284-8d20-f933b7ae31e3",
"nome": "Clarkson Neitzel",
"id_legado": null
}
]
curl -X GET 'https://api-v2.contaazul.com/v1/venda/proximo-numero' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
⚠️ Pode retornar texto puro (não JSON). Trate com
Number(response.body)antes deJSON.parse.
| Parâmetro | Tipo | Descrição |
|---|---|---|
pagina | integer | Página |
tamanho_pagina | integer | Itens por página |
data_inicio | string | Data início da emissão (YYYY-MM-DD) |
data_fim | string | Data fim da emissão (YYYY-MM-DD) |
data_criacao_de | string | Data criação de (YYYY-MM-DD) |
data_criacao_ate | string | Data criação até (YYYY-MM-DD) |
data_alteracao_de | string | Data alteração de (ISO, SP/GMT-3) — adicionado Nov/2025 |
data_alteracao_ate | string | Data alteração até (ISO, SP/GMT-3) |
termo_busca | string | Busca por nome/email do cliente ou número da venda |
ids_vendedores | array | IDs dos vendedores |
ids_clientes | array | IDs dos clientes |
ids_produtos | array | IDs dos produtos |
ids_categorias | array | IDs das categorias |
ids_natureza_operacao | array | IDs da natureza de operação |
numeros | array | Números das vendas |
situacoes | array | Situações das vendas |
tipos | array | Tipos de venda (SALE, SCHEDULED_SALE, SALE_PROPOSAL) |
origens | array | Origens das vendas |
pendente | boolean | Somente vendas pendentes |
campo_ordenado_ascendente | string | NUMERO, CLIENTE, DATA |
campo_ordenado_descendente | string | NUMERO, CLIENTE, DATA |
curl -X GET \
'https://api-v2.contaazul.com/v1/venda/busca?pagina=1&tamanho_pagina=50&data_alteracao_de=2026-01-01T00:00:00&data_alteracao_ate=2026-01-31T23:59:59' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
⚠️ A resposta devolve as vendas em
response.data.itens(array). Nunca leiaresponse.datadiretamente!
curl -X GET 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
| Parâmetro | Tipo | Valores aceitos |
|---|---|---|
tamanho_pagina | integer | 10, 20, 50, 100, 200, 500, 1000 |
Retorna também o campo id_centro_custo por item (adicionado Fev/2026).
curl -X GET 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA/itens?tamanho_pagina=100' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X GET 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA/imprimir' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X POST 'https://api-v2.contaazul.com/v1/venda' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{...}'
{
"id_cliente": "UUID-DO-CLIENTE",
"numero": 12345,
"situacao": "APROVADO",
"data_venda": "2025-03-15",
"id_categoria": "UUID-CATEGORIA",
"id_centro_custo": "UUID-CENTRO-CUSTO",
"id_vendedor": "UUID-DO-VENDEDOR",
"observacoes": "Texto livre sobre a venda",
"observacoes_pagamento": "Observações sobre o pagamento",
"itens": [
{
"id": "UUID-DO-PRODUTO",
"descricao": "Nome do produto / obs",
"quantidade": 10.5,
"valor": 15.90,
"valor_custo": 10.00,
"tipo": "PRODUTO"
}
],
"composicao_de_valor": {
"frete": 10.00,
"desconto": {
"tipo": "PORCENTAGEM",
"valor": 5
}
},
"condicao_pagamento": {
"tipo_pagamento": "BOLETO_BANCARIO",
"id_conta_financeira": "UUID-CONTA",
"opcao_condicao_pagamento": "7, 14",
"nsu": "1234567890",
"parcelas": [
{
"data_vencimento": "2025-04-15",
"valor": 166.95,
"descricao": "Venda 12345"
}
]
}
}
tipo_pagamentoBOLETO_BANCARIO, CARTAO_CREDITO, CARTAO_DEBITO, CARTEIRA_DIGITAL, CASHBACK, CHEQUE, CREDITO_LOJA, CREDITO_VIRTUAL, DEPOSITO_BANCARIO, DINHEIRO, OUTRO, DEBITO_AUTOMATICO, CARTAO_CREDITO_VIA_LINK, PIX_PAGAMENTO_INSTANTANEO, PIX_COBRANCA, PROGRAMA_FIDELIDADE, SEM_PAGAMENTO, TRANSFERENCIA_BANCARIA, VALE_ALIMENTACAO, VALE_COMBUSTIVEL, VALE_PRESENTE, VALE_REFEICAO
situacaoEM_ANDAMENTO, APROVADO
⚠️ Limitações Fiscais: A API
POST /v1/vendafoca apenas na criação do pedido de venda. Não suporta envio de Natureza de Operação (CFOP) nem dados de transportadora/frete logístico. O faturamento da NF-e ocorre dentro do painel CA.
✅ Padrão validado no App Hardt (Mar/2026): para boleto parcelado,
opcao_condicao_pagamentoaceita lista de dias ("7, 14") e as parcelas devem ser enviadas comdata_vencimentoindividual por parcela.
⚠️ Natureza de Operação no Hardt: enviar em 2 etapas — primeiro
POST /v1/venda, depoisPUT /v1/venda/{id}comid_natureza_operacao(CNPJ/CPF). Incluirid_natureza_operacaono POST não está surtindo efeito no cenário atual.
| Status Local | Descrição |
|---|---|
ABERTO | Pedido rascunho/bloqueado. Vendedor pode alterar |
ENVIAR | Finalizado pelo vendedor, pronto para envio |
SINCRONIZANDO | Worker pegou o pedido, processando com CA |
RECEBIDO | Processado com sucesso. Temos id_venda_contaazul. Intocável |
ERRO | Falha no envio. Mensagem em erro_envio |
Prevenção de duplicidade:
id_venda_contaazul: verifica via GET /v1/venda/{id} se existe no CAnumero: busca via GET /v1/venda/busca?numeros={numero}GET /v1/venda/proximo-numero e dispara POST /v1/vendacurl -X PUT 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ ...payload_completo... }'
curl -X POST 'https://api-v2.contaazul.com/v1/venda/exclusao-lote' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "ids": ["UUID-1", "UUID-2"] }'
Campos extendidos no banco local (não existem na API CA):
| Campo | Descrição |
|---|---|
email | E-mail de login/contato |
flex_mensal | Limite de desconto mensal (R$) |
flex_disponivel | Saldo atual de desconto disponível (R$) |
login | Nome de usuário para acesso ao App |
senha | Hash da senha de acesso ao App |
permissoes | JSON de controle granular de acesso |
Fluxo upsert:
where: { contaAzulId: api.id }update: { nome: api.nome, id_legado: api.id_legado ?? null }create: { contaAzulId: api.id, nome: api.nome, id_legado: api.id_legado ?? null }email ou flex_* com null durante updateBase URL: https://api-v2.contaazul.com
| Método | Endpoint | Descrição |
|---|---|---|
GET | /v1/centro-de-custo | Listar centros de custo por filtro |
POST | /v1/centro-de-custo | Criar novo centro de custo |
GET | /v1/categorias | Listar categorias financeiras |
GET | /v1/financeiro/categorias-dre | Listar estrutura DRE |
GET | /v1/conta-financeira | Listar contas financeiras |
GET | /v1/conta-financeira/{id}/saldo-atual | Saldo atual de uma conta financeira |
GET | /v1/financeiro/eventos-financeiros/{id_evento}/parcelas | Parcelas por evento financeiro |
GET | /v1/financeiro/eventos-financeiros/parcelas/{id} | Parcela por ID |
PATCH | /v1/financeiro/eventos-financeiros/parcelas/{id} | Atualizar parcela (parcial) |
POST | /v1/financeiro/eventos-financeiros/contas-a-receber | Criar conta a receber |
GET | /v1/financeiro/eventos-financeiros/contas-a-receber/buscar | Buscar receitas por filtro |
POST | /v1/financeiro/eventos-financeiros/contas-a-pagar | Criar conta a pagar |
GET | /v1/financeiro/eventos-financeiros/contas-a-pagar/buscar | Buscar despesas por filtro |
curl -X GET 'https://api-v2.contaazul.com/v1/conta-financeira' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X GET 'https://api-v2.contaazul.com/v1/conta-financeira/UUID-DA-CONTA/saldo-atual' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Adicionado em Out/2025 para monitoramento em tempo real.
| Parâmetro | Tipo | Obrig.? | Descrição |
|---|---|---|---|
pagina | integer | Sim | Página |
tamanho_pagina | integer | Sim | Itens por página |
data_vencimento_de | string | Sim | ISO date (YYYY-MM-DD) |
data_vencimento_ate | string | Sim | ISO date (YYYY-MM-DD) |
data_competencia_de | string | Não | ISO date |
data_competencia_ate | string | Não | ISO date |
data_pagamento_de | string | Não | ISO date |
data_pagamento_ate | string | Não | ISO date |
data_alteracao_de | string | Não | ISO (SP/GMT-3) — adicionado Out/2025 |
data_alteracao_ate | string | Não | ISO (SP/GMT-3) |
valor_de | string | Não | Valor mínimo |
valor_ate | string | Não | Valor máximo |
status | array | Não | PERDIDO, RECEBIDO, EM_ABERTO, RENEGOCIADO, RECEBIDO_PARCIAL, ATRASADO |
ids_contas_financeiras | array | Não | IDs de contas financeiras |
ids_categorias | array | Não | IDs de categorias |
ids_centros_de_custo | array | Não | IDs de centros de custo |
ids_clientes | array | Não | IDs de clientes (adicionado Fev/2026) |
descricao | string | Não | Descrição da conta |
curl -X GET \
'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/contas-a-receber/buscar?pagina=1&tamanho_pagina=50&data_vencimento_de=2025-01-01&data_vencimento_ate=2025-12-31' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Mesmos parâmetros das Receitas, com descricao como "Pagamento do salário".
curl -X GET \
'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/contas-a-pagar/buscar?pagina=1&tamanho_pagina=50&data_vencimento_de=2025-01-01&data_vencimento_ate=2025-12-31' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
{
"itens_totais": 6,
"itens": [
{
"id": "c6a28b6e-efe4-11ee-8ef8-8b86c5251537",
"descricao": "Aluguel do escritório",
"data_vencimento": "2027-08-15",
"status_traduzido": "ATRASADO",
"total": 781201.79,
"nao_pago": 213023.79,
"pago": 0,
"data_criacao": "2027-08-15T14:30:00Z",
"data_alteracao": "2027-08-15T14:30:00Z",
"data_competencia": "2018-03-16",
"categorias": [
{ "id": "b134ec6b-...", "nome": "Adiantamento Salarial" }
],
"centros_custo": [
{ "id": "428389c6-...", "nome": "Centro de custo de Teste" }
],
"fornecedor": { "nome": "Maria da Silva" }
}
],
"totais": { "ativo": 6, "inativo": 0, "todos": 6 }
}
curl -X POST 'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/contas-a-receber' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{...}'
{
"data_competencia": "2024-07-15",
"valor": 500.00,
"observacao": "Pagamento de serviço",
"descricao": "Prestação de serviço",
"contato": "UUID-DO-CLIENTE",
"conta_financeira": "UUID-DA-CONTA-FINANCEIRA",
"rateio": [
{
"id_categoria": "UUID-DA-CATEGORIA",
"valor": 500.00,
"rateio_centro_custo": [
{
"id_centro_custo": "UUID-DO-CENTRO-CUSTO",
"valor": 500.00
}
]
}
],
"condicao_pagamento": {
"parcelas": [
{
"descricao": "Parcela 1",
"data_vencimento": "2024-08-15",
"nota": "Pagamento via PIX",
"conta_financeira": "UUID-DA-CONTA-FINANCEIRA",
"detalhe_valor": {
"valor_bruto": 500.00,
"valor_liquido": 497.90,
"desconto": 0,
"juros": 0,
"multa": 0,
"taxa": 2.10
}
}
]
}
}
{
"protocolId": "UUID-DO-PROTOCOLO",
"status": "PENDING",
"createdAt": "2024-10-22T14:30:00Z"
}
Status possíveis do protocolo:
PENDING,SUCCESS,ERROR
Mesmo payload da conta a receber. Substitua contato pelo UUID do fornecedor.
curl -X POST 'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/contas-a-pagar' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ ...mesmo_payload_de_receber... }'
Retorna também: rateio, centros de custo, categoria financeira e novos status (adicionado Ago/2025 e Nov/2025).
curl -X GET 'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/parcelas/UUID-DA-PARCELA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Novos status de parcela (Nov/2025): RENEGOCIADO, RECEBIDO_PARCIAL, ATRASADO, PERDIDO
curl -X PATCH 'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/parcelas/UUID-DA-PARCELA' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"data_vencimento": "2025-05-10",
"valor": 150.00,
"observacoes": "Ajuste de vencimento"
}'
curl -X GET 'https://api-v2.contaazul.com/v1/categorias?pagina=1&tamanho_pagina=50' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X GET 'https://api-v2.contaazul.com/v1/financeiro/categorias-dre' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Adicionado Out/2025 para listar categorias da Demonstração do Resultado do Exercício (DRE).
| Parâmetro | Tipo | Descrição |
|---|---|---|
pagina | integer | Página |
tamanho_pagina | integer | Itens por página |
busca | string | Busca textual |
status | string | ativo, inativo, todos |
campo_ordenado_ascendente | string | ID, CODIGO, NOME, ATIVO |
campo_ordenado_descendente | string | ID, CODIGO, NOME, ATIVO |
curl -X GET 'https://api-v2.contaazul.com/v1/centro-de-custo?pagina=1&tamanho_pagina=50' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X POST 'https://api-v2.contaazul.com/v1/centro-de-custo' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "codigo": "CC001", "nome": "Comercial" }'
IDs reais no Conta Azul que devem ser preservados (Seeds):
| Nome | Tipo | ID (UUID Conta Azul) |
|---|---|---|
| Caixinha | DINHEIRO | 1dc7f96e-7658-4e0c-8d0a-5c5980234c90 |
| Conta Azul (Boleto) | BOLETO_BANCARIO | ed4798c2-f8e3-4e87-9ff3-8f264dcf6aa0 |
| Acredicoop | BOLETO_BANCARIO | dc83b583-4a49-47c4-b238-c7d14ab77d5f |
| Sicoob | BOLETO_BANCARIO | f756dd56-4946-493e-9343-0a2e2fdfe681 |
Base URL: https://api-v2.contaazul.com/v1/notas-fiscais
A API de NF é somente consulta — não é possível emitir NFs pela API. A emissão ocorre dentro do painel Conta Azul.
Retorna somente NF-e com status EMITIDA e CORRIGIDA COM SUCESSO.
| Parâmetro | Descrição |
|---|---|
data_inicio | Data inicial de emissão |
data_fim | Data final de emissão |
numero_nota | Número da nota |
id_venda | ID da venda associada (adicionado Nov/2025) |
ids | IDs (UUID) das NF-e |
curl -X GET \
'https://api-v2.contaazul.com/v1/notas-fiscais?data_inicio=2025-01-01&data_fim=2025-12-31' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X GET 'https://api-v2.contaazul.com/v1/notas-fiscais/CHAVE_ACESSO_NF' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Retorna NFS-e com todos os status possíveis a partir da emissão.
| Parâmetro | Descrição |
|---|---|
data_inicio | Data inicial |
data_fim | Data final |
numero_nota | Número da nota |
id_venda | ID da venda associada |
ids | IDs (UUID) das NFS-e (adicionado Fev/2026) |
curl -X GET \
'https://api-v2.contaazul.com/v1/notas-fiscais-servico?data_inicio=2025-01-01&data_fim=2025-12-31' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Associa notas fiscais (pelas chaves de acesso) a um MDF-e logístico.
curl -X POST 'https://api-v2.contaazul.com/v1/notas-fiscais/vinculo-mdfe' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"chaves_acesso": ["CHAVE_1", "CHAVE_2"],
"status": "AUTORIZADO"
}'
Status aceitos:
AUTORIZADO,ENCERRADO,CANCELADO
Base URL: https://api-v2.contaazul.com/v1/contratos
Contratos geram vendas automaticamente conforme a periodicidade configurada (
SCHEDULED_SALE).
curl -X GET 'https://api-v2.contaazul.com/v1/contratos?pagina=1&tamanho_pagina=50' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl -X GET 'https://api-v2.contaazul.com/v1/contratos/proximo-numero' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Adicionado Nov/2025 para criação automatizada de contratos.
curl -X POST 'https://api-v2.contaazul.com/v1/contratos' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"id_cliente": "UUID-DO-CLIENTE",
"numero": 1,
"itens": [...],
"condicao_pagamento": {...}
}'
| Erro | Causa | Solução |
|---|---|---|
invalid_grant | Código de autorização já usado, expirado ou redirect_uri incorreto | Use o código imediatamente (validade: 3 min). Verifique redirect_uri e client_id |
401 Unauthorized | Token ausente, inválido ou expirado | Use refresh_token para renovar. No App: _axiosGet faz isso automaticamente |
429 Too Many Requests | Rate limit excedido (600/min ou 10/seg) | Implemente backoff exponencial + cache de dados |
500 Internal Server Error | Erro no servidor CA ou payload malformado | Verifique o JSON, tente novamente após alguns segundos |
| Versão | Data | O que mudou |
|---|---|---|
| Fev/2026 | 2026-02-xx | Itens de venda: campo id_centro_custo no retorno; PIX padronizado como PIX_PAGAMENTO_INSTANTANEO; NFS-e: filtro por ids; Receitas: filtro ids_clientes + campos data_competencia, centros_de_custo, categorias no retorno |
| Dez/2025 | 2025-12-18 | Novo endpoint: NFS-e por filtro (GET /v1/notas-fiscais-servico); campo url_imagem no produto por ID |
| Dez/2025 | 2025-12-10 | Canal de suporte migrado para Portal do Desenvolvedor (email [email protected] descontinuado) |
| Nov/2025 | 2025-11-19 | Rate limit atualizado: 600/min e 10/seg — agora por conta conectada (antes por aplicação) |
| Nov/2025 | 2025-11-14 | NF-e: filtro por id_venda |
| Nov/2025 | 2025-11-12 | Produtos: novos filtros sku, data_alteracao_de, data_alteracao_ate |
| Nov/2025 | 2025-11-11 | Contratos: novo endpoint GET /v1/contratos/proximo-numero |
| Nov/2025 | 2025-11-07 | Parcelas: novos status (RENEGOCIADO, RECEBIDO_PARCIAL, ATRASADO, PERDIDO); objeto de renegociação nas parcelas |
| Nov/2025 | 2025-11-05 | Pessoas: filtro por data_alteracao_de/ate |
| Nov/2025 | 2025-11-04 | Vendas: filtro por data_alteracao_de/ate; campo id_contrato no retorno das vendas |
| Out/2025 | 2025-10-23 | Receitas/Despesas: filtro por data_alteracao_de/ate; Itens de venda: campo valor_custo no retorno |
| Out/2025 | 2025-10-10 | Saldo de conta financeira: GET /v1/conta-financeira/{id}/saldo-atual; Categorias DRE: GET /v1/financeiro/categorias-dre |
| Ago/2025 | 2025-08-27 | Parcelas: retorna rateio, centros de custo e categoria financeira |