Codout.Apis.ContaAzul

Name: Codout.Apis.ContaAzul
Author: 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.

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

Classe	Descricao
`FilterBase`	Classe base abstrata com `ToQueryString()` que converte propriedades `[QueryParam]` em query string
`PaginatedFilter`	Extends `FilterBase` com `Page` (pagina) e `PageSize` (tamanho_pagina)
`TextSearchFilter`	Extends `PaginatedFilter` com `TextSearch` (busca_textual)
`QueryParamAttribute`	Atributo que mapeia propriedade C# para nome do parametro na API

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

Filtro	Endpoint	Base	Parametros obrigatorios
`PersonFilter`	GET /v1/pessoas	`PaginatedFilter`	-
`ProductFilter`	GET /v1/produtos	`PaginatedFilter`	-
`SaleSearchFilter`	GET /v1/venda/busca	`PaginatedFilter`	-
`SaleItemFilter`	GET /v1/venda/{id}/itens	`PaginatedFilter`	-
`ServiceFilter`	GET /v1/servicos	`TextSearchFilter`	-
`ProductCategoryFilter`	GET /v1/produtos/categorias	`TextSearchFilter`	-
`NcmFilter`	GET /v1/produtos/ncm	`TextSearchFilter`	-
`CestFilter`	GET /v1/produtos/cest	`TextSearchFilter`	-
`UnitOfMeasureFilter`	GET /v1/produtos/unidades-medida	`TextSearchFilter`	-
`EcommerceBrandFilter`	GET /v1/produtos/ecommerce-marcas	`PaginatedFilter`	-
`EcommerceCategoryFilter`	GET /v1/produtos/ecommerce-categorias	`FilterBase`	-
`InvoiceFilter`	GET /v1/notas-fiscais	`PaginatedFilter`	`startDate`, `endDate`
`ServiceInvoiceFilter`	GET /v1/notas-fiscais-servico	`PaginatedFilter`	`competencyDateFrom`, `competencyDateUntil`
`ContractFilter`	GET /v1/contratos	`PaginatedFilter`	`startDate`, `endDate`
`CostCenterFilter`	GET /v1/centro-de-custo	`PaginatedFilter`	-
`FinancialAccountFilter`	GET /v1/conta-financeira	`PaginatedFilter`	-
`FinancialCategoryFilter`	GET /v1/categorias	`PaginatedFilter`	-
`ReceivableFilter`	GET /v1/.../contas-a-receber/buscar	`PaginatedFilter`	`dueDateFrom`, `dueDateUntil`
`PayableFilter`	GET /v1/.../contas-a-pagar/buscar	`PaginatedFilter`	`dueDateFrom`, `dueDateUntil`

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

Model	Descricao
`Person`	Dados completos de cliente/fornecedor/transportadora
`PersonSummary`	Resumo de pessoa para listagens
`Product`	Dados completos de produto com estoque, fiscal, variacoes
`ProductSummary`	Resumo de produto para listagens
`Sale`	Venda completa com cliente, itens, pagamento
`SaleSearch`	Resultado de busca de vendas com totais
`SaleItemsPaginated`	Itens de venda paginados com contagem por tipo
`Service`	Servico com classificacao fiscal
`Category`	Categoria de produto
`Address`	Endereco completo
`TokenResponse`	Resposta de autenticacao OAuth2

Models Financeiros

Model	Descricao
`FinancialEvent`	Lancamento financeiro (conta a pagar/receber)
`FinancialInstallment`	Parcela de evento financeiro
`FinancialEventSearchResult`	Resultado de busca de contas a receber/pagar
`FinancialEventSearchItem`	Item retornado na busca de eventos financeiros
`Acquittance`	Baixa (pagamento/recebimento)
`CostCenter`	Centro de custo
`FinancialAccount`	Conta financeira (corrente, poupanca, etc.)
`AccountBalance`	Saldo de conta financeira
`FinancialCategory`	Categoria financeira (receita/despesa)
`DreCategory`	Categoria DRE

Models Fiscais

Model	Descricao
`Invoice`	Nota Fiscal Eletronica (NF-e)
`ServiceInvoice`	Nota Fiscal de Servico (NFS-e)
`FiscalInfo`	Inscricoes estadual/municipal/Suframa
`Ncm`	Nomenclatura Comum do Mercosul
`Cest`	Codigo Especificador da Substituicao Tributaria
`TaxScenario`	Cenario tributario para servicos

Models de Contrato

Model	Descricao
`Contract`	Contrato completo com termos e itens
`ContractSummary`	Resumo de contrato para listagens
`NextNumber`	Proximo numero de contrato disponivel

Outros Models

Model	Descricao
`Municipality`	Municipio (codigo IBGE, nome, UF)
`OperationalNature`	Natureza da operacao
`OtherContact`	Contato adicional de pessoa
`Profile`	Perfil de pessoa (cliente, fornecedor, transportadora)
`Seller`	Vendedor
`UnitOfMeasure`	Unidade de medida
`PaginatedResponse<T>`	Wrapper generico de paginacao

Enums

Enums de dominio

Enum	Valores
`PaymentMethod`	BankSlip, CreditCard, DebitCard, DigitalWallet, Cash, PixInstantPayment, BankTransfer, Check, ... (22 valores)
`PersonType`	Physical, Legal, Foreign
`ProfileType`	Customer, Supplier, Carrier
`SaleStatus`	ReviewPending, InQuotation, QuotationAccepted, Approved, Invoiced, Canceled, ... (11 valores)
`ProductType`	Product, ProductKit, ProductVariation
`ProductStatus`	Active, Inactive
`ProductFormat`	Simple, Variation
`ProductOrigin`	Domestic, ForeignDirectImport, ForeignAcquiredInternally, ... (9 valores)
`ProductCondition`	New, Used
`FiscalProductType`	MerchandiseForResale, RawMaterial, FinishedProduct, FixedAsset, Services, ... (12 valores)
`ServiceType`	Provided, Received, Both
`ServiceStatus`	Active, Inactive
`MeasureUnit`	Percentage, Value
`StateRegistrationType`	NonContributor, Contributor, Exempt
`FinancialAccountType`	CheckingAccount, Savings, PettyCash, CreditCard, Investment, PaymentMethods, ContaAzulCharges, EasyReceiveCard, Others (9 valores)
`FinancialCategoryType`	Revenue, Expense
`BillingPeriod`	Monthly, Weekly, Biweekly, Quarterly, Semiannual, Annual, ... (7 valores)
`InstallmentStatus`	Pending, Settled, Canceled, Renegotiated, PartiallyReceived, Overdue, Lost (7 valores)
`ItemType`	Product, Service, FixedAssets, Financial, ProductKit (5 valores)
`OperationType`	Sale, Shipment, Purchase, Return (4 valores)
`StockLevel`	Minimum, Maximum, Standard
`StockMovement`	StockEntry, StockExit, NoStockChange (3 valores)
`TransactionDirection`	Sale, Purchase

Enums de filtro

Enum	Valores
`SortDirection`	Ascending (ASC), Descending (DESC)
`PersonSortField`	Name, Email, Document, Active
`ProductSortField`	Name
`SaleSortField`	Number, Client, Date
`SaleTotalType`	WaitingApproved, Approved, Canceled, All
`ContractSortField`	StartDate, EndDate
`CostCenterSortField`	Id, Code, Name, Active
`NegotiationType`	Sale, Contract
`FinancialEventStatus`	Lost, Received, Open, Renegotiated, PartiallyReceived, Overdue
`QuickFilterType`	Active, Inactive, All

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

Codout.Apis.ContaAzul

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

Indice

Instalacao
Inicio Rapido
Autenticacao
Filtros Tipados
APIs Disponiveis
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

Classe	Descricao
`FilterBase`	Classe base abstrata com `ToQueryString()` que converte propriedades `[QueryParam]` em query string
`PaginatedFilter`	Extends `FilterBase` com `Page` (pagina) e `PageSize` (tamanho_pagina)
`TextSearchFilter`	Extends `PaginatedFilter` com `TextSearch` (busca_textual)
`QueryParamAttribute`	Atributo que mapeia propriedade C# para nome do parametro na API

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

Filtro	Endpoint	Base	Parametros obrigatorios
`PersonFilter`	GET /v1/pessoas	`PaginatedFilter`	-
`ProductFilter`	GET /v1/produtos	`PaginatedFilter`	-
`SaleSearchFilter`	GET /v1/venda/busca	`PaginatedFilter`	-
`SaleItemFilter`	GET /v1/venda/{id}/itens	`PaginatedFilter`	-
`ServiceFilter`	GET /v1/servicos	`TextSearchFilter`	-
`ProductCategoryFilter`	GET /v1/produtos/categorias	`TextSearchFilter`	-
`NcmFilter`	GET /v1/produtos/ncm	`TextSearchFilter`	-
`CestFilter`	GET /v1/produtos/cest	`TextSearchFilter`	-
`UnitOfMeasureFilter`	GET /v1/produtos/unidades-medida	`TextSearchFilter`	-
`EcommerceBrandFilter`	GET /v1/produtos/ecommerce-marcas	`PaginatedFilter`	-
`EcommerceCategoryFilter`	GET /v1/produtos/ecommerce-categorias	`FilterBase`	-
`InvoiceFilter`	GET /v1/notas-fiscais	`PaginatedFilter`	`startDate`, `endDate`
`ServiceInvoiceFilter`	GET /v1/notas-fiscais-servico	`PaginatedFilter`	`competencyDateFrom`, `competencyDateUntil`
`ContractFilter`	GET /v1/contratos	`PaginatedFilter`	`startDate`, `endDate`
`CostCenterFilter`	GET /v1/centro-de-custo	`PaginatedFilter`	-
`FinancialAccountFilter`	GET /v1/conta-financeira	`PaginatedFilter`	-
`FinancialCategoryFilter`	GET /v1/categorias	`PaginatedFilter`	-
`ReceivableFilter`	GET /v1/.../contas-a-receber/buscar	`PaginatedFilter`	`dueDateFrom`, `dueDateUntil`
`PayableFilter`	GET /v1/.../contas-a-pagar/buscar	`PaginatedFilter`	`dueDateFrom`, `dueDateUntil`

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

Model	Descricao
`Person`	Dados completos de cliente/fornecedor/transportadora
`PersonSummary`	Resumo de pessoa para listagens
`Product`	Dados completos de produto com estoque, fiscal, variacoes
`ProductSummary`	Resumo de produto para listagens
`Sale`	Venda completa com cliente, itens, pagamento
`SaleSearch`	Resultado de busca de vendas com totais
`SaleItemsPaginated`	Itens de venda paginados com contagem por tipo
`Service`	Servico com classificacao fiscal
`Category`	Categoria de produto
`Address`	Endereco completo
`TokenResponse`	Resposta de autenticacao OAuth2

Models Financeiros

Model	Descricao
`FinancialEvent`	Lancamento financeiro (conta a pagar/receber)
`FinancialInstallment`	Parcela de evento financeiro
`FinancialEventSearchResult`	Resultado de busca de contas a receber/pagar
`FinancialEventSearchItem`	Item retornado na busca de eventos financeiros
`Acquittance`	Baixa (pagamento/recebimento)
`CostCenter`	Centro de custo
`FinancialAccount`	Conta financeira (corrente, poupanca, etc.)
`AccountBalance`	Saldo de conta financeira
`FinancialCategory`	Categoria financeira (receita/despesa)
`DreCategory`	Categoria DRE

Models Fiscais

Model	Descricao
`Invoice`	Nota Fiscal Eletronica (NF-e)
`ServiceInvoice`	Nota Fiscal de Servico (NFS-e)
`FiscalInfo`	Inscricoes estadual/municipal/Suframa
`Ncm`	Nomenclatura Comum do Mercosul
`Cest`	Codigo Especificador da Substituicao Tributaria
`TaxScenario`	Cenario tributario para servicos

Models de Contrato

Model	Descricao
`Contract`	Contrato completo com termos e itens
`ContractSummary`	Resumo de contrato para listagens
`NextNumber`	Proximo numero de contrato disponivel

Outros Models

Model	Descricao
`Municipality`	Municipio (codigo IBGE, nome, UF)
`OperationalNature`	Natureza da operacao
`OtherContact`	Contato adicional de pessoa
`Profile`	Perfil de pessoa (cliente, fornecedor, transportadora)
`Seller`	Vendedor
`UnitOfMeasure`	Unidade de medida
`PaginatedResponse<T>`	Wrapper generico de paginacao

Enums

Enums de dominio

Enum	Valores
`PaymentMethod`	BankSlip, CreditCard, DebitCard, DigitalWallet, Cash, PixInstantPayment, BankTransfer, Check, ... (22 valores)
`PersonType`	Physical, Legal, Foreign
`ProfileType`	Customer, Supplier, Carrier
`SaleStatus`	ReviewPending, InQuotation, QuotationAccepted, Approved, Invoiced, Canceled, ... (11 valores)
`ProductType`	Product, ProductKit, ProductVariation
`ProductStatus`	Active, Inactive
`ProductFormat`	Simple, Variation
`ProductOrigin`	Domestic, ForeignDirectImport, ForeignAcquiredInternally, ... (9 valores)
`ProductCondition`	New, Used
`FiscalProductType`	MerchandiseForResale, RawMaterial, FinishedProduct, FixedAsset, Services, ... (12 valores)
`ServiceType`	Provided, Received, Both
`ServiceStatus`	Active, Inactive
`MeasureUnit`	Percentage, Value
`StateRegistrationType`	NonContributor, Contributor, Exempt
`FinancialAccountType`	CheckingAccount, Savings, PettyCash, CreditCard, Investment, PaymentMethods, ContaAzulCharges, EasyReceiveCard, Others (9 valores)
`FinancialCategoryType`	Revenue, Expense
`BillingPeriod`	Monthly, Weekly, Biweekly, Quarterly, Semiannual, Annual, ... (7 valores)
`InstallmentStatus`	Pending, Settled, Canceled, Renegotiated, PartiallyReceived, Overdue, Lost (7 valores)
`ItemType`	Product, Service, FixedAssets, Financial, ProductKit (5 valores)
`OperationType`	Sale, Shipment, Purchase, Return (4 valores)
`StockLevel`	Minimum, Maximum, Standard
`StockMovement`	StockEntry, StockExit, NoStockChange (3 valores)
`TransactionDirection`	Sale, Purchase

Enums de filtro

Enum	Valores
`SortDirection`	Ascending (ASC), Descending (DESC)
`PersonSortField`	Name, Email, Document, Active
`ProductSortField`	Name
`SaleSortField`	Number, Client, Date
`SaleTotalType`	WaitingApproved, Approved, Canceled, All
`ContractSortField`	StartDate, EndDate
`CostCenterSortField`	Id, Code, Name, Active
`NegotiationType`	Sale, Contract
`FinancialEventStatus`	Lost, Received, Open, Renegotiated, PartiallyReceived, Overdue
`QuickFilterType`	Active, Inactive, All

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

cloviscoli/Codout.Apis.ContaAzulv2.3.0

Get Started

Readme

Codout.Apis.ContaAzul

Indice

Instalacao

Inicio Rapido

Autenticacao

Obter Token (Authorization Code)

Renovar Token (Refresh Token)

Filtros Tipados

Infraestrutura

Exemplo de uso

Filtros com parametros obrigatorios

Filtros disponiveis

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

Models Principais

Models Financeiros

Models Fiscais

Models de Contrato

Outros Models

Enums

Enums de dominio

Enums de filtro

Paginacao

Configuracao Avancada

HttpClient Customizado

Serializacao JSON Customizada

Convencoes de Serializacao

Requisitos

Build

Arquitetura

Licenca

cloviscoli/Codout.Apis.ContaAzulv2.3.0

Get Started

Readme

Codout.Apis.ContaAzul

Indice

Instalacao

Inicio Rapido

Autenticacao

Obter Token (Authorization Code)

Renovar Token (Refresh Token)

Filtros Tipados

Infraestrutura

Exemplo de uso

Filtros com parametros obrigatorios

Filtros disponiveis

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

Models Principais

Models Financeiros

Models Fiscais

Models de Contrato

Outros Models

Enums

Enums de dominio

Enums de filtro

Paginacao