README

🚀 使用 PHP 语言的 Melhor Envio 平台集成 SDK，简化集成过程。

索引

• 安装
• 认证
• 更新 Token
• 计算运费
• 标签
  • 请求购买
  • 处理购买
  • 生成标签
  • 检索跟踪码

预要求

在开始之前，您需要在您的计算机上安装以下工具

• Composer
• Apache 服务器

您需要在 Melhor Envio 平台上注册账户 Melhor Envio

安装

要安装此组件到您的项目，请使用 composer。 composer require duug-com-br/melhorenvio-sdk-php

认证

首先，您需要请求应用程序的使用权限。为此，请使用以下示例代码。

// Instancia o objeto
$MelhorEnvio = new MelhorEnvio\MelhorEnvio(
    "CLIENT ID",
    "SECRET KEY",
    "NOME DO APP",
    "EMAIL TECNICO"
);

// Adiciona a url de callback  
$MelhorEnvio->setCallbackURL("URL PARA RETORNO");

// Solicita a autenticacao
// O usuario será redirecionado para uma página da melhor envio.
$MelhorEnvio->requestAuthorization();

在请求权限后，用户将被重定向到提供的回调 URL。在该 URL 上将通过 GET 传递一个代码，该代码将用于生成 token。

// Solicita o token
$retorno = $MelhorEnvio->requestToken($_GET["code"]);

// Verifica se não ocorreu erro 
if(!$retorno["error"])
{
    // Recupera as informações 
    $retorno = $retorno["data"];
}

在返回的数据中，返回一个包含以下信息的数组

(Array)
[
    "accessToken" => "TOKEN PARA REQUISIÇÕES",
    "refreshToken" => "TOKEN PARA RENOVAÇÂO DO accessToken",
    "tokenValidate" => "Data de validade do token (+ 30 dias)"
]

更新 Token

更新过期 Token 的示例

// Solicita a atualizacao
$resposta = $MelhorEnvio->refreshToken($refreshToken);

// Verifica se deu certo
if(!$resposta["error"])
{
    // Armaze os novos tokens 
    $resposta["data"];
}

计算运费

计算特定产品的运费的示例。如果有多个产品，只需复制配置产品的行。

// Informa o token
$MelhorEnvio->setAccessToken("Access Token");

// Instancia o produto
$Product = new MelhorEnvio\Resoucers\Product();

// Seta as informações do produto.
// Pode duplicar esse item para adicionar mais produtos
$Product->setProducts(
    "Id do produto",
    "Nome do produto",
    "Largura",
    "Altura",
    "Comprimento",
    "Peso",
    "Valor do Produto",
    "Quantidade"
);

// Realiza o calculo do frete
$resposta = $MelhorEnvio->calculate("CEP do remetente", "CEP do destinatario", $Product);

// Verifica se deu certo
if(!$resposta["error"])
{
    // As informações do frete estão no array 
    $resposta["data"]
}

查看运费计算返回的示例数组。

(Array)
[
    company" => [
         "name" => Nome da transportadora
         "image" => Imagem da logo da transportadora
    ],
    "service" => Nome do serviço (ex: Pac, Sedex...)
    "timeDays" => Prazo em dias para entrega
    "code" => Codigo do servico
    "packages" => (Array) Lista dos pacotes que serão enviados
]

标签

使用此 SDK 可以通过 Melhor Envio 平台购买标签。请注意，您需要

请求购买

首先，您需要请求购买标签。请查看以下示例代码

// Informa o token
$MelhorEnvio->setAccessToken("Access Token");

// Destinatario e Remetente
$Destinatario = new MelhorEnvio\Resoucers\User();
$Remetente = new MelhorEnvio\Resoucers\User();


// Adiciona as informações
$Destinatario->setDocumentos("CPF");

$Destinatario->setInformacaoPessoal("NOME", "EMAIL", "CELULAR");

$Destinatario->setEndereco([
    "endereco" => "Rua xyz",
    "numero" => 123,
    "bairro" => "Jardim São José",
    "cidade" => "São Paulo",
    "cep" => 11200363
]);



// Adiciona as informações do remetente
$Remetente->setDocumentos("CPF", "CNPJ", "INCRICAO ESTADUAL");

$Remetente->setInformacaoPessoal("NOME", "EMAIL", "CELULAR");

$Remetente->setEndereco([
    "endereco" => "Rua xyz",
    "numero" => 123,
    "bairro" => "Jardim São José",
    "cidade" => "São Paulo",
    "cep" => 11200363
]);



// Instancia o produto
$Product = new MelhorEnvio\Resoucers\Product();

// Seta as informações do produto.
// Pode duplicar esse item para adicionar mais produtos
$Product->setProducts(
    "Id do produto",
    "Nome do produto",
    "Largura",
    "Altura",
    "Comprimento",
    "Peso",
    "Valor do Produto",
    "Quantidade"
);

// Pacote 
// Quando foi calculado o valor do frete, ele retorno os pacotes disponiveis
$pacotes = []; 


/**
* OBS: 
* Em caso de vários pacotes para a transportadora correios 
* deverá realizar uma solicitação por pacote. As demais poderá 
* realizar apenas uma solicitação passando um array de pacotes, 
* da maneira que iremos fazer agora.
**/

// Percorre os pacotes 
foreach ($packages as $package)
{
    $pacotes[] = [
        "height" => $packages->dimensions->height,
        "width" => $packages->dimensions->width,
        "length" => $packages->dimensions->length,
        "weight" => $packages->weight
    ];
}

// Codigo do serviço de envio
$code = "CODIGO DO SERVICO (RETORNADO NA BUSCA DO VALOR)";

// Realiza a solicitação de compra das etiqueta
$resposta = $MelhorEnvio->requestBuyTag($Destinatario, $Remetente, $Product, $pacote, $code, "Identificador do Pedido");

// Verifica se deu certo
if(!$resposta["error"])
{
    // Será retorno os ids da solicitação
    // Armaze os ids para poder realizar a compra da etiqueta
    $ids = $resposta["data"];
}

处理购买

拥有请求 ID 后，您现在需要购买标签。为了使此过程正常工作，您需要在平台上拥有余额。

// Verifica se o id retornado não é um array 
if(!is_array($ids))
{
    // Força ser um array
    $ids = [$ids];
}

// Realiza a compra da etiqueta
$resposta = $MelhorEnvio->processBuyTag($ids);

// Verifica se deu certo
if(!$resposta["error"])
{
    // Apos o pagamento é necessário realizar a solicitação 
    // para impressão da etiqueta.
}

生成标签

购买标签后，您需要请求打印标签，平台将返回一个包含 PDF 标签文件的链接。

// Solicita a impressão das etiquetas
$resposta = $MelhorEnvio->printTag($ids);

// Verifica se deu certo
if(!$resposta["error"])
{
    // É retornado um array contendo a url para impressão 
    $resposta["data"]
    
    // Exemplo do array retornado no item data
    // (Array) ["url" => "URL DO PDF DA ETIQUETA"]
}

检索跟踪码

生成标签后，您可以请求跟踪码以通知客户。

请查看以下示例代码

// Gera o codigo de rastreio
$rasteio = $MelhorEnvio->getTracking($ids);

// Verifica se deu certo
if(!$resposta["error"])
{
    // É retornado um array contendo os códigos 
    $resposta["data"]
}

查看数据数组返回的示例

(Array)
[
    [
        "tracking" => "CÓDIGO DE RASTREIO"
    ],
    [
        "tracking" => "CÓDIGO DE RASTREIO"
    ]
]

如果是单个包裹，则数组中只返回 1 项，包含跟踪码。

许可证