README

此 Laravel 扩展包允许您轻松与 ArmSoft API 交互，提供认证和操作商品、商品退货、价格列表、文档日记和 MTBill 等端点的方法。

认证和刷新访问令牌
从 ArmSoft API 获取商品、商品退货、价格列表、文档日记和 MTBill
发送数据以创建发票

备注

该软件包目前处于测试版本。
ArmSoft API 正在开发中，可能未经通知进行更改。
一旦他们给我更多信息，我将更新软件包。

🚀 安装

您可以使用 Composer 安装此软件包

composer require ayvazyan10/armsoft

释放配置文件和数据库迁移。

首先，您需要使用您的 ArmSoft API 凭据配置软件包。您可以通过发布配置文件来完成此操作

php artisan vendor:publish --provider="Ayvazyan10\ArmSoft\ArmSoftServiceProvider"

然后，在 config/armsoft.php 文件中填写您的 ArmSoft API 凭据和设置。

⚙️ 配置

发布配置文件后，您应该在 config/armsoft.php 文件或 .env 文件中设置您的 ArmSoft 凭据/选项

ARM_SOFT_CLIENT_ID - 您的 ArmSoft API 客户端 ID。
ARM_SOFT_SECRET - 您的 ArmSoft API 密钥。
ARM_SOFT_DB_ID - 您的 ArmSoft 数据库 ID。

ARM_SOFT_CLIENT_ID=your_client_id
ARM_SOFT_SECRET=your_secret
ARM_SOFT_DB_ID=your_db_id

或者在 config/armsoft.php 中提供它

/**
 * Configuration for the ArmSoft API package.
 *
 * Note: This package is currently in beta version and the ArmSoft API is not yet finished.
 */

return [
    // Required: Your ArmSoft client ID
    'ClientId' => env('ARM_SOFT_CLIENT_ID', '00000000-0000-0000-0000-000000000000'),

    // Required: Your ArmSoft client secret
    'Secret' => env('ARM_SOFT_SECRET', '000000000000'),

    // Required: The ID of your ArmSoft database
    'DBId' => env('ARM_SOFT_DB_ID', '00000'),

    // Optional: The price type to use for price-related API calls (01 - wholesale, 02 - retail, 03 - purchase price)
    'priceType' => '02',

    // Optional: The language to use in API responses
    'language' => 'en-US,en;q=0.5',

    // Optional: Additional settings to pass to the ArmSoft API
    'settings' => [
        'ShowProgress' => false,
        'ShowColumns' => false,
    ],
];

⚡ 所有方法

请注意，此列表仅包含方法签名，不包含实现细节。

// getGoods
final public function getGoods(string $date = null): ?array { /*...*/ }

// getGoodsRem
final public function getGoodsRem(string $date = null, string $mtcode = null): ?array { /*...*/ }

// getPrices
final public function getPrices(string $date = null, string $mtcode = null, string $pricetypes = null): ?array { /*...*/ }

// getDocumentsJournal
final public function getDocumentsJournal(string $dateBegin = null, string $dateEnd = null): ?array { /*...*/ }

// getMTbill
final public function getMTbill(mixed $guid): mixed { /*...*/ }

// setMTbill
final public function setMTbill(array $data): mixed { /*...*/ }

📚 使用

以下是如何在 Laravel 应用程序中使用 ArmSoft Facade 或辅助函数的示例

use ayvazyan10\ArmSoft\Facades\ArmSoft;

// with facade
$goods = ArmSoft::getGoods('2023-04-24');

// or use the helper function
$goods = armsoft()->getGoods('2023-04-24');

// or ArmSoft class directly 
use ayvazyan10\ArmSoft\ArmSoft;

$armSoft = new ArmSoft();
$goods = $armSoft->getGoods('2023-04-24');

📖 示例与说明

以下是一些如何使用 Facade 使用这些方法的示例

在此示例中，Armsoft 是一个 Facade，允许您使用 Armsoft 类提供的方法访问 ArmSoft API。该 Facade 在 app.php 配置文件中注册，并使用 Laravel 服务容器绑定到 Armsoft 类。

// In your controller or anywhere else
use ayvazyan10\ArmSoft\Facades\ArmSoft;

public function myMethod()
{
    // Get the goods for today
    $goods = Armsoft::getGoods();

    // Get the goods rem for a specific MTCode
    $goodsRem = Armsoft::getGoodsRem(null, 'MTCode123');

    // Get the prices for a specific date and MTCode
    $prices = Armsoft::getPrices('2023-04-24', 'MTCode123');

    // Get the documents journal for a date range
    $documentsJournal = Armsoft::getDocumentsJournal('2023-04-01', '2023-04-30');

    // Get an MTBill by its GUID
    $mtBill = Armsoft::getMTbill('MTBill123');

    // Create an MTBill with some data
    $newMTBill = Armsoft::setMTbill([
        'MTCode' => 'MTCode123',
        'Description' => 'Some description',
        // ...
    ]);
}

您可以使用 Facade 来调用 Armsoft 类提供的 getGoods()、getGoodsRem()、getPrices()、getDocumentsJournal()、getMTbill() 和 setMTbill() 方法。您可以传递任何必要的参数给这些方法，如上面的示例所示。如果调用 API 时发生错误，这些方法将抛出一个包含描述性错误消息的异常。

产品导入示例

    // in your controller or anywhere else
    // in this example we using helper
    /**
     * Products Import from ArmSoft API.
     *
     * @throws Exception
     */
    public function importGoods()
    {
        $items = armsoft()->getGoods(now()->format('Y-m-d'));

        if (count($items["rows"]) === 0) {
            throw new Exception('ArmSoft API error: no products');
        }

        foreach ($items["rows"] as $key => $item) {
            if (((int)$key + 1) % 2 === 0) {
                continue;
            }

            $priceRequest = armsoft()->getPrices(null, $item["MTCode"], config('armsoft.PriceType', '02'));
            $price = !empty(current($priceRequest["rows"])["Price"]) ? current($priceRequest["rows"])["Price"] : 0;

            $stockRequest = armsoft()->getGoodsRem(null, $item["MTCode"]);
            $stock = !empty(current($stockRequest["rows"])["Qty"]) ? current($stockRequest["rows"])["Qty"] : 0;

            $productData = [
                'armsoft_title' => $item["FullCaption"]    
                'category_id' => $item["Group"],
                'MTCode' => $item["MTCode"],
                'discount' => $item["Discount"],
                'stock' => intval($stock),
                'price' => $price
                // ... fields
            ];

            try {
                YourModel::where('MTCode', $item["MTCode"])->updateOrCreate([
                    'MTCode' => $item["MTCode"]
                ], $productData);
            } catch (Exception $e) {
                return $e->getMessage();
            }
        }

        return redirect()->back();
    }

每个方法的详细说明

getGoods(string $date = null): ?array: 此方法返回具有给定 RemDate 的商品。您可以传递 yyyy-mm-dd 格式的日期字符串来检索特定日期的商品。如果没有提供日期，则方法将检索当前日期的商品。该方法返回商品数组，如果没有找到商品则返回 null。getGoodsRem(string $date = null, string $mtcode = null): ?array: 此方法返回具有给定 RemDate 和（如果提供 MTCode）单个商品的 GoodsRem。您可以传递 yyyy-mm-dd 格式的日期字符串来检索特定日期的商品退货。如果没有提供日期，则方法将检索当前日期的商品退货。您还可以传递一个唯一的 MTCode 来检索特定的 GoodsRem。该方法返回 GoodsRem 数组，如果没有找到 GoodsRem 则返回 null。

getPrices(string $date = null, string $mtcode = null, string $pricetypes = null): ?array: 此方法返回包含给定RemDate和单个MTCode|PriceType的PriceList。您可以使用yyyy-mm-dd格式的日期字符串来检索特定日期的价格。如果没有提供日期，该方法将检索当前日期的价格。您还可以传入唯一的MTCode和/或价格类型来检索特定价格。该方法返回价格数组，如果未找到价格则返回null。

getDocumentsJournal(string $dateBegin = null, string $dateEnd = null): ?array: 此方法返回包含给定RemDate和单个MTCode|PriceType的DocumentsJournal。您可以通过传入日期范围来检索特定范围内的文档。如果没有提供日期范围，该方法将检索所有文档。该方法返回文档数组，如果未找到文档则返回null。

getMTbill(mixed $guid): mixed: 此方法返回包含给定GUID的MTBill。您可以通过传入GUID字符串来检索特定的MTBill。该方法返回MTBill对象，如果未找到MTBill则返回null。

setMTbill(array $data): mixed: 此方法发送MTBill数据以创建发票。您可以通过传入MTBill数据数组来创建新发票。该方法返回创建的MTBill对象，如果MTBill无法创建则返回null。

所有这些方法在调用ArmSoft API时如果发生错误可能会抛出异常。

您可以通过以下方式捕获它：

// in your controller method or anywhere else
try {
    $mtbill = ArmSoft::getMTbill('your_guid_here');
} catch (Exception $e) {
    return $e->getMessage();
}
// Perform actions with $mtbill or $response data

贡献

有关详细信息和工作列表，请参阅contributing.md。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件ayvazyan403@gmail.com联系，而不是使用问题跟踪器。

作者

Razmik Ayvazyan

许可证

MIT。有关更多信息，请参阅许可证文件。

ayvazyan10 / armsoft

维护者

详细信息