devaguia / correios-php

Correios API library for PHP

Correios PHP

Correios API library for PHP

• Utilização Básica (Basic Usage)
• Respostas API (API Response)
• Autenticação (Authentication)
• Contribua - Contribute
• Árvore de Arquivos (File Tree)

Utilização Básica (Basic Usage)

Configuração (Setup)

// Parâmetros obrigatórios - Required Paramns
$correios = new \Correios\Correios(
    username: 'user',
    password: 'password',
    postcard: 'postcard',
    isTestMode: true
);

// Parâmetros opcionais - Optional parameters
$correios = new \Correios\Correios(
    username: 'user',
    password: 'password',
    postcard: 'postcard',
    isTestMode: true,
    token: 'string'
);

// Use um número de requisição e ID do lot personalizado - Use a custom request number and Lot ID
$correios->setRequestNumber(requestNumber: '20230831');
$correios->setLotId(requestNumber: '20230831LT');

Rastro (Tracking)

$response = $correios->tracking()->get(
    trackingCode: 'AASD546115A',
    filtered: 'U'
);

Preço (Price)

// Parâmetros obrigatórios - Required Paramns
$correios->price()->get(
    serviceCodes:['04162'],
    products:[
        ['weight' => 300]
    ],
    originCep:'71930000',
    destinyCep:'05336010'
);

// Parâmetros opcionais - Optional parameters
$correios->price()->get(
    serviceCodes:['04162'],
    products:[
        [
          'weight'      => 300,
          'length'      => 0,
          'height'      => 200,
          'width'       => 200,
          'diameter'    => 0,
          'cubicWeight' => 0,
          /** 1 - Envelope (Default); 2 - Caixa; 3 - Rolo*/
          'objectType' => 2
        ]
    ],
    originCep:'71930000',
    destinyCep:'05336010',
    fields: [
        'nuContrato' => '0000000000',
        'nuDR' => 20
    ]
);

Prazo (Date)

// Parâmetros obrigatórios - Required Paramns
$response = $correios->date()->get(
    serviceCodes: ['39870'],
    originCep: '71930000',
    destinyCep: '05336010'
);

// Parâmetros opcionais - Optional parameters
$correios->date()->get(
    serviceCodes:['04162'],
    originCep:'71930000',
    destinyCep:'05336010',
    fields: [
        'dtEvento' => '2023-01-01T01:01:01.001Z',
    ]
);

Endereço (Address)

$response = $correios->address()->get(cep: '05336010');

Respostas API (API Response)

$responseBody = $response->getResponseBody();
$responseCode = $response->getResponseCode();

if (empty($responseBody)) {
    $errors = $response->getErrors();
}

Autenticação (Authentication)

// Gerando um novo token - Generating a new token
$correios = new \Correios\Correios(
    username: 'user',
    password: 'password',
    postcard: 'postcard',
    isTestMode: true
);

$token           = $correios->authentication()->getToken();
$tokenExpiration = $correios->authentication()->getTokenExpiration();
$responseBody    = $correios->authentication()->getResponseBody();
$responseCode    = $correios->authentication()->getResponseCode();
$errors          = $correios->authentication()->getErrors();


// Usando um token gerado anteriormente - Using a token generated earlie
$correios = new \Correios\Correios(
    username: 'user',
    password: 'password',
    postcard: 'postcard',
    isTestMode: true
    token: 'eyJhbGciOiJSUzUxMiJ9.eyJhbWJpZW50ZSI6IlBST0RVQ0FPIiwiaWQiOiI0MDExMjE1NDAwMDE5MCIsInBmbCI6IlBKIiwiY25waiI6IjQwMTEyMTU0MDAwMTkwIiwiY29udHJhdG8iOnsibnVtZXJvIjoiOTkxMjYxNjgzOSIsImRyIjoyMCwiYXBpIjpbMjcsMzQsMzUsNDEsNzYsODcsNTY2XX0sImlwIjoiMTcwLjc4LjY4Ljg2LDE3MC43OC42OC44NiIsImlhdCI6MTY5MjY0MTU2MywiaXNzIjoidG9rZW4tc2VydmljZSIsImV4cCI6MTY5MjcyNzk2MywianRpIjoiZGViMTczM2EtYmVjYS00NmIyLWFkNGYtYWQ5ZjBkYWFlZjhlIn0.uxJCCQFj0c1qzI4BGk9JWTh6TT_Drp7YaMbKQoT9m-ie5wXRun4cOuQdbj28MQR3IYuntB2B9C8aqSoa_eXADtvf4J2H-ZTWS0wAnxsxxkNf1lXmHYrD2jCgRMVgQ_2dy40uBt0bJyk0M9e4jNg2almtZMlAwjbVrgSbopuNrqhHe49GuDIuQzJLqsNC60mA6KberD9eSSNZsvHbgNYQysK0mZTkIFdWy8DBJ7b5FrbLzbeikqKbRW9pDj_3Q-YrxhwQ79ZjEF8dLiAU3BcCDHwOxpSv6HKD5984mz1VppFXcaBAsqW6oB9iCHrENjVqtRXa8mx0nqbjelyz0Of6qA'
);

Contribua - Contribute

Por favor, se for contribuir, leia os arquivos de Manual de contribuição e Código de Conduta.

SonarLint

Durante o desenvolvimento, pedimos que use o plugin SonarLint, para que ele verifique a qualidade do código que está sendo desenvolvido - During development, we request that you use the SonarLint plugin to check the quality of the code being developed:

• VSCode
• PHPStorm

Instalação - Installation

Installing the composer dependencies

composer install

Running the unit tests

composer test

File Tree

.
├── CODE_OF_CONDUCT.md
├── composer.json
├── CONTRIBUTING.md
├── LICENSE
├── phpunit.xml
├── phpunit.xml.bak
├── README.md
├── src
│   ├── Correios.php
│   ├── Exceptions
│   │   ├── ApiRequestException.php
│   │   ├── InvalidCepException.php
│   │   ├── InvalidCorreiosServiceCode.php
│   │   ├── MissingProductParamException.php
│   │   └── SameCepException.php
│   ├── Helpers
│   │   ├── Cep.php
│   │   └── Settings.php
│   ├── Includes
│   │   ├── Cep.php
│   │   ├── Product.php
│   │   ├── Settings.php
│   │   └── Traits
│   │       └── CepHandler.php
│   └── Services
│       ├── AbstractRequest.php
│       ├── Address
│       │   └── Cep.php
│       ├── Authorization
│       │   └── Authentication.php
│       ├── Date
│       │   └── Date.php
│       ├── Price
│       │   └── Price.php
│       └── Tracking
│           └── Tracking.php
└── tests
    └── Unit
        ├── CorreiosTest.php
        ├── Helpers
        │   ├── CepTest.php
        │   └── SettingsTest.php
        ├── Includes
        │   ├── CepTest.php
        │   ├── ProductTest.php
        │   └── SettingsTest.php
        └── Services
            ├── Address
            │   └── CepTest.php
            ├── Authorization
            │   └── AuthenticationTest.php
            ├── Date
            │   └── DateTest.php
            ├── Price
            │   └── PriceTest.php
            └── Tracking
                └── TrackingTest.php

correios-php's Issues

testing

testing

Create the Settings class unit tests

Criar novos testes para a propriedade 'objectType' na classe de produto

Uma nova funcionalidade foi criada na classe de produto, porem nenhum teste automatizado foi criado para ela. Necessário elaborar novos cenários de testes e aplicá-los para garantir o bom funcionamento do código.

Add a Code of conduct file to the project

Create service code list on the Settings class

Create the Price class unit tests

Funcionalidades de Emissão de Etiquetas

Bom dia @devaguia
Tem algum vontade/ideia de portar para o correios-php as funcionalidades de emissão de etiquetas, o bom e velho sigep?
Se tiver algo no roadmap, me avisa. Vou precisar portar o @php-sigep para a nova api dentro de breve.
Abraço
Mauro

Create a trait to handle the CEPs validation methods

Create a trait to be used by classes how needs CEP validation functions. The file must to have the follow methods:

• cleanUpCep
• validadeCep

Create the Cep class unit tests

Create the Product class unit tests

Creating the new Product class unit tests.

The class must to have the follow params:

• requestNumber - string;
• weight - float (required);
• length - float;
• height - float;
• width - float;
• diameter - float;
• cubicWeight - float;

Add a Contributing guidelines to the project

Using an invalid service code should throw an InvalidCorreiosServiceCode

Create the Tracking class unit tests

Duvida Sobre authenticação

Matheus @devaguia ,
Estava olhando o código, e acho que me perdi na analise..kkkk.
Quando eu já tenho o token, ele chama a api dos correios de token novamente no construct do Correios(), certo? Ou entendi errado?
Teoricamente, esta chamada adicional poderia ser 'economizada', e passar o token direto, pois ele que é usado no restante do código?
Pensei bobagem ou entendi errado?
Abraço,
Mauro

Create the Date class unit tests

Creating new optional params in the main class(Correios.php)

Create a new parameter on the main class constructor.
The 'lotId' parameter should be an string type and has to be possible access and change him using a get and set method.

Tests
Create new tests for this new methods and for the possible to use the new params on the class constructor

Send the library to the packagist.org

Create the Address class unit tests

Error handler to other type of Exceptions on the get methods

The 'get' method, present on the Address, Price, Date and Tracking files, should not generate a fatal error. Instead, she should handler and treat the error using the $errors property.

The get method shoul be able to treat the following Exceptions:

• InvalidCepException
• InvalidCorreiosServiceCode
• MissingProductParamException
• SameCepException

Add the contributing section to the README.md