Актуальная версия документи в Confluence 4Конверта !!

Обзор

API сервиса www.4konverta.com построено на основе принципов REST. На этой страничке я привел адреса страниц API и какие операции с ними возможны.

В общем, в ответе на POST и GET запросы возвращается документ в формате XML. Данные на сервер передаются в виде параметров в POST-запросах. Для удаления объета используется запрос DELETE.

При необходимости, некоторые символы в XML могут быть заменены на XML-сущности для квотирования (например, <actualExpression>12 пиво &quot;Янтарь&quot;</actualExpression>)

Считается, что все входные данные синтаксически верные. В случае ошибки сервер возвращает код статуса 500, тело ответа при этом неопределенное.

Комментарии и вопрос писать в форуме "4-х конвертов" по адресу http://www.4konverta.com/forum/forums/show/10.page

В описании в фигурных скобках описаны параметры, которые нужно подставлять в адреса. Пример параметров:

История

Текущая ревизия API - 1.2 (в процессе разработки)

- Добавлено управления счетами
- Убраны фактические накопления на цель
- Добавлено распределение остатка
- Управление целями (в процессе)

Версия 1.1

- Добавлена поддержка счетов

Версия 1.0

Авторизация

Для авторизации с каждым запросом нужно передавать два заголовка.

Если авторизация неверна, будет возращен код ошибки 401. После неверных 3-х попыток логина, учетная запись пользователя блокируется. Чтобы её разблокировать, нужно ввести логин/пароль на сайте, указав при этом капчу.

Версионность

Для указания версии используется заголовок 4KVersion. Клиент может опускать этот заголовок, в таком случае будет использована версия 1.0. Формат версии - число с плавающей точкой.

Описание API

1. Общие функции

1.1. Получение информации о пользователе
URL: /data/{user}
Доступные действия: GET
Результат:

<user>
  <country code="gb">Великобритания</country>
  <currency id="gb" code="GBP">фунт</currency> <!-- Основная валюта -->
  <firstDayOfWeek>1</firstDayOfWeek> <!-- 1 - sunday, 2 - monday -->
  <timeZone>Europe/London</timeZone>
  <disableExtendedSyntax>true<disableExtendedSyntax> <!-- Отключить обработку слова "по" в описании тратах -->

  <persons>
    <person id="23443234" name="Петя"/>
    <person>...</person>
  </persons>

  <accounts>
    <account id="441232" name="Наличка" archived="false">
      <currency id="gb" code="GBP">фунт</currency>
      <value>250.0</value>
    </account>
    ...
  </accounts>
</user>

Получение списка доступных валют
URL: /data/{user}/currencies
Доступные действия: GET
Результат:

<currencies>
  <currency id="ru" code="RUB" rate="43.2">фунт</currency>
</user>

1.2. Работа со счетами
URL: /data/{user}/account/{accountId}
Доступные действия: GET,POST,DELETE
Результат:

<account id="441232" name="Наличка" archived="true">
  <currency id="gb" code="GBP">фунт</currency>
  <value>250.0</value>
</account>

Параметры POST:

При создании нового счета нужно передавать в качестве id строку new. При этом вместе с предыдущими доступны такие параметры

Управление переводами между счетами
Каждый перевод между счетами записывается как две операции изменения счетам (AccountChange).
При создании (удалении) одного изменения второе создается (удаляется) автоматически.
Суммы, на которые изменяются счета, не зависит одна от другой (это сделано для поддержки обменных курсов).
URL: /data/{user}/accountChange/{accountChangeId}
Доступные действия: GET,POST,DELETE.
Редактирование переводов не предусмотрено.
Результат:

<accountChange id="3423467" accountId="441232">
  <change>250.0</change> <!-- баланс счета увеличивается на эту величину -->
  <date>2009-05-20</date>
  <comment>Снял наличку с депо</comment>
  
  <matchingAccountChange id="544523" accountId="321233"> <!-- Ссылка на изменения счета-корреспондента -->
    <change>-250.0</change> <!-- баланс счета-корреспондента увеличивается на эту величину -->
  </matchingAccountChange> 
 </account>

Параметры POST:

1.3. Работа с целями
Получение списка категорий целей
URL: /data/{user}/goalCategories/
Доступные действия: GET

<goalCategories>
  <goalCategory id="1" bold="true" order="1">Автомобиль</goalCategory>
</goalCategories>

Получение списка целей
URL: /data/{user}/goals/
Доступные действия: GET

<goals>
  <goal id="2332" name="Лыжи" category="Отдых" categoryId="1" default="false" archived="false"> <!-- default=true для резервного фонда -->
    .. <!-- Тело такое же, как и при управлении целью -->
  </goal>
</goals>

Управление целью
URL: /data/{user}/goal/{goalId}
Доступные действия: GET, POST, DELETE

<goal id="2332" name="Лыжи" category="Отдых" categoryId="1" default="false" archived="false"> <!-- default=true для резервного фонда -->
  <currency id="gb" code="GBP">фунт</currency>
  <price>250.0</price> 
  <created>2009-01-12</created> 
  <planned>2011-12-01</planned> 
  
  <credit>
    <value>100.0</value>
    <period>WEEKLY</period>
  </credit>
  
  <accumulated>125.0</accumulated>
  <withdrawn>100.0</withdrawn> <!-- Сколько средств потрачено из накопленных на цель -->
</goal>

Параметры POST:

Для новосоздаваемых целей также можно указать

Перечень списаний с цели не реализовано
URL: /data/{user}/goal/{goalId}/withdrawals

<goalWithdrawals>
  <goalWithdrawal id="4313">
    <goal id="2332" name="Машина" category="Покупка" default="false" archived="false"/>
    <date>2012-01-15</date>
    <comment>Аванс за машину</comment>
    <account id="441232" name="Наличка"/>
    <value>150000.0</value>
  </goalWithdrawal>
</goalWithdrawals>

Управление списаниями с цели
URL: /data/{user}/goalWithdrawal/{goalWithdrawalId} Доступные действия: GET, POST, DELETE

<goalWithdrawal id="4313">
  <goal id="2332" name="Машина" category="Покупка" default="false"/>
  <date>2012-01-15</date>
  <comment>Аванс за машину</comment>
  <account id="441232" name="Наличка"/>
  <value>150000.0</value>
</goalWithdrawal>

Параметры POST:

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

Перечень переносов с цели/на цель
URL: /data/{user}/goal/{goalId}/updates
Доступные действия: GET

<goalUpdates>
  <goalUpdate id="213" type="goal">
    .. <!-- Тело как при управлении переносами  -->
  </goalUpdate>
</goalUpdates>

Управление переносами с цели/на цель
URL: /data/{user}/goalUpdate/{goalUpdateId}
Доступные действия: GET, POST, DELETE
У переноса может быть один из следующих типов

Результат:

<goalUpdate id="213" type="GoalTransfer">
  <goal id="2332" name="Машина" category="Покупка" default="false"/>
  <date>2012-05-12</date>
  <value>150.0</value> <!-- На эту величину увеличиваются накопленные на цель средства -->
  <comment>Купил машину дешевле, разницу в резервный фонд</comment>
  
  <account id="441232" name="Наличка"/> <!-- Только для type = Update -->
  <matchingGoalUpdate id="223" type=""/> <!-- Только для type = GoalTransfer -->
</goalUpdate>

Параметры POST:

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

2. Ежедневные траты из конвертов

2.1. Информация о недельном конверте
URL: /data/{user}/envelope/{envelopeBegin}
Доступные действия: GET
Результат:

<envelope begin="2009-05-18" size="1005.0">
  ...
  <person id="23443234" name="Петя">
    <dailyExpense date="2009-05-20" defaultAccount="441232">
      <!-- Если нет ни одного expression, трата не введена -->
      <expression account="441232" currency="gb">150 кафе, 20 еда</expression> <!-- В качестве account может быть любой счет в нац.валюте -->
      <expression account="21442" currency="gb">30 интернет</expression>
      <sum>170.0</sum>
    </dailyExpense>
    ...
  </person>
  ...
</envelope>

2.2. Получение и внесение ежедневных трат
URL: /data/{user}/dailyExpense/{personId}/{date}
Доступные действия: GET, POST
Результат:

<dailyExpense date="2009-05-20" defaultAccount="441232">
  <!-- Если нет ни одного expression, трата не введена -->
  <expression account="441232" currency="gb">150 кафе, 20 еда</expression> 
  <expression account="21442" currency="ru">30 интернет</expression>
  <sum>170.0</sum>
</dailyExpense>

Параметры POST:

2.3. Распределение остатка недельного конверта
URL: /data/{user}/envelopeResult/{envelopeBegin}/
Доступные действия: GET, POST
Результат:

<envelopeResult>
  <value>150.0</value> <!-- Сколько осталось из указанного конверта, может быть со значком минус -->
  <distributeTo>remaining</distributeTo> <!-- Куда ложить остаток, м.б. remaining или nextEnvelope -->
  <distributed>true</distributed> <!-- При ответе пользователе (первом вызове POST) становится false -->
</envelopeResult>

Параметры POST:

3. Выполнение плана трат и доходов

3.1. Перечень пунктов для выполнения на выбранной неделе
URL: /data/{user}/execution/{envelopeBegin}
Доступные действия: GET
Результат:

<execution begin="2009-05-18" remaining="950.0"> <!-- Текущий остаток, не зависит от начала недели -->
  <!-- Планируемая и фактическая дата получаемого дохода -->
  <actualIncome actualDate="2009-05-18" plannedDate="2009-05-18" defaultAccount="441232">
    <income id="3341123" name="Зарплата">
      <currency code="RUR" id="ru">руб</currency>
    </income>
    <planned>16000.0</planned>
    <actual>15500.0</actual> <!-- Сумма всех actualExpression -->
    <!-- Если нет ни одного actualExpression, трата не введена -->
    <actualExpression account="441232" currency="gb">аванс 8000 + зарплата 7500<actualExpression>
    <actualExpression account="3323 currency="ru">323</actualExpression>
  </actualIncome>
  <actualExpense actualDate="2009-05-18" plannedDate="2009-05-18" defaultAccount="441232">
    <expense id="44324553" name="Арендная плата">
      <currency code="RUR" id="ru">руб</currency>
    </expense>
    <planned>3000</planned>
    <actual></actual>
  </actualExpense>
  ...
  <envelope begin="2009-05-18" size="1005.0"> <!-- Такой же, как в п.2.1 -->
    ...
  </envelope>
</execution>

3.2. Получение дохода
URL: /data/{user}/actualIncome/{incomeId}/{plannedDate}
Доступные действия: GET, POST
Результат:

<actualIncome actualDate="2009-05-18" plannedDate="2009-05-18" defaultAccount="441232">
  <income id="3341123" name="Зарплата">
    <currency code="RUR" id="ru">руб</currency>
  </income>
  <planned>16000.0</planned>
  <actual>15500.0</actual>
  <actualExpression account="2212" currency="ru">15500</actualExpression>
</actualIncome>

Параметры POST:

value=1500.0&account=2123&currency=ru

или

date=2009-05-20

3.3. Выполнение траты
URL: /data/{user}/actualExpense/{expenseId}/{plannedDate}
Доступные действия: GET, POST
Результат:

<actualExpense actualDate="2009-05-18" plannedDate="2009-05-18" defaultAccount="441232">
  <expense id="44324553" name="Арендная плата">
    <currency code="RUR" id="ru">руб</currency>
  </expense>
  <planned>3000</planned>
  <actual></actual>
</actualExpense>

Параметры POST:

value=1500.0&account=2123&currency=ru

или

date=2009-05-20