Download the PHP package serjazz/diadoc-php-openapi without Composer

Клиент API Диадок для PHP

PHP-библиотека для работы с API Диадок (protobuf + HTTP), совместимая с PHP 7.1.

Происхождение и доработки

За основу взят модуль magdv/diadoc-php.
В рамках этого репозитория выполнены ключевые доработки:

• перевод авторизации на OpenID Connect (Authorization Code Flow) как основной путь;
• опциональный legacy-режим authenticate_v3 (POST /V3/Authenticate, DiadocAuth) для сред без OIDC;
• добавлен Bearer-заголовок и обработка жизненного цикла access_token/refresh_token;
• добавлено проактивное и реактивное обновление токена (refresh);
• обновлены примеры, тестовая обвязка и конфигурация окружения;
• добавлен локальный тестовый OAuth-сервер для сценария CLI + браузер.

Механизм авторизации актуальный на 14.04.2026

Документация API Диадок:

• Интеграция с API
• Авторизация (OIDC)

Требования

• PHP >=7.1.3 (проект тестируется на 7.1.33);
• расширения ext-curl, ext-json;
• composer;
• для генерации классов из proto: установленный protoc.

Установка

Быстрый пример использования

Выбор способа авторизации

Переключение через .env, без правок кода потребителя:

Пример legacy (устаревший API, только fallback):

В коде для legacy:

Конфигурация окружения

Пример в .env.example.

Основные переменные:

• DIADOC_AUTH_MODE — oidc или authenticate_v3;
• OAUTH_CLIENT_ID — client_id приложения из кабинета интегратора;
• OAUTH_CLIENT_SECRET — client_secret приложения;
• OAUTH_IDENTITY_URL — URL identity-провайдера (обычно https://identity.kontur.ru);
• DIADOC_URL — базовый URL API Диадок (prod / staging / test);
• OAUTH_REDIRECT_URI — redirect для OAuth callback (для локального теста по умолчанию http://127.0.0.1:8765/oauth/callback);
• ORG_ID, FROM_BOX_ID, TO_BOX_ID — данные для интеграционных тестов.

Опционально (ручная подстановка токенов):

• DIADOC_ACCESS_TOKEN
• DIADOC_REFRESH_TOKEN
• DIADOC_ACCESS_EXPIRES_AT (unix timestamp)

Для authenticate_v3:

• DD_AUTH — API-ключ (ddauth_api_client_id);
• AUTH_LOGIN, AUTH_PASSWORD — для /V3/Authenticate;
• DIADOC_LEGACY_TOKEN — готовый ddauth_token (опционально).

Развертывание (локально через Docker)

В проекте есть docker-compose.yml с сервисами:

• cli — запуск скриптов, smoke и интеграционных проверок;
• oauth-test (профиль oauth) — встроенный PHP-сервер для получения OAuth-токена через браузер.

Запуск CLI-среды

Запуск тестового OAuth-сервера

После запуска откройте в браузере:

• http://127.0.0.1:8765/

Важно:

• в кабинете интегратора должен быть зарегистрирован ровно тот же redirect_uri, что и OAUTH_REDIRECT_URI;
• для локального сценария по умолчанию: http://127.0.0.1:8765/oauth/callback.

После успешного callback сервер:

• сохраняет OAuth-сессию в var/oauth_last_session.json;
• сохраняет кэш-сессию в var/*.cache (формат совместим с tests/helpers/ApiClient.php).

Тестирование

1) Smoke/compat тест

Проверяет:

• PHP/расширения;
• синтаксис src/ и phpProto/;
• автозагрузку;
• базовый protobuf roundtrip;
• критичные конструкторы/хелперы.

Запуск:

2) Интеграционный тест с реальным API

Пример проверки чтения контрагентов:

Если приходит Organization ... is not found, обновите ORG_ID значением из getMyOrganizations() текущего пользователя в той же среде (DIADOC_URL).

Разработка

Полезные команды:

• composer run generate-proto — генерация PHP-классов из proto/;
• composer run test:compat — smoke-проверка совместимости.

Генерация классов из proto

Поток работы:

1. Обновить/добавить схемы в proto/;
2. Выполнить composer run generate-proto;
3. Проверить сгенерированный код в phpProto/;
4. Обновить использование новых полей/методов в src/.