astrotechlabs/melhorenvio-sdk

用于简化与Melhor Envio服务和API集成的库

维护者

详细信息

github.com/AstrotechLabs/melhorenvio-sdk

源代码

问题

安装: 2

依赖项: 0

建议者: 0

安全: 0

星级: 0

关注者: 1

分支: 0

开放问题: 0

类型：项目

1.0.0 2024-01-09 14:57 UTC

Requires

Requires (Dev)

BSD-3-Clause 605ef9b78d15f3c4f036477a3d3592a7bc19f236

This package is auto-updated.

Last update: 2024-09-09 16:32:28 UTC

README

欢迎使用Melhor Envio SDK！我们的库允许开发者与Melhor Envio服务进行简单直接的通信。使用它，可以执行操作，如进行运费报价、创建订单、购买运费和生成标签（查看示例）。

目录

安装

安装此软件包的最佳方式是通过composer。

要安装，只需执行以下命令

php composer.phar require astrotechlabs/melhorenvio-sdk

或添加以下行

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

到您的composer.json文件中的require部分。

如何使用？

运费报价

在我们的SDK中，允许通过产品或包装进行运费报价。

按产品

可以单独为产品计算运费，提供以下重量和其他数据。

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);

输出

[
    '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
                    ]
                ]
            ...... 
    ]
]

按包装

可以按照以下模型进行包装计算

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);

输出

[
    '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
                    ]
                ]
            ...... 
    ]
]

将商品添加到购物车

我们的SDK允许用户将需要发送的产品集中组织到一处。

可以添加商品到购物车，并详细说明信息，如重量、尺寸和申报价值。

在继续之前，您需要将发送的商品添加到购物车中。在此步骤中，将生成包含所有详细信息的订单，并返回一个id，该id将在后续购买运费和生成标签时使用。

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);

输出

[
    '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' => 
            
        ]
]

购买运费

在选择基于可用报价的最佳运费选项后，可以直接购买合作伙伴物流公司的运输服务。

为此操作需要订单id。

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);

输出

[
    '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' => 
                                                ]
                                    ]
                                   ]
                     ]
    ]
]

生成标签

在选择所需的运费选项并购买服务后，我们的SDK可以快速简单地创建发货标签。

为此操作需要订单id。

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);

输出

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

以下是从运费报价到生成标签的流程示例

<?php
// imports aqui

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

/**
 Aqui executamos a ação de calcular o frete.
 */

$melhorEnvioService->freightCalculate(
    new FreightCalculationInputData(
        to: new FreightCalculationToData(postalCode: "60820050"),
        from: new FreightCalculationFromData(postalCode: "60820050"),
        products: new FreightCalculationProductCollection(
            [
                new FreightCalculationProduct(
                    id: 'x',
                    width: 11,
                    height: 17,
                    length: 11,
                    weight: 3,
                    insurance_value: 10.1,
                    quantity: 1
                )
            ]
        )
    )
);

/**
Iniciando o fluxo de adição do pedido no carrinho, compra de frete e geração da etiqueta
 */

$addShippingToCartResponse = $melhorEnvioService->addShippingToCart(new AddShippingToCartItem(
    service: 2,
    from: new AddShippingToCartFromData(
        name: self::$faker->name(),
        companyDocument: "93.472.569/0001-30",
        address: "Jardim sem Oliveiras",
        city: "Cidade dos Empregados",
        postalCode:"08552070"
    ),
    to: new AddShippingToCartToData(
        name: self::$faker->name(),
        document: "21540911055",
        address: "Jardim das Oliveiras",
        city: "Cidade 2000",
        postalCode:"60820050",
        isPf: true
    ),
    products: new AddShippingToCartProductCollection(
        [
            new AddShippingToCartProduct(
                name: 'perfume'
            )
        ]
    ),
    volumes: new AddShippingToCartVolumeCollection(
        [
            new AddShippingToCartVolume(
                height: 43,
                width: 60,
                length: 70,
                weight: 30
            )
        ]
    ),
    options:new AddShippingToCartOptionData(
        insuranceValue: 50.00,
    )
));

/**
 Compra de frete
 */

$confirmPurchaseLabelResponse = $melhorEnvioService->confirmPurchase(
    new ConfirmPurchaseLabelInput(
        orders: new ConfirmPurchaseLabelOrderCollection(
            [
                new ConfirmPurchaseLabelOrder(
                    key: $addShippingToCartResponse['id']
                )
            ]
        )
    )
);

/**
 Geração da etiqueta
 */

$generateLabelResponse = $melhorEnvioService->generateLabel(new GenerateLabelInputData(
    orders: new GenerateLabelOrderCollection(
        [
                new GenerateLabelOrder(
                    key: $addShippingToCartResponse['id']
                )
            ]
    )
));

贡献

欢迎Pull Request。对于重要的更改，请首先创建一个issue来讨论您想进行哪些更改。

请确保根据需要更新测试。

许可证

此软件包是在MIT许可证下发布的。有关详细信息，请参阅LICENSE。