HTTP Basic для серверных интеграций
HTTP Basic позволяет серверной программе обращаться к API TesLab по логину и паролю сотрудника. Этот способ используется в готовом обмене с 1С. Программа передаёт учётные данные заголовком Authorization в каждом запросе по HTTPS. Отдельно получать token.auth не требуется.
В этой статье
Когда использовать HTTP Basic
Используйте Basic, если его поддерживает подключаемая серверная программа или он предусмотрен готовым протоколом обмена. В отличие от токенового входа, пароль здесь передают с каждым запросом. При токеновом входе пароль нужен для получения сессии, а затем программа повторно использует выданный token.auth.
Обычный клиент TesLab использует токеновый вход. Basic настраивают в программе, которая обращается к API.
Что нужно для подключения
- HTTPS-адрес API вашей инсталляции.
- Логин и пароль действующей учётной записи сотрудника TesLab. Учётная запись контрагента или ОДС из другого портала для этого сценария не подходит.
- Доступ к нужному методу. Для готового обмена с 1С предусмотрено право «Обмен с 1С»; делать сотрудника администратором только ради обмена не требуется. Подготовка учётной записи описана в отдельной статье.
Веб-сервер и прокси должны передавать Basic-данные в PHP как PHP_AUTH_USER и PHP_AUTH_PW. Наличие заголовка в исходящем запросе ещё не означает, что обработчик получил эти значения.
Как передавать учётные данные
| Заголовок | Что передать |
|---|---|
Authorization | Basic, пробел и Base64 от всей строки login:password, без добавленного пробела после двоеточия. |
Lang | ru для русского языка ответа. |
Out | json для обычных JSON-ответов API. У команд обмена с 1С бывает собственный формат ответа. |
Позвольте HTTP-библиотеке сформировать Basic-заголовок. В curl это делает параметр --user 'login:password'. Передавайте исходный пароль: отдельно кодировать его в Base64 и отправлять поле pwd не нужно. Двоеточие в логине недопустимо, в пароле оно может использоваться.
Настройте отправку Basic сразу. Не рассчитывайте, что TesLab обязательно сначала вернёт 401 с WWW-Authenticate: при отсутствии учётных данных обработчик может ответить 403. Не добавляйте одновременно auth или другой способ авторизации.
Base64 не шифрует пароль, поэтому используйте HTTPS. Если учётные данные содержат кириллицу и вход не проходит, проверьте кодировку HTTP-библиотеки: сервер сравнивает полученный пароль без отдельной перекодировки.
Проверка подключения
Для первой проверки вызовите GET /api/auth/check. В примерах адрес и учётные данные условные; замените их своими:
curl 'https://lab.example/api/auth/check' \
--user 'integration-demo:Demo-pass-123!' \
-H 'Lang: ru' \
-H 'Out: json'При успехе сервер возвращает HTTP 200 и сведения о сотруднике прямо в корне JSON. Фрагмент ответа:
{
"id": 900301,
"login": "integration-demo",
"adm": 0,
"department": 900501
}Проверьте id и login. Этот ответ показывает, под каким сотрудником обработан запрос. Он не выдаёт token.auth и не подтверждает право на другие методы. В следующем Basic-запросе снова передайте логин и пароль.
Как создаются сессии
После проверки логина, пароля и статуса сотрудника сервер создаёт новую сессию с начальным сроком пять часов. Затем проверяет её и обрабатывает метод. Поэтому запись сессии может появиться и при последующем отказе из-за недостатка прав или закрытого сервера.
Каждый следующий Basic-запрос создаёт ещё одну сессию. При частом опросе записи сеансов накапливаются. Для собственной интеграции с серией обычных API-запросов можно выбрать токеновый вход и повторно использовать одну сессию. Проверка может менять её срок; подробнее в статье «Срок действия токена, проверка и завершение сессии».
system/logout с Basic не отключает интеграцию: этот запрос создаёт сессию и закрывает именно её. Следующее обращение с верным логином и паролем снова сможет авторизоваться. Отзыв отдельной сессии не отзывает сами учётные данные.
Проверка подключения 1С
Для проверки доступа к транспорту обмена выполните GET-запрос:
curl 'https://lab.example/api/1c/buh?api=version' \
--user 'integration-demo:Demo-pass-123!'При успехе обработчик возвращает HTTP 200 и текст 1. Это версия сервисного протокола, а не версия установленного сервера TesLab и не JSON-объект.
Такой ответ не создаёт связь с 1С, не сопоставляет справочники и не подтверждает импорт XML-документа. Дальнейшие команды описаны в протоколе обмена с 1С:Бухгалтерия.
Ошибки и их причины
| Ситуация | Что проверить |
|---|---|
403 при первой проверке | Отправлен ли Basic сразу, получил ли PHP учётные данные, верны ли логин и пароль, действует ли сотрудник. Такой отказ возможен также из-за ограничения IP или закрытого сервера. |
auth/check успешен, нужный метод возвращает 403 | Право сотрудника на этот метод. Для обмена с 1С нужно право «Обмен с 1С». Учитывайте также ограничения инсталляции. |
429 при обмене с 1С | Частоту запросов. Сделайте паузу перед повтором, не запускайте немедленный цикл повторных обращений. |
| В ответе другой сотрудник | Учётные данные подключения и отсутствие одновременно передаваемого токена. Оставьте один способ авторизации. |
Сохраняйте путь метода, время, HTTP-код и сообщения title/mess. Не записывайте в журналы пароль, Authorization, токены и cookies.
Переход к рабочим запросам
После проверки подключения вызывайте нужный метод с тем же способом авторизации. Запускать auth/check перед каждой операцией не требуется: обычные авторизованные методы сами проверяют сессию.
Оценивайте результат по ответу конкретного метода. Успешная проверка входа сама по себе не означает, что документ создан или данные импортированы. Для готового обмена с 1С соблюдайте последовательность его команд.
Связанные материалы
- API TesLab: адрес сервера и первый запрос.
- Ответы API и обработка ошибок.