Онлайн-оплата (xml)
Содержание
Описание сервиса
Сервис для работы с online-заявками является стандартным веб-сервисом, который предоставляет WSDL документ с описанием всех методов и типов данных. Текущая версия сервиса работает только по протоколу HTTP. Для большей совместимости с различными клиентами сервис основан на SOAP версии 1.1. Взаимодействие с сервисом возможно одним из двух способов:
- Как с обычным веб-сервисом посредством SOAP запросов, WSDL доступен.
- Как с сервисом WCF (Windows Communication Foundation) - самый простой способ, если клиент под .NET Framework 3.5 или выше.
Логика обработки запросов не зависит от способа работы с сервисом. При передаче строк и XML пакетов используется кодировка UTF-8. Сервис не требует сессий при работе с ним, и все методы не зависят друг от друга с точки зрения очередности вызова. Таким образом, очередность вызова методов диктуется реализуемым алгоритмом для работы с сервисом. Сервис требует авторизации для работы с ним, используются логин и пароль от личного кабинета SLETAT.RU.
Краткое описание возможностей
С помощью методов данного сервиса вы можете:
- Создать online-заявку на приобретение тура, при этом происходят E-Mail и СМС оповещения как для клиента-покупателя, так и для менеджера агентства;
- Получать информацию о ранее созданной заявке, при этом вы получаете возможность отправить клиента-покупателя на страницу выбранного платежного провайдера для оплаты заказа. Текущий платежный провайдер настраивается в личном кабинете SLETAT.RU.
Подключение к сервису
Для начала работы с сервисом вам нужно зарегистрироваться на сайте http://www.sletat.ru и обратиться в службу поддержки SLETAT.RU (info@sletat.ru) для выдачи тестовой лицензии, при этом сообщив свой логин. После того, как лицензия будет выдана, можно начинать работать с API данного сервиса. Для работы с сервисом вам нужно использовать WSDL документ, который расположен по адресу:
http://claims.sletat.ru/xmlgate.svc?wsdl
Современные среды разработки позволяют автоматически создавать все необходимые классы, используя WSDL документ, избавляя разработчика от необходимости работать вручную с SOAP конвертами.
После того, как WSDL был использован для создания обёртки, можно переходить к описанию логики работы с сервисом. Ниже будут даны более подробные примеры работы с сервисом для клиентов, использующих .NET Framework.
Старый клиент на .NET 1.0 - 2.0
Добавьте в проект ссылку на WSDL документ используя Web Reference. После того, как ссылка была добавлена, ваш проект готов к работе с сервисом. Ниже приведен пример вызова метода для создания online-заявки на приобретение тура по заданным RequestId, OfferId, SourceID:
using System; using System.Collections.Generic; using ClaimsServiceClient.ru.sletat.claims; namespace ClaimsServiceClient { class Program { static void Main(string[] args) { // authentication info AuthData authTicket = new AuthData(); authTicket.Login = "<your login>"; authTicket.Password = "<type password>"; // xml gate client and authentication ticket XMLGate client = new XMLGate(); client.AuthInfo = authTicket; // request definition CreateClaimRequest request = new CreateClaimRequest { OfferIdSpecified = true, RequestIdSpecified = true, SourceIdSpecified = true, OfferId = 1725432283, RequestId = 61455627, SourceId = 5, Comments = "There are some comments", Customer = new Customer { Address = "СПБ", Email = "<........>@gmail.com", FullName = "Смирнов Андрей Валерьевич", Passport = "1122 5500", Phone = "+7(921)<...-..-..>" }, InitialURL = "http://www.google.com", Tourists = new List<Tourist> { new Tourist { BirthDate = DateTime.Now, BirthDateSpecified = true, Citizenship = "Россия", City = "СПБ", Country = "Россия", DateOfIssue = DateTime.Now, DateOfIssueSpecified = true, Email = "<........>@gmail.com", Expires = DateTime.Now, ExpiresSpecified = true, FirstName = "Andrey", Gender = Gender.Male, PassportNumber = "11", PassportSeries = "22", Patronymic = "V", Phone = "+7(921)<...-..-..>", Surname = "Smirnov", Title = Title.MR } }.ToArray() }; // attempt to create online claim var response = client.CreateClaim(request); // futher we can analise the request from xml gate if (response.OperationStatus) { // continue } } } }
Не забудьте указать логин и пароль вашей учетной записи на сайте SLETAT.RU.
Обратите также внимание на то, что требуется указывать поля _Specified для типов данных DateTime и int.
Клиент на .NET 3.5 или выше
Добавьте в проект ссылку на WSDL документ используя Service Reference. После добавления ссылки ваш проект готов к работе с сервисом. Ниже приведен пример вызова метода для создания online-заявки на приобретение тура по заданным RequestId, OfferId, SourceID:
Указан неподдерживаемый язык.
Вы должны указать язык следующим образом: <source lang="html4strict">...</source>
Поддерживаемые языки:
4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, aimms, algol68, apache, applescript, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, caddcl, cadlisp, cfdg, cfm, chaiscript, chapel, cil, clojure, cmake, cobol, coffeescript, cpp, csharp, css, cuesheet, d, dart, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, ezt, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, ispfpanel, j, java, java5, javascript, jcl, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nginx, nimrod, nsis, oberon2, objc, objeck, ocaml, octave, oobas, oorexx, oracle11, oracle8, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, pic16, pike, pixelbender, pli, plsql, postgresql, postscript, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, qml, racket, rails, rbs, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, rust, sas, scala, scheme, scilab, scl, sdlbasic, smalltalk, smarty, spark, sparql, sql, standardml, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vbscript, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xpp, yaml, z80, zxbasic
static void Main(string[] args)
{
// данные для авторизации на сервисе
AuthData authTicket = new AuthData();
authTicket.Login = "<type your login here>";
authTicket.Password = "<and password>";
// экземпляр клиента для обращения к XMLGate сервису для работы с online-заявками
using (XMLClaimsGateClient client = new XMLClaimsGateClient())
{
CreateClaimRequest request = new CreateClaimRequest
{
OfferId = 1,
RequestId = 2,
SourceId = 3,
Comments = "There are some comments",
Customer = new Customer
{
Address = "СПБ",
FullName = "Смирнов Андрей Валерьевич",
Passport = "1122 5500",
Email = "<email заказчика, на который будут приходить оповещения>",
Phone = "+7(921)...-..-.. <телефон заказчика, на который будут приходить
оповещения>"
},
InitialURL = "http://www.google.com",
Tourists = new List<Tourist>
{
new Tourist
{
BirthDate = DateTime.Now,
Citizenship = "Россия",
City = "СПБ",
Country = "Россия",
DateOfIssue = DateTime.Now,
Expires = DateTime.Now,
Title = Title.MR,
FirstName = "Andrey",
Patronymic = "V",
Surname = "Smirnov",
Gender = Gender.Male,
PassportNumber = "11",
PassportSeries = "22",
Email = "<email туриста>",
Phone = "<телефон туриста>"
}
}.ToArray()
};
var response = client.CreateClaim(authTicket, request);
}
}
Не забудьте указать логин и пароль вашей учетной записи на сайте SLETAT.RU. Данные для авторизации передаются первым параметром для всех методов сервиса.
Версионность
Сервис может содержать несколько контрактов, каждое изменение, несовместимое с предыдущей публикацией, будет вести к созданию контракта новой версии. Описание контрактов всех поддерживаемых версий включено в WSDL.
WSDL - автоматически формируемый документ описывающий все контракты веб-сервиса, описывает их методы и используемые типы данных. Каждый контракт веб-сервиса имеет уникальное имя используемое для его идентификации. Эти имена также используются для указания версии, например, в виде даты публикации, или любым иным образом. Текущая версия сервиса состоит из одного контракта, который использует имя:
urn:SletatRu:XMLClaimsGate:v1
Используется URN (Uniform Resource Name) для обозначения имени контракта и его версии. Все разрабатываемые сервисы имеют префикс SletatRu, после которого указывается название контракта, последним указывается его версия.
Следующие версии контракта Soap11Gate будут иметь другое значение версии в последней части URN, например:
urn:SletatRu:XMLClaimsGate:v1
Используется URN (Uniform Resource Name) для обозначения имени контракта и его версии. Все разрабатываемые сервисы имеют префикс SletatRu, после которого указывается название контракта, последним указывается его версия.
Следующие версии контракта Soap11Gate будут иметь другое значение версии в последней части URN, например:
urn:SletatRu:XMLClaimsGate:v2
Чтобы использовать новую версию контракта, клиенту необходимо указать нужную версию в SOAP конверте:
<soap:Envelope> <soap:Body> <CreateClaim xmlns=" urn:SletatRu:XMLClaimsGate:v1"> … </CreateClaim> </soap:Body> </soap:Envelope>
Если же вы используете автоматически создаваемую обёртку для сервиса создания online-заявок, то при изменении текущего контракта, или при создании контракта новой версии, вам нужно заново создать обёртку к сервису.
Новые версии контрактов будут создаваться только при наличии обратно несовместимых изменений. Все обратно совместимые изменения (добавление новых методов, добавление новых параметров в методы, добавление новых полей в структуры данных) будут добавляться в текущую версию контракта.
Версионность также соблюдается для всех типов данных.
Создание новых версий также может быть сопряжено с иными задачами в ходе развития сервиса, например, группированием методов в контракты новых версий таким образом, чтобы в дальнейшем можно было отказаться от устаревших методов.
Логика работы с сервисом
Используя сервис по работе с online-заявками, вам доступны следующие операции:
CreateClaim – используется для создания заявки на приобретение тура. Данная операция полностью аналогична ручному вводу данных о заказчике тура и списке туристов в форме ввода для регистрации заявки в результатах выдачи поискового модуля на сайте клиента; После регистрации заявки она становится доступной для просмотра и редактирования в личном кабинете менеджера агентства по адресу: https://sletat.ru/workspace/agencyorders.aspx
В качестве ответа от данной операции приходит флаг успешности операции, сообщение об ошибке в случае неуспешности попытки, и идентификатор ClaimIdentity, который потом можно использовать для получения данных по данной заявке. В вызове данной операции вы можете указать запрос на проведение актуализации тура (Actualize). В таком случае в дальнейшем вам необходимо учитывать состояние актуализации для выполнения последующих операций. Важно понимать, что сама актуализация может занимать некоторое время и выполняется асинхронно. Текущее состояние актуализации можно увидеть в результатах операций GetClaimInfo или GetActualization. После успешного завершения актуализации стоимость тура будет изменена на новое полученное значение.
UpdateClaimToWasSentState – Переводит заказ в состояние - "Отправлен на оплату". С указанной даты ссылка на оплату будет действительна в течении 48 часов (значение может быть изменено в настройках вашего аккаунта в разделе «Ограничения по платежам» - https://sletat.ru/workspace/billingsettings.aspx?tab=restrictions). Данную операцию необходимо использовать первой, если вы хотите, чтобы ссылка на оплату RedirectToPaymentPageURL из запроса GetClaimInfo была действительной.
ВАЖНО: использование данной операции оправдано, если только вы используете схему с предварительной обработкой тура менеджером. В случае прямой схемы оплаты тура данный шаг в обработке онлайн-заказа необязателен.
UpdateClaimToWasViewedState – Переводит заказ в состояние - "Просмотрен (заказчиком)". Данную операцию необходимо использовать как следующий шаг после создания заказа (СreateClaim) и регистрации даты выставленного к оплате счета (UpdateClaimToWasSentState).
ВАЖНО: использование данной операции оправдано, если только вы используете схему с предварительной обработкой тура менеджером. В случае прямой схемы оплаты тура данный шаг в обработке онлайн-заказа необязателен.
Такой заказ в списке заказов будет выглядеть так:
GetClaimInfo – возвращает все необходимую информацию по ранее созданной заявке. Вместе с результатами данной операции вы также получаете специальным образом сформированный URL (RedirectToPaymentURL), который можно использовать для последующего редиректа покупателя на страницу оплаты того платежного провайдера, который был ранее выбран и настроен в личном кабинете: https://sletat.ru/workspace/billingsettings.aspx. Обратите также внимание на поле PaymentIsAvailable. В случае, если данное поле имеет значение false, попытка пройти на страницу оплаты для совершения платежа закончится неудачей (см. также замечания относительно актуализации тура).
Для совершения платежа ранее созданный заказ должен быть сначала переведен в состояние «В оплату» с указанием даты фиксации выставленного к оплате счета, а затем должен быть переведен в состояние «Просмотрен (заказчиком)»
ВАЖНО: использование данных операций оправдано, если только вы используете схему с предварительной обработкой тура менеджером. В случае прямой схемы оплаты тура данный шаг в обработке онлайн-заказа необязательны.
Обращайте ваше внимание также на срок актуальности выставляемой к оплате ссылки (PayableUntil).
GetActualization – возвращает текущее состояние актуализации тура, если она была ранее запрошена в методе CreateClaim (Actualize).
Фактом завершения актуализации будет являться получение свойства CurrentState в структуре Actualization, равного состояниям: Completed, Failed, IncorrectCurrency, AuthenticationProblem, HotelIsInStop, DepartureIsInStop, ReturnIsInStop. (См. описание статусов далее)
GetPayments – возвращает список доплат в разрезе указанного через ClaimIdentity онлайн-заказа. Дополнительно выставляемые счета на доплаты формируются в личном кабинете SLETAT.RU.
Методы
В данном разделе описаны все методы сервиса для работы с online-заявками на приобретение туров. К методам приведены примеры запросов и ответов в SOAP. Все методы требуют авторизации, информация для авторизации (логин и пароль) передаётся в заголовке SOAP - AuthInfo:
<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsi="ttp://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Header> <AuthInfo xmlns="urn:SletatRu:DataTypes:AuthData:v1"> <Login>********</Login> <Password>********</Password> </AuthInfo> </soap:Header> <soap:Body> <CreateClaim xmlns="urn:SletatRu:Contracts:XMLClaimsGate:v1" /> </soap:Body> </soap:Envelope>
В примерах SOAP запросов и ответов, что приводятся ниже для каждого метода, элемент soap:Header убран для лучшей читаемости документа.
CreateClaim
Метод используется для регистрации online-заявки, которая становится доступной для последующей ее обработки менеджером агентства в личном кабинете на SLETAT.RU. В новой версии в запросе можно указать необходимость провести актуализацию тура, что позволит получить актуальную стоимость тура на момент заказа со стороны туроператора.
Сигнатура:
CreateClaimResponse CreateClaim(CreateClaimRequest request)
Параметры:
CreateClaimRequest – параметр данного типа описывает всю структуру online-заявки и содержит следующие важные поля:
 - Tourist[] Tourists - список туристов. Каждая запись представляет собой описание туриста, на которого оформляется тур, и может содержать следующие свойства:
Title Обращение, MR, MR, INF Gender Пол string FirstName Имя string Surname Фамилия string Patronymic Отчество DateTime BirthDate Дата рождения byte Age Возраст, можно не указывать string Phone Номер телефона string Email Email string Country Страна string City Город проживания string PassportSeries Серия паспорта string PassportNumber Номер паспорта DateTime DateOfIssue Дата выдачи паспорта string IssuedBy Кем выдан паспорт DateTime Expires Срок окончания действия паспорта string Citizenship Гражданство
- Customer - Заказчик тура, именно на данного человека и его контактные данные будут отсылаться СМС оповещения и email
string FullName ФИО заказчика string Phone Телефон заказчика, именно этот телефон будет использоваться для СМС-оповещения и для связи со стороны турагентства string Email Email заказчика, именно этот адрес будет использоваться для отправки Email-оповещений заказчику обо всех важных операциях над заявкой string Address Адрес заказчика, одной строкой string Passport Паспорт заказчика, одной строкой Серия-Номер string IssuedBy Паспорт заказчика, поле «Кем выдан, когда» - 128 символов
Следующие поля описывают запрашиваемый тур:
int SourceId Идентификатор туроператора в системе SLETAT.RU, может быть получен со стороны поискового сервиса long OfferId Идентификатор предложения туроператора в системе SLETAT.RU, может быть получен со стороны поискового сервиса int RequestId Идентификатор поискового запроса в системе SLETAT.RU, может быть получен со стороны поискового сервиса
