mingnini/correios-sdk

SDK PHP para integracao com APIs dos Correios

v0.1.3 2026-04-09 15:40 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.9

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Mingnini

• php
• sdk
• cep
• correios
• frete

README

SDK PHP para integracao com APIs dos Correios.

Requisitos

• PHP 8.0 ou superior
• Credenciais de acesso da API dos Correios
• Base URL da API correspondente ao ambiente usado pela sua conta

Instalacao

Pacote publicado no Packagist:

mingnini/correios-sdk

Packagist:

https://packagist.org/packages/mingnini/correios-sdk

composer require mingnini/correios-sdk

Depois da instalacao, carregue o autoload do Composer normalmente:

require 'vendor/autoload.php';

Instalacao Rapida

composer require mingnini/correios-sdk

<?php

require 'vendor/autoload.php';

use mingnini\CorreiosSdk\Correios;

$correios = new Correios(
    baseUrl: 'https://api.correios.com.br/',
    usuario: 'seu-usuario',
    codigoAcesso: 'seu-codigo',
    cartaoPostagem: 'seu-cartao',
    contrato: 'seu-contrato'
);

Configuracao

O SDK precisa de:

• baseUrl: URL base da API dos Correios do seu ambiente
• usuario: identificador usado para autenticacao
• codigoAcesso: codigo de acesso da API
• cartaoPostagem: cartao de postagem vinculado ao contrato
• contrato: numero do contrato usado nas consultas

Uso Basico

<?php

use mingnini\CorreiosSdk\Correios;
use mingnini\CorreiosSdk\Exceptions\CorreiosException;

$correios = new Correios(
    baseUrl: 'https://api.correios.com.br/',
    usuario: 'seu-usuario',
    codigoAcesso: 'seu-codigo',
    cartaoPostagem: 'seu-cartao',
    contrato: 'seu-contrato'
);

try {
    $endereco = $correios->cep()->buscar('01001-000');

    $cotacao = $correios->cotacao()->nacional([
        'codigo_servico' => '03220',
        'cep_origem' => '01001000',
        'cep_destino' => '20040002',
        'peso' => 200,
        'nu_requisicao' => '0001',
        'nu_dr' => 72,
        'tp_objeto' => '2',
        'comprimento' => 20,
        'largura' => 15,
        'altura' => 10,
        'diametro' => 0,
        'valor_declarado' => 0,
        'dt_evento' => date('d/m/Y'),
        'data_postagem' => date('Y-m-d'),
    ]);

    $rastreio = $correios->rastreio()->rastrear('AA123456789BR');
} catch (CorreiosException $exception) {
    echo $exception->getMessage();
}

Recursos Disponiveis

• cep()->buscar(string $cep): array
• preco()->nacional(array $payload): array
• prazo()->nacional(string $codigoServico, array $query): array
• prazo()->nacional(array $payload): array
• cotacao()->nacional(array $payload): array
• rastreio()->rastrear(array|string $dados): array

Payload de Preco

O metodo preco()->nacional() aceita um payload simplificado em snake_case e converte automaticamente para o formato oficial da API dos Correios (idLote + parametrosProduto).

Exemplo:

$preco = $correios->preco()->nacional([
    'codigo_servico' => '03220',
    'cep_origem' => '01001001',
    'cep_destino' => '06280180',
    'peso' => 200,
    'comprimento' => 20,
    'altura' => 20,
    'largura' => 20,
    'diametro' => 0,
    'valor_declarado' => 0,
    'nu_requisicao' => '0001',
    'nu_dr' => 72,
    'tp_objeto' => '2',
]);

Campos suportados no payload simplificado:

• codigo_servico
• cep_origem
• cep_destino
• peso
• comprimento
• altura
• largura
• diametro
• valor_declarado
• nu_requisicao
• nu_dr
• tp_objeto
• nu_contrato
• nu_unidade
• id_lote

Payload de Prazo

O metodo prazo()->nacional() tambem aceita um payload simplificado em snake_case e converte automaticamente para o formato oficial da API de prazo em lote.

Exemplo:

$prazo = $correios->prazo()->nacional([
    'codigo_servico' => '03220',
    'nu_requisicao' => '0001',
    'dt_evento' => date('d/m/Y'),
    'cep_origem' => '01001001',
    'cep_destino' => '06280180',
    'data_postagem' => date('Y-m-d'),
]);

Cotacao Combinada

O metodo cotacao()->nacional() executa preco e prazo com o mesmo payload e retorna ambos no mesmo array.

Exemplo:

$cotacao = $correios->cotacao()->nacional([
    'codigo_servico' => '03220',
    'cep_origem' => '01001001',
    'cep_destino' => '06280180',
    'peso' => 200,
    'nu_requisicao' => '0001',
    'nu_dr' => 72,
    'tp_objeto' => '2',
    'comprimento' => 20,
    'largura' => 20,
    'altura' => 20,
    'diametro' => 0,
    'valor_declarado' => 0,
    'dt_evento' => date('d/m/Y'),
    'data_postagem' => date('Y-m-d'),
]);

Retorno esperado:

[
    'preco' => [...],
    'prazo' => [...],
]

Rastreio

O metodo rastreio()->rastrear() aceita um array com codigo ou uma string direta.

Exemplos:

$rastreio = $correios->rastreio()->rastrear('AA123456789BR');

$rastreio = $correios->rastreio()->rastrear([
    'codigo' => 'AA123456789BR',
]);

Comportamento de Autenticacao

• O token e obtido automaticamente na primeira chamada autenticada.
• O token fica em cache na instancia do SDK.
• Se a API responder 401, o SDK limpa o token e tenta autenticar novamente uma vez.

Exemplos

Veja a pasta examples/ para scripts prontos de uso:

• examples/bootstrap.php
• examples/cep.php
• examples/preco.php
• examples/prazo.php
• examples/cotacao.php
• examples/rastreio.php

Executando Testes

composer dump-autoload
vendor/bin/phpunit

Publicacao

O fluxo de release esta resumido em RELEASE.md.

Estrutura

src/
  Auth/
  Exceptions/
  Http/
  Resources/
tests/
  Integration/
  Unit/
examples/

Licenca

MIT