05 Ca Api Referencia

⚙️ PADRÕES GLOBAIS

Códigos de Retorno HTTP

🔐 AUTENTICAÇÃO (OAuth 2.0)

O Conta Azul usa o fluxo Authorization Code do OAuth 2.0.

ETAPA 1 — Solicitar código de autorização

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.

ETAPA 2 — Trocar o código pelo access_token

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"))

Resposta (200 OK)

{
  "access_token": "ACCESS_TOKEN_GERADO",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_GERADO",
  "token_type": "Bearer"
}

⚠️ CRÍTICO: Salve o refresh_token a cada renovação — ele muda a cada uso.

ETAPA 3 — Renovar o access_token (refresh)

Quando o access_token expirar, use o refresh_token para obter um novo par de tokens sem re-autenticar o usuário.

ETAPA 4 — Usar o token nas requisições

Todas as chamadas à API devem incluir:

Authorization: Bearer <access_token>

Regra crítica do App Hardt — _axiosGet obrigatório

NUNCA use axios.get() ou axios.post() diretamente. Use contaAzulService._axiosGet(url, 'LOG_NAME') para GETs, pois ele intercepta erros 401 e renova o token automaticamente. Para POST/PUT, capture o token com contaAzulService.getAccessToken() e em caso de 401 force renovação com getAccessToken(true).

👥 PESSOAS (Clientes e Fornecedores)

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.

GET /v1/pessoas — Listar Pessoas

Consulta pessoas cadastradas com suporte a filtros.

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'

POST /v1/pessoas — Criar Nova Pessoa

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": []
}

PUT /v1/pessoas/{id} — Atualizar Pessoa (Completo)

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... }'

PATCH /v1/pessoas/{id} — Atualizar Pessoa (Parcial)

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" }]
  }'

GET /v1/pessoas/{id} — Consultar por ID

curl -X GET 'https://api-v2.contaazul.com/v1/pessoas/UUID-DA-PESSOA' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/pessoas/legado/{id} — Consultar por ID Legado (V1)

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'

POST /v1/pessoas/ativar — Ativar em Lote

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"] }'

POST /v1/pessoas/inativar — Desativar em Lote

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"] }'

POST /v1/pessoas/excluir — Excluir em Lote

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"] }'

Campos Extendidos Hardt (Banco Local)

Além dos campos padrão do CA, a tabela clientes local possui:

📦 PRODUTOS E ESTOQUE

Base URL: https://api-v2.contaazul.com/v1/produtos

GET /v1/produtos — Listar Produtos

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'

Resposta (lista simplificada)

{
  "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}.

GET /v1/produtos/{id} — Consultar Produto por ID

curl -X GET 'https://api-v2.contaazul.com/v1/produtos/UUID-DO-PRODUTO' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Resposta (detalhes completos)

{
  "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 objeto estoque, não na raiz
• estoque.custo_medio — Custo está dentro de estoque, não na raiz
• estoque.minimumStock — camelCase! (não estoque_minimo)
• url_imagem — adicionado em Dez/2025 para download de imagens

POST /v1/produtos — Criar Produto

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.

PATCH /v1/produtos/{id} — Atualizar Produto (Parcial)

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" }'

DELETE /v1/produtos/{id} — Deletar Produto

curl -X DELETE 'https://api-v2.contaazul.com/v1/produtos/UUID-DO-PRODUTO' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Endpoints Auxiliares de Produtos (Cadastros Básicos)

# 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'

🛒 VENDAS

Base URL: https://api-v2.contaazul.com/v1/venda

⚠️ CRÍTICO [FEV/2026]: Use exclusivamente api-v2.contaazul.com. A antiga api.contaazul.com rejeita os novos tokens Cognito com 401 Unauthorized.

GET /v1/venda/vendedores — Listar Vendedores

curl -X GET 'https://api-v2.contaazul.com/v1/venda/vendedores' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Resposta (200)

[
  {
    "id": "cd3dff75-91e1-4284-8d20-f933b7ae31e3",
    "nome": "Clarkson Neitzel",
    "id_legado": null
  }
]

GET /v1/venda/proximo-numero — Próximo Número de Venda

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 de JSON.parse.

GET /v1/venda/busca — Listar Vendas por Filtro

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 leia response.data diretamente!

GET /v1/venda/{id} — Buscar Venda por ID

curl -X GET 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/venda/{id_venda}/itens — Itens de uma Venda

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'

GET /v1/venda/{id}/imprimir — PDF de uma Venda

curl -X GET 'https://api-v2.contaazul.com/v1/venda/UUID-DA-VENDA/imprimir' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

POST /v1/venda — Criar Nova Venda

curl -X POST 'https://api-v2.contaazul.com/v1/venda' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Payload Completo

{
  "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"
      }
    ]
  }
}

Valores aceitos para tipo_pagamento

BOLETO_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

Valores aceitos para situacao

EM_ANDAMENTO, APROVADO

⚠️ Limitações Fiscais: A API POST /v1/venda foca 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_pagamento aceita lista de dias ("7, 14") e as parcelas devem ser enviadas com data_vencimento individual por parcela.

⚠️ Natureza de Operação no Hardt: enviar em 2 etapas — primeiro POST /v1/venda, depois PUT /v1/venda/{id} com id_natureza_operacao (CNPJ/CPF). Incluir id_natureza_operacao no POST não está surtindo efeito no cenário atual.

Fluxo de Sincronização (App Hardt)

Prevenção de duplicidade:

1. Se já tem id_venda_contaazul: verifica via GET /v1/venda/{id} se existe no CA
2. Se não tem ID mas tem numero: busca via GET /v1/venda/busca?numeros={numero}
3. Se não existe no CA: gera novo número via GET /v1/venda/proximo-numero e dispara POST /v1/venda

PUT /v1/venda/{id} — Atualizar Venda

curl -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... }'

POST /v1/venda/exclusao-lote — Excluir Vendas em Lote

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"] }'

Vendedores — Estratégia de Sincronização (App Hardt)

Campos extendidos no banco local (não existem na API CA):

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 }
• NUNCA sobrescrever email ou flex_* com null durante update

💰 FINANCEIRO

Base URL: https://api-v2.contaazul.com

Endpoints Disponíveis

GET /v1/conta-financeira — Listar Contas Financeiras

curl -X GET 'https://api-v2.contaazul.com/v1/conta-financeira' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/conta-financeira/{id}/saldo-atual — Saldo da Conta

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.

GET /v1/financeiro/eventos-financeiros/contas-a-receber/buscar — Buscar Receitas

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'

GET /v1/financeiro/eventos-financeiros/contas-a-pagar/buscar — Buscar Despesas

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'

Resposta das Despesas (200)

{
  "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 }
}

POST /v1/financeiro/eventos-financeiros/contas-a-receber — Criar Conta a Receber

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
        }
      }
    ]
  }
}

Resposta (202 — processamento assíncrono)

{
  "protocolId": "UUID-DO-PROTOCOLO",
  "status": "PENDING",
  "createdAt": "2024-10-22T14:30:00Z"
}

Status possíveis do protocolo: PENDING, SUCCESS, ERROR

POST /v1/financeiro/eventos-financeiros/contas-a-pagar — Criar Conta a Pagar

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... }'

GET /v1/financeiro/eventos-financeiros/parcelas/{id} — Parcela por ID

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

PATCH /v1/financeiro/eventos-financeiros/parcelas/{id} — Atualizar Parcela

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"
  }'

GET /v1/categorias — Listar Categorias Financeiras

curl -X GET 'https://api-v2.contaazul.com/v1/categorias?pagina=1&tamanho_pagina=50' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/financeiro/categorias-dre — Estrutura DRE

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).

GET /v1/centro-de-custo — Listar Centros de Custo

curl -X GET 'https://api-v2.contaazul.com/v1/centro-de-custo?pagina=1&tamanho_pagina=50' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

POST /v1/centro-de-custo — Criar Centro de Custo

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" }'

Contas Financeiras Fixas (App Hardt)

IDs reais no Conta Azul que devem ser preservados (Seeds):

🧾 NOTAS FISCAIS

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.

GET /v1/notas-fiscais — Listar NF-e por Filtro

Retorna somente NF-e com status EMITIDA e CORRIGIDA COM SUCESSO.

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'

GET /v1/notas-fiscais/{chave} — NF-e por Chave de Acesso

curl -X GET 'https://api-v2.contaazul.com/v1/notas-fiscais/CHAVE_ACESSO_NF' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/notas-fiscais-servico — Listar NFS-e por Filtro

Retorna NFS-e com todos os status possíveis a partir da emissão.

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'

POST /v1/notas-fiscais/vinculo-mdfe — Vincular NF a MDF-e

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

📑 CONTRATOS (Vendas Recorrentes)

Base URL: https://api-v2.contaazul.com/v1/contratos

Contratos geram vendas automaticamente conforme a periodicidade configurada (SCHEDULED_SALE).

GET /v1/contratos — Listar Contratos por Filtro

curl -X GET 'https://api-v2.contaazul.com/v1/contratos?pagina=1&tamanho_pagina=50' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /v1/contratos/proximo-numero — Próximo Número de Contrato

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.

POST /v1/contratos — Criar Novo Contrato

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": {...}
  }'

📋 ERROS COMUNS

📈 CHANGELOG RESUMIDO (últimas versões)