README

请参阅 CycleSoftware 文档。

CycleSoftware Twsc 提供商和客户端，用于访问 TWSC Api 资源

本包提供 CycleSoftware TWSC Api 支持，使用 PHP League 的 OAuth 2.0 客户端。

安装

通过 Composer

$ composer require cyclesoftware/oauth2-twsc

使用授权授予使用

使用场景与 The League OAuth 客户端类似，使用 \League\OAuth2\Client\Provider\Twsc 作为提供商。

$provider = new League\OAuth2\Client\Provider\Twsc([
    'clientId'     => '{cs-client-id}',
    'clientSecret' => '{cs-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
]);

if (!isset($_GET['code'])) {

    // If we don't have an authorization code then get one
    $authUrl = $provider->getAuthorizationUrl();
    $_SESSION['oauth2state'] = $provider->getState();
    header('Location: '.$authUrl);
    exit;

// Check given state against previously stored one to mitigate CSRF attack
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

    unset($_SESSION['oauth2state']);
    exit('Invalid state');

} else {

    // Try to get an access token (using the authorization code grant)
    $token = $provider->getAccessToken('authorization_code', [
        'code' => $_GET['code']
    ]);

    // Optional: Now you have a token you can look up a users profile data
    try {

        // We got an access token, now we can access resources on TWSC Api 
        // First create client
        $client = new League\OAuth2\Client\Provider\Client($provider);
        // now we can get list of available repair codes
        $result = $client->getRepairCodes($token);
        // We have list of repair codes 
        print_r($result);

    } catch (Exception $e) {
        // Failed to get resources
        exit('Oh dear...');
    }

    // Use this to interact with an API on the users behalf
    echo $token->getToken();
}

Client 类实现了许多从服务器获取资源的方法。

有两个创建和更新方法用于创建新对象和更新现有对象。我们使用 Client 创建 RepairObject。场景与之前类似，并假设我们已经有了访问令牌。

    try {

        // We got an access token, now we can access resources on TWSC Api 
        // First create client
        $client = new League\OAuth2\Client\Provider\Client($provider);
        // Create RepairObject instance
        $repairObject = new League\OAuth2\Client\Provider\ValueObjects\RepairObject();
        // Fill repairObject fields
        $repairObject->is_active = 1;
        $repairObject->object_barcode = '3600 2600';
        $repairObject->customer_id = 2002;
        $repairObject->object_type_name = 'bicycle';
        $repairObject->brand = 'A-bike';
        $repairObject->model = 'mountain bike';
        $repairObject->color = 'red';
        $repairObject->phone_number_id = '12345';
        $repairObject->license_plate = 'nl 1234';
        $repairObject->km_mileage = '200';
        $repairObject->frame_id = 'HK6429';
        $repairObject->chip_id = '4321';
        $repairObject->key_id = '1234';
        $repairObject->engine_id = '4321';
        $repairObject->model_year = '2017';
        $repairObject->battery_id = '1234';
        $repairObject->lock_id = '4321';
        // Now we can create repair object on the server
        $repairObjectId = $client->createRepairObject($token, $repairObject);
        // We got repair object identifier 
        print_r($repairObjectId);
    } catch (Exception $e) {
        // Failed to create repair object
        exit('Oh dear...');
    }

使用客户端凭证授予使用

当使用凭证授予时，第一步是获取 AccessToken。

try {
    $provider = new League\OAuth2\Client\Provider\Twsc([
        'clientId'     => '{cs-client-id}',
        'clientSecret' => '{cs-client-secret}',
    ]);  
    $access_token = $provider->getAccessToken('client_credentials');
    $customer = new Customer();
    $customer->customer_reference = ''; // e.g. your customer number
    $customer->postcode = '100AM';
    $customer->house_number = '1';
    $customer->house_number_postfix = '2';
    $customer->title = 'Dhr.';
    $customer->initials = 'A';
    $customer->insertion = 'van';
    $customer->name = 'Laak';
    $customer->street = 'Hoofdweg';
    $customer->city = 'Amsterdam';
    $customer->country_code_iso_3166 = 'NL';
    $customer->email = 'email@mail.com';
    $customer->discount_percentage = 10;
    $customer_phones = [];
    $customer_phone = new CustomerPhone();
    $customer_phone->phone_number = '+31612345678';
    $customer_phones[] = $customer_phone;
    $customer_phone = new CustomerPhone();
    $customer_phone->phone_number = '+3173030050';
    $customer_phones[] = $customer_phone;
    $customer->phone_numbers = $customer_phones;
    $client = new Client($provider);
    $result = $client->createCustomer($access_token, $customer);
} catch(League\OAuth2\Client\Provider\ClientErrorException $e){
    // ClientErrorException gives you information about what went wrong
    // echo $e->getMessage();
    // echo $e->getReason();
    // echo $e->getMessageNL();
}

创建维修订单

try {
    $provider = new League\OAuth2\Client\Provider\Twsc([
        'clientId' => '{cs-client-id}',
        'clientSecret' => '{cs-client-secret}',
    ]);
    $access_token = $provider->getAccessToken('client_credentials');
    $repair = new Repair();
    $repair->customer_id = 24;
    $repair->repair_object_id = 1105;
    $repair->reference_text = 'some-reference'; // your reference
    $repair->datetime_scheduled_start = '2019-03-11T15:41:46+01:00';
    $repair->mechanic_employee_id = 1; // default for TWSC 1
    $repair->repair_description = 'Some description of the repair order';
    /**
     * Status:
     * STATUS_WAIT_FOR_OBJECT = 1;
     * STATUS_WAIT_FOR_REPAIR = 2;
     * STATUS_WAIT_FOR_ARTICLES = 3;
     * STATUS_IN_REPAIR = 4;
     * STATUS_WAIT_FOR_CUSTOMER = 5;
     * STATUS_WAIT_FOR_INVOICE = 6;
     * STATUS_COMPLETED = 7;
     * STATUS_DONE = 8;
     * STATUS_WAIT_FOR_SUPPLIER = 9;
     * STATUS_WAIT_FOR_OBJECT_ONLINE = 10;
     * STATUS_WAIT_FOR_INSURANCE = 11;
     * STATUS_WAIT_FOR_INSURANCE_EXPERT = 12;
     * STATUS_PICKUP_AT_CUSTOMER = 13;
     * STATUS_WAIT_FOR_OBJECT_SUPPLIER = 14;
     * STATUS_CANCELLED = 15;
     * STATUS_DECLINED = 16;
     */
    $repair->status_id = 10; // default: 10  
    $repair->custom_repair_time_minutes = 0; // time not related to order_items

    // add a normal article
    $item = new RepairOrderItem();
    $item->item_type_id = 1; // 1: Article, 4: RepairCode
    $item->special_type_id = 1;
    $item->quantity = 1;
    $item->barcode = '8712812812';
    $item->pos_group_id = 2; // 2: Repair, 21: Parts
    $item->description = 'In- en uitbouwen electromotor in- en uitbouwen accu';
    $item->unit_price_in_vat_cents = 12100;
    $item->unit_discount_amount_in_vat_cents = 0;
    $item->price_in_vat_cents = 12100;
    $item->discount_percentage = 0;
    $item->vat_code = 2; // 1: LOW VAT; 2: HIGH VAT, 0: NO VAT
    $item->vat_percentage = 21.0;
    $item->vat_amount_cents = 2100;
    $item->item_status_id = 0; // 0: No status, 1: Ordered at supplier 2: Ready for pickup 3: Delivered 4: Picked up 5: Cancelled
    $item->unit_work_time_minutes = 15;
    $repair->order_items[] = $item;

    $client = new Client($provider);
    $result = $client->createRepair($access_token, $repair);
}
catch (League\OAuth2\Client\Provider\ClientErrorException $e) {
    // ClientErrorException gives you information about what went wrong
    // echo $e->getMessage();
    // echo $e->getReason();
    // echo $e->getMessageNL();
}

更新带订单项的维修订单

确保 service_items 和 repair_codes 的值为 null。只有数组 order_items 中提供的 order_item 被更新。当添加新订单项时，留 item_id=null。当在 PUT 中省略现有的 order_item 时，它不会被删除或更新。要取消项目，请使用 item_status_id=5

查找客户以防止重复

当创建客户时，尽量通过保留已创建客户的索引并重复使用客户 ID 或基于唯一的标识符（如电话号码或电子邮件）查找客户来避免创建新客户。

try {
    $provider = new League\OAuth2\Client\Provider\Twsc([
        'clientId' => '{cs-client-id}',
        'clientSecret' => '{cs-client-secret}',
    ]);
    $access_token = $provider->getAccessToken('client_credentials');

    $client = new Client($provider);
    $result = $client->findCustomers($token, ['phone_number' => '0733030050']);
    var_dump($result);
    if(empty($result)){
        $result = $client->findCustomers($token, ['email' => 'example@domain.nl']);
    }
    var_dump($result);
}
catch (League\OAuth2\Client\Provider\ClientErrorException $e) {
    // ClientErrorException gives you information about what went wrong
    // echo $e->getMessage();
    // echo $e->getReason();
    // echo $e->getMessageNL();
}

测试

$ ./vendor/bin/phpunit

安全

如果您发现任何安全相关的问题，请通过 :author_email 发送电子邮件，而不是使用问题跟踪器。

许可证

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