Codout.Apis.ContaAzul 2.3.0

Codout.Apis.ContaAzul

Biblioteca .NET para integrar com a API v2 do Conta Azul, o ERP de gestao financeira e contabil para pequenas empresas.

Fornece classes fortemente tipadas em C# para autenticacao OAuth2, clientes, produtos, vendas, servicos, financeiro, notas fiscais, contratos e mais, com filtros de query string tipados para todos os endpoints de listagem.

Indice

• Instalacao
• Inicio Rapido
• Autenticacao
• Filtros Tipados
• APIs Disponiveis
  • Clientes (CustomerApi)
  • Produtos (ProductApi)
  • Vendas (SaleApi)
  • Servicos (ServiceApi)
  • Categorias (CategoryApi)
  • Financeiro (FinancialApi)
  • Baixas (AcquittanceApi)
  • Notas Fiscais (InvoiceApi)
  • NFS-e (ServiceInvoiceApi)
  • Contratos (ContractApi)
• Models
• Enums
• Paginacao
• Configuracao Avancada
• Requisitos
• Build
• Licenca

Instalacao

Via NuGet Package Manager:

Install-Package Codout.Apis.ContaAzul

Via .NET CLI:

dotnet add package Codout.Apis.ContaAzul

Inicio Rapido

using Codout.Apis.ContaAzul.Api;
using Codout.Apis.ContaAzul.Models;
using Codout.Apis.ContaAzul.Models.Enums;
using Codout.Apis.ContaAzul.Models.Filters;
using Codout.Apis.ContaAzul.Models.Request;

// 1. Obter token de acesso
var authApi = new AuthorizationApi();
var token = await authApi.GetToken(
    username: "seu-client-id",
    password: "seu-client-secret",
    redirectUri: "https://sua-app.com/callback",
    code: "codigo-de-autorizacao"
);

// 2. Listar clientes com filtros tipados
var customerApi = new CustomerApi();
var customers = await customerApi.GetAsync(token.AccessToken, new PersonFilter
{
    Page = 1,
    PageSize = 50,
    ProfileType = ProfileType.Customer,
    SortField = PersonSortField.Name,
    SortDirection = SortDirection.Ascending
});

// 3. Criar um produto
var productApi = new ProductApi();
var product = await productApi.CreateAsync(new CreateProductRequest
{
    Name = "Camiseta Basica",
    SkuCode = "CAM-001",
    Stock = new CreateProductStock { SalePrice = 49.90m }
}, token.AccessToken);

// 4. Criar uma venda
var saleApi = new SaleApi();
var sale = await saleApi.CreateAsync(new CreateSaleRequest
{
    ClientId = "uuid-do-cliente",
    SaleDate = "2026-02-11",
    Items = new List<CreateSaleItemRequest>
    {
        new() { Description = "Camiseta Basica", Quantity = 2, Value = 49.90m }
    },
    PaymentCondition = new CreateSalePaymentConditionRequest
    {
        PaymentType = "A_VISTA",
        FinancialAccountId = "uuid-da-conta"
    }
}, token.AccessToken);

Autenticacao

A biblioteca utiliza OAuth2 com o servidor de autorizacao do Conta Azul.

Obter Token (Authorization Code)

var authApi = new AuthorizationApi();

// Trocar o authorization code por um access token
var token = await authApi.GetToken(
    username: "client-id",       // Client ID da sua aplicacao
    password: "client-secret",   // Client Secret da sua aplicacao
    redirectUri: "https://sua-app.com/callback",
    code: "authorization-code"   // Codigo recebido no callback
);

// token.AccessToken  -> Token para chamadas de API
// token.RefreshToken -> Token para renovar o acesso
// token.ExpiresIn    -> Tempo de expiracao em segundos

Renovar Token (Refresh Token)

var newToken = await authApi.RefreshToken(
    clientId: "client-id",
    clientSecret: "client-secret",
    refreshToken: token.RefreshToken
);

URLs de autenticacao:

• Servidor de autorizacao: https://auth.contaazul.com/oauth2/token
• API base: https://api-v2.contaazul.com

Filtros Tipados

Todos os endpoints de listagem e busca aceitam filtros fortemente tipados, proporcionando IntelliSense, seguranca em tempo de compilacao e documentacao inline.

Infraestrutura

Exemplo de uso

// Antes (string - propenso a erros, sem autocomplete)
var result = await customerApi.GetAsync(token, "pagina=1&tamanho_pagina=20&busca=acme");

// Depois (tipado - com IntelliSense e validacao em tempo de compilacao)
var result = await customerApi.GetAsync(token, new PersonFilter
{
    Page = 1,
    PageSize = 20,
    Search = "acme"
});

Filtros com parametros obrigatorios

Alguns filtros exigem parametros via construtor:

// Notas fiscais exigem data inicial e final
var filter = new InvoiceFilter("2026-01-01", "2026-12-31")
{
    Page = 1,
    PageSize = 50,
    RecipientDocument = "12345678000190"
};

// Contas a receber exigem datas de vencimento
var filter = new ReceivableFilter("2026-01-01", "2026-06-30")
{
    Statuses = new() { FinancialEventStatus.Open, FinancialEventStatus.Overdue },
    Page = 1,
    PageSize = 100
};

Filtros disponiveis

APIs Disponiveis

Clientes (CustomerApi)

Gerenciamento completo de pessoas (clientes, fornecedores, transportadoras).

Endpoint base: /v1/pessoas

var api = new CustomerApi();

// Listar com filtros tipados
var result = await api.GetAsync(token, new PersonFilter
{
    Page = 1,
    PageSize = 25,
    Search = "joao",
    ProfileType = ProfileType.Customer,
    SortField = PersonSortField.Name,
    SortDirection = SortDirection.Ascending,
    WithAddress = true
});
// result.Items     -> Lista de PersonSummary
// result.Pagination -> Informacoes de paginacao

// Filtrar por datas de criacao
var recent = await api.GetAsync(token, new PersonFilter
{
    CreationDateStart = "2026-01-01T00:00:00",
    CreationDateEnd = "2026-02-11T23:59:59"
});

// Buscar por ID
var person = await api.GetByIdAsync("uuid", token);

// Buscar por ID legado (migracao v1 -> v2)
var person = await api.GetByLegacyIdAsync("12345", token);

// Criar pessoa
var created = await api.CreateAsync(new CreatePersonRequest
{
    Name = "Joao da Silva",
    PersonType = PersonType.Physical,
    Email = "joao@email.com",
    Code = "CLI-001",
    MobilePhone = "11999999999",
    Profiles = new List<Profile> { new() { ProfileType = ProfileType.Customer } }
}, token);

// Atualizar pessoa (PUT - substituicao total)
await api.UpdateAsync(new UpdatePersonRequest { /* ... */ }, "uuid", token);

// Atualizar parcialmente (PATCH)
await api.PatchAsync(new PatchPersonRequest { Name = "Novo Nome" }, "uuid", token);

// Operacoes em lote
await api.ActivateAsync(new BatchUuidsRequest { Uuids = new() { "uuid1", "uuid2" } }, token);
await api.DeactivateAsync(new BatchUuidsRequest { Uuids = new() { "uuid1" } }, token);
await api.DeleteBatchAsync(new BatchUuidsRequest { Uuids = new() { "uuid1" } }, token);

Produtos (ProductApi)

CRUD de produtos com suporte a categorias, estoque, informacoes fiscais, kits e variacoes.

Endpoint base: /v1/produtos

var api = new ProductApi();

// Listar produtos com filtros tipados
var products = await api.GetAsync(token, new ProductFilter
{
    Page = 1,
    PageSize = 50,
    Search = "notebook",
    Status = ProductStatus.Active,
    SortField = ProductSortField.Name,
    SortDirection = SortDirection.Ascending,
    SalePriceFrom = 100.00,
    SalePriceTo = 5000.00
});

// Buscar produto por ID
var product = await api.GetByIdAsync("uuid", token);

// Criar produto completo
var created = await api.CreateAsync(new CreateProductRequest
{
    Name = "Notebook Pro",
    SkuCode = "NB-PRO-001",
    EanCode = "7891234567890",
    Format = ProductFormat.Simple,
    Active = true,
    Stock = new CreateProductStock
    {
        SalePrice = 4999.90m,
        AverageCost = 3500.00m,
        AvailableStock = 50,
        MinimumStock = 5,
        MaximumStock = 100
    },
    Fiscal = new CreateProductFiscal
    {
        Origin = ProductOrigin.Domestic,
        ProductType = FiscalProductType.MerchandiseForResale
    }
}, token);

// Atualizar produto (PATCH)
await api.PatchAsync(new UpdateProductRequest { SalePrice = 4499.90m }, "uuid", token);

// Excluir produtos em lote
await api.DeleteBatchAsync(new { ids = new[] { "uuid1", "uuid2" } }, token);

// Consultar categorias de produtos
var categories = await api.GetCategoriesAsync(token, new ProductCategoryFilter
{
    TextSearch = "eletronicos"
});

// Consultar NCMs (classificacao fiscal)
var ncms = await api.GetNcmsAsync(token, new NcmFilter { TextSearch = "8471" });

// Consultar CESTs
var cests = await api.GetCestsAsync(token, new CestFilter { TextSearch = "28" });

// Consultar unidades de medida
var units = await api.GetUnitsAsync(token, new UnitOfMeasureFilter());

// Consultar marcas de e-commerce
var brands = await api.GetEcommerceBrandsAsync(token, new EcommerceBrandFilter
{
    TextSearch = "samsung",
    Direction = SortDirection.Ascending
});

// Consultar categorias de e-commerce
var ecCategories = await api.GetEcommerceCategoriesAsync(token, new EcommerceCategoryFilter
{
    TextSearch = "celulares"
});

Vendas (SaleApi)

Gestao completa de vendas com suporte a PDF, itens paginados e vendedores.

Endpoint base: /v1/venda

var api = new SaleApi();

// Buscar vendas com filtros tipados
var search = await api.SearchAsync(token, new SaleSearchFilter
{
    Page = 1,
    PageSize = 25,
    StartDate = "2026-01-01",
    EndDate = "2026-12-31",
    AscendingSortField = SaleSortField.Date,
    Totals = SaleTotalType.Approved
});
// search.Items     -> Lista de SaleSearchItem
// search.Totals    -> Totais agregados

// Buscar venda por ID
var sale = await api.GetByIdAsync("uuid", token);

// Criar venda
var created = await api.CreateAsync(new CreateSaleRequest
{
    ClientId = "uuid-cliente",
    Number = 1001,
    SaleDate = "2026-02-11",
    Items = new List<CreateSaleItemRequest>
    {
        new() { Description = "Produto A", Quantity = 2, Value = 150.00m },
        new() { Description = "Servico B", Quantity = 1, Value = 200.00m }
    },
    PaymentCondition = new CreateSalePaymentConditionRequest
    {
        PaymentType = "A_VISTA",
        FinancialAccountId = "uuid-conta"
    }
}, token);

// Atualizar venda
await api.UpdateAsync(new UpdateSaleRequest { /* ... */ }, "uuid", token);

// Excluir vendas em lote (max 10 por request)
await api.DeleteBatchAsync(new BatchDeleteSaleRequest
{
    Ids = new() { "uuid1", "uuid2" }
}, token);

// Gerar PDF da venda
using var pdfStream = await api.GetPDFAsync("uuid", token);

// Listar itens da venda (paginado)
var items = await api.GetItemsAsync("uuid", token, new SaleItemFilter
{
    Page = 1,
    PageSize = 50
});
// items.Items      -> Lista de SaleItem
// items.TotalItems -> Total de itens
// items.Totals     -> Contagem por tipo (produtos, servicos, nao conciliados)

// Listar vendedores
var sellers = await api.GetSellersAsync(token);

Servicos (ServiceApi)

CRUD de servicos com classificacao fiscal.

Endpoint base: /v1/servicos

var api = new ServiceApi();

// Listar servicos com filtro
var services = await api.GetAsync(token, new ServiceFilter
{
    Page = 1,
    TextSearch = "consultoria"
});

// Buscar servico por ID
var service = await api.GetByIdAsync("uuid", token);

// Criar servico
var created = await api.CreateAsync(new CreateServiceRequest
{
    Code = "SRV-001",
    Description = "Consultoria em TI",
    Price = 250.00m,
    Cost = 100.00m,
    ServiceType = ServiceType.Provided,
    Status = ServiceStatus.Active
}, token);

// Atualizar servico (PATCH)
await api.PatchAsync(new UpdateServiceRequest { Price = 300.00m }, "uuid", token);

// Excluir servicos em lote
await api.DeleteBatchAsync(new { ids = new[] { "uuid1" } }, token);

Categorias (CategoryApi)

Consulta de categorias de produtos (somente leitura).

Endpoint base: /v1/produtos/categorias

var api = new CategoryApi();

// Listar todas as categorias com filtro
var categories = await api.GetAsync(token, new ProductCategoryFilter
{
    TextSearch = "roupas"
});

// Buscar categoria por ID
var category = await api.GetByIdAsync("uuid", token);

Financeiro (FinancialApi)

Gestao de centros de custo, categorias financeiras, contas financeiras, lancamentos e busca de contas a receber/pagar.

Endpoint base: /v1

var api = new FinancialApi();

// --- Centros de Custo ---
var costCenters = await api.GetCostCentersAsync(token, new CostCenterFilter
{
    Search = "TI",
    QuickFilter = QuickFilterType.Active,
    AscendingSortField = CostCenterSortField.Name
});

var newCenter = await api.CreateCostCenterAsync(new CreateCostCenterRequest
{
    Code = "CC-001",
    Name = "Departamento de TI"
}, token);

// --- Categorias Financeiras ---
var categories = await api.GetCategoriesAsync(token, new FinancialCategoryFilter
{
    Search = "receita",
    Type = "RECEITA",
    ChildrenOnly = true
});

// --- Categorias DRE (Demonstrativo de Resultado) ---
var dreCategories = await api.GetDreCategoriesAsync(token);

// --- Contas Financeiras ---
var accounts = await api.GetFinancialAccountsAsync(token, new FinancialAccountFilter
{
    ActiveOnly = true,
    Types = new() { "CONTA_CORRENTE", "POUPANCA" }
});

var balance = await api.GetAccountBalanceAsync("uuid-conta", token);

// --- Contas a Pagar ---
var payable = await api.CreatePayableAsync(new CreateFinancialEventRequest
{
    PersonId = "uuid-fornecedor",
    CategoryId = "uuid-categoria",
    Description = "Compra de material",
    CompetenceDate = "2026-02-11",
    Installments = new List<InstallmentItemRequest>
    {
        new()
        {
            Number = 1,
            Value = 500.00m,
            DueDate = "2026-03-11",
            FinancialAccountId = "uuid-conta",
            PaymentMethod = PaymentMethod.BankSlip
        }
    }
}, token);

// --- Contas a Receber ---
var receivable = await api.CreateReceivableAsync(new CreateFinancialEventRequest
{
    PersonId = "uuid-cliente",
    CategoryId = "uuid-categoria",
    Description = "Venda de servico",
    CompetenceDate = "2026-02-11",
    Installments = new List<InstallmentItemRequest>
    {
        new() { Number = 1, Value = 1000.00m, DueDate = "2026-03-11" }
    }
}, token);

// --- Busca de Contas a Receber ---
var receivables = await api.SearchReceivablesAsync(token, new ReceivableFilter("2026-01-01", "2026-12-31")
{
    Page = 1,
    PageSize = 50,
    Statuses = new() { FinancialEventStatus.Open, FinancialEventStatus.Overdue },
    ValueFrom = "100.00",
    ValueUntil = "10000.00"
});
// receivables.Items      -> Lista de FinancialEventSearchItem
// receivables.TotalItems -> Total de registros
// receivables.Totals     -> Contagem (ativo, inativo, todos)

// --- Busca de Contas a Pagar ---
var payables = await api.SearchPayablesAsync(token, new PayableFilter("2026-01-01", "2026-06-30")
{
    Page = 1,
    PageSize = 50,
    Statuses = new() { FinancialEventStatus.Open }
});

// --- Parcelas ---
var installments = await api.GetInstallmentsByEventAsync("uuid-evento", token);
var installment = await api.GetInstallmentByIdAsync("uuid-parcela", token);

Baixas (AcquittanceApi)

Registro e acompanhamento de pagamentos/recebimentos vinculados a parcelas.

Endpoint base: /v1/financeiro/eventos-financeiros/parcelas

var api = new AcquittanceApi();

// Registrar baixa (pagamento) em uma parcela
var acquittance = await api.CreateAsync("uuid-parcela", new CreateAcquittanceRequest
{
    PaymentDate = "2026-02-11",
    ValueComposition = new AcquittanceValueCompositionRequest
    {
        GrossValue = 1000.00m,
        Discount = 50.00m,
        Interest = 0m,
        Penalty = 0m,
        Fee = 0m
    },
    FinancialAccount = new { id = "uuid-conta" },
    PaymentMethod = PaymentMethod.PixInstantPayment
}, token);

// Listar baixas de uma parcela
var acquittances = await api.GetByInstallmentAsync("uuid-parcela", token);

// Buscar baixa por ID
var detail = await api.GetByIdAsync("uuid-baixa", token);

// Atualizar baixa (PATCH)
await api.PatchAsync("uuid-baixa", new UpdateAcquittanceRequest { /* ... */ }, token);

// Excluir baixa
await api.DeleteAsync("uuid-baixa", token);

Notas Fiscais (InvoiceApi)

Consulta de Notas Fiscais Eletronicas (NF-e) e vinculo com MDF-e.

Endpoint base: /v1/notas-fiscais

var api = new InvoiceApi();

// Listar notas fiscais com filtro tipado (datas obrigatorias)
var invoices = await api.GetAsync(token, new InvoiceFilter("2026-01-01", "2026-12-31")
{
    Page = 1,
    PageSize = 25,
    RecipientDocument = "12345678000190"
});

// Buscar nota fiscal por chave de acesso
var invoice = await api.GetByKeyAsync("chave-de-acesso-44-digitos", token);

// Vincular MDF-e a notas fiscais
await api.LinkMdfeAsync(new MdfeBindingRequest
{
    AccessKeys = new() { "chave1", "chave2" },
    Identifier = "identificador-mdfe",
    Status = "VINCULADO"
}, token);

NFS-e (ServiceInvoiceApi)

Consulta de Notas Fiscais de Servico Eletronicas (NFS-e).

Endpoint base: /v1/notas-fiscais-servico

var api = new ServiceInvoiceApi();

// Listar NFS-e com filtro tipado (datas de competencia obrigatorias, intervalo max 15 dias)
var serviceInvoices = await api.GetAsync(token, new ServiceInvoiceFilter("2026-02-01", "2026-02-15")
{
    Page = 1,
    PageSize = 25,
    NegotiationType = NegotiationType.Sale
});

Contratos (ContractApi)

Gestao de contratos recorrentes.

Endpoint base: /v1/contratos

var api = new ContractApi();

// Criar contrato
var contract = await api.CreateAsync(new CreateContractRequest
{
    ClientId = "uuid-cliente",
    IssuanceDate = "2026-02-11",
    Terms = new ContractTermsRequest
    {
        FrequencyType = BillingPeriod.Monthly,
        ExpirationType = "DATA",
        StartDate = "2026-03-01",
        EndDate = "2027-02-28",
        FrequencyInterval = 1,
        SaleIssuanceDay = 1
    },
    Items = new List<ContractItemRequest>
    {
        new() { Description = "Mensalidade", Quantity = 1, Value = 299.90m }
    },
    PaymentCondition = new ContractPaymentConditionRequest
    {
        PaymentType = "BOLETO_BANCARIO",
        FinancialAccountId = "uuid-conta",
        DueDay = 10
    }
}, token);

// Listar contratos com filtro tipado (datas obrigatorias)
var contracts = await api.GetAsync(token, new ContractFilter("2026-01-01", "2026-12-31")
{
    AscendingSortField = ContractSortField.StartDate,
    TextSearch = "mensalidade"
});

// Obter proximo numero de contrato
var next = await api.GetNextNumberAsync(token);

Models

Models Principais

Models Financeiros

Models Fiscais

Models de Contrato

Outros Models

Enums

Enums de dominio

Enums de filtro

Todos os enums utilizam [EnumMember(Value = "VALOR_API")] para serializar corretamente com os valores esperados pela API.

Paginacao

Endpoints que retornam listas utilizam o wrapper generico PaginatedResponse<T>:

var result = await customerApi.GetAsync(token, new PersonFilter
{
    Page = 1,
    PageSize = 50,
    SortField = PersonSortField.Name,
    SortDirection = SortDirection.Ascending
});

// Dados
foreach (var customer in result.Items)
{
    Console.WriteLine($"{customer.Name} - {customer.Document}");
}

// Informacoes de paginacao
Console.WriteLine($"Pagina {result.Pagination.Page} de {result.Pagination.TotalPages}");
Console.WriteLine($"Total de registros: {result.Pagination.TotalItems}");

Parametros de paginacao (disponiveis em todos os filtros que herdam PaginatedFilter):

• Page (pagina) - Numero da pagina (comeca em 1, default 1)
• PageSize (tamanho_pagina) - Itens por pagina (default 10)

Configuracao Avancada

HttpClient Customizado

A biblioteca permite injetar um IHttpClientWrapper customizado para cenarios de teste ou configuracao especial:

// Usar HttpClient customizado
var customClient = new StandardHttpClient(myHttpClient);
var api = new CustomerApi("/v1/pessoas", customClient, null);

Serializacao JSON Customizada

var jsonOptions = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
};

var api = new ProductApi("/v1/produtos", new StandardHttpClient(), jsonOptions);

Convencoes de Serializacao

A biblioteca utiliza System.Text.Json com as seguintes configuracoes padrao:

• Propriedades null sao omitidas na serializacao (WhenWritingNull)
• Mapeamento de propriedades via [JsonPropertyName] (nomes da API em portugues)
• Enums serializados como string via [JsonStringEnumConverter] com [EnumMember]
• Todas as chamadas async usam ConfigureAwait(false)

Requisitos

• .NET 9.0 ou superior
• System.Text.Json 9.0.10+
• Credenciais de API do Conta Azul (Client ID e Client Secret)

Build

# Compilar o projeto
dotnet build Codout.Apis.ContaAzul.csproj

# Gerar pacote NuGet
dotnet pack Codout.Apis.ContaAzul.csproj -c Release

Arquitetura

Codout.Apis.ContaAzul/
├── Api/                          # Classes de API (endpoints)
│   ├── AuthorizationApi.cs       # OAuth2 (token, refresh)
│   ├── CustomerApi.cs            # Pessoas/Clientes
│   ├── ProductApi.cs             # Produtos
│   ├── SaleApi.cs                # Vendas
│   ├── ServiceApi.cs             # Servicos
│   ├── CategoryApi.cs            # Categorias
│   ├── FinancialApi.cs           # Financeiro
│   ├── AcquittanceApi.cs         # Baixas
│   ├── InvoiceApi.cs             # NF-e
│   ├── ServiceInvoiceApi.cs      # NFS-e
│   └── ContractApi.cs            # Contratos
├── Interfaces/
│   ├── IApiResources.cs          # Interface base CRUD
│   └── IHttpClientWrapper.cs     # Abstracao de HttpClient
├── Models/                       # Models de dominio
│   ├── Enums/                    # 33 enums (dominio + filtro)
│   ├── Filters/                  # 20 filtros tipados + infraestrutura
│   └── Request/                  # DTOs de request (Create/Update)
├── ApiResource.cs                # Classe base com metodos HTTP genericos
└── StandardHttpClient.cs         # Implementacao padrao de HttpClient

Fluxo de chamada: SuaApp -> XxxApi -> ApiResource -> IHttpClientWrapper -> HttpClient -> API Conta Azul

Licenca

Copyright (c) Codout. Todos os direitos reservados.