API Corteos представляет собой набор SOAP-сервисов, с которыми необходимо работать при помощи SOAP-клиента на используемой вами платформе. За счет этого обеспечивается целостность структур данных и безопасность XML-взаимодействия.
API позволяет работать со статикой (справочники персон, кодов и так далее), а также работать с заказами для клиента и агента:
API доступен пользователям клиентов и агентов с административными системными ролями: для клиента это Тревел-менеджер, для агента - Администратор.
Для работы с API необходимо получить токен, кроме того, на стороне разработчика следует определить политику работы с токеном:
можно создать токен, который годен условно бесконечное время, и генерить его заново в том случае, если безопасность токена скомпрометирована;
можно создать токен, который годен в течение короткого времени (например, в течение одного дня) и автоматически генерить токен по завершению периода его годности.
В общем случае, второй механизм является чуть более безопасным, но менее удобным в поддержке, так как в этом случае на стороне пользователя API необходимо хранить также дату и время годности токена в формате DateTime.
Для принудительной деактивации токена следует использовать метод уничтожения токена.
Разбор ответа
Ответ метода API содержит в себе следующие элементы:
Trace - информация, которую необходимо предоставить в службу поддержки для анализа инцидента:
ResponseDate - дата и время формирования ответа;
SessionID - идентификатор сеанса. По нему сотрудник поддержки сможет найти лог взаимодействия;
IP - адрес, с которого было отправлено обращение;
WebSite - название сайта, на котором был выполнен данный запрос.
Errors - коллекция ошибок. Каждая ошибка содержит в себе тип ошибки и описание.
Type - тип ошибки. Классические типы ошибок следующие:
ValidationException - ошибка целостности данных (например, обращение к недоступному объекту);
InvalidDataException - ошибка валидации данных (например, передан пустой email или номер телефона);
AccessRightsException - ошибка, связанная с валидацией прав (например, если из-под агента обращаться к данным клиента, не выполнив предварительно вход от имени клиента).
Text - текстовое сообщение с деталями ошибки;
ResponseDetails - контейнер, содержащий ответ на запрос.
Пример успешного ответа:
Пример ответа с ошибкой:
Соответственно, по SessionID сотрудник службы поддержки может найти событие в журнале запросов:
И далее в списке событий находим интересующее нас по времени из ResponseDate:
Успешный запрос или ответ с ошибками уровня бизнес-логики возвращает HTTP Status Code 200.
В том случае, если мы передали некорректные данные для авторизации или обращаемся к удаленному токену, то возвращается код 500 и стандартная обертка SOAP Exception:
Про два вида API для работы со статикой можно прочитать здесь.
Примеры:
____