Shipment SDK - Serviço de cotações do Melhor Envio

Agora ficou mais fácil ter o serviço de cotações do Melhor Envio no seu projeto de e-commerce.

Índice

• Instalação
• Cofiguração Inicial
• Exemplos de uso
  • Criação da calculadora
  • Adicionando CEPs de origem e destino
  • Produtos
    • Adicionando os produtos para cotação
  • Pacotes
    • Adicionando os pacotes para cotação
  • Adicionando os serviços das transportadoras
  • Adicionando serviços adicionais
  • Retornando a cotação
• Mais exemplos
• Testes
• Changelog
• Contribuindo
• Segurança
• Créditos
• Licença

Dependências

require

• PHP 7.4, 8.0 ou 8.1
• Ext-json = *
• Guzzlehttp/guzzle >= 7.0
• symfony/polyfill-php74 >= 1.23

require-dev

• mockery/mockery >= 1.3.6
• phpunit/phpunit >= 9.5

Instalação

Você pode instalar o pacote via composer, rodando o seguinte comando:

composer require melhorenvio/shipment-sdk-php

Configuração inicial

A instância criada de Shipment permite que você passe como parâmetros o seu token e o ambiente que você trabalhará, assim terá a autenticação pronta.

Lembrando que só será válido, se a criação do token pertencer ao mesmo ambiente passado como parâmetro.

Se você ainda não fez o processo de autorização, o Melhor Envio possui outro pacote para facilitar o processo. Você pode acessá-lo clicando aqui.

require "vendor/autoload.php";

use MelhorEnvio\Shipment;
use MelhorEnvio\Resources\Shipment\Package;
use MelhorEnvio\Enums\Service;
use MelhorEnvio\Enums\Environment;

// Create Shipment Instance
$shipment = new Shipment('your-token', Environment::PRODUCTION);

Exemplos de uso

Criando a instância calculadora

Neste exemplo você criará uma instância para calculadora no seu código.

// Create Calculator Instance
$calculator = $shipment->calculator();

Adicionando CEPs de origem e destino

Nesta parte você deve definir os CEPs de origem e destino respectivamente.

// Builds calculator payload
$calculator->postalCode('01010010', '20271130');

Produtos

Adicionando os produtos para cotação

Nesta parte, você irá definir os produtos que servirão para a sua cotação as informações que devem ser passadas como parâmetro são as seguintes:

• Altura
• Largura
• Comprimento
• Peso
• Valor segurado
• Quantidade

Lembrando que o valor segurado por padrão deve ser o valor do produto.

$calculator->addProducts(
        new Product(uniqid(), 40, 30, 50, 10.00, 100.0, 1),
        new Product(uniqid(), 5, 1, 10, 0.1, 50.0, 1)
    );

Pacotes

Adicionando os pacotes para cotação

Nesta parte, você irá definir os pacotes que servirão para sua cotação, as informações que devem ser passadas como parâmetro são as seguintes:

• Altura
• Largura
• Comprimento
• Peso
• Valor segurado

As dimensões sempre devem ser passadas em centímetros e o peso em quilogramas. São as unidades que o Melhor Envio opera.

Lembrando que o valor segurado por padrão deve ser o valor do produto em Reais.

 $calculator->addPackages(
        new Package(12, 4, 17, 0.1, 6.0),
        new Package(12, 4, 17, 0.1, 6.0),
        new Package(12, 4, 17, 0.1, 6.0),
        new Package(12, 4, 17, 0.1, 6.0)
    );

É importante ressaltar que os métodos de PACOTES e PRODUTOS não poderão ser utilizados conjuntamente, devendo ser utilizado apenas um ou outro.

Adicionando os serviços das transportadoras

Se você desejar customizar, nesta parte serão escolhidos os serviços das transportadoras que você deseja utilizar. Hoje, no Melhor Envio, estão disponíveis:

• Correios
• Jadlog
• Via Brasil
• Azul Cargo
• Latam Cargo

$calculator->addServices(
        Service::CORREIOS_PAC, 
        Service::CORREIOS_SEDEX,
        Service::CORREIOS_MINI,
        Service::JADLOG_PACKAGE, 
        Service::JADLOG_COM, 
        Service::AZULCARGO_AMANHA,
        Service::AZULCARGO_ECOMMERCE,
        Service::LATAMCARGO_JUNTOS,
        Service::VIABRASIL_RODOVIARIO
    );

Adicionando serviços adicionais

Se você desejar customizar, pode configurar alguns serviços adicionais na sua cotação, são eles:

• Mão própria
• Aviso de recebimento
• Coleta

Lembrando que a adição desses serviços podem gerar acréscimos no preço na hora da cotação.

$calculator->setOwnHand();
$calculator->setReceipt();
$calculator->setCollect();

Retornando as informações da cotação

Aqui você retornará as informações do payload montado.

$quotations = $calculator->calculate();

Mais exemplos

Aqui você pode acessar mais exemplos de implementação

Testes

Dentro do projeto você encontrará alguns documentos de teste baseados em testes unitários

Você pode usar na aplicação tanto o comando:

composer test

Quanto o comando:

vendor/bin/phpunit tests 

Changelog

Consulte CHANGELOG para mais informações de alterações recentes.

Contribuindo

Consulte CONTRIBUTING para mais detalhes.

Segurança

Se você descobrir algum problema de segurança, por favor, envie um e-mail para tecnologia@melhorenvio.com, ao invés de usar um issue tracker.

Créditos

• Rodrigo Silveira
• Marçal Pizzi
• Pedro Barros

Licença

Melhor Envio. Consulte Arquivo de licença para mais informações.