Correios.DataProvider 1.1.0

Correios.DataProvider

Biblioteca .NET 8 para integração com APIs oficiais dos Correios. Cobre autenticação por contrato, consulta de CEP, cálculo de preço, prazo e consulta combinada de preço com prazo.

Requisitos

• .NET 8 ou superior
• Contrato ativo com os Correios
• Usuario, codigo de acesso da API, cartao de postagem, contrato e codigo DR

Instalacao

dotnet add package Correios.DataProvider

Autenticacao

using Correios.DataProvider.Common;
using Correios.DataProvider.Models.Authorization;
using Correios.DataProvider.Services.Authentication;

var usuario = new UsuarioCorreios
{
    Usuario = "usuario",
    CodigoDeAcessoAPI = "codigo-api",
    CartaoDePostagem = "0000000000",
    Contrato = "0000000000",
    CodigoDR = CodigoDR.SaoPaulo
};

var login = await Login.InitializeAsync(usuario);

Login reutiliza token valido e renova autenticação quando necessário.

Consulta de CEP

using Correios.DataProvider.Services;

var service = new CEPService(login);
var response = await service.GetEnderecoAsync("01001-000");

if (response.Success)
{
    Console.WriteLine(response.Data?.Logradouro);
}

Consulta de preco

using Correios.DataProvider.Common;
using Correios.DataProvider.Requests;
using Correios.DataProvider.Services;

var request = new PrecoRequest
{
    IdLote = Guid.NewGuid().ToString(),
    ParametrosProduto =
    [
        new ParametroPrecoRequest
        {
            CoProduto = ProdutoCorreios.PAC_CONTRATO_AG,
            CepOrigem = "01001-000",
            CepDestino = "20040-020",
            Comprimento = "20",
            Largura = "15",
            Altura = "10",
            PsObjeto = "1000",
            NuContrato = usuario.Contrato,
            NuDR = usuario.CodigoDR
        }
    ]
};

var service = new PrecoService(login);
var response = await service.GetPrecoAsync(request);

Consulta de prazo

using Correios.DataProvider.Common;
using Correios.DataProvider.Requests;
using Correios.DataProvider.Services;

var request = new PrazoRequest
{
    IdLote = Guid.NewGuid().ToString(),
    ParametrosPrazo =
    [
        new ParametroPrazoRequest
        {
            CoProduto = ProdutoCorreios.SEDEX_CONTRATO_AG,
            CepOrigem = "01001-000",
            CepDestino = "20040-020"
        }
    ]
};

var service = new PrazoService(login);
var response = await service.GetPrazoAsync(request);

Preco com prazo

using Correios.DataProvider.Services;

var service = new PrecoPrazoService(login);
var response = await service.GetPrecoAsDtoAsync(request);

if (response.Success)
{
    Console.WriteLine(response.Data?.Valor);
    Console.WriteLine(response.Data?.PrazoDeEntrega);
}

Produtos suportados

Produtos ficam no enum ProdutoCorreios. Principais:

• PAC_CONTRATO_AG
• SEDEX_CONTRATO_AG
• SEDEX_10_CONTRATO_AG
• SEDEX_12_CONTRATO_AG
• SEDEX_HOJE_CONTRATO_AG
• CORREIOS_MINI_ENVIOS_CTR_AG

Use helpers para codigo e descricao:

var codigo = ProdutoCorreios.SEDEX_CONTRATO_AG.GetCodigo();
var descricao = ProdutoCorreios.SEDEX_CONTRATO_AG.GetDescricaoProduto();
var produto = ProdutoCorreiosExtensions.FromCodigo("03220");

Helpers

using Correios.DataProvider.Helper;

CEPHelper.IsValid("01001-000");
CEPHelper.Normalize("01001-000");
CEPHelper.Format("01001000");

var seguro = Calculadora.CalculaValorSeguro(1000m);

Validacao

A biblioteca limita consultas de preco e prazo a um produto por request. A API dos Correios aceita lotes, mas erros de um item podem quebrar a resposta inteira com mensagem genérica. Consulta individual preserva diagnóstico e compatibilidade.

Campos validados antes da chamada:

• CEP de origem
• CEP de destino
• Contrato em consulta de preco
• Lista de parametros com exatamente um item
• NuRequisicao, gerado automaticamente quando nulo

Configuracao

Valores padrao da API dos Correios já vêm embutidos. Se precisar sobrescrever endpoints, crie appsettings.json no diretório de execução:

{
  "CorreiosApi": {
    "BaseUrl": "https://api.correios.com.br",
    "Endpoints": {
      "CEP": "cep/v2/enderecos/",
      "Autentica": "token/v1/autentica/cartaopostagem",
      "Prazo": "prazo/v1/nacional",
      "Preco": "preco/v1/nacional"
    }
  }
}

Testes

dotnet test Correios.DataProvider.sln

Stack atual:

• xUnit
• FluentAssertions
• Microsoft.NET.Test.Sdk
• coverlet.collector

Desenvolvimento

dotnet restore Correios.DataProvider.sln
dotnet build Correios.DataProvider.sln
dotnet test Correios.DataProvider.sln

Dependencias principais

• ARSoft.RestApiClient 3.0.0
• Microsoft.Extensions.Configuration.Json 8.0.1
• Newtonsoft.Json 13.0.3

Observacoes

Esta biblioteca nao é oficial dos Correios. Valide valores críticos com as fontes oficiais antes de apresentar preço ou prazo ao cliente final.