WT CDEK для Joomla: документация PHP-библиотеки

WT CDEK library - Документация

Категория: Библиотеки

WT CDEK в библиотеке WT CDEK для Joomla: подключение библиотеки и работа с API. На странице — назначение, параметры и примеры PHP для расширений Joomla.

WT CDEK Joomla PHP library — это нативная библиотека для Joomla 4.2.7+, Joomla 5 и Joomla 6, которая закрывает типовой сценарий интеграции со СДЭК через REST API без необходимости писать свой транспортный слой, отдельно заниматься OAuth 2.0 и вручную собирать URL для каждого метода API.

Начиная с версии 1.3.0, библиотека построена по entity-based подходу. Это значит, что вы работаете не с одним «толстым» классом, а с фасадом Webtolk\Cdekapi\Cdek, который отдает специализированные Entity:

calculator() — расчёт тарифов;
check() — чеки;
delivery() — договорённости о доставке;
deliverypoints() — ПВЗ и постаматы;
intakes() — вызов курьера;
international() — ограничения по международным отправлениям;
location() — регионы, города, индексы, подсказки;
oauth() — ручное получение токена;
orders() — заказы;
passport() — паспортные данные для международных отправлений;
payment() — наложенные платежи;
photoDocument() — фотоуслуги;
prealert() — преалерты;
print() — печатные формы и штрихкоды;
reverse() — проверка реверса;
webhooks() — подписки на вебхуки.

С чего начать

Если плагин System - WT Cdek уже включен и в нем заполнены client_id и client_secret, достаточно создать объект Cdek без аргументов.

<?php

declare(strict_types=1);

use Webtolk\Cdekapi\Cdek;

defined('_JEXEC') or die;

$cdek = new Cdek();

Если credentials нужно передать явно, это можно сделать в конструкторе:

<?php

declare(strict_types=1);

use Webtolk\Cdekapi\Cdek;

defined('_JEXEC') or die;

$cdek = new Cdek(
    true,
    'your_client_id',
    'your_client_secret'
);

Как читать эту документацию

В каждой Entity-странице есть:

объяснение, зачем сущность нужна в реальной интеграции;
список всех публичных методов;
сигнатура метода в том виде, в котором он есть в библиотеке;
REST endpoint и HTTP-метод;
описание параметров, которые реально проверяет библиотека;
описание результата;
минимальный пример PHP-кода с нужными namespace и use.

Важно понимать разницу между двумя уровнями валидации:

библиотека проверяет только часть обязательных полей;
полную бизнес-валидацию выполняет уже API СДЭК.

Поэтому ситуация, когда библиотека вернула успешный HTTP-запрос, а API СДЭК ответило ошибкой в массиве error_code и error_message, является нормальной и ожидаемой.

Общий формат ответа

Почти все методы библиотеки возвращают array.

Успешный ответ:

это обычный массив данных API СДЭК;
структура зависит от конкретного endpoint.

Ответ с ошибкой:

[
    'error_code'    => 400,
    'error_message' => 'Текст ошибки',
]

Что библиотека делает сама

Библиотека автоматически:

определяет боевую или тестовую среду;
получает OAuth-токен;
кэширует токен средствами Joomla;
нормализует часть ошибок API;
кэширует некоторые справочные запросы, например тарифы и ПВЗ.

Поля Joomla Form

Общее поведение полей подключается через Watchfield WebAsset: источники и события. Отдельный тип поля Watchfield не требуется.

Entity

Исходный код WT CDEK 1.4.0 на GitHub