API сервера agenta.pro

API позволяет взаимодействовать терминалам (мобильным клиентам) с сервером по GET- или POST-запросам.

Параметры и доступ к серверу

Адрес API: https://agenta.pro/api

Кодовая страница: UTF8

Пользователь для тестирования (sid): worker

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

Обязательные параметры:

  • method - содержит имя метода API
  • clientversion - версия мобильного клиента ("0.9.2.5")

Опциональные общие параметры:

  • sid - содержит id пользователя, зарегистрированного на сервере
  • clientversion - строка, версия клиента, в формате 9.99.99
  • gmt - смещение часового пояса устройства, в минутах. Например, для Москвы +240 (летнее время)

Например, чтобы вызвать метод connect, нужно указать следующее:

https://agenta.pro/api?method=connect&cid=3333

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

Структура ответов сервера в формате JSON общая для всех методов:

В результате возвращается структура JSON со следующими полями:

  • success: true/false, является флагом успешности выполнения запроса: Истина - все ок, Ложь - возникли ошибки.
  • data: данные с сервера. Содержит структуру полей ответа, либо строку (в зависимости от метода). В данном случае, здесь передаются id (guid) созданной заявки и ее номер (number)
  • error: код ошибки. Содержит строковое id ошибки, в случае неудачного выполненния запроса, например, ‘invalid’ - неверный параметр.
  • errormsg: сообщение (описание ошибки). Содержит текстовое описание ошибки, например “неверный параметр”
  • errors: структура ошибок (ключ:значение). Служит уточнением ошибки, какой параметр заполнен неверно, является структурой в виде “поле”: “значение”
  • time: служебное, время сервера в формате YYYY-MM-DD H:i:s (например, 2012-08-30 17:46:00)
  • worktime: служебное, время работы скрипта на сервере (секуды), например 0.007

Коды основных ошибок сервера

Коды ошибок сервера передаются в поле “error” ответа сервера.

Перечень общих ошибок всех методов:

unknownmethod

Нет такого метода API

invalid

Не верно указаны параметры запроса
licencenotfound Лицензия не найдена

Описание методов API

Метод Описание

register

Регистрация мобильного устройства

Параметры:

  • method - метод сервера, в данном случае “register”,
  • sid - ключ устройства (выданный в СМС)

Возвращает:

Поле data :

  • cid - временный ключ устройства (для метода connect)
  • name - имя пользователя
  • dataserver - адрес сервера данных (для SaaS тот же самый сервер где API)

Пример http-запроса:

https://agenta.pro/api?
    method=register
    &sid=f594f9b9-d531-22e0-b34f1-021e8c8f505d

Ответ сервера:

{
    "success":true,
    "data":{
        "name":"Вова",
        "dataserver":"http://agenta.pro/api"
    }
}

connect

Подключиться к серверу

Параметры:

  • method - метод сервера, в данном случае “connect”,
  • cid - ключ устройства (выданный в методе register)
  • clientversion - версия мобильног клиента
  • lastupdate - число, метка времени предыдущей синхронизации (передайте 0 если это первая синхронизация). Метка это 16-значное целое, в виде строки: UNIX TIMESTAMP сервера, плюс еще 6 знаков микросекунд

Возвращает:

Поле data:

  • lastupdate - метка синхронизации
  • name - имя пользователя
  • dataserver - адрес сервера данных (для SaaS тот же самый сервер где API)
  • departments : [{guid: <guid>,name: <name>}] - структура подразделений

Пример http-запроса:

https://agenta.pro/api?
    method=connect
    &cid=b294f9b8-c729-11e3-991a-001e8c8f500c
    &lastupdate=0

Ответ сервера:

{
    "success":true,
    "data":{
        "name":"Вова",
        "lastupdate":"1398424235536855",
        "dataserver":"http://agenta.pro/api",
        "departments":[{"guid":"a32342-5f3f-4db9-9413-d47354d735a66","name":"Маяковского"},
			{"guid":"a51234d02-a258-4f84-bd2d-f13435371d361","name":"Центр"}]
    }
}
getdata

Получить список клиентов из справочника.

Параметры:

  • method - метод сервера, в данном случае “getdata”,
  • sid - id устройства (guid)
  • lastupdate - число, метка времени предыдущей синхронизации (передайте 0 если это первая синхронизация). Метка это 16-значное целое, в виде строки: UNIX TIMESTAMP сервера, плюс еще 6 знаков микросекунд

Возвращает:

Поле data содержит:

  • data - текст base64encode zip-файла
  • lastupdate - метка синхронизации

Пример http-запроса:

https://agenta.pro/api?
    method=getdata
    &sid=f594f9b9-d531-22e0-b34f1-021e8c8f505d
    &lastupdate=0

Ответ сервера:

{
    "success":true,
    "data":{
        "data":"CADwAXFxTRVJWXEJp...YmZjYi05NGJlZWE0NDRmZjkuZXhi",
        "lastupdate":"1398424235536855"
    }
}

setdocument

Метод, сохраняющий данные документа на сервер. Каждый документ отправляется на сервер отдельным запросом.

Параметры:

  • method - метод сервера, в данном случае “getdata”,
  • sid - id устройства (guid)
  • guid - уникальный id документа, в формате GUID
  • number - порядковый номер документа на устройстве
  • date - дата и время документа
  • senddate - дата и время отправки документа
  • tradepoint - код торговой точки
  • tradepointview - представление торговой точки
  • discountsum - сумма скидки
  • sum - сумма документа
  • kind - вид документа (произвольная строка)
  • properties - структура доп.свойств в формате JSON
  • data - текст base64encode zip-файла

Возвращает:

Поле data содержит:

  • data - текст base64encode zip-файла
  • lastupdate - метка синхронизации

Пример http-запроса:

https://agenta.pro/api?
    method=setdocument
    &sid=f594f9b9-d531-22e0-b34f1-021e8c8f505d
    &number=324
    &date=2014-04-28 19:38:48
    &senddate=2014-04-28 19:44:25
    &guid=2e550896-9547-4a67-bc99-5a196a785889
    &tradepoint=S0496
    &tradepointview=Маяковского 120
    &discountsum=0.00
    &sum=1133.70
    &kind:заказ
    &properties={"Цвет":"Белый"}
    &data=UEsDBBQACAgIAIydnEQAAAAZG...AAQA2AAAASwIAAAAA

Ответ сервера:

{
    "success":true,
    "data":{}
}