README

简介

此包提供了一个易于使用的PHP客户端，用于与Correios API交互。它允许您获取Correios提供的不同产品的定价和交货时间。

安装

首先，您需要使用Composer将包添加到项目中。

composer require pedroquezado/correios

使用

初始化客户端

要初始化Cliente类，您需要提供您的Correios API凭据（用户名和密码）、卡号以及可选的第四个参数以指定环境（生产或测试）。默认情况下，客户端使用生产环境。

示例

require 'vendor/autoload.php';

use PedroQuezado\Code\Correios\Cliente;

// Initialize for production (default)
$cliente = new Cliente('correios_usuario', 'correios_senha_key', 'numero_cartao_postagem');

// Initialize for homologation
$clienteHomologacao = new Cliente('correios_usuario', 'correios_senha_key', 'numero_cartao_postagem', false);

correios_usuario：您的Correios API用户名。
correios_senha_key：您的Correios API密码。
numero_cartao_postagem：您的Correios卡号。
producao（可选）：布尔标志，用于指定环境。使用true表示生产（默认）和false表示测试。

添加产品

inserirProduto方法允许您将产品添加到客户端以进行进一步操作，例如价格和交货时间计算。该方法接受两个参数：$coProduto和包含产品详细信息的数组$arrProduto。

参数

$coProduto：这是产品代码（例如，SEDEX的‘03220’或PAC的‘03298’）。在后续操作中，它对于识别产品类型至关重要。
$arrProduto：一个包含产品详细信息的关联数组，包括
- nuRequisicao：请求号。
- cepOrigem：起始邮政编码。
- cepDestino：目的地邮政编码。
- psObjeto：物体的重量（克）。
- tpObjeto：物体类型（例如，‘1’表示盒子/包裹）。
- comprimento：物体长度（厘米）。
- largura：物体宽度（厘米）。
- altura：物体高度（厘米）。
- servicosAdicionais：附加服务的数组（例如，["001", "019"]）。
- vlDeclarado：申报价值。
- dtEvento：事件日期（DD/MM/YYYY）。

示例

$cliente->inserirProduto('03220', [
    "nuRequisicao" => "1",
    "cepOrigem" => "70002900",
    "cepDestino" => "05311900",
    "psObjeto" => "8000",
    "tpObjeto" => "1", // Caixa/Pacote
    "comprimento" => "20",
    "largura" => "20",
    "altura" => "20",
    "servicosAdicionais" => ["001", "019"], // Valor Declarado adicionado
    "vlDeclarado" => "100",
    "dtEvento" => "18/03/2022"
]);

$cliente->inserirProduto('03298', [
    "nuRequisicao" => "2",
    "cepOrigem" => "70002900",
    "cepDestino" => "05311900",
    "psObjeto" => "5000",
    "tpObjeto" => "1", // Caixa/Pacote
    "comprimento" => "30",
    "largura" => "30",
    "altura" => "30",
    "servicosAdicionais" => ["001", "064"], // Valor Declarado adicionado
    "vlDeclarado" => "200",
    "dtEvento" => "18/03/2022"
]);

在其他方法中的重要性

$coProduto参数对于consultarPrecoTotal和consultarPrazoTotal方法是必需的。这些方法使用$coProduto来过滤和计算指定产品类型的总价或交货时间。通过使用$coProduto组织产品，您可以轻松管理和检索特定产品类型的详细信息。

获取价格

您可以使用consultarPreco方法获取添加产品的价格。

try {
    $precos = $cliente->consultarPreco();
    print_r($precos);
} catch (ClienteException $e) {
    echo 'Erro: ' . $e->getMessage();
}

获取交货时间

consultarPrazo方法允许您计算产品的交货时间。它需要四个参数

$dataPostagem：以YYYY-MM-DD格式的邮寄日期。
$cepOrigem：邮寄的邮政编码。
$cepDestino：交付的邮政编码。
$dtEvento：（可选）以DD-MM-YYYY格式的日期。如果未提供，则默认为转换为所需格式的邮寄日期。

示例

try {
    $prazo = $cliente->consultarPrazo("2024-07-25", "70002900", "05311900");
    print_r($prazo);
} catch (ClienteException $e) {
    echo 'Erro: ' . $e->getMessage();
}

参数说明

$dataPostagem：包裹发送的日期。这对于计算估计交货时间至关重要。
$cepOrigem：包裹发送的邮政编码。
$cepDestino：包裹交付的邮政编码。
$dtEvento：此参数是可选的。如果未提供，则方法将自动将其设置为$dataPostagem的值，格式为DD-MM-YYYY。它代表与交付相关的事件日期。

通过调用 consultarPrazo，您可以获取您已添加的每个产品的估计配送时间和其他相关信息。该方法返回详细的配送时间信息，可用于告知客户他们的预期配送日期。

获取总价

您可以使用 consultarPrecoTotal 方法获取特定产品代码的总价。

try {
    $precoTotal03220 = $cliente->consultarPrecoTotal('03220');
    echo 'Preço total para o produto 03220: ' . $precoTotal03220 . PHP_EOL;

    $precoTotal03298 = $cliente->consultarPrecoTotal('03298');
    echo 'Preço total para o produto 03298: ' . $precoTotal03298 . PHP_EOL;
} catch (ClienteException $e) {
    echo 'Erro: ' . $e->getMessage();
}

获取总配送时间

您可以使用 consultarPrazoTotal 方法获取特定产品代码的总配送时间。

try {
    $prazoTotal03220 = $cliente->consultarPrazoTotal('03220');
    echo 'Prazo total para o produto 03220: ' . $prazoTotal03220['prazoEntrega'] . PHP_EOL;

    $prazoTotal03298 = $cliente->consultarPrazoTotal('03298');
    echo 'Prazo total para o produto 03298: ' . $prazoTotal03298['prazoEntrega'] . PHP_EOL;
} catch (ClienteException $e) {
    echo 'Erro: ' . $e->getMessage();
}

异常处理

所有异常都使用 ClienteException 类进行处理。此类提供附加信息，如HTTP代码和API的响应。

try {
    $precos = $cliente->consultarPreco();
    print_r($precos);

    $prazo = $cliente->consultarPrazo("2024-07-25", "70002900", "05311900");
    print_r($prazo);

    $precoTotal03220 = $cliente->consultarPrecoTotal('03220');
    echo 'Preço total para o produto 03220: ' . $precoTotal03220 . PHP_EOL;

    $precoTotal03298 = $cliente->consultarPrecoTotal('03298');
    echo 'Preço total para o produto 03298: ' . $precoTotal03298 . PHP_EOL;

    $prazoTotal03220 = $cliente->consultarPrazoTotal('03220');
    echo 'Prazo total para o produto 03220: ' . $prazoTotal03220['prazoEntrega'] . PHP_EOL;

    $prazoTotal03298 = $cliente->consultarPrazoTotal('03298');
    echo 'Prazo total para o produto 03298: ' . $prazoTotal03298['prazoEntrega'] . PHP_EOL;
} catch (ClienteException $e) {
    echo 'Erro: ' . $e->getMessage();
    echo 'HTTP Code: ' . $e->getHttpCode();
    echo 'Response: ' . $e->getResponse();
}

文档

有关更详细的信息，请参阅官方Correios API文档。

Correios API文档（需要登录）
Correios API集成手册（PDF）

结论

此包通过提供结构化和易于使用的客户端简化了与Correios API交互的过程。它支持获取各种产品的价格和配送时间，处理身份验证，并提供详细的错误处理。

pedroquezado / correios

维护者

详细信息