Download the PHP package alex-nzr/bit-umc-sdk without Composer

SDK для 1С-БИТ.УМЦ

Требования

• PHP >= 8.1
• ext-soap
• ext-json
• ext-xml
• ext-libxml
• ext-xmlreader

API версии 2

SDK построен вокруг единой публичной точки входа: ANZ\\BitUmc\\SDK\\BitUmcClient.

Принципы

• Учётные данные передаются во время выполнения.
• SDK не читает .env, ini-файлы и базы данных.
• Тип транспорта явно выбирается через TransportType.
• Сейчас реализован SOAP; HTTP-транспорт зарезервирован для следующего этапа.
• XML-ответы SOAP разбираются через XMLReader, чтобы уменьшить пиковое потребление памяти.
• Успешные вызовы возвращают нормализованные массивы.
• Ошибки выбрасывают типизированные исключения из ANZ\\BitUmc\\SDK\\Domain\\Exception.

Использование

Доступные операции

Большие коллекции

Методы getClinics(), getEmployees(), getNomenclature() и getSchedule() для обратной совместимости продолжают возвращать полные массивы. Приложения, которым не нужно хранить всю большую коллекцию, могут использовать соответствующий итератор:

Доступны iterateClinics(), iterateEmployees(), iterateNomenclature(string $clinicUid) и iterateSchedule(?ScheduleQuery $query = null).

iterateClinics(), iterateEmployees() и iterateNomenclature() возвращают те же нормализованные элементы и ключи UID, что и соответствующие get*() методы, но не накапливают результирующий массив внутри SDK.

iterateSchedule() возвращает записи расписания последовательно. Первая запись по сотруднику имеет kind = employee и содержит нормализованные данные сотрудника без периодов. Следующие записи имеют kind = period, timeType = free|busy, исходный интервал в period и разбитые свободные слоты в formattedSlots.

Форма записи iterateSchedule():

Крупные чтения getClinics(), getEmployees(), getNomenclature() и getSchedule() используют файловый streaming transport: SDK получает SOAP response через потоковый HTTP POST, извлекает <return> в временный payload-файл и разбирает его через XMLReader. get*() методы всё равно накапливают итоговый массив ради совместимости, а iterate*() методы позволяют обрабатывать элементы без накопления результата в SDK. Исключения итераторов возникают при начале обхода.

DTO запросов

• ANZ\\BitUmc\\SDK\\Domain\\Request\\ScheduleQuery
• ANZ\\BitUmc\\SDK\\Domain\\Request\\ReserveRequest
• ANZ\\BitUmc\\SDK\\Domain\\Request\\WaitListRequest
• ANZ\\BitUmc\\SDK\\Domain\\Request\\BookAppointmentRequest

Полный пример приведён в examples/index.php.

Возвращаемые данные

getClinics(): array

getEmployees(): array

getNomenclature(string $clinicUid): array

getSchedule(?ScheduleQuery $query = null): array

Метод сохраняет прежний формат ответа и собирает итоговую карту поверх iterateSchedule(). Для больших расписаний это означает накопление итогового массива в памяти приложения.

getAppointmentStatus(string $appointmentUid): array

sendReserve(ReserveRequest $request): array

sendWaitList(WaitListRequest $request): array

sendAppointment(BookAppointmentRequest $request): array

deleteAppointment(string $appointmentUid): array

Обработка ошибок

Тесты

Что покрыто

Текущий набор тестов покрывает следующие случаи.

Unit-тесты с fixtures:

• разрешение endpoint;
• маппинг запросов расписания, статуса и создания записи;
• разбор клиник, сотрудников, услуг, расписания и статусов;
• обработка SOAP-ответов:
  • Ok
  • Error
  • plain text error responses
  • XML responses with ОписаниеОшибки

Интеграционные тесты с реальной 1С:

• getClinics()
• getEmployees()
• поиск Центральная клиника;
• поиск врача Барбышева;
• getNomenclature() для центральной клиники с поиском Первичная консультация офтальмолога;
• sendReserve() -> getAppointmentStatus() -> deleteAppointment()
• sendWaitList()
• sendAppointment()
• негативные сценарии транспорта: неверное имя базы и web-сервиса.

Как работают unit-тесты

Unit-тесты не подключаются к 1С. Они используют локальные fixtures из tests/Fixtures/soap: необработанные XML и текстовые ответы, полученные из тестового экземпляра 1С.

Это означает, что тесты детерминированы и быстры, поведение парсера проверяется на реальных ответах, а учётные данные не требуются.

Запуск unit-тестов:

Как обновить fixtures из реальной 1С

Скрипт получения fixtures:

• CaptureSoapFixtures.php

Перед запуском задайте переменные окружения:

• BIT_UMC_TEST_PROTOCOL = HTTP or HTTPS
• BIT_UMC_TEST_HOST
• BIT_UMC_TEST_BASE_NAME
• BIT_UMC_TEST_LOGIN
• BIT_UMC_TEST_PASSWORD

Пример для PowerShell:

Как запустить интеграционные тесты против реальной 1С

Интеграционные тесты выполняют сетевые вызовы и требуют переменных окружения.

Поддерживаемые переменные:

• BIT_UMC_RUN_INTEGRATION_TESTS=1
• BIT_UMC_TEST_PROTOCOL=HTTP or HTTPS
• BIT_UMC_TEST_HOST
• BIT_UMC_TEST_BASE_NAME
• BIT_UMC_TEST_LOGIN
• BIT_UMC_TEST_PASSWORD

Example PowerShell:

Важно:

• интеграционные тесты предполагают, что в целевой базе есть данные, похожие на использованные fixtures;
• сейчас они ориентированы на клинику Центральная клиника, врача Барбышева и услугу Первичная консультация офтальмолога;
• в другой базе эти сущности могут отсутствовать, поэтому отдельные проверки могут завершиться ошибкой при исправных транспорте и парсинге;
• общие негативные проверки транспорта применимы к любой базе.

Примечание о транспорте

В ConnectionOptions поле apiKey уже зарезервировано для будущего HTTP-транспорта. SOAP его игнорирует.

Параметр responseMaxBytes ограничивает размер полезной части SOAP-ответа для streaming transport. Значение по умолчанию: 536870912 байт.