Updated Nov 16, 2009 by vasyl.stashuk

ApiDescription

Описание API сервиса

Обзор

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

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

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

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

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

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

Название	Описание
user	Логин пользователя
date	Дата в формате yyyy-MM-dd
personId	Идентификатор члена семьи, возвращается в /data/{user}
envelopeBegin	Дата начала недели. Если на указанной дате неделя не начинается, буде выбран конверт, в который входит указанная дата.

История

Текущая ревизия API - 1.1

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

Версия 1.0

Авторизация

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

4KApplication

Идентификатор стороннего приложения.
Раздается авторами сервиса "4 конверта"
Для тестов можно использовать значение Demo. При использовании Demo использование API ограничено 25 различными логинами в сутки (для всех пользователей)

4KAuth

Пароль пользователя

Если авторизация неверна, будет возращен код ошибки 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="Наличка">
      <currency id="gb" code="GBP">фунт</currency>
      <value>250 фунтов</value>
    </account>
    ...
  </accounts>
</user>

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 (URL-encoded UTF-8):

expression=150%20кафе,%2020%20еда&account=21442&currency=gb

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>
  <actualGoalCredit actualDate="2009-05-22" plannedDate="2009-05-20" defaultAccount="441232">
    <goal id="234234" name="(Первоначальный взнос) Авто">
      <currency code="USD" id="us">дол</currency>
    </goal>
    <planned>1000.0</planned>
    <actual>950.0</actual>
    <actualExpression account="441232" currency="gb">950</actualExpression>
    <actualExpression account="3323" currency="ru">11</actualExpression>
    <goalAccount id="3323"/> <!-- Счет, куда ложить деньги. Есть значение по умолчанию. Вся сумма ложиться на один счет. Можно ложить на любой счет в соотв.валюте -->
  </actualGoalCredit>
  <actualGoalCredit actualDate="2009-05-23" plannedDate="2009-05-01" defaultAccount="441232">
    <goal id="234234" name="(Другое) Шкаф">
      <currency code="RUR" id="ru">руб</currency>
    </goal>
    <planned>1000.0</planned>
    <actual></actual> <!-- Сумма еще не внесена -->
    <goalAccount id="3323"/>
  </actualGoalCredit>
  <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}/actualGoalCredit/{goalId}/{plannedDate}
Доступные действия: GET, POST
Результат:

<actualGoalCredit actualDate="2009-05-22" plannedDate="2009-05-20" defaultAccount="441232">
  <goal id="234234" name="(Первоначальный взнос) Авто">
    <currency code="USD" id="us">дол</currency>
  </goal>
  <planned>1000.0</planned>
  <actual>950.0</actual>
  <actualExpression account="1323" currency="ru">500 и еще 450</actualExpression>
  <goalAccount id="323"/>
</actualGoalCredit>

Параметры POST:

value=950&account=1323&goalAccount=323&currency=us

или

date=2009-05-20

3.4. Выполнение траты
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

Comment by Yury.Korolev, May 25, 2009

А если возвращается 2?

Comment by vasyl.stashuk, Nov 13, 2009

2 Yury.Korolev, спасибо за замечание.

Действительно, правильно будет 1 - Воскресенье 2 - Понедельник