пятница, 11 января 2013 г.

Kassa API draft

Kassa API draft

Помимо привычного веб-интерфейса, существует ещё один, на принципе REST — на определённый адрес отправляются запросы методом POST, возвращаются данные в формате XML. С помощью такого интерфейса можно осуществлять взаимодействие каких-нибудь внешних проложений с модулем «Касса».

В каждом запросе должны присутствовать поля login и password, значение которых — соответственно логин и пароль пользователя, имеющего доступ к кассе. Если пользователя с таким паролем нет или он не имеет доступа к кассе, будет возвращена ошибка 403. Третье поле POST — поле method. В зависимости от его значения вызываются разные методы API.

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

method=getaccounts

Метод возвращает список счетов в кассе. XML имеет следующий формат:

<reply>
 <accounts>
  <account id="123" active="1" default="0">Наличные</account>
  …
 </accounts>
</reply>

У каждого элемента account его значение — это название счёта. Свойства:

  • id внутренний идентификатор;
  • active — активность счёта (неактивные не отображаются в веб-интерфейсе);
  • default — счёт по умолчанию в выпадающем списке. Вовсе не обязательно, что будет один счёт, у которого default=1, их может быть сколько угодно, хоть 0, хоть все.

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

method=getcurrencies

Метод возвращает список валют в кассе. Возвращаемый XML имеет следующий вид:

<reply>
 <currencies>
  <currency id="1" default="0" symbol="$">американский доллар</currency>
  …
 </currencies>
</reply>

У кажого элемента currency его значение — это полное наименование валюты в кассе. Свойства элемента:

  • id — внутренний идентификатор валюты;
  • active — активность валюты (неактивные не отображаются в веб-интерфейсе);
  • symbol — один символ, принятый для обозначения этой валюты.

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

method=getoptypes

Этот метод возвращает список типов операций в кассе. Кроме трёх обычных, этот метод имеет ещё один параметр group. Если он задан и не ноль (а также не false и не пустая строка), то типы операции будут выведены сгруппированные по типам операций. Если параметр group не задан, то типы операций будут выведены плоским списком.

XML списка типов операций без группировки имеет следующий вид:

<reply>
 <optypes>
  <optype id="7" group_id="2" is_income="0">Соседний супермаркет</optype>
  …
 </optypes>
</reply>

У каждого элемента optype значение — название типа операций. Элемент имеет следующие свойства:

  • id — внутренний идентификатор;
  • group_id — внутренний идентификатор группы;
  • is_income — 0 или 1, является или нет данная операция приходной (0 — если операция расходная).

В том случае, если задан параметр group, и он не ноль, то XML имеет следующий вид:

<reply>
 <optypegroups>
  <optypegroup id="1" name="Прибыль">
   <optype id="2" is_income="1">Зарплата</optype>
   …
  </optypegroup>
  …
 </optypegroups>
</reply>

Каждый элемент optypegroup имеет свойства id и name — внутренний идентификатор и название группы типов операций соответственно. Элемент optypegroup имеет внутри несколько вложенных элементов optype — типов операций, рассортированных по группам. Каждый тип операций входит в одну группу. Элементы optype в этом случае идентичны элементам optype списка без группировки, за исключением того, что в случае группировки в них отсутствует за ненадобностью свойство group_id.

Получение списка операций

Получение списка операций осуществляется с помощью передачи в параметре method значения getoperations. Существуют дополнительные переменные, которые можно передавать.

date_start При выборе всех операций за какой-то период, в этой переменной указыватся timestamp начала периода. Если не указано, то по умолчанию считается минут семь суток от текущей секунды
date_end При выборе операций за какой-то период времени, в этой переменной указывается timestamp окончания периода. Если не указано, то считается текущей секундой.
account Внутренний идентификатор счёта, по которому выбрать операции. Если не указано или передан 0, то фильтрации по счёту не ведётся.
currency Внутренний идентификатор валюты, по которой выбрать операции. Если не указано или передан 0, то фильтрации по валюте не ведётся.
optype Внутренний идентификатор типа операции, по которому выбрать операции. Если не указано или передан 0, то фильтрации по типу операции не проводится.
optypegroup Внутренний идентификатор группы типов операций, по которым выбирать операции. Если не задано или передан 0, то фильтрация по группам типов не проводится.

XML списка операций имеет следующий вид:

<reply>
 <operations>
  <operation id=" внутренний идентификатор операции">
   <currency id=" внутренний идентификатор валюты ">название валюты</currency>
   <account id=" внутренний идентификатор счёта ">название счёта</account>
   <comment>комментарий к операции</comment>
   <time timestamp=" таймстемп даты проведения операции ">дата проведения операции</time>
   <amount>сумма операции</amount>
   <optype id=" внутренний идентификатор типа операций ">название типа операции</optype>
  <operation>
 </operations>
</reply>

Пример:

<reply>
 <operations>
  <operation id="3639">
   <currency id="4">белорусский рубль</currency>
   <account id="1">Наличные</account>
   <comment>Нашёл</comment>
   <time timestamp="1357222778">2013-01-03 18:19:38</time>
   <amount>20</amount>
   <optype id="17">Прочее</optype>
  <operation>
 </operations>
</reply>

Добавление операции

Добавление операции осуществляется запросом всё на тот же адрес с параметрами login, password и параметром method, равным «add». Для добавления также необходимо указать тип операции и сумму. Перечень всех параметров в таблице ниже.

Параметр Обязательный? Пояснение
login Да Логин пользователя кассы
password Да Пароль пользователя кассы
method Да, «add» Должен быть равен add
optype Да Идентификатор типа операции
amount Да Сумма операции. Если не указана или равна нулю, то операция не будет добавлена
currency Нет Внутренний идентификатор валюты. Если не указан, для добавления операции берётся первая попавшаяся валюта по умолчанию. Если передан идентификатор несуществующей валюты или не передан идентификатор валюты, а ни одной валюты по умолчанию не задано, то операция не будет добавлена
account Нет Внутренний идентификатор счёта. Если не указан, то для добавления операции берётся первый попавшийся счёт по умолчанию. Если идентификатор не передан и нет ни одного счёта по умолчанию, или передан идентификатор не существующего счёта, то операция добавлена не будет
comment Нет Комментарий к операции

Если операция не добавлена, возвращается ошибка. XML ошибки имеет следующий вид:

<reply>
 <error code=" код ошибки ">текст ошибки</error>
</reply>

Если операция добавилась нормально, то возвращается уведомление о том, что всё в порядке. Оно имеет следующий вид:

<reply>
 <success />
</reply>

Комментариев нет:

Отправка комментария

Ублюдочный Гугл поломал форму комментариев. Извините.