NAV Navbar

Параметры доступа и формат сообщений

Взаимодействие с сервисом реализовано в соответствии со спецификацией JSON-RPC

Адрес тестового API: https://api.test.dev.smartway.today/v2

Для доступа к тестовой среде необходимо установить предоставленный сертификат в список доверенных корневых сертификатов операционной системы.

Production-версия доступна по адресу https://api.smartway.today/v2

Структура запроса

POST https://api.test.dev.smartway.today/v2

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ping",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
    }
  }
}

OK (HTTP 200)

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": null
}

Неверные авторизационные данные (HTTP 401)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 401,
    "data": null,
    "message": "Error: Unauthorized",
    "name": "Error"
  }
}

Все запросы выполняются методом POST

Параметр Тип Обязательный Описание
jsonrpc string да версия протокола JSON-RPC. Требуемое значение для всех запросов: "2.0"
method string да наименование метода
params string да параметры запроса
id string / integer да идентификатор запроса. Полученное значение будет содержаться в ответе для синхронизации

Параметры запроса передаются в поле params и состоят из двух обязательных объектов — authorization и query.

authorization

Параметр Тип Обязательный Описание
username string да логин (email) пользователя
password string да пароль

query

Структура объекта query различается в зависимости от запроса.

Примеры реализации интеграции

Пример 1

Получение данных по поездкам

Метод trip.get_by_range

Запрос - передаем в query период, за который хотим получить поездки

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "trip.get_by_range",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query": {
                "start_date": "2019-06-01",
                "end_date": "2019-06-15"
            }
    }
}

Ответ - массив услуг, сгруппированных по поездкам

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "last_version_id": 263427,
        "trips": [
            {
                "amount": 7038,
                "book_date": "2019-06-13T13:43:59.063",
                "checkin_date": "2019-06-17T14:40:00",
                "checkout_date": "2019-06-19T16:50:00",
                "id": 189703,
                "items": [
                    {
                        "amount": 7038,
                        "book_date": "2019-06-13T13:43:59",
                        "checkin_date": "2019-06-17T14:40:00",
                        "checkout_date": "2019-06-19T16:50:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246215,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-17T16:15:00",
                                        "date_depart": "2019-06-17T14:40:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            },
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-19T16:50:00",
                                        "date_depart": "2019-06-19T15:20:00",
                                        "place_arrive": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        },
                                        "place_depart": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        }
                                    }
                                ],
                                "travel_time": 90
                            }
                        ],
                        "last_change_date": "2019-06-13T13:43:59",
                        "number": "421-2888857716",
                        "project": "",
                        "request_id": "rqb1126017_8dc7_11e9_b991_802bf9e8178c",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 185,
                        "travellers": [
                            {
                                "birthday": "1990-04-15T00:00:00",
                                "documents": [
                                    {
                                        "number": "1134111133",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "gordina@smartway.today",
                                "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                "name": "Елена",
                                "patronymic": "Владимировна",
                                "phone": "+79256666666",
                                "sex": "Woman",
                                "surname": "Гордина"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 639.82,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-06-17T14:40:00",
                                "checkout_date": "2019-06-19T16:50:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-06-13T13:43:59",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-17T16:15:00",
                                                "date_depart": "2019-06-17T14:40:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    },
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-19T16:50:00",
                                                "date_depart": "2019-06-19T15:20:00",
                                                "place_arrive": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                },
                                                "place_depart": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                }
                                            }
                                        ],
                                        "travel_time": 90
                                    }
                                ],
                                "item_id": 246215,
                                "number": "421-2888857716",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 7038,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 617.09,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 185,
                                "travellers": [
                                    {
                                        "birthday": "1990-04-15T00:00:00",
                                        "documents": [
                                            {
                                                "number": "1134111133",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "gordina@smartway.today",
                                        "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                        "name": "Елена",
                                        "patronymic": "Владимировна",
                                        "phone": "+79256666666",
                                        "sex": "Woman",
                                        "surname": "Гордина"
                                    }
                                ],
                                "trip_id": 189703,
                                "version_id": 263426
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-06-13T13:43:59",
                "name": "Санкт-Петербург",
                "status": "AwaitingConfirmation"
            },
            {
                "amount": 7513,
                "book_date": "2019-06-14T17:11:28.687",
                "checkin_date": "2019-06-14T19:25:00",
                "checkout_date": "2019-06-15T01:25:00",
                "id": 189704,
                "items": [
                    {
                        "amount": 7513,
                        "book_date": "2019-06-14T17:11:28",
                        "checkin_date": "2019-06-14T19:25:00",
                        "checkout_date": "2019-06-15T01:25:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246216,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-14T21:00:00",
                                        "date_depart": "2019-06-14T19:25:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            },
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-15T01:25:00",
                                        "date_depart": "2019-06-14T23:55:00",
                                        "place_arrive": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        },
                                        "place_depart": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        }
                                    }
                                ],
                                "travel_time": 90
                            }
                        ],
                        "last_change_date": "2019-06-14T17:11:28",
                        "number": "421-2888857748",
                        "project": "",
                        "request_id": "",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 185,
                        "travellers": [
                            {
                                "birthday": "1978-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "1234111109",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "grab@mail.ru",
                                "external_id": "333da0bd-7bff-11e2-9362-001b11b25590",
                                "name": "Светлана",
                                "patronymic": "Марковна",
                                "phone": "+79165555555",
                                "sex": "Woman",
                                "surname": "Габровская"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 683,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-06-14T19:25:00",
                                "checkout_date": "2019-06-15T01:25:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-06-14T17:11:28",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-14T21:00:00",
                                                "date_depart": "2019-06-14T19:25:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    },
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-15T01:25:00",
                                                "date_depart": "2019-06-14T23:55:00",
                                                "place_arrive": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                },
                                                "place_depart": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                }
                                            }
                                        ],
                                        "travel_time": 90
                                    }
                                ],
                                "item_id": 246216,
                                "number": "421-2888857748",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 7513,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 660.27,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 185,
                                "travellers": [
                                    {
                                        "birthday": "1978-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "1234111109",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "grab@mail.ru",
                                        "external_id": "333da0bd-7bff-11e2-9362-001b11b25590",
                                        "name": "Светлана",
                                        "patronymic": "Марковна",
                                        "phone": "+79165555555",
                                        "sex": "Woman",
                                        "surname": "Габровская"
                                    }
                                ],
                                "trip_id": 189704,
                                "version_id": 263427
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-06-14T17:11:28",
                "name": "Санкт-Петербург",
                "status": "Completed"
            }
        ]
    }
}

Метод trip.get_after_change

Запрос - в первый раз передаем в query 0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "trip.get_after_change",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": 0
  }
}

Ответ - массив услуг, сгруппированных по поездкам

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "last_version_id": 263427, #'этот номер будем использовать в следующем запросе в query'
        "trips": [
            {
                "amount": 2916.6,
                "book_date": "2019-05-13T19:45:26.067",
                "checkin_date": "2019-05-14T00:20:00",
                "checkout_date": "2019-05-14T08:59:00",
                "id": 189686,
                "items": [
                    {
                        "amount": 2916.6,
                        "book_date": "2019-05-13T19:45:26",
                        "checkin_date": "2019-05-14T00:20:00",
                        "checkout_date": "2019-05-14T08:59:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246194,
                        "info": {
                            "station_arrive": "Санкт-Петербург-Главн. (московский Вокзал)",
                            "station_depart": "Москва Октябрьская (ленинградский Вокзал)"
                        },
                        "last_change_date": "2019-05-13T19:45:26",
                        "number": "70000416557990",
                        "project": "",
                        "request_id": "",
                        "service_type": "Train",
                        "status": "Created",
                        "travel_time": 519,
                        "travellers": [
                            {
                                "birthday": "1960-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "4500000000",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "example@smartway.today",
                                "external_id": null,
                                "name": "Геннадий",
                                "patronymic": "Сергеевич",
                                "phone": "+79165555555",
                                "sex": "Man",
                                "surname": "Абрамов"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 0,
                                "vat_rate": "0%"
                            },
                            {
                                "vat_amount": 0,
                                "vat_rate": "0%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-05-14T00:20:00",
                                "checkout_date": "2019-05-14T08:59:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-05-13T19:45:26",
                                "info": {
                                    "station_arrive": "Санкт-Петербург-Главн. (московский Вокзал)",
                                    "station_depart": "Москва Октябрьская (ленинградский Вокзал)"
                                },
                                "item_id": 246194,
                                "number": "70000416557990",
                                "service_type": "Train",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 2916.6,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 0,
                                                "vat_rate": "0%"
                                            },
                                            {
                                                "vat_amount": 0,
                                                "vat_rate": "0%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 519,
                                "travellers": [
                                    {
                                        "birthday": "1960-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "4500000000",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "example@smartway.today",
                                        "external_id": null,
                                        "name": "Геннадий",
                                        "patronymic": "Сергеевич",
                                        "phone": "+79165555555",
                                        "sex": "Man",
                                        "surname": "Абрамов"
                                    }
                                ],
                                "trip_id": 189686,
                                "version_id": 263393
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-05-13T19:45:26",
                "name": "Санкт-петербург",
                "status": "Completed"
            },
            {
                "amount": 3319,
                "book_date": "2019-05-14T12:45:01.44",
                "checkin_date": "2019-05-14T14:40:00",
                "checkout_date": "2019-05-14T16:15:00",
                "id": 189687,
                "items": [
                    {
                        "amount": 3319,
                        "book_date": "2019-05-14T12:45:01",
                        "checkin_date": "2019-05-14T14:40:00",
                        "checkout_date": "2019-05-14T16:15:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246195,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-05-14T16:15:00",
                                        "date_depart": "2019-05-14T14:40:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            }
                        ],
                        "last_change_date": "2019-05-14T12:45:01",
                        "number": "421-2888854844",
                        "project": "",
                        "request_id": "",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 95,
                        "travellers": [
                            {
                                "birthday": "1960-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "4500000000",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "example@smartway.today",
                                "external_id": null,
                                "name": "Геннадий",
                                "patronymic": "Сергеевич",
                                "phone": "+79165555555",
                                "sex": "Man",
                                "surname": "Абрамов"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 279,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-05-14T14:40:00",
                                "checkout_date": "2019-05-14T16:15:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-05-14T12:45:01",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-05-14T16:15:00",
                                                "date_depart": "2019-05-14T14:40:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    }
                                ],
                                "item_id": 246195,
                                "number": "421-2888854844",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 3319,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 279,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 95,
                                "travellers": [
                                    {
                                        "birthday": "1960-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "4500000000",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "example@smartway.today",
                                        "external_id": null,
                                        "name": "Геннадий",
                                        "patronymic": "Сергеевич",
                                        "phone": "+79165555555",
                                        "sex": "Man",
                                        "surname": "Абрамов"
                                    }
                                ],
                                "trip_id": 189687,
                                "version_id": 263394
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-05-14T12:45:01",
                "name": "Санкт-Петербург",
                "status": "AwaitingConfirmation"
            },

Цель

получать в свою систему данные о всех бронированиях (билеты, гостиницы, трансфер) и учитывать их удобным образом.

По какой причине возникла такая потребность:

Варианты реализации

Система получает информацию о совершенных бронирования с помощью метода trip.get_by_range или trip.get_after_change для получения всех поездок за указанный период или всех поездок, оформленных с момента последнего запроса

  1. Метод trip.get_by_range используется для получения всех поездок в указанном диапазоне дат. При этом отбор идет исключительно по датам, и обязательно указывать и start_date, и end_date в запросе. Если хотя бы одна дата не указана, запрост вернет ошибку. Результат запроса - массив поездок за указанный период с подробной информацией по ним, а также параметр last_version_id - идентфикатор самой поздней версии поездки (необходим в первую очередь для использования в других методах)

  2. Метод trip.get_after_change используется для получения новых поездок, то есть поездок, забронированных или измененных после реализации последнего запроса. Для того, чтобы идентифицировать "новые" поездки, в query передается параметр last_version_id. Если в query задать 0, метод вернет все поездки без исключения. Чтобы получать новые поездки, необходимо:

    • отправить первый запрос с "query": 0
    • в ответе получить last_version_id (в примере это 263405)
    • запомнить его
    • передать его в следующем запросе и так далее.

Пример 2

Регулярная актуализация списка сотрудников

Запрос - передаем в массиве employees данные по нашему новому сотруднику

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "employees.save",
    "params":{
        "authorization": {"username": "example@smartway.today", "password": "example"},
        "query": {
            "employees": [{
                "id": "8754",
                "mobile_phone": "+79990000000",
                "surname": "Илларионов",
                "name": "Петр",
                "patronymic": "Сергеевич",
                "surname_eng": "Illarionov",
                "name_eng": "Piotr",
                "patronymic_eng": "Sergeevich",
                "email": "illarionov@piotr.com",
                "citizenship_code": "RU",
                "birthday": "1981-01-01",
                "sex": "male",
                "bonuses": [],
                "documents": [{"number": "5608999999", "due_date": null, "type": "domestic_passport"}],
                "companies_inn": ["7799555550"]
            }]
        }
    }
}

Ответ - получаем ответ об успешной обработке нашего запроса

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "8754",
            "success": true
        }
    ]
}

Цель

постоянно синхронизировать список сотрудников между внутренней системой компании и сервисом Смартвэй, для того, чтобы поддерживать список сотрудников в личном кабинете Смартвэй в актуальном состоянии.

При каждом изменении в карточке сотрудника (или через равные промежутки времени, с заданной регулярностью) система отправляет запрос в сервис Смартвэй с помощью метода employees.save. В запросе передается актуальная информация по сотруднику, его id в системе (по нему ведется сопоставление), а также данные о том, актуален сотрудник или нет (параметр is_archive).

id сотрудника передается и сохраняется в Смартвэй, в дальнейшем сопоставление будет осуществляться по этому id, либо (если id передан как null или не найдено соответствие) по следующим полям: surname, name, patronymic, birthday, citizenship_code, companies_inn/companies_id. При этом сопоставление осуществляется при точном одновременном совпадении параметров surname, name, patronymic, birthday, citizenship_code и хотя бы при одном совпадении в массиве companies_inn/companies_id.

Если соответствие найдено по id или по перечисленным полям, данные по сотруднику обновляются по тем полям, которые переданы в запросе. Если соответствие не найдено ни по id, ни по перечисленным полям, создается новый сотрудник (при условии, что заполнены все обязательные поля - иначе запрос вернет ошибку).

Если сотрудник больше не работает в компании, отправляется запрос, в котором is_archive = True. Этот сотрудник перемещен в архив, и больше не отражается в личном кабинете сервиса Смартвэй.

Пример 3

Отправление в Smartway заявок на командировку, получение данных по бронированиям и закрывающим документам

Цель

автоматизировать процесс оформления командировок и формирования отчетности по командировкам сотрудников.

Описание процесса

  1. У сотрудника А возникает необходимость отправиться в командировку. Он формирует заявку на командировку и получает согласование от руководителя (во внутренней системе или на бумаге).
  2. Сотрудник, отвечающий за бронирование билетов и гостиниц для командировок (трэвел менеджер, секретарь или сам сотрудник А):
    • подбирает билет и гостиницу в соответствии с заявкой,
    • при необходимости согласовывает возможные варианты и детали с сотрудником А/его руководителем, пока не будет выбран и одобрен конкретный вариант,
    • осуществляет бронирование (за счет организации или на средства самого сотрудника А).
  3. Сотрудник А возвращается из командировки и передает подтверждающие документы сотруднику, отвечающему за составление авансовых отчетов (бухгалтер, секретарь или сам сотрудник А). Ответственный сотрудник формирует авансовый отчет.

Описание процесса, автоматизированного с помощью сервиса Smartway и интеграции с внутренней системой клиента через API.

  1. Сотрудник А формирует заявку на командировку во внутренней системе. Согласованная руководителем заявка отправляется в сервис Smartway с помощью метода request.save. При этом, если в массиве travellers передается сотрудник, которого нет в сервисе Smartway (сопоставление по id), его данные автоматически добавляются в сервис.
  2. Сотрудник, отвечающий за бронирование:
    • заходит в личный кабинет Smartway, находит заявку и осуществляет поиск билетов/гостиниц. Параметры поиска заполняются автоматически из заявки (что исключает необходимость заполнения полей поиска вручную и возможность ошибки)
    • может из личного кабинета отправить PDF файлы с вариантами проезда/проживания сотруднику А/его руководителю для ознакомления/согласования (механизм согласования предусмотрен в сервисе Smartway)
    • осуществляет бронирование в сервисе Smartway (за счет организации) Статус заявки можно отслеживать во внутренней системе компании с помощью метода request.status Если руководитель отозвал согласование, или по какой-то причине заявка была отменена, в сервис Smartway отправляется запрос request.cancel.
  3. Система получает информацию о совершенных бронированиях:
    • с помощью метода trip.get_by_request, для сохранения цепочки заявка-командировка
    • с помощью метода trip.get_by_range или trip.get_after_change для получения всех поездок за указанный период или всех поездок, оформленных с момента последнего запроса
  4. Система получает закрывающие документы от сервиса Smartway (акт выполненных работ, реестр билетов, счет-фактура на гостиницы) с помощью метода packages.get. Таким образом, все необходимые операции отражаются в системе клиента на основании полученных данных по поездкам, например:
    • автоматически формируется авансовый отчет
    • принимаются к учету расходы на командировку - не только расходы на проезд и проживание, но также комиссии Smartway
    • принимается к вычету НДС
    • автоматически заполняется книга покупок
    • формируются счета-фактуры по билетам
    • автоматически актуализируется табель учета рабочего времени

Этапы 1 и 3 не зависимы друг от друга, поэтому можно реализовать любой из этапов по отдельности, в зависимости от стоящей задачи.

Сотрудники

Сохранение / обновление сотрудников

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "employees.save",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
      "employees": [
        {
          "id": null,
          "mobile_phone": "+79990000000",
          "surname": "Илларионов",
          "name": "Петр",
          "patronymic": "Сергеевич",
          "surname_eng": "Illarionov",
          "name_eng": "Piotr",
          "patronymic_eng": "Sergeevich",
          "email": "illarionov@piotr.com",
          "citizenship_code": "RU",
          "birthday": "1981-01-01",
          "sex": "male",
          "bonuses": [],
          "documents": [
            {
              "number": "5608999999",
              "due_date": null,
              "type": "domestic_passport"
            }
          ],
          "companies_inn": [
            "7897897897",
            "1234567891"
          ]
        }
      ]
    }
  }
}

Ответ содержит массив идентификаторов сотрудников и признаков успешности сохранения/обновления

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": 112233,
      "success": true
    },
    {
      "id": 112234,
      "success": true
    }
  ]
}

"method": "employees.save"

В query передается массив employees, состоящий из объектов со следующей структурой:

Параметр Тип Обязательный Описание
id string нет Идентификатор сотрудника в системе клиента (см. Примечание под таблицей)
surname string да Фамилия
name string да Имя
patronymic string нет Отчество (обязательно при наличии)
surname_eng string нет Транслитерация фамилии (для оформления проездных документов)
name_eng string нет Транслитерация имени (для оформления проездных документов)
patronymic_eng string нет Транслитерация отчества
sex enum да Пол. Допустимые значения:
  • male или man - мужской
  • female или woman - женский
birthday date да Дата рождения в формате YYYY-MM-DD
citizenship_code string да Гражданство: двухбуквенный код страны (RU, US, UK и т.д.)
mobile_phone string да Мобильный телефон
email string да e-mail
employee_number string нет Табельный номер сотрудника
is_archive bool нет Флаг неактивности сотрудника:
  • true - уволен ("архивный" в ЛК Smartway)
  • false - работает в настоящее время
documents array of objects нет Документы сотрудника. См. структуру document
bonuses array of objects нет Карты лояльности сотрудника. См. структуру bonus
companies_inn array of strings нет Массив ИНН компаний, в которых числится сотрудник
companies_id array of strings нет Массив id компаний, в которых числится сотрудник.

Среди параметров companies_inn и companies_id обязательно указывать хотя бы один. При этом, если указать оба, приоритетным является companies_id - то есть, если компания найдена по id, то её ИНН уже не проверяется.

id сотрудника передается и сохраняется в Смартвэй, в дальнейшем сопоставление будет осуществляться по этому id, либо (если id передан как null или не найдено соответствие) по следующим полям: surname, name, patronymic, birthday, citizenship_code, companies_inn/companies_id. При этом сопоставление осуществляется при точном одновременном совпадении параметров surname, name, patronymic, birthday, citizenship_code и хотя бы при одном совпадении в массиве companies_inn/companies_id.

Если соответствие найдено по id или по перечисленным полям, данные по сотруднику обновляются по тем полям, которые переданы в запросе. Если соответствие не найдено ни по id, ни по перечисленным полям, создается новый сотрудник (при условии, что заполнены все обязательные поля - иначе запрос вернет ошибку).

document

Параметр Тип Обязательный Описание
number string да Номер документа
due_date date нет Срок действия. Не требуется для общероссийского паспорта
type enum да Тип документа. Возможные значения:
  • domestic_passport - Внутренний паспорт. Для граждан РФ - общероссийский паспорт гражданина РФ
  • foreign_passport - Заграничный паспорт гражданина. Как правило, имеется только у граждан РФ

bonus

Параметр Тип Обязательный Описание
code string да Для авиакомпаний: IATA код перевозчика (SU, S7, U6 и т.д.)
Для ЖД: FPK
number string да Номер бонусной карты
type enum да Тип услуги. Допустимые значения:
  • air - авиа
  • train - ЖД

Получение списка сотрудников

Запрос содержит массив id компании, в которой числится сотрудник, и при необходимости, массив id сотрудников

{
  "jsonrpc": "2.0",
  "id": 777,
  "method": "employees.list",
  "params": {
    "authorization": {
      "username": "example@smartway.today",
      "password": "example"
    },
    "query": {"companies_id": [11525], "employees_id": [99999]}
  }
}

Ответ содержит массив сотрудников. Структура объектов массива аналогичная структуре employee в методе employees.save.

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": [
    {
      "Birthday": "1981-01-01T00:00:00",
      "Bonuses": [
        {
          "Code": "SU",
          "EmployeeId": 159304,
          "Id": 15156,
          "Number": "4444",
          "Type": "Air"
        },
        {
          "Code": "FPK",
          "EmployeeId": 159304,
          "Id": 15157,
          "Number": "555",
          "Type": "Train"
        }
      ],
      "Code": "RU",
      "Code3": "RUS",
      "Companies": [
        {
          "CompanyId": 11525,
          "CompanyName": "ООО \"Конфетпром\"",
          "EmployeeId": 159304,
          "ShortCompanyName": "ООО \"Конфетпром\""
        }
      ],
      "Documents": [],
      "Email": "shishkin@piotr.com",
      "EmployeeNumber": "",
      "ExternalId": "99999",
      "Id": 159304,
      "MobilePhone": "+79990000000",
      "Name": "Петр",
      "Patronymic": "Сергеевич",
      "Sex": "Man",
      "Status": "Active",
      "Surname": "Шишкин",
      "Tags": []
    }
  ]
}

"method": "employees.list"

Получение информации по сотрудникам. Можно получить сотрудников всех компаний аккаунта (если передать companies_id и employees_id пустыми), либо всех сотрудников из массива компаний companies_id, либо определенных сотрудников, заданных массивом employees_id. При этом, данные по сотрудникам передаются с учетом прав пользователя, отправляющего запрос: если у пользователя нет прав редактировать данные других сотрудников, то он будет получать информацию только о себе.

Структура запроса:

Параметр Тип Обязательный Описание
companies_id array да Массив id компаний, сотрудников которых надо передать
employees_id array да Массив идентификаторов сотрудников в системе клиента

Структура ответа:

Параметр Тип Обязательный Описание
Id int да Идентификатор сотрудника в Smartway
ExternalId string да Идентификатор сотрудника в системе клиента
Name string да Имя
Surname string да Фамилия
Patronymic string да Отчество
Email string да email
MobilePhone string да номер телефона
Sex enum да Пол. Допустимые значения:
  • Man - мужской
  • Woman - женский
EmployeeNumber string да Табельный номер сотрудника
Birthday datetime да дата рождения
Code string да двубуквенный код страны гражданства
Code3 string да трехбуквенный код страны гражданства
Companies array of objects да Массив объектов компаний, в которых работает сотрудник
Documents array of objects да Массив документов сотрудника
Bonuses array of objects да Массив бонусных карт сотрудника
Status enum да Статус сотрудника. Допустимые значения:
  • Active - активный сотрудник без доступа в сервис
  • Archived - архивный сотрудник
  • User - сотрудник с доступом в сервис
Tags array of strings да Метки

Document

Параметр Тип Обязательный Описание
Number string да Номер документа
DueDate datetime нет Срок действия. Не требуется для общероссийского паспорта
Type enum да Тип документа. Возможные значения:
  • DomesticPassport - Внутренний общегражданский паспорт. Для граждан РФ - паспорт гражданина РФ, для иностранцев - паспорт иностранного гражданина
  • ForeignPassport - Заграничный паспорт гражданина. Как правило, имеется только у граждан РФ
Id int да Идентификатор документа
FirstName string да Имя сотрудника (транслитерация на латинице для паспорта гражданина РФ)
LastName string да Фамилия сотрудника (транслитерация на латинице для паспорта гражданина РФ)
Patronymic string нет Отчество сотрудника(транслитерация на латинице для паспорта гражданина РФ)
Name string да Имя, как в паспорте
Surname string да Фамилия, как в паспорте
MiddleName string да Отчество, как в паспорте
Selected bool да по умолчанию - false

Bonus

Параметр Тип Обязательный Описание
Id int да Идентификатор бонусной карты
EmployeeId string да Идентификатор сотрудника в Smartway
Code string да Для авиакомпаний: IATA код перевозчика (SU, S7, U6 и т.д.)
Для ЖД: FPK
Number string да Номер бонусной карты
Type enum да Тип услуги. Допустимые значения:
  • Air - авиа
  • Train - ЖД

Companies

Параметр Тип Обязательный Описание
CompanyId int да Идентификатор компании в Smartway
CompanyName string да Наименование компании
ShortCompanyName string да Краткое наименование компании
EmployeeId int да Идентификатор сотрудника в Smartway

Установление прав сотруднику

Запрос содержит массив id сотрудника и список прав

{
  "jsonrpc": "2.0",
  "id": 777,
  "method": "employees.setRights",
  "params": {
    "authorization": {
      "username": "example@smartway.today",
      "password": "example"
    },
    "query": {
        "employeeId": 159305,
        "rights": {
            "Approve": "Available",
            "BuyTripAccount": "OnlyAfterApprove",
            "BuyTripPersonal": "TravelPolicy",
            "EditEmployee": "Personal",
            "EditRights": "Unavailable",
            "Finance": "Available",
            "Notifications": "AccountVouchersAndInvoices",
            "ViewTrips": "All",
            "CanLogin": "True"
        }
    }
  }
}

В случае успешного запроса в ответе возвращается список прав

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": {
    "Rights": {
      "Approve": "Available",
      "BuyTripAccount": "OnlyAfterApprove",
      "BuyTripPersonal": "TravelPolicy",
      "CanLogin": true,
      "EditEmployee": "Personal",
      "EditRights": "Unavailable",
      "Finance": "Available",
      "Notifications": "AccountVouchersAndInvoices",
      "ViewTrips": "All"
    }
  }
}

"method": "employees.setRights"

В query передается id сотрудника (employeeId, тип int) и объект rights со следующей структурой:

Параметр Тип Обязательный Описание
CanLogin bool да Возможность входа в сервис
Approve enum нет Согласование поездок другим сотрудникам. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не может согласовывать поездки
  • Available - может согласовывать поездки
BuyTripAccount enum нет Покупка поездок для всех сотрудников в аккаунте. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не может покупать поездки для других сотрудников
  • OnlyAfterApprove - может покупать только по согласованию
  • Unlimited - может покупать без ограничений
  • TravelPolicy - может покупать в рамках travel политик сотрудников
BuyTripPersonal enum нет Покупка поездок для сеебя. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не может покупать поездки для себя
  • OnlyAfterApprove - может покупать поездки со согласованию
  • Unlimited - может покупать поездки для себя без ограничений
  • TravelPolicy - может покупать поездки для себя в рамках travel политики
EditEmployee enum нет Редактирование информации сотрудников. Допустимые значения:
  • Undefined - не определено
  • Personal - может редактировать только свои данные
  • All - может редактировать данные всех сотрудников
EditRights enum нет Редактирование прав других сотрудников. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не может редактировать права доступа
  • Available - может редактировать права доступа
Finance enum нет Просмотр финансовых документов. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не может просматривать фин документы
  • Available - может просматривать фин документы
Notifications enum нет Уведомления от сервиса. Допустимые значения:
  • Undefined - не определено
  • Unavailable - не получает уведомления
  • PersonalVouchers - получает ваучеры по своим поездкам
  • PersonalVouchersAndInvoices - получает ваучеры и счета по своим поездкам
  • AccountVouchers - получает ваучеры по всем поездкам аккаунта
  • AccountVouchersAndInvoices - получает ваучеры и счета по всем поездкам аккаунта
  • PersonalInvoices - получает счета по своим поездкам
  • AccountInvoices - получает счета по всем поездкам аакаунта
ViewTrips enum нет Просмотр поездок. Допустимые значения:
  • Undefined - не определено
  • Personal - может просматривать свои поездки
  • All - может просматривать все поездки аккаунта

Авиабилеты

Автокомплит аэропортов

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "airline.airport_autocomplete",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": "Санкт"
  }
}

Ответ:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "city": {
                "name_eng": "St. Petersburg",
                "name_rus": "Санкт-Петербург"
            },
            "code": "LED",
            "country": {
                "name_eng": "Russia",
                "name_rus": "Россия"
            },
            "name_eng": "St. Petersburg Pulkovo",
            "name_rus": "Пулково. Санкт-Петербург"
        },
        {
            "city": {
                "name_eng": "Saint Petersburg",
                "name_rus": "Санкт-Петербург"
            },
            "code": "PIE",
            "country": {
                "name_eng": "United States",
                "name_rus": "США"
            },
            "name_eng": "St. Petersburg-Clearwater",
            "name_rus": "Сент-Питерсберг-Клируотер"
        }
    ]
}

"method": "airline.airport_autocomplete"

Получение списка аэропортов, начинающихся со строки, переданной в query. Поиск производится одновременно по названию города, названию аэропорта и трехбуквенному коду аэропорта, который используется в дальнейшем для поиска.

Ответ содержит массив совпадений с запросом

Параметр Тип Обязательный Описание
code string да IATA код аэропорта или города (для случаев, когда к одному городу относится несколько аэропортов)
name_eng string да Название на английском языке
name_rus string да Название на русском языке
city object да Город, в котором находится аэропорт
country object да Страна, в которой находится аэропорт

Структура полей city и country

Параметр Тип Обязательный Описание
name_eng string да Название на английском языке
name_rus string да Название на русском языке

Поиск авиабилетов

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "airline.search",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
      "class": "Econom",
      "direct": false,
      "baggage": "all",
      "travelers": 1,
      "routes": [
        {
          "departure": "PEZ",
          "arrival": "MOW",
          "date": "2019-10-04"
        }
      ]
    }
  }
}

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "class": "Econom",
    "search_id": "bdff179a-f96c-43a3-ac7b-70d51fa5e07b",
    "trips": [
      {
        "id": 1,
        "duration": 5100,
        "price": 5373,
        "routes": [
          {
            "duration": 5100,
            "segments": [
              {
                "aircraft_name": "Embraer 170 Regional Jet",
                "airline": {
                  "id": "S7",
                  "name": "S7"
                },
                "arrival_airport": {
                  "id": "DME",
                  "name": "Домодедово"
                },
                "arrival_city": {
                  "id": "DME",
                  "name": "Москва"
                },
                "arrival_country": "Россия",
                "arrival_terminal": null,
                "arrival_time": 1570223100,
                "available_seats": 6,
                "change_duration": 0,
                "departure_airport": {
                  "id": "PEZ",
                  "name": "Пенза"
                },
                "departure_city": {
                  "id": "PEZ",
                  "name": "Пенза"
                },
                "departure_country": "Россия",
                "departure_terminal": null,
                "departure_time": 1570218000,
                "flight_number": "256"
              }
            ]
          },
          // ... другие варианты перелета
        ],
        "fares": [
          {
            "additional_services": {},
            "airline_bonus_information": null,
            "baggage_places": null,
            "can_buy_baggage": "Charge",
            "can_registration_seat": "NotOffered",
            "can_upgrade_rate": "Charge",
            "carryon_places": "10 кг. 55*40*20см.",
            "change_ticket_with_condition": {},
            "have_internet_access": "NotDefined",
            "id": null,
            "is_baggage_included": "Charge",
            "is_business_hall_included": "NotOffered",
            "is_carryon_included": "Included",
            "is_default": true,
            "is_priority_baggage_reception": "NotOffered",
            "is_priority_registration": "NotOffered",
            "is_ticket_changeable": "Charge",
            "is_ticket_changeable_after_departure": "NotOffered",
            "is_ticket_refundable": "NotOffered",
            "is_ticket_refundable_after_departure": "NotOffered",
            "name": "Эконом",
            "price": 5373,
            "refund_ticket_with_condition": {}
          },
          // ... другие тарифы для данного перелета
        ]
      }
    ]
  }
}

"method": "airline.search"

Возвращает доступные варианты перелета по указанномым маршрутам на указанные даты в соответствии с выбранными фильтрами

Структура запроса

Параметр Тип Обязательный Описание
class string да Класс перелета. Допустимые значения:
  • Econom
  • Business
  • First
Поиск по всем классам одновременно не поддерживается.
direct bool да При значении true выдача будет ограничена только прямыми перелетами
baggage enum да Ограничить выдачу в соответствии с требованиями по багажу. Допустимые значения:
  • all - без ограничений
  • included - только результаты с багажом
  • not_included - только результаты без багажа
В выдачу not_included также попадут результаты, для которых перевозчик не предоставил информацию о багажности.
travelers int да Количество путешественников. Допустимые значения: от 1 до 6
routes array да Перелеты — массив route

route

Параметр Тип Обязательный Описание
departure string да IATA код аэропорта/города вылета. 3 знака
arrival string да IATA код аэропорта/города прилета. 3 знака
date string да Дата вылета в формате YYYY-MM-DD

Структура ответа

Параметр Тип Обязательный Описание
search_id string да Уникальный идентификатор результатов поиска
trips array да Массив вариантов перелета. См. структуру trip

trip

Параметр Тип Обязательный Описание
id int да Идентификатор результата
duration int да Суммарная длительность всех перелетов в секундах
price decimal да Стоимость в рублях
routes array да Маршрут — массив route
fares array да Массив fare. Тарифы, применимые к данному варианту перелета

route

Параметр Тип Обязательный Описание
duration int да Длительность перелета в сеундах
segments array да Сегменты — массив segment

segment

Параметр Тип Обязательный Описание
departure_country string да Страна вылета
departure_city string да Город вылета
arrival_country string да Страна прилета
arrival_city string да Город прилета
airline airline да Авиакомпания, выполняющая перелет
departure_airport airport да Аэропорт вылета
arrival_airport airport да Аэропорт прилета
aircraft_name string да Тип воздушного судна (Boeing 737-800, Airbus 320 и т.д.)
flight_number string да Номер рейса
available_seats int да Количество доступных для бронирования мест
change_duration int да При значении больше 0 указывает на длительность пересадки
departure_time timestamp да Местное время вылета в формате UNIX time
arrival_time timestamp да Местное время прилета в формате UNIX time
departure_terminal string да Терминал вылета (null, если нет информации или неприменимо к аэропорту)
arrival_terminal string да Терминал прилета (null, если нет информации или неприменимо к аэропорту)

airline

Параметр Тип Обязательный Описание
id string да IATA код авиакомпании
name string да Название авиакомпании

airport

Параметр Тип Обязательный Описание
id string да IATA код аэропорта
name string да Название аэропорта

fare

Параметр Тип Обязательный Описание
id string да Идентификатор тарифной семьи (null, если неприменимо)
name string да Название тарифа
is_default bool да Признак базового тарифа — самого дешевого для данного варианта
price decimal да Стоимость
is_carryon_included status да Включена ли ручная кладь
carryon_places string да Описание ограничений ручной клади
is_baggage_included status да Включен ли багаж
baggage_places string да Описание ограничений включенного багажа (количество мест, вес, допустимые габариты)
can_buy_baggage status да Возможность доплаты за багаж в аэропорту
is_ticket_refundable status да Возможность возврата билета до завершения регистрации
is_ticket_refundable _after_departure status да Возможность возврата билета после завершения регистрации
refund_ticket _with_condition dictionary<string, status> да <Описание условий возврата, Статус>
is_ticket_changeable status да Возможность изменить время/дату вылета до завершения регистрации
is_ticket_changeable _after_departure status да Возможность изменить время/дату вылета после завершения регистрации
change_ticket _with_condition dictionary<string, status> да <Описание условий изменения, Статус>
can_registration_seat status да Выбор места в салоне
is_business _hall_included status да Доступ в бизнес-зал
have_internet _access status да Доступ в интернет
is_priority _registration status да Приоритетная регистрация
is_priority_baggage _reception status да Приоритетное получение багажа
airline_bonus _information string да Информация о бонусных милях авиакомпании
can_upgrade_rate status да Возможность повышения тарифа
additional_services dictionary<string, status> да Описание дополнительных услуг и их доступность (см. структуру status)

status

Значение Тип Описание
Included string Включено
Charge string Предоставляется за дополнительную плату
NotOffered string Недоступно для указанного рейса
NotDefined string Перевозчик не предоставил информацию

Покупка авиабилетов

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "airline.book",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
      "item": {
        "search_id": "01b009a9-dd73-4cea-bb9d-b07edf934db6",
        "trip_id": 2
      },
      "employees": [
        {
          "id": "123e4567-e89b-12d3-a456-426655440000",
          "phone": "+79999999999",
          "surname": "Иванов",
          "name": "Андрей",
          "patronymic": "Петрович",
          "surname_e": "Ivanov",
          "name_e": "Andrei",
          "patronymic_e": "Petrovich",
          "email": "ivanov@andrei.com",
          "citizenship": "RU",
          "birthday": "1986-02-17",
          "sex": "man",
          "airline_bonuses": [
            {
              "iata": "SU",
              "number": "2143235345"
            }
          ],
          "passports": [
            {
              "number": "5607123456",
              "due_date": null,
              "type": "DomesticPassport",
              "selected": true
            }
          ],
          "companies_inn": "7897897897"
        }
      ]
    }
  }
}

Поле result в ответе содержит идентификатор бронирования, по которому можно проверить статус бронирования

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "ebb84671-2a79-4352-be59-12f04485dcb1"
}

"method": "airline.book"

Покупка выбранных билетов для указанных сотрудников

Структура запроса

Параметр Тип Обязательный Описание
item item да Идентификаторы найденного варианта перелета для бронирования
employees array да Массив employee. Сотрудники, на которых выполняется бронирование перелета

item

Параметр Тип Обязательный Описание
search_id string да Идентификатор поиска
trip_id int да Идентификатор варианта перелета
fare_id string нет Идентификатор тарифа в варианте перелета

employee

Параметр Тип Обязательный Описание
id string да Идентификатор сотрудника во внешней системе
phone string да Номер телефона сотрудника в формате +7XXXXXXXXXX
surname string да Фамилия сотрудника
name string да Имя сотрудника
patronymic string да Отчество сотрудника
surname_e string да Фамилия сотрудника (транслитерация)
name_e string да Имя сотрудника (транслитерация)
patronymic_e string обязательно, при наличии Отчество сотрудника (транслитерация)
email string да Email сотрудника
citizenship string да Гражданство сотрудника (RU, US и т.д.)
birthday date да Дата рождения сотрудника в формате YYYY-MM-DD
sex enum да Пол. Допустимые значения:
  • male или man - мужской
  • female или woman - женский
airline_bonuses bonus нет Бонусные карты авиакомпаний
passports array да Массив passport. Паспорта сотрудника
companies_inn object да, если не указан company_id

ИНН организации, за которой будет закреплен сотрудник и на которую будет выставлен счет.

company_id string да, если не указан companies_inn Идентификатор компании в Smartway. Имеет приоритет, если указан вместе с companies_inn

Получение статуса покупки авиабилета

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "airline.result",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": "ebb84671-2a79-4352-be59-12f04485dcb1"
  }
}

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "error": null,
    "status": "done",
    "trip_id": 20932
  }
}

"method": "airline.result"

Получение статуса авиабилета по UUID, полученному в ответе на запрос airline.book

Структура ответа

Параметр Тип Обязательный Описание
status enum да Текущий статус покупки. Возможные значения:
  • done - завершено успешно
  • pending - выполняется
  • failed - закончено с ошибкой
trip_id int только если "status": "done" Идентификатор забронированной поездки или null в случае ошибки бронирования
error string только если "status": "failed" Текст ошибки. Примеры:
  • Бронирование невозможно. Стоимость: {0}. Доступно: {1}
  • Бронирование невозможно. Задолженность: {0}
  • Бронирование невозможно. Доступ запрещен.
  • Бронирование невозможно. Превышен лимит бронирований.

Ж/Д билеты

Автокомплит ж/д станций

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "train.station_autocomplete",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": "новосиб"
  }
}

Ответ

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "code": "2044000",
      "name": "новосибирск"
    },
    {
      "code": "2044002",
      "name": "новосибирск-восточный"
    },
    {
      "code": "2044001",
      "name": "новосибирск-главный"
    },
    {
      "code": "2044003",
      "name": "новосибирск-западный"
    },
    {
      "code": "2044004",
      "name": "новосибирск-южный"
    }
  ]
}

"method": "train.station_autocomplete"

Получение списка станций, начинающихся со строки, переданной в query

Ответ содержит массив совпадений с запросом: наименование станции и её код в системе АСУ "Экспресс", использующийся для операций поиска и покупки билетов

Отели

Автокомплит отелей

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "hotel.autocomplete",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": "новосиб"
  }
}

Ответ

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": 2721,
      "is_region": true,
      "location": "Россия",
      "name": "Новосибирск"
    },
    {
      "id": 154922,
      "is_region": false,
      "location": "Новосибирск",
      "name": "Domina Hotel Novosibirsk (Домина отель Новосибирск)"
    },
    {
      "id": 311842,
      "is_region": false,
      "location": "Новосибирск",
      "name": "Отель DoubleTree by Hilton Novosibirsk"
    }
    // ...
  ]
}

"method": "hotel.autocomplete"

Получение списка отелей и регионов (либо конкретных населенных пунктов), содержащих строку, переданную в query

Ответ содержит массив лучших совпадений с запросом - не более 4 регионов и 10 отелей

Формат элемента массива в ответе

Параметр Тип Обязательный Описание
id int да Идентификатор региона/гостиницы, используемый для дальнейших операций поиска и бронирования
is_region bool да

true — регион; false — отель

location string да Для региона — название страны, для отеля — название города.
name string да Название региона/гостиницы

Заявки

Создание новой заявки

Запрос

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "request.save",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query" : {
                "id" : "rqb1126017_8dc7_11e9_b991_802bf9e81780",
                "travellers" : [
                    {
                        "id": "159307",
                        "mobile_phone": "+79165555555",
                        "surname": "Волина",
                        "name": "Ирина",
                        "patronymic": "Валерьевна",
                        "surname_eng": "Volina",
                        "name_eng": "Irina",
                        "patronymic_eng": "Valerevna",
                        "email": "vinogradova4@smartway.today",
                        "citizenship_code": "RU",
                        "birthday": "1991-05-04T00:00:00",
                        "sex": "female",
                        "bonuses": [],
                        "documents": [{"number": "1234111134", "due_date": null, "type": "domestic_passport"}],
                        "companies_inn": ["7799555550"]
                    }
                ],
                "creator" : {
                    "id": "159307",
                    "mobile_phone": "+79165555555",
                    "surname": "Волина",
                    "name": "Ирина",
                    "patronymic": "Валерьевна",
                    "surname_eng": "Volina",
                    "name_eng": "Irina",
                    "patronymic_eng": "Valerevna",
                    "email": "vinogradova4@smartway.today",
                    "citizenship_code": "RU",
                    "birthday": "1991-05-04",
                    "sex": "female",
                    "bonuses": [],
                    "documents": [{"number": "1234111134", "due_date": null, "type": "domestic_passport"}],
                    "companies_inn": ["7799555550"]
                },
                "comment" : "blablabla",
                "train_items" : [
                    {
                        "project_id" : "",
                        "departure_station_code" : "2000000",
                        "arrival_station_code" : "2044000",
                        "departure_date" : "2019-08-25T00:00:00",
                        "travellers" : [
                            {
                                "id": "159307",
                                "mobile_phone": "+79165555555",
                                "surname": "Волина",
                                "name": "Ирина",
                                "patronymic": "Валерьевна",
                                "surname_eng": "Volina",
                                "name_eng": "Irina",
                                "patronymic_eng": "Valerevna",
                                "email": "vinogradova4@smartway.today",
                                "citizenship_code": "RU",
                                "birthday": "1991-05-04T00:00:00",
                                "sex": "female",
                                "bonuses": [],
                                "documents": [{"number": "1234111134", "due_date": null, "type": "domestic_passport"}],
                                "companies_inn": ["7799555550"]
                            }
                        ]
                    }
                ]
            }
        }
    }

Ответ

  {
      "id": "777",
      "jsonrpc": "2.0",
      "result": "not_processing"
  }

"method": "request.save"

Параметр Тип Обязательный Описание
id string нет Идентификатор заявки в 1С
travellers array of objects да массив сотрудников, отправляющихся в командировку
creator object да Создатель командировки - структура аналогична объекту traveller
comment string нет Комментарий с пожеланиями
air_items array нет массив услуг, которые необходимо забронировать
train_items array нет массив услуг, которые необходимо забронировать
hotel_items array нет массив услуг, которые необходимо забронировать
transfer_items array нет массив услуг, которые необходимо забронировать

travellers

Параметр Тип Обязательный Описание
id string да Идентификатор сотрудника в 1С
name string да Имя сотрудника
surname string да Фамилия сотрудника
patronymic string нет Отчество сотрудника
name_eng string да Имя сотрудника (транслитерация)
surname_eng string да Фамилия сотрудника (транслитерация)
patronymic_eng string нет Отчество сотрудника (транслитерация)
sex enum да Пол. Допустимые значения:
  • male или man - мужской
  • female или woman - женский
birthday date да Дата рождения в формате YYYY-MM-DD
citizenship_code string да Гражданство: двухбуквенный код страны (RU, US, UK и т.д.)
mobile_phone string да Мобильный телефон
email string да e-mail
documents array да Документы сотрудника. См. структуру document
bonuses array нет Карты лояльности сотрудника. См. структуру bonus
companies_inn array of strings нет Массив ИНН компаний, в которых числится сотрудник
companies_id array of strings нет Массив id компаний, в которых числится сотрудник.

Среди параметров companies_inn и companies_id обязательно указывать хотя бы один. При этом, если указать оба, приоритетным является companies_id - то есть, если компания найдена по id, то её ИНН уже не проверяется.

bonus

Параметр Тип Обязательный Описание
code string да Для авиакомпаний: IATA код перевозчика (SU, S7, U6 и т.д.)
Для ЖД: FPK
number string да Номер бонусной карты
type enum да Тип услуги. Допустимые значения:
  • air - авиа
  • train - ЖД

Отмена заявки

Запрос

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "request.cancel",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query": "rq87761063_8ea0_11e9_b992_802bf9e8178c"
    }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": "canceled"
}

Если заявка не найдена

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": "not_found"
}

"method": "request.cancel" В query передается строка - id заявки в 1С, которую необходимо отменить. В ответе передается "canceled", если заявка успешно отменена.

Получение статуса заявки

Запрос

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "request.status",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query": ["rq87761062_8ea0_11e9_b992_802bf9e8178c", "rq87761063_8ea0_11e9_b992_802bf9e8178c", "rq87761064_8ea0_11e9_b992_802bf9e8178c", "rqb1126017_8dc7_11e9_b991_802bf9e8178c", "rqb1126017_8dc7_11e9_b991_802bf9e8178"]
    }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "rq87761062_8ea0_11e9_b992_802bf9e8178c": "not_processing",
        "rq87761063_8ea0_11e9_b992_802bf9e8178c": "canceled",
        "rq87761064_8ea0_11e9_b992_802bf9e8178c": "processed",
        "rqb1126017_8dc7_11e9_b991_802bf9e8178": "not_found",
        "rqb1126017_8dc7_11e9_b991_802bf9e8178c": "processing"
    }
}

"method": "request.status"

В query передается массив строк - id заявок в 1С, по которым необходимо получить статус. В ответе передается словарь из id заявок (ключ) и статусов заявок (значение) или not_found, если заявка не найдена.

Возможные статусы заявок: processing - заявка обрабатывается (в Личном кабинете Смартвэй был осуществлен поиск по запросу в заявке, выбран вариант проезда/проживания и добавлен в корзину, то есть сформирована поездка) not_processing - заявка не обрабатывается (вариант проезда/проживания не выбран и/или не добавлен в корзину, то есть поездка не сформирована) processed - поездка оформлена canceled - заявка отменена

Поездки

Поездка — одна или несколько услуг, оплаченные единовременно.

Информация о поездке

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "trip.info",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": 7949
  }
}

Ответ

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "amount": 24963,
    "book_date": "2017-05-08T20:15:18.95",
    "id": 7949,
    "items": [
      {
        "amount": 4449,
        "checkin": "2017-05-14T17:00:00",
        "checkout": "2017-05-14T18:35:00",
        "id": 13026,
        "service_type": "Air"
      },
      {
        "amount": 4452,
        "checkin": "2017-05-14T17:00:00",
        "checkout": "2017-05-14T18:35:00",
        "id": 13027,
        "service_type": "Air"
      },
      {
        "amount": 4452,
        "checkin": "2017-05-16T00:40:00",
        "checkout": "2017-05-16T02:10:00",
        "id": 13028,
        "service_type": "Air"
      },
      {
        "amount": 4450,
        "checkin": "2017-05-16T00:40:00",
        "checkout": "2017-05-16T02:10:00",
        "id": 13029,
        "service_type": "Air"
      },
      {
        "amount": 7160,
        "checkin": "2017-05-14T00:00:00",
        "checkout": "2017-05-16T00:00:00",
        "id": 13030,
        "service_type": "Hotel"
      }
    ],
    "name": "Москва",
    "status": "AwaitingConfirmation"
  }
}

"method": "trip.info"

В query передается идентификатор поездки в Smartway

Структура ответа

Параметр Тип Обязательный Описание
amount decimal Да Стоимость поездки в рублях
book_date date Да Дата бронирования в формате ISO (YYYY-MM-DDTHH:mm:ss)
id int Да Идентификатор поездки
items array of objects Да Массив приобретенных услуг. См. структуру item
name string Да Название поездки
status enum Да Статус поездки. Возможные значения:
  • Booked - оформлена
  • Cancelled - отменена
  • Completed - завершена

item

Параметр Тип Обязательный Описание
amount decimal Да Стоимость в рублях
checkin date Да Дата отправления поезда/самолета/трансфера или дата заселения в отель в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout date Да Дата прибытия поезда/самолета/трансфера или дата выезда из отеля в формате ISO (YYYY-MM-DDTHH:mm:ss)
id int Да Идентификатор приобретенной услуги
service_type enum Да Тип услуги. Возможные значения:
  • Air - авиабилет
  • Hotel - отель
  • Train - ж/д билет
  • Transfer - трансфер

Просмотр истории состояний (версий) приобретенных услуг

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "trip.versions",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
      "inn_companies": [],
      "document_numbers": [
        "2058437587"
      ],
      "start_date": "2018-01-01",
      "end_date": "",
      "start_id": ""
    }
  }
}

Ответ

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "checkin_date": "2018-07-18T00:00:00",
      "checkout_date": "2018-07-20T00:00:00",
      "company": {
        "inn": "1111111111",
        "name": "Общество с ограниченностью ответственностью \"Бета\""
      },
      "event_date": "2018-05-31T11:48:49",
      "info": {
        "city": "Ростов-на-Дону",
        "hotel_name": "ДОН ПЛАЗА КОНГРЕСС ОТЕЛЬ",
        "room_category": "Стандартный одноместный номер",
        "stars": 4
      },
      "item_id": 186583,
      "number": "123321",
      "service_type": "Hotel",
      "status": "Created",
      "transaction_details": [
        {
          "amount": 7413,
          "type": "Booking"
        }
      ],
      "travel_time": null,
      "travellers": [
        {
          "birthday": "1991-01-10T00:00:00",
          "documents": [
            {
              "number": "2058437587",
              "type": "DomesticPassport"
            }
          ],
          "email": "demo_sw@smartway.today",
          "external_id": null,
          "name": "Олег",
          "patronymic": "Евгеньевич",
          "phone": "+73568743674",
          "sex": "Man",
          "surname": "Семенов"
        }
      ],
      "version_id": 196711
    }
  ]
}

"method": "trip.versions"

Версия — состояние, возникающее при покупке, изменении или отмене услуг.

Если услуга в поездке была куплена и никогда не изменялась, у нее будет одна версия. Если услуга была куплена, а затем, например, отменена, первая версия будет содержать состояние после покупки, а вторая версия — состояние после отмены, и будет включать информацию о возникших штрафах.

Структура запроса

Параметр Тип Обязательный Описание
inn_companies array of strings нет Массив ИНН компаний. Если передан пустой массив, возвращается информация по всем компаниям в аккаунте
document_numbers array of strings нет Массив номеров документов. Если передан пустой массив, возвращается информация по поездкам всех сотрудников
start_date string нет Отфильтровать выдачу версиями не раньше указанной даты. Формат YYYY-MM-DD
end_date string нет Отфильтровать выдачу версиями не позже указанной даты. Формат YYYY-MM-DD
start_id int нет Идентификатор версии, начиная с которой необходимо получить историю. По умолчанию возвращаются все версии

Структура ответа

Массив версий поездок. См. структуру version

version

Параметр Тип Обязательный Описание
item_id int да Идентификатор приобретенной услуги
version_id int да Идентификатор версии заказа
service_type enum да Тип услуги. Возможные значения:
  • Air — авиабилет
  • Hotel — отель
  • Train — ж/д билет
  • Transfer — трансфер
status enum да Статус услуги. Возможные значения:
  • Created — куплена
  • Changed — изменена
  • Cancelled — отменена
transaction_details array of objects да Массив деталей транзакций. См. структуру transaction_detail
event_date date да Дата создания версии в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkin_date date да Дата отправления поезда/самолета/трансфера или дата заселения в отель в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout_date date да Дата прибытия поезда/самолета/трансфера или дата выезда из отеля в формате ISO (YYYY-MM-DDTHH:mm:ss)
travel_time int нет Длительность поездки в минутах
number string да Номер билета или номер ваучера трансфера/гостиницы
info object да Дополнительная информация в зависимости от типа заказа. См. структуру info
travellers array of objects да Массив сотрудников. См. структуру traveller
company object да Информация о юридическом лице, от которого оформлена поездка. См. структуру company

transaction_detail

Параметр Тип Обязательный Описание
type enum да Тип транзакции. Возможные значения:
  • Booking — покупка
  • Penalty — штраф
  • Surcharge — доплата
  • Return — возврат
amount decimal да Стоимость
vats array of objects да НДС

info для service_type = Air

Параметр Тип Обязательный Описание
travel_time enum да Длительность маршрута в минутах
segments array object да Сегменты маршрута. См. структуру segment

segment

Параметр Тип Обязательный Описание
place_depart object да Аэропорт отправления. См. структуру place
date_depart date да Время отправления в формате YYYY-MM-DDTHH:mm:ss
place_arrive object да Аэропорт прибытия. См. структуру place
date_arrive date да Время прибытия в формате YYYY-MM-DDTHH:mm:ss

info для service_type = Hotel

Параметр Тип Обязательный Описание
hotel_name string да Название отеля
stars int да Звездность отеля
city string да Город
room_category string да Категория номера

info для service_type = Train

Параметр Тип Обязательный Описание
station_depart string да Станция отправления
station_arrive string да Станция прибытия

info для service_type = Transfer

Параметр Тип Обязательный Описание
place_depart object да Станция отправления
place_arrive object да Станция прибытия
car_class enum да Класс автомобиля. Возможные значения:
  • Undefined — не определен
  • Standart — стандарт
  • Comfort — комфорт
  • Business — бизнес
  • BusinessComfort — бизнес комфорт
  • Minivan — минивэн
  • Minibus — микроавтобус
  • Executive — представительский

place

Параметр Тип Обязательный Описание
country string да Страна
city string да Город
place string да Название или адрес объекта

traveller

Параметр Тип Обязательный Описание
name string да Имя
patronymic string да Отчество
surname string да Фамилия
documents array да Документы сотрудника. См. структуру document
external_id string нет Идентификатор сотрудника во внешней системе

document

Параметр Тип Обязательный Описание
type enum да Тип документа. Возможные значения:
  • DomesticPassport — домашний паспорт (паспорт гражданина РФ или паспорт иностранного гражданина)
  • ForeignPassport — заграничный паспорт гражданина РФ
number string да Номер документа

company

Параметр Тип Обязательный Описание
name string да Название компании
inn string да ИНН

vats

Параметр Тип Обязательный Описание
vat_rate enum да Тип документа. Возможные значения:
  • 10%
  • 18%
  • 20%
  • 0%
  • Без НДС
vat_amount decimal нет Сумма НДС

Получение поездок за указанный период

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "trip.get_by_range",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query": {
                "start_date": "2019-06-01",
                "end_date": "2019-06-15"
            }
    }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "last_version_id": 263427,
        "trips": [
            {
                "amount": 7038,
                "book_date": "2019-06-13T13:43:59.063",
                "checkin_date": "2019-06-17T14:40:00",
                "checkout_date": "2019-06-19T16:50:00",
                "id": 189703,
                "items": [
                    {
                        "amount": 7038,
                        "book_date": "2019-06-13T13:43:59",
                        "checkin_date": "2019-06-17T14:40:00",
                        "checkout_date": "2019-06-19T16:50:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246215,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-17T16:15:00",
                                        "date_depart": "2019-06-17T14:40:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            },
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-19T16:50:00",
                                        "date_depart": "2019-06-19T15:20:00",
                                        "place_arrive": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        },
                                        "place_depart": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        }
                                    }
                                ],
                                "travel_time": 90
                            }
                        ],
                        "last_change_date": "2019-06-13T13:43:59",
                        "number": "421-2888857716",
                        "project": "",
                        "request_id": "rqb1126017_8dc7_11e9_b991_802bf9e8178c",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 185,
                        "travellers": [
                            {
                                "birthday": "1990-04-15T00:00:00",
                                "documents": [
                                    {
                                        "number": "1134111133",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "gordina@smartway.today",
                                "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                "name": "Елена",
                                "patronymic": "Владимировна",
                                "phone": "+79256666666",
                                "sex": "Woman",
                                "surname": "Гордина"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 639.82,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-06-17T14:40:00",
                                "checkout_date": "2019-06-19T16:50:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-06-13T13:43:59",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-17T16:15:00",
                                                "date_depart": "2019-06-17T14:40:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    },
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-19T16:50:00",
                                                "date_depart": "2019-06-19T15:20:00",
                                                "place_arrive": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                },
                                                "place_depart": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                }
                                            }
                                        ],
                                        "travel_time": 90
                                    }
                                ],
                                "item_id": 246215,
                                "number": "421-2888857716",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 7038,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 617.09,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 185,
                                "travellers": [
                                    {
                                        "birthday": "1990-04-15T00:00:00",
                                        "documents": [
                                            {
                                                "number": "1134111133",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "gordina@smartway.today",
                                        "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                        "name": "Елена",
                                        "patronymic": "Владимировна",
                                        "phone": "+79256666666",
                                        "sex": "Woman",
                                        "surname": "Гордина"
                                    }
                                ],
                                "trip_id": 189703,
                                "version_id": 263426
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-06-13T13:43:59",
                "name": "Санкт-Петербург",
                "status": "AwaitingConfirmation"
            },
            {
                "amount": 7513,
                "book_date": "2019-06-14T17:11:28.687",
                "checkin_date": "2019-06-14T19:25:00",
                "checkout_date": "2019-06-15T01:25:00",
                "id": 189704,
                "items": [
                    {
                        "amount": 7513,
                        "book_date": "2019-06-14T17:11:28",
                        "checkin_date": "2019-06-14T19:25:00",
                        "checkout_date": "2019-06-15T01:25:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246216,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-14T21:00:00",
                                        "date_depart": "2019-06-14T19:25:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            },
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-15T01:25:00",
                                        "date_depart": "2019-06-14T23:55:00",
                                        "place_arrive": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        },
                                        "place_depart": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        }
                                    }
                                ],
                                "travel_time": 90
                            }
                        ],
                        "last_change_date": "2019-06-14T17:11:28",
                        "number": "421-2888857748",
                        "project": "",
                        "request_id": "",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 185,
                        "travellers": [
                            {
                                "birthday": "1978-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "1234111109",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "grab@mail.ru",
                                "external_id": "333da0bd-7bff-11e2-9362-001b11b25590",
                                "name": "Светлана",
                                "patronymic": "Марковна",
                                "phone": "+79165555555",
                                "sex": "Woman",
                                "surname": "Габровская"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 683,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-06-14T19:25:00",
                                "checkout_date": "2019-06-15T01:25:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-06-14T17:11:28",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-14T21:00:00",
                                                "date_depart": "2019-06-14T19:25:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    },
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-15T01:25:00",
                                                "date_depart": "2019-06-14T23:55:00",
                                                "place_arrive": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                },
                                                "place_depart": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                }
                                            }
                                        ],
                                        "travel_time": 90
                                    }
                                ],
                                "item_id": 246216,
                                "number": "421-2888857748",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 7513,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 660.27,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 185,
                                "travellers": [
                                    {
                                        "birthday": "1978-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "1234111109",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "grab@mail.ru",
                                        "external_id": "333da0bd-7bff-11e2-9362-001b11b25590",
                                        "name": "Светлана",
                                        "patronymic": "Марковна",
                                        "phone": "+79165555555",
                                        "sex": "Woman",
                                        "surname": "Габровская"
                                    }
                                ],
                                "trip_id": 189704,
                                "version_id": 263427
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-06-14T17:11:28",
                "name": "Санкт-Петербург",
                "status": "Completed"
            }
        ]
    }
}

"method": "trip.get_by_range"

Метод возвращает все поездки в указанном диапазоне дат

Структура запроса

Параметр Тип Обязательный Описание
start_date string да Начальная дата в формате YYYY-MM-DD
end_date string да Конечная дата в формате YYYY-MM-DD

Структура ответа

Параметр Тип Обязательный Описание
last_version_id int да Идентификатор самой поздней версии поездки в выбранном диапазоне
trips array of objects да Список поездок за выбранный период. См. структуру trip

trip

Параметр Тип Обязательный Описание
id int да Идентификатор поездки
status enum да Статус поездки. Возможные значения:
  • Booked — оформлена
  • Cancelled — отменена
  • AwaitingConfirmation — ожидает ручного подтверждения travel помощником
  • Completed — завершена
book_date datetime да Дата создания поездки в формате ISO (YYYY-MM-DDTHH:mm:ss)
last_change_date datetime да Дата последнего изменения поездки в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkin_date datetime да Дата начала поездки в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout_date datetime да Дата окончания поездки в формате ISO (YYYY-MM-DDTHH:mm:ss)
name string да Название поездки
amount decimal да Стоимость
items array of objects да Список приобретенных в рамках поездки услуг. См. структуру item

item

Параметр Тип Обязательный Описание
id int да Идентификатор приобретенной услуги
request_id string нет Идентификатор заявки из 1С
service_type enum да Тип услуги. Возможные значения:
  • Air — авиабилет
  • Hotel — отель
  • Train — ж/д билет
  • Transfer — трансфер
status enum да Статус услуги. Возможные значения:
  • Created — куплена
  • Changed — изменена
  • Cancelled — отменена
book_date date да Дата покупки в формате ISO (YYYY-MM-DDTHH:mm:ss)
last_change_date date да Дата последнего изменения в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkin_date date да Дата отправления поезда/самолета/трансфера или дата заселения в отель в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout_date date да Дата прибытия поезда/самолета/трансфера или дата выезда из отеля в формате ISO (YYYY-MM-DDTHH:mm:ss)
travel_time int нет Длительность поездки в минутах
number string да Номер билета или номер ваучера трансфера/гостиницы
info object да Дополнительная информация в зависимости от типа заказа. См. структуру info в методе trip.versions
company object да Информация о юридическом лице, от которого оформлена поездка. См. структуру company
project string да Номер билета или номер ваучера трансфера/гостиницы
travellers array of objects да Массив сотрудников. См. структуру traveller
amount decimal да Общая стоимость поездки
vats array of objects да НДС
versions array of objects да История состояний (версии) поездки. См. структуру version в методе trip.versions

company

Параметр Тип Обязательный Описание
name string да Название компании
inn string да ИНН

traveller

Параметр Тип Обязательный Описание
name string да Имя
patronymic string да Отчество
surname string да Фамилия
external_id string нет Идентификатор сотрудника во внешней системе
phone string да Телефон
email string да e-mail
birthday datetime да Дата рождения в формате ISO (YYYY-MM-DDTHH:mm:ss)
sex string да Пол. Возможные значения:
  • Man — мужской
  • Woman — женский
documents array да Документы сотрудника. См. структуру document

document

Параметр Тип Обязательный Описание
type enum да Тип документа. Возможные значения:
  • DomesticPassport — домашний паспорт (паспорт гражданина РФ или паспорт иностранного гражданина)
  • ForeignPassport — заграничный паспорт гражданина РФ
number string да Номер документа

vats

Параметр Тип Обязательный Описание
vat_rate enum да Тип документа. Возможные значения:
  • 10%
  • 18%
  • 20%
  • 0%
  • Без НДС
vat_amount decimal нет Сумма НДС

Получение поездок после указанной

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "trip.get_after_change",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": 0
  }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "last_version_id": 263427,
        "trips": [
            {
                "amount": 2916.6,
                "book_date": "2019-05-13T19:45:26.067",
                "checkin_date": "2019-05-14T00:20:00",
                "checkout_date": "2019-05-14T08:59:00",
                "id": 189686,
                "items": [
                    {
                        "amount": 2916.6,
                        "book_date": "2019-05-13T19:45:26",
                        "checkin_date": "2019-05-14T00:20:00",
                        "checkout_date": "2019-05-14T08:59:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246194,
                        "info": {
                            "station_arrive": "Санкт-Петербург-Главн. (московский Вокзал)",
                            "station_depart": "Москва Октябрьская (ленинградский Вокзал)"
                        },
                        "last_change_date": "2019-05-13T19:45:26",
                        "number": "70000416557990",
                        "project": "",
                        "request_id": "",
                        "service_type": "Train",
                        "status": "Created",
                        "travel_time": 519,
                        "travellers": [
                            {
                                "birthday": "1960-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "4500000000",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "example@smartway.today",
                                "external_id": null,
                                "name": "Геннадий",
                                "patronymic": "Сергеевич",
                                "phone": "+79165555555",
                                "sex": "Man",
                                "surname": "Абрамов"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 0,
                                "vat_rate": "0%"
                            },
                            {
                                "vat_amount": 0,
                                "vat_rate": "0%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-05-14T00:20:00",
                                "checkout_date": "2019-05-14T08:59:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-05-13T19:45:26",
                                "info": {
                                    "station_arrive": "Санкт-Петербург-Главн. (московский Вокзал)",
                                    "station_depart": "Москва Октябрьская (ленинградский Вокзал)"
                                },
                                "item_id": 246194,
                                "number": "70000416557990",
                                "service_type": "Train",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 2916.6,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 0,
                                                "vat_rate": "0%"
                                            },
                                            {
                                                "vat_amount": 0,
                                                "vat_rate": "0%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 519,
                                "travellers": [
                                    {
                                        "birthday": "1960-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "4500000000",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "example@smartway.today",
                                        "external_id": null,
                                        "name": "Геннадий",
                                        "patronymic": "Сергеевич",
                                        "phone": "+79165555555",
                                        "sex": "Man",
                                        "surname": "Абрамов"
                                    }
                                ],
                                "trip_id": 189686,
                                "version_id": 263393
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-05-13T19:45:26",
                "name": "Санкт-петербург",
                "status": "Completed"
            },
            {
                "amount": 3319,
                "book_date": "2019-05-14T12:45:01.44",
                "checkin_date": "2019-05-14T14:40:00",
                "checkout_date": "2019-05-14T16:15:00",
                "id": 189687,
                "items": [
                    {
                        "amount": 3319,
                        "book_date": "2019-05-14T12:45:01",
                        "checkin_date": "2019-05-14T14:40:00",
                        "checkout_date": "2019-05-14T16:15:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246195,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-05-14T16:15:00",
                                        "date_depart": "2019-05-14T14:40:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            }
                        ],
                        "last_change_date": "2019-05-14T12:45:01",
                        "number": "421-2888854844",
                        "project": "",
                        "request_id": "",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 95,
                        "travellers": [
                            {
                                "birthday": "1960-01-01T00:00:00",
                                "documents": [
                                    {
                                        "number": "4500000000",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "example@smartway.today",
                                "external_id": null,
                                "name": "Геннадий",
                                "patronymic": "Сергеевич",
                                "phone": "+79165555555",
                                "sex": "Man",
                                "surname": "Абрамов"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 279,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-05-14T14:40:00",
                                "checkout_date": "2019-05-14T16:15:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-05-14T12:45:01",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-05-14T16:15:00",
                                                "date_depart": "2019-05-14T14:40:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    }
                                ],
                                "item_id": 246195,
                                "number": "421-2888854844",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 3319,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 279,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 95,
                                "travellers": [
                                    {
                                        "birthday": "1960-01-01T00:00:00",
                                        "documents": [
                                            {
                                                "number": "4500000000",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "example@smartway.today",
                                        "external_id": null,
                                        "name": "Геннадий",
                                        "patronymic": "Сергеевич",
                                        "phone": "+79165555555",
                                        "sex": "Man",
                                        "surname": "Абрамов"
                                    }
                                ],
                                "trip_id": 189687,
                                "version_id": 263394
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-05-14T12:45:01",
                "name": "Санкт-Петербург",
                "status": "AwaitingConfirmation"
            },

"method": "trip.get_after_change"

Метод возвращает все поездки, созданные или измененные после даты, указанной в запросе версии поездки, номер которой передан в query.

В ответе на запрос trip.get_after_change, trip.get_by_range и trip.get_by_requestсодержится поле last_version_id, которое можно использовать при следующем запросе в случае, если все поездки были обработаны и необходимо получить только обновления с момента последнего запроса.

Для получения всех поездок используйте значение 0.

Структура ответа аналогична методу trip.get_by_range

Получение забронированной поездки по заявке

Запрос

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "trip.get_by_request",
    "params":
        {
            "authorization": {"username": "example@smartway.today", "password": "example"},
            "query": "rqb1126017_8dc7_11e9_b991_802bf9e8178c"
    }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": {
        "last_version_id": 263426,
        "trips": [
            {
                "amount": 7038,
                "book_date": "2019-06-13T13:43:59.063",
                "checkin_date": "2019-06-17T14:40:00",
                "checkout_date": "2019-06-19T16:50:00",
                "id": 189703,
                "items": [
                    {
                        "amount": 7038,
                        "book_date": "2019-06-13T13:43:59",
                        "checkin_date": "2019-06-17T14:40:00",
                        "checkout_date": "2019-06-19T16:50:00",
                        "company": {
                            "inn": "7799555550",
                            "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                        },
                        "id": 246215,
                        "info": [
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-17T16:15:00",
                                        "date_depart": "2019-06-17T14:40:00",
                                        "place_arrive": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        },
                                        "place_depart": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        }
                                    }
                                ],
                                "travel_time": 95
                            },
                            {
                                "segments": [
                                    {
                                        "date_arrive": "2019-06-19T16:50:00",
                                        "date_depart": "2019-06-19T15:20:00",
                                        "place_arrive": {
                                            "city": "Москва",
                                            "country": "Россия",
                                            "place": "Домодедово"
                                        },
                                        "place_depart": {
                                            "city": "Санкт-Петербург",
                                            "country": "Россия",
                                            "place": "Пулково. Санкт-Петербург"
                                        }
                                    }
                                ],
                                "travel_time": 90
                            }
                        ],
                        "last_change_date": "2019-06-13T13:43:59",
                        "number": "421-2888857716",
                        "project": "",
                        "request_id": "rqb1126017_8dc7_11e9_b991_802bf9e8178c",
                        "service_type": "Air",
                        "status": "Created",
                        "travel_time": 185,
                        "travellers": [
                            {
                                "birthday": "1990-04-15T00:00:00",
                                "documents": [
                                    {
                                        "number": "1134111133",
                                        "type": "DomesticPassport"
                                    }
                                ],
                                "email": "gordina@smartway.today",
                                "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                "name": "Елена",
                                "patronymic": "Владимировна",
                                "phone": "+79256666666",
                                "sex": "Woman",
                                "surname": "Гордина"
                            }
                        ],
                        "vats": [
                            {
                                "vat_amount": 617.09,
                                "vat_rate": "10%"
                            }
                        ],
                        "versions": [
                            {
                                "checkin_date": "2019-06-17T14:40:00",
                                "checkout_date": "2019-06-19T16:50:00",
                                "company": {
                                    "id": 7133,
                                    "inn": "7799555550",
                                    "name": "Общество с ограниченной ответственностью \"Конфетпром\""
                                },
                                "event_date": "2019-06-13T13:43:59",
                                "info": [
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-17T16:15:00",
                                                "date_depart": "2019-06-17T14:40:00",
                                                "place_arrive": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                },
                                                "place_depart": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                }
                                            }
                                        ],
                                        "travel_time": 95
                                    },
                                    {
                                        "segments": [
                                            {
                                                "date_arrive": "2019-06-19T16:50:00",
                                                "date_depart": "2019-06-19T15:20:00",
                                                "place_arrive": {
                                                    "city": "Москва",
                                                    "country": "Россия",
                                                    "place": "Домодедово"
                                                },
                                                "place_depart": {
                                                    "city": "Санкт-Петербург",
                                                    "country": "Россия",
                                                    "place": "Пулково. Санкт-Петербург"
                                                }
                                            }
                                        ],
                                        "travel_time": 90
                                    }
                                ],
                                "item_id": 246215,
                                "number": "421-2888857716",
                                "service_type": "Air",
                                "status": "Created",
                                "transaction_details": [
                                    {
                                        "amount": 7038,
                                        "type": "Booking",
                                        "vats": [
                                            {
                                                "vat_amount": 617.09,
                                                "vat_rate": "10%"
                                            }
                                        ]
                                    }
                                ],
                                "travel_time": 185,
                                "travellers": [
                                    {
                                        "birthday": "1990-04-15T00:00:00",
                                        "documents": [
                                            {
                                                "number": "1134111133",
                                                "type": "DomesticPassport"
                                            }
                                        ],
                                        "email": "gordina@smartway.today",
                                        "external_id": "bcbb0cbc-2d55-11e6-9b29-5404a6b49dba",
                                        "name": "Елена",
                                        "patronymic": "Владимировна",
                                        "phone": "+79256666666",
                                        "sex": "Woman",
                                        "surname": "Гордина"
                                    }
                                ],
                                "trip_id": 189703,
                                "version_id": 263426
                            }
                        ]
                    }
                ],
                "last_change_date": "2019-06-13T13:43:59",
                "name": "Санкт-Петербург",
                "status": "AwaitingConfirmation"
            }
        ]
    }
}

"method": "trip.get_by_request"

В query передается строка - id заявки в 1С, по которой необходимо получить данные о поездке. Структура ответа аналогична методу trip.get_by_range

Получение ваучера услуги в формате PDF

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "trip.item_voucher",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": 1234
  }
}

Ответ (содержимое content сокращено)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "JVBERi0xLjQKJdP0zO.........AAAAAAAA="
  }
}

"method": "trip.item_voucher" — получение ваучера по идентификатору услуги

"method": "trip.version_voucher" — получение ваучера по идентификатору версии

В query передается идентификатор услуги или идентификатор версии, полученный в ответе на запрос trip.info, trip.versions, trip.get_by_range или trip.get_after_change

Структура ответа

Строка content содержит ваучер в формате PDF, закодированный в base64

Закрывающие документы

Получение закрывающих документов за период

{
    "jsonrpc": "2.0",
    "id": "777",
    "method": "packages.get",
    "params": {
        "authorization": {
            "username": "example@smartway.today",
            "password": "example"
        },
        "query": {
            "inn": "7799555550",
            "start_date": "2019-06-01",
            "end_date": ""
        }
    }
}

Ответ

{
    "id": "777",
    "jsonrpc": "2.0",
    "result": [
        {
            "date": "2019-06-13T23:59:59",
            "documents": [
                {
                    "items": [
                        {
                            "amount": 7038,
                            "count": 1,
                            "measurement": "pc",
                            "name": "А/б Москва-Санкт-Петербург-Москва #421-2888857716, Гордина Е. В., 17.06-19.06.2019",
                            "price": 7038,
                            "vat": 617.09
                        }
                    ],
                    "type": "act"
                },
                {
                    "items": [
                        {
                            "amount": 7038,
                            "carrier": "S7",
                            "checkin_date": "2019-06-17T14:40:00",
                            "checkout_date": "2019-06-19T16:50:00",
                            "event_date": "2019-06-13T13:43:59.05",
                            "operation": {
                                "Booking": "Air"
                            },
                            "route": "Москва-Санкт-Петербург-Москва",
                            "ticket_numbers": [
                                "421-2888857716"
                            ],
                            "traveller": "Гордина Елена",
                            "vat": 617.09
                        }
                    ],
                    "type": "registry"
                }
            ],
            "number": "7133/8"
        },
        {
            "date": "2019-06-14T23:59:59",
            "documents": [
                {
                    "items": [
                        {
                            "amount": 7513,
                            "count": 1,
                            "measurement": "pc",
                            "name": "А/б Москва-Санкт-Петербург-Москва #421-2888857748, Габровская С. М., 14.06-15.06.2019",
                            "price": 7513,
                            "vat": 660.27
                        }
                    ],
                    "type": "act"
                },
                {
                    "items": [
                        {
                            "amount": 7513,
                            "carrier": "S7",
                            "checkin_date": "2019-06-14T19:25:00",
                            "checkout_date": "2019-06-15T01:25:00",
                            "event_date": "2019-06-14T17:11:28.687",
                            "operation": {
                                "Booking": "Air"
                            },
                            "route": "Москва-Санкт-Петербург-Москва",
                            "ticket_numbers": [
                                "421-2888857748"
                            ],
                            "traveller": "Габровская Светлана",
                            "vat": 660.27
                        }
                    ],
                    "type": "registry"
                }
            ],
            "number": "7133/9"
        }
    ]
}

"method": "packages.get"

Структура запроса

Параметр Тип Обязательный Описание
inn string да ИНН компании
start_date string нет Начальная дата в формате YYYY-MM-DD. Если дата не указана, возвращаются пакеты документов, начиная с самого раннего.
end_date string нет Конечная дата в формате YYYY-MM-DD. Если дата не указана, возвращаются пакеты документов, заканчивая самым поздним.

Структура ответа

Массив пакетов документов. См. структуру package

package

Параметр Тип Обязательный Описание
number string да Номер пакета документов
date string да Дата создания пакета документов в формате ISO (YYYY-MM-DDTHH:mm:ss)
documents array of objects да Массив документов в пакете. См. структуру document

document

Параметр Тип Обязательный Описание
type string да Тип документа. Возможные значения:
  • act — акт
  • registry — реестр
  • invoice — счет-фактура
items array of objects да Массив документов в пакете. См. структуру item (набор полей зависит от типа документа)

item для type = act

Параметр Тип Обязательный Описание
name string да Наименование услуги
count int да Количество
measurement enum да Единица измерения. Возможные значения:
  • service — услуга
  • pc — шт
price decimal да Цена за единицу
amount decimal да Сумма
vat decimal да В том числе НДС

item для type = registry

Параметр Тип Обязательный Описание
amount decimal да Сумма
carrier string да Наименование перевозчика
checkin_date string да Дата отправления в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout_date string да Дата прибытия в формате ISO (YYYY-MM-DDTHH:mm:ss)
event_date string да Дата выписки билета в формате YYYY-MM-DDTHH:mm:ss.ZZZ
operation dictionary <operation, service> да Тип операции и тип услуги. Возможные значения operation:
  • Booking — покупка
  • Penalty — штраф
  • Surcharge — доплата
  • Return — возврат
Возможные значения service:
  • Air — авиабилет
  • Train — ж/д билет
ticket_numbers array of strings да Массив с номерами билетов
route string да Маршрут
traveller string да Пассажир
vat decimal да В том числе НДС

item для type = invoice

Параметр Тип Обязательный Описание
event_date string да Дата выписки билета в формате YYYY-MM-DDTHH:mm:ss.ZZZ
operation dictionary <operation, service> да Тип операции и тип услуги. Возможные значения operation:
  • Booking — покупка
  • Penalty — штраф
  • Surcharge — доплата
  • Return — возврат
Возможные значения service:
  • Air — авиабилет
  • Train — ж/д билет
ticket_numbers array of strings да Массив с номерами билетов
carrier string да Перевозчик
route string да Маршрут
traveller string да Пассажир
checkin_date string да Дата отправления в формате ISO (YYYY-MM-DDTHH:mm:ss)
checkout_date string да Дата прибытия в формате ISO (YYYY-MM-DDTHH:mm:ss)
amount decimal да Стоимость
vat decimal да В том числе НДС

Travel политики

Получение списка travel политик для аккаунта

Запрос

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "travel_policy.list",
  "params": {
    "authorization": {
      "username": "example@smartway.today",
      "password": "example"
    },
    "query": {}
    }
}

Ответ

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "Description": "для топ менеджеров",
      "Id": "5d4c002af915aa000701e436",
      "Name": "ТОП"
    }
  ]
}

"method": "travel_policy.list"

Запрос позволяет получить массив travel политик для аккаунта, с которого отправляется запрос. Необходим особенно для получения id travel политки для передачи в запросе методом travel_policy.apply.

Структура ответа:

Параметр Тип Обязательный Описание
Description string нет Описание travel политки (текст в поле Описание, заполняющийся при создании travel политики)
Id string да id travel политики в базе Smartway (используется в методе `travel_policy.apply`)
Name string да Наименование travel политики

Присвоение travel политики

Запрос

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "travel_policy.apply",
  "params": {
    "authorization": {
      "username": "example@smartway.today",
      "password": "example"
    },
    "query": {
      "employee_id": 159305,
      "travel_policy_id": "5d4c002af915aa000701e436"
    }
  }
}

Ответ при успешном присвоении travel политики

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "error": null,
    "success": true
  }
}

Ошибка при некорректном id сотрудника

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "error": "Employee with id = 159",
    "success": false
  }
}

"method": "travel_policy.apply"

Метод присваивает определенному сотруднику определенную travel политику. В query передается id сотрудника (в системе Смартвэй) и id travel политики (его можно получить методом travel_policy.list)

Структура запроса:

Параметр Тип Обязательный Описание
employee_id int да id сотрудника в системе Смартвэй
travel_policy_id string да id travel политики в базе Smartway (можно получить методом travel_policy.list)

Автовход

"method": "auth.guid"

Запрос: email активного пользователя сервиса

{
  "jsonrpc": "2.0",
  "id": 777,
  "method": "auth.guid",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": "example@email.address"
  }
}

Ответ: guid, используемый в url

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": {
    "expiration_date": "2019-08-06T15:44:26.409591+00:00",
    "uuid": "84f85401-5a4c-4f7e-9b20-4db51a5122d2"
  }
}

Ответ (в запросе передан email, по которому не найдено активного пользователя данного аккаунта):

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": {
    "error": "employee with email example@smartway.today not found",
    "success": false
  }
}

Метод позволяет получить guid идентификатор для входа в личный кабинет без необходимости ввода логина/пароля.

Описание запроса

В query передается валидный email пользователя сервиса. Email обязательно должен принадлежать активному пользователю того же аккаунта, который используется для авторизации.

Описание ответа

Ответом на запрос является объект, содержащий guid для входа в личный кабинет и его срок действия. С данным guid необходимо открыть:

production - https://smartway.today/auth?guid=valid_guid_from_api test – https://wp.test.dev.smartway.today/auth?guid=valid_guid_from_api

После чего произойдет редирект на главную страницу личного кабинета либо сообщение об ошибке, если guid не будет являться действующим.

При попытке получить guid "чужого" пользователя возвращается ошибка.

Контрольные коды

Механизм контрольных кодов используется для верификации согласования поездки, если согласование проводится на стороне системы клиента. В этом случае механизм согласования на стороне Smartway не используется клиентом.

Алгоритм следующий:

  1. Использование механизма контрольных кодов включается на стороне Smartway по запросу клиента.

  2. Когда согласование поездки прошло на стороне клиента, система клиента присылает в Smartway контрольный код для сотрудников, которым согласовали командировку. Контрольный код генерируется и передается сотрудникам на стороне клиента по алгоритму, определенному клиентом.

  3. Если есть категория сотрудников, которые по процессу не должны согласовывать поездки, и следовательно, вводить контрольный код, для таких сотрудников система клиента один раз присылает суперкод (параметр "auto_verification": true) без текста и срока давности.

  4. После выбора сотрудников в корзине система Smartway проверяет, есть ли для них не просроченные коды (именно для всех, то есть если указан Иванов и Петров, должен быть код, который выдан для них обоих, либо код без указанных id)

  5. Если есть хотя бы один код на сотрудника, и у него еще не истек срок давности, Smartway показывает поле ввода кода, который валидируется по мере ввода. Если код введен корректно, разблокируется кнопка “Оплатить”.

Если нет ни одного кода для выбранных сотрудников, возвращается ошибка : "Отсутствует информация о согласованных командировках для выбранных сотрудников (Иванов Иван Игоревич, Петров Петр Павлович). Пожалуйста, получите контрольный код у авторизующего лица."

В мобильном приложении диалог с вводом контрольного кода или с текстом ошибки появляется после нажатия кнопки Оплатить/Отправить на согласование.

  1. Во время оплаты контрольный код записывается его в информацию о поездке, чтобы впоследствии можно было выгрузить аналитику. Иначе возвращается ошибка "Контрольный код не указан или просрочен. Пожалуйста, обратитесь к авторизующему лицу в вашей компании."

Добавление контрольного кода

Запрос: добавление/изменение контрольного кода

{
  "jsonrpc": "2.0",
  "id": 777,
  "method": "verification_code.add",
  "params": {
    "authorization": {
      "username": "your@email.address",
      "password": "your_password"
    },
    "query": {
  "verification_code": "159305",
  "employees": [
    "e1",
    "e2"
  ],
  "expiration_date": "2020-12-31T15:44:26Z",
  "auto_verification": true
}

  }
}

Ответ: добавленный code и его срок действия

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": {
    "expiration_date": "2020-12-31T15:44:26Z",
    "verification_code": "159305"
  }
}

Ответ (в запросе передан id сотрудника, которого нет в аккаунте):

{
  "id": 777,
  "jsonrpc": "2.0",
  "result": {
    "error": "employee with id=”e2” not found",
    "success": false
  }

"method": "verification_code.add"

Параметр Тип Обязательный Описание
verification_code string да Контрольный код - текст, до 50 символов
employees array of strings да Массив id сотрудников, которым присваивается контрольный код. id из системы клиента (убедитесь, что ранее в Смартвэй были переданы id из системы клиента)
expiration_date datetime да Время и дата, после которого код станет невалидным
auto_verification bool нет Признак суперкода. по умолчанию - значение false. Чтобы код сохранился как суперкод, надо передать этот параметр со значением true

Журнал изменений

Дата Версия Изменения
18 ноября 2019 2.0.12
  • Добавлено описание механизма контрольных кодов
08 августа 2019 2.0.12
  • Добавлен employee_number (табельный номер) в описание метода employees.save
  • Добавлено описание методов travel_policy.list, travel_policy.apply, employees.setRights
5 августа 2019 2.0.12
  • Добавлен пример запроса и ответа для метода request.save
  • Добавлено описание метода employees.list
  • Добавлено описание мтеода auth.guid
20 июня 2019 2.0.12
  • Добавлены 3 примера интеграции клиент-Smartway
  • Исправлено описание метода employees.save, добавлен параметр companies_id, описание алгоритма сопоставления сотрудников - по id и по полям
  • Добавлено описание методов request_status, request_save, request_cancel, trip_get_by_request и примеры
  • Добавлен параметр vats в item и transaction_details, в методы trip_get_by_range, trip_get_by_request, trip_get_after_change, обновлены примеры этих запросов и ответов
  • Обновлен пример запроса и ответа к методу packages_get, добавлено опиание параметра item для type = registry
25 января 2019 2.0.11
  • В модели сотрудника свойство sex теперь не зависит от регистра и принимает значения: man, woman, male, female
  • Если в личном кабинете зарегистрированы 2 и более организации, то при бронировании авиабилетов можно указать ИНН организации от которой выполняется перелет и, соответственно, на которую будет выставлен счет.
  • При сохранении сотрудника(-ов) (employees.save) можно указывать ИНН организации и строкой и массивом. Свойство "companies_inn"
  • Исправлено значение бонуса, указывающего на принадлежность к ж/д билетам: FPC → FPK
29 ноября 2018 2.0.10
  • Добавлен метод employees.save для сохранение массива сотрудников и его описание
  • Добавлен метод trip.get_by_range и его описание
20 июня 2018 2.0.9
  • Добавлен параметр идентификатор начальной версии "start_id" в объект запроса "trip.versions"  и его описание
  • Изменен объект и описание возвращаемого результата метода "trip.versions"
  • Добавлен метод trip.get_after_change и его описание
  • Убран метод trip.voucher и его описание
  • Добавлен метод trip.item_voucher и его описание
  • Добавлен метод trip.version_voucher и его описание
  • Убран метод airline.airports и его описание
  • Добавлен метод airline.airport_autocomplete и его описание
  • Добавлен тип запросов "Поезда"
  • Добавлен метод train.station_autocomplete и его описание
  • Добавлен тип запросов "Отели"
  • Добавлен метод hotel.autocomplete и его описание
10 мая 2018 2.0.8
  • Добавлен метод "trip.versions" и его описание
26 марта 2018 2.0.7
  • Добавлено описание ошибок при бронировании авиаперелета (метод "airline.result")
5 марта 2018 2.0.6
  • Добавлен раздел "Пакеты документов"
  • Добавлен метод "packages.get" и его описание
24 ноября 2017 2.0.5
  • Изменен объект и описание возвращаемого результата метода "airline.result"
30 октября 2017 2.0.4
  • Добавлен тип запросов "Поездка"
  • Добавлен метод "trip.info" и его описание
  • Добавлен метод "trip.voucher" и его описание
13 октября 2017 2.0.3
  • Исправлено название метода поиска авиаперелетов search => airline.search
  • Изменен тип фильтра багажа bool => enum
  • Добален метод "airline.book" и его описание
  • Добавлен метод "airline.result" и его описание
03 октября 2017 2.0.2
  • Добавлено описание свойства тарифа "is_baggage_included"
  • Добавлен параметр багажа "baggage" в объект запроса "airline.search"
14 сентября 2017 2.0.1
  • Добавлен раздел "Авиабилеты"
  • Добавлен метод "airline.airports" и его описание
  • Добавлен метод "airline.search" и его описание