PHPackages                             astrotechlabs/melhorenvio-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. astrotechlabs/melhorenvio-sdk

ActiveProject[API Development](/categories/api)

astrotechlabs/melhorenvio-sdk
=============================

Biblioteca para facilitar integração com serviços e API's do Melhor Envio

1.0.0(2y ago)06BSD-3-ClausePHPPHP ^8.2

Since Dec 29Pushed 2y ago1 watchersCompare

[ Source](https://github.com/AstrotechLabs/melhorenvio-sdk)[ Packagist](https://packagist.org/packages/astrotechlabs/melhorenvio-sdk)[ RSS](/packages/astrotechlabs-melhorenvio-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (12)Versions (5)Used By (0)

Melhor Envio SDK para PHP
=========================

[](#melhor-envio-sdk-para-php)

Bem-vindo ao SDK do Melhor Envio! Nossa biblioteca permite ao desenvolvedor realizar uma comunicação simples e direta com o serviço Melhor Envio. Com ela é possível realizar operações como fazer cotação de frete, criação de pedidos, compra de frete e geração de etiquetas (veja exemplos).

Índice
------

[](#índice)

- [Instalação](#instala%C3%A7%C3%A3o)
- [Como Usar?](#como-usar)
- [Cotações de Frete](#cota%C3%A7%C3%B5es-de-frete)
    - [Por Produtos](#por-produtos)
    - [Por Pacotes](#por-pacotes)
    - [Inserção de itens ao carrinho](#inser%C3%A7%C3%A3o-de-itens-ao-carrinho)
    - [Compra de Fretes](#compra-de-fretes)
    - [Geração de Etiquetas](#gera%C3%A7%C3%A3o-de-etiquetas)
- [Exemplo de uso](#abaixo-veja-o-exemplo-do-fluxo-desde-a-cota%C3%A7%C3%A3o-do-frete-%C3%A0-gera%C3%A7%C3%A3o-de-etiquetas)
- [Contributing](#contributing)
- [Licence](#licence)

Instalação
----------

[](#instalação)

A forma mais recomendada de instalar este pacote é através do [composer](http://getcomposer.org/download/).

Para instalar, basta executar o comando abaixo

```
php composer.phar require astrotechlabs/melhorenvio-sdk
```

ou adicionar esse linha

```
"astrotechlabs/melhorenvio-sdk": "^1.0"

```

na seção `require` do seu arquivo `composer.json`.

Como Usar?
----------

[](#como-usar)

Cotações de Frete
-----------------

[](#cotações-de-frete)

Em nosso SDK é permitido realizar as cotações tanto por produtos, quanto por pacotes.

### Por Produtos

[](#por-produtos)

É possível realizar o cálculo de um frete por produtos individualmente, informando o peso e os demais dados abaixo.

```
use AstrotechLabs\MelhorEnvio\MelhorEnvioService;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\InputData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\ToData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\FromData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\ProductCollection;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\Product;

$melhorEnvioService = new MelhorEnvioService(
    accessToken: "xxxxxx.yyyyyyy.zzzzzz",
    userAgent: "name project (email vinculed)", // esse nome e email são os dados que foram cadastrados no melhor envio
    //isSandBox: true (Optional)
);

$freightCalculationResponse = $melhorEnvioService->freightCalculate(
    new InputData(
        to: new ToData(postalCode: "60820050"),
        from: new FromData(postalCode: "60820050"),
        products: new ProductCollection(
            [
                new Product(
                    id: 'x',
                    width: 11,
                    height: 17,
                    length: 11,
                    weight: 3,
                    insurance_value: 10.1,
                    quantity: 1
                )
            ]
        )
    )
);

print_r($freightCalculationResponse);
```

Saída

```
[
    'deliveryDetails' => [
            [
              'id' => 1
              'name' => PAC
              'error' => Serviço econômico indisponível para o trecho.
              'company' => [
                      'id' => 1
                      'name' => Correios
                      'picture' => https://sandbox.melhorenvio.com.br/images/shipping-companies/correios.png
                  ]
                ],
             [
                'id' => 2
                'name' => SEDEX
                'price' => 18.08
                'custom_price' => 18.08
                'discount' => 9.12
                'currency' => R$
                'delivery_time' => 2
                'delivery_range' => [
                        'min' => 1
                        'max' => 2
                    ]
                'custom_delivery_time' => 2
                'custom_delivery_range' => [
                        'min' => 1
                        'max' => 2
                    ]
                'packages' => [
                      [
                        'price' => 18.08
                        'discount' => 9.12
                        'format' => box
                        'dimensions' => [
                                'height' => 11
                                'width' => 11
                                'length' => 17
                            ]
                        'weight' => 3.00
                        'insurance_value' => 10.10
                        'products' => [
                                [
                                  'id' => x
                                  'quantity' => 1
                                ]
                            ]
                     ]
                  ],
                'additional_services' => [
                        'receipt' =>
                        'own_hand' =>
                        'collect' =>
                    ]
                'company' => [
                      'id' => 1
                      'name' => Correios
                      'picture' => https://sandbox.melhorenvio.com.br/images/shipping-companies/correios.png
                    ]
                ]
            ......
    ]
]

```

### Por Pacotes

[](#por-pacotes)

É possível realizar o cálculo por pacotes, seguindo o modelo abaixo:

```
use AstrotechLabs\MelhorEnvio\MelhorEnvioService;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\InputData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\ToData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\FromData;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\PackageCollection;
use AstrotechLabs\MelhorEnvio\FreightCalculation\Dto\Package;

$melhorEnvioService = new MelhorEnvioService(
    accessToken: "xxxxxx.yyyyyyy.zzzzzz",
    userAgent: "name project (email vinculed)",
    //isSandBox: true (Optional)
);

$freightCalculationResponse = $melhorEnvioService->freightCalculate(
    new InputData(
        to: new ToData(postalCode: "60876590"),
        from: new FromData(postalCode: "60820050"),
        package: new PackageCollection(
            [
                new Package(
                    height: 17,
                    width: 11,
                    length: 11,
                    weight: 3,
                )
            ]
        ),
        isProduct: false
    )
);

print_r($freightCalculationResponse);
```

Saída

```
[
    'deliveryDetails' => [
            [
              'id' => 1
              'name' => PAC
              'error' => Serviço econômico indisponível para o trecho.
              'company' => [
                      'id' => 1
                      'name' => Correios
                      'picture' => https://sandbox.melhorenvio.com.br/images/shipping-companies/correios.png
                  ]
                ],
             [
                'id' => 2
                'name' => SEDEX
                'price' => 18.08
                'custom_price' => 18.08
                'discount' => 9.12
                'currency' => R$
                'delivery_time' => 2
                'delivery_range' => [
                        'min' => 1
                        'max' => 2
                    ]
                'custom_delivery_time' => 2
                'custom_delivery_range' => [
                        'min' => 1
                        'max' => 2
                    ]
                'packages' => [
                      [
                        'price' => 18.08
                        'discount' => 9.12
                        'format' => box
                        'dimensions' => [
                                'height' => 11
                                'width' => 11
                                'length' => 17
                            ]
                        'weight' => 3.00
                        'insurance_value' => 10.10
                        'products' => [
                                [
                                  'id' => x
                                  'quantity' => 1
                                ]
                            ]
                     ]
                  ],
                'additional_services' => [
                        'receipt' =>
                        'own_hand' =>
                        'collect' =>
                    ]
                'company' => [
                      'id' => 1
                      'name' => Correios
                      'picture' => https://sandbox.melhorenvio.com.br/images/shipping-companies/correios.png
                    ]
                ]
            ......
    ]
]

```

### Inserção de itens ao carrinho

[](#inserção-de-itens-ao-carrinho)

Nosso SDK permite aos usuários reunir e organizar os produtos a serem enviados em um único local.

É possível adicionar itens ao carrinho detalhando informações como peso, dimensões e valor declarado.

Antes de prosseguir, você deverá adicionar num carrinho os produtos que serão enviados. Nesse passo será gerado o pedido com todos os detalhes e será retornado um id, que será necessário posteriormente para a compra de frete e geração de etiqueta.

```
use AstrotechLabs\MelhorEnvio\MelhorEnvioService;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\AddShippingToCartItem;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\ToData;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\FromData;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\ProductCollection;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\Products;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\VolumeCollection;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\Volume;
use AstrotechLabs\MelhorEnvio\AddShippingToCart\Dto\OptionsData;

$melhorEnvioService = new MelhorEnvioService(
    accessToken: "xxxxxx.yyyyyyy.zzzzzz",
    userAgent: "name project (email vinculed)",
    //isSandBox: true (Optional)
);

$addShippingToCartResponse = $melhorEnvioService->addShippingToCart(new AddShippingToCartItem(
        service: 2,
        from: new FromData(
            name: self::$faker->name(),
            companyDocument: "93.472.569/0001-30",
            address: "Jardim sem Oliveiras",
            city: "Cidade dos Empregados",
            postalCode:"08552070" // Considera-se apenas números.
        ),
        to: new ToData(
            name: self::$faker->name(),
            document: "21540911055",
            address: "Jardim das Oliveiras",
            city: "Cidade 2000",
            postalCode:"60820050",
            isPf: true // Caso verdadeiro deverá ser informado para o atributo document um CPF válido, caso contrário será considerado um CNPJ válido
        ),
        products: new ProductCollection(
            [
                new Product(
                    name: 'perfume'
                )
            ]
        ),
        volumes: new VolumeCollection(
            [
                new Volume(
                    height: 43,
                    width: 60,
                    length: 70,
                    weight: 30
                )
            ]
        ),
        options:new OptionsData(
            insuranceValue: 50.00,
        )
    )
);

print_r($addShippingToCartResponse);
```

Saída

```
[
    'id' => 9af54411-a4c1-4e64-9ccd-06959f59b984
    'protocol' => ORD-202312198407
    'serviceId' => 2
    'price' => 615.76
    'deliveryMinDays' => 4
    'deliveryMaxDays' => 5
    'status' => pending
    'payloadDetails' => [
            'id' => 9af54411-a4c1-4e64-9ccd-06959f59b984
            'protocol' => ORD-202312198407
            'service_id' => 2
            'agency_id' =>

        ]
]

```

### Compra de Fretes

[](#compra-de-fretes)

Após selecionar a melhor opção de frete com base nas cotações disponíveis, é possível realizar a compra direta dos serviços de transporte de transportadoras parceiras.

Para esta ação é necessário o id do pedido.

```
use AstrotechLabs\MelhorEnvio\MelhorEnvioService;
use AstrotechLabs\MelhorEnvio\ConfirmPurchaseLabel\Dto\InputData;
use AstrotechLabs\MelhorEnvio\ConfirmPurchaseLabel\Dto\OrderCollection;
use AstrotechLabs\MelhorEnvio\ConfirmPurchaseLabel\Dto\Order;

$melhorEnvioService = new MelhorEnvioService(
    accessToken: "xxxxxx.yyyyyyy.zzzzzz",
    userAgent: "name project (email vinculed)",
    //isSandBox: true (Optional)
);

$confirmPurchaseLabelResponse = $melhorEnvioService->confirmPurchase(
    new InputData(
        orders: new OrderCollection(
            [
                new Order(
                    key: '9af3f99a-301e-4239-9c3d-7cb7e7bb3825'
                )
            ]
        )
    )
);

print_r($confirmPurchaseLabelResponse);
```

Saída

```
[
    'purchase' =>
    [
        'id' => 9af54936-6611-4152-a4dc-8cba23127b2e
        'protocol' => PUR-20231235457
        'total' => 615.76
        'discount' => 107.05
        'status' => paid
        'paid_at' => 2023-12-28 17:00:59
        'canceled_at' =>
        'created_at' => 2023-12-28 17:00:59
        'updated_at' => 2023-12-28 17:00:59
        'payment' =>
            'transactions' =>
                [
                    [
                    'id' => 9af54936-6d78-4215-87b0-19f7581056ec
                    'protocol' => TRN-20231275008
                    'value' => 615.76
                    'type' => debit
                    'status' => authorized
                    'description' => Pagamento de envios (PUR-20231235457)
                    'authorized_at' => 2023-12-28 17:00:59
                    'unauthorized_at' =>
                    'reserved_at' =>
                    'canceled_at' =>
                    'created_at' => 2023-12-28 17:00:59
                    'description_internal' =>
                    'reason' => [
                                'id' => 7
                                'label' => Pagamento de envios
                                'description' =>
                            ]
                    ]
                ]
            ......
        ]
'payloadDetails' =>
    [
        'purchase' => [
                'id' => 9af54936-6611-4152-a4dc-8cba23127b2e
                'protocol' => PUR-20231235457
                'total' => 615.76
                'discount' => 107.05
                'status' => paid
                'paid_at' => 2023-12-28 17:00:59
                'canceled_at' =>
                'created_at' => 2023-12-28 17:00:59
                'updated_at' => 2023-12-28 17:00:59
                'payment' =>
                'transactions' => [
                                   [
                                    'id' => 9af54936-6d78-4215-87b0-19f7581056ec
                                    'protocol' => TRN-20231275008
                                    'value' => 615.76
                                    'type' => debit
                                    'status' => authorized
                                    'description' => Pagamento de envios (PUR-20231235457)
                                    'authorized_at' => 2023-12-28 17:00:59
                                    'unauthorized_at' =>
                                    'reserved_at' =>
                                    'canceled_at' =>
                                    'created_at' => 2023-12-28 17:00:59
                                    'description_internal' =>
                                    'reason' => [
                                                    'id' => 7
                                                    'label' => Pagamento de envios
                                                    'description' =>
                                                ]
                                    ]
                                   ]
                     ]
    ]
]

```

### Geração de Etiquetas

[](#geração-de-etiquetas)

Após a escolha da opção de frete desejada e a compra do serviço, nosso SDK possibilita a criação rápida e simples de etiquetas de envio.

Para realizar essa ação será necessário o id do pedido.

```
use AstrotechLabs\MelhorEnvio\MelhorEnvioService;
use AstrotechLabs\MelhorEnvio\GenerateLabel\Dto\InputData;
use AstrotechLabs\MelhorEnvio\GenerateLabel\Dto\OrderCollection;
use AstrotechLabs\MelhorEnvio\GenerateLabel\Dto\Order;

$melhorEnvioService = new MelhorEnvioService(
    accessToken: "xxxxxx.yyyyyyy.zzzzzz",
    userAgent: "name project (email vinculed)",
    //isSandBox: true (Optional)
);

$generateLabelResponse = $melhorEnvioService->generateLabel(new InputData(
        orders: new OrderCollection(
            [
                new Order(
                    key: '9af3f99a-301e-4239-9c3d-7cb7e7bb3825'
                )
            ]
        )
    )
);

print_r($generateLabelResponse);
```

Saída

```
[
    'details' => [
            '9af54411-a4c1-4e64-9ccd-06959f59b984' => [
                    'status' => 1
                    'message' => Envio gerado com sucesso
                ]
        ]
]

```

Abaixo veja o exemplo do fluxo desde a cotação do frete à geração de etiquetas
------------------------------------------------------------------------------

[](#abaixo-veja-o-exemplo-do-fluxo-desde-a-cotação-do-frete-à-geração-de-etiquetas)

```