API используется для доступа к партнерской программе perevod22.ru сторонними сервисами и приложениями.

Обращение к функциям API осуществляется по протоколу HTTP, посредством POST-запроса на соотвествующий URL.

Базовый URL для обращений к функциям API - http://api.perevod22.ru/v2.0/

API принимает и возвращает данные в кодировке utf-8. Параметры передаются в теле запроса в формате JSON, а поле Content-Type запроса должно иметь значение application/json. Результат выполнения возвращается так же в формате JSON.

Пример обращения к API-функции /auth:

POST /v2.0/auth HTTP/1.1
Host: api.perevod22.ru
Content-Type: application/json; charset=utf-8
Content-Length: 137

{
  "email": "test@test.ru",
  "password": "foobar"
}

Формат ответа

При остутствии сетевых ошибок, в ответ на любое обращение к API, сервер всегда отвечает HTTP кодом 200, возвращая JSON-объект, содержащий результаты выполнения запроса.

В случае возникновения ошибок в процессе обработки запроса, в ответном JSON будет присутствовать массив errors. Каждый элемент этого массива содержит поля code и msg, отвечающие соотвественно за код ошибки и её описание. errors всегда является массивом, даже если ошибка всего одна.

Вот пример ответа функции /auth, в процессе выполнения которой возникли ошибки:

{
  "errors": [
    {
      "code": 1,
      "msg": "Необходимо указать e-mail адрес"
    },
    {
      "code": 2,
      "msg": "Необходимо указать пароль"
    }
  ]
}

Отсутствие в ответе элемента errors свидетельствует о том, что выполнение запроса прошло без ошибок.

Пример использования API на PHP

<?php

  $req = [
    'email' => 'me@mail.com',
    'password' => 'foobar',
  ];

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
  curl_setopt($ch, CURLOPT_URL, 'http://api.perevod22.ru/v2.0/auth');
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($req));

  $res = curl_exec($ch);
  $json = json_decode($res, true);
  
  if (count($json) == 0)
    die("ERROR - Network error");

  if (isset($json['errors'])) {
    foreach($json['errors'] as $error)
      print("ERROR - " . $error['code'] . " - " . $error['msg'] . PHP_EOL);
    die();
  }

  // Запрос выполнился успешно
  print_r($json);

Пример использования API на JavaScript (jQuery)

  $.ajax({
    type: 'POST',
    cache: false,
    dataType: 'json',
    contentType: 'application/json; charset=utf-8',
    url: 'http://api.perevod22.ru/v2.0/auth',
    data: JSON.stringify({
      email: 'me@mail.com',
      password: 'foobar',
    }),
    error: function(xhr, ajaxOptions, thrownError) {
      console.log('ERROR - Network error');
    },
    success: function(data) {
      if ((data.hasOwnProperty('errors')) && (data.errors.length > 0))
      {
        for (var i = 0; i < data.errors.length; i++)
          console.log('ERROR - ' + data.errors[i].code + ' - ' + data.errors[i].msg);
        return false;
      }

      // Запрос выполнился успешно
      console.log(data)
    },
  });

Авторизация

Авторизация при обращении к функциям API осуществляется посредством ключа доступа, передаваемого параметром token.

Ключи доступа деляется на сессионные (token) и постоянные (API Key).

Сессионные ключи идентифицируют пользователей системы и действуют лишь в пределах одной сесиии работы с API. Сессионные ключи выдаются функцией /auth.

Постоянные ключи формируются в пользовательском интерфейсе партнерской программы и действуют до момента их удаления из системы.

Коды и описания ошибок