Организации

Управление организациями осуществляется с помощью двух ресурсов:

  • /companies - ресурс для управления коллекцией организаций
  • /companies/:id - ресурс для управления конкретной организацией с идентификатом :id
Метод Ресурс Результат
POST /companies создать организацию
GET /companies найти организации
GET /companies/:id получить данные организации
POST /companies/:id изменить данные организации
DELETE /companies/:id удалить организацию

Создание организации

Чтобы создать организацию, необходимо выполнить запрос POST /companies с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
id Id организации Да
Строка содержащая латинские символы,
цифры, ‘_’, ‘-‘, ‘.’
Длина: 3-100 символов.
“^[-\w\.]{3,100}$”
account_views Счет в показах Да
Число,
Длина: 5-40 символов.
account_clicks Счет в кликах Да
Число,
Длина: 5-40 символов.
money Счет Да
Число,
Длина: 5-40 символов.
owner Id владельца Да
Существующий id пользователя
“^[-\w]{3,20}$”
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”
moderation Режим модерации Нет disabled, pre, post
moderate_updated_banners Ремодерация измененных баннеров Нет true, false

При достижении любым из счетов (account_views, account_clicks, money) нулевого значения, все кампании организации будут приостановлены.

Поля moderation и moderate_updated_banners действуют только для рекламодателей.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "id":"example",
          "account_views":100500,
          "account_clicks":100500,
          "money":100500,
          "owner":"alice",
          "description":"This is your company"
        }' \
       --url http://api.example.com/companies

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:58:01 GMT
Content-Type: application/json
Content-Length: 71
Connection: keep-alive
Location: http://api.example/companies/example

{
  "id":"example",
  "money":100500.0,
  "account_views":100500.0,
  "account_clicks":100500.0,
  "owner":"alice",
  "description":"This is your company",
  "moderation":null,
  "moderate_updated_banners":null
}

Только пользователи с ролью administrator могут создавать новые организации.

Поиск организаций

Чтобы получить список организаций, необходимо выполнить запрос GET /companies.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/companies

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:00:30 GMT
Content-Type: application/json
Content-Length: 85
Connection: keep-alive

{
  "results": [
    {
      "id":"example",
      "money":100500.0,
      "account_views":100500.0,
      "account_clicks":100500.0,
      "owner":"alice",
      "description":"This is your company",
      "moderation":null,
      "moderate_updated_banners":null
    }
  ],
  "total_count": 1
}

Только пользователи с ролью administrator могут получить список организаций.

Получение данных организации

Чтобы получить данные организации, необходимо выполнить запрос GET /companies/:id.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/companies/example

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:01:52 GMT
Content-Type: application/json
Content-Length: 71
Connection: keep-alive

{
  "id":"example",
  "money":100500.0,
  "account_views":100500.0,
  "account_clicks":100500.0,
  "owner":"alice",
  "description":"This is your company",
  "moderation":null,
  "moderate_updated_banners":null
}

Только пользователи с ролью administrator и владелец данной организации могут получить данные организации.

Изменение данных организации

Чтобы изменить данные организации, необходимо выполнить запрос POST /companies/:id.

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

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "description":"Example Inc."
        }' \
       --url http://api.example.com/companies/example

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:05:38 GMT
Content-Type: application/json
Content-Length: 66
Connection: keep-alive

{
  "id":"example",
  "money":100500.0,
  "account_views":100500.0,
  "account_clicks":100500.0,
  "owner":"alice",
  "description":"Example Inc.",
  "moderation":null,
  "moderate_updated_banners":null
}

Пользователь с ролью administrator может изменять любые поля поля организации.

Владелец организации может изменять все поля организации кроме money, account_views, account_clicks и owner.

Удаление организации

Чтобы удалить организацию, необходимо выполнить запрос DELETE /companies/:id.

Пример:

$ curl --request DELETE \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/companies/example

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:06:51 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

Только пользователи с ролью administrator и владелец данной организации могут удалить организацию.

Добавление сотрудника

Чтобы добавить сотрудника в организацию, необходимо выполнить запрос POST /companies/:company_id/members/:user_id

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/companies/company1/members/publisher2

HTTP/1.1 204 No Content
Server: nginx/1.4.6 (Ubuntu)
Date: Wed, 17 Dec 2014 04:40:46 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive

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

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

Чтобы удалить сотрудника из организации, необходимо выполнить запрос DELETE /companies/:company_id/members/:user_id

Пример:

$ curl --request  DELETE \
       --include \
       --user "admin:admin" \
      --url http://api.example.com/companies/example/members/alice

HTTP/1.1 204 No Content
Server: nginx/1.4.6 (Ubuntu)
Date: Wed, 17 Dec 2014 04:40:46 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive

Только пользователи с ролью administrator и владелец данной организации могут удалить сотрудника.

Поиск сотрудников

Чтобы получить список сотрудников организации, необходимо выполнить запрос GET /companies/:company_id/members

Пример:

 $ curl --request GET \
        --include \
        --user "admin:admin" \
        --url http://api.example.com/companies/example/members/

 HTTP/1.1 200 OK
 Server: nginx/1.4.6 (Ubuntu)
 Date: Wed, 17 Dec 2014 05:58:26 GMT
 Content-Type: application/json
 Content-Length: 197
 Connection: keep-alive

 {
   "results": [
     {
       "id": "alice",
       "company": "example",
       "email": "alice@example.com",
       "name": "Alice",
       "role": "publisher"
     }
   ],
   "total_count": 1
}

Любой сотрудник организации может получить список сотрудников организации.

Управление счетами

Управление счетами организации осуществляется с помощью ресурса /companies/:id/transactions.

Метод Ресурс Результат
POST /companies/:id/transactions Исполнить операцию начисления/списания
GET /companies/:id/transactions Найти транзакции

API позволяет начислять/списывать/устанавливать значение счетов money, account_views и account_clicks организаций, а также получать информацию по исполненным транзакциям.

Начисления/списания

Чтобы выполнить операцию начисления/списания средств, необходимо выполнить запрос POST /companies/:id/transactions с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
action Тип операции Да
set - установить новое значение счета
increase - начислить средства на счет
decrease - списать средства со счета
field Тип счета Да money, account_views, account_clicks
amount Сумма начисления / списания Да Положительное число
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
         "action":"increase",
         "field":"money",
         "amount":100,
         "description":"test transaction"
        }' \
       --url http://api.example.com/companies/company1/transactions

HTTP/1.1 204 No Content
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 15 Jan 2015 08:20:57 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive

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

Получение информации о выполненых транзакциях

Чтобы получить информацию о выполненных транзакциях, необходимо выполнить запрос /companies/:id/transactions

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/companies/company1/transactions

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Mon, 19 Jan 2015 08:35:59 GMT
Content-Type: application/json
Content-Length: 660
Connection: keep-alive

{
  "results": [
    {
      "id":1,
      "timestamp":"2015-01-19T11:35:03Z",
      "action":"increase",
      "field":"money",
      "amount":100.0,
      "company":"company1",
      "user_id":"administrator",
      "before_value":0.0,
      "after_value":100.0,
      "description":"some description"
    },
  ],
  "total_count":1
}