Подробнее о работе с Protemos API

Есть такая система как Protemos (protemos.com), для переводческого бизнеса. Не буду углубляться в красочное описание системы, это можно посмотреть на их сайте, а постараюсь более подробно описать как пользоваться их API, так как честно говоря, на момент написания статьи, ихнее описание по работе с API скудновато, и без пол литры не разобраться, а то понадобится и ящик горячительного.

Все запросы в Protemos идут через следующий урл

НО к нему обязательно нужно прицепить параметр с апи ключем (api_key) и кусок урла для выполнения определенных действий.

Например

У нас есть API ключ: «XXXXXXXXYYYYYYYYYZZZZZZZZZZZZZZZ»

И нам нужно создать проект, это project/create

Тогда урл запроса примет вид

По данному урлу отсылает POST или GET запросы, в зависимости от применяемых команд.

Как получить ключ API

Для этого переходив в меню «Настройки -> Учетная запись»

В таблице «Информация об учетной записи» будет Ключ API

Список команд из документации по Protemos API

• client/create — создание клиента
• client/index — получить список всех клиентов
• client/view — получить данные по определенному клиенту
• job/index — получить список всех работ
• job/view — получить данные по определенной работе
• language-pair/index — получить список всех языковых пар
• language-pair/view — получить данные по определенной языковой паре
• manager/index — получить список всех менеджеров
• manager/view — получить данные по определенному менеджеру
• project/create — создать проект
• project/index — получить список всех проектов
• project/view — получить данные по определенному проекту
• quote/create —
• quote/index —
• quote/view —
• specialization/index —
• specialization/view —

Поскольку некоторые команды используют POST запросы, я создал функцию по отправке запросов

function ProtemosAction($url, $sPostFields){
  //global $result_x;
  $obCurl = curl_init();
  curl_setopt($obCurl, CURLOPT_URL, $url);
  curl_setopt($obCurl, CURLOPT_RETURNTRANSFER, true);
  if($sPostFields)
  {
    curl_setopt($obCurl, CURLOPT_POST, true);
    curl_setopt($obCurl, CURLOPT_POSTFIELDS, $sPostFields);
  }
  curl_setopt($obCurl, CURLOPT_FOLLOWLOCATION, 1);
  $out = curl_exec($obCurl);
  $info = curl_getinfo($obCurl);
  if(curl_errno($obCurl))
  {
    $info[ 'curl_error' ] = curl_error($obCurl);
  }

  $result_x = json_decode($out, true);
  curl_close($obCurl);
  return $result_x;
}

Теперь по подробней о командах

Создание клиента (client/create)

Метод запроса: POST

Параметры:

«type_id» — тип клиента (1 — individual, 2 — company)
«branch_id» — ID of default legal entity for the client
«company_name» — название компании клиента, используется только когда type_id = 2 (string)
«tax_number» — client TAX number (string)
«website» — вэб-сайт клиента (string)
«time_zone» — часовой пояс клиента / основного пользователя (string)
«country_id» — ID страны клиента
«zip_code» — почтовый код клиента (string)
«city» — город клиента (string)
«address» — адрес клиента (string)
«note» — примечание (string)
«is_assignable» — if the client can be assigned to project/quotes (boolean)
«first_name» — имя основного пользователя (string)
«last_name» — фамилия основного пользователя (string)
«gender_id» — пол основного пользователя (1 — male, 2 — female)
«phone» — phone основного пользователя (string)
«skype» — skype основного пользователя (string)
«email» — электронная почта основного пользователя (string)

Возвращаемые данные: json

Получить список всех клиентов (client/index)

Метод запроса: GET

Параметры: нет

Возвращаемые данные: json

Пример кода по отправке запроса

$key = 'ваш API ключ';
$url = 'https://api.protemos.com/v1/client/index?api_key='.$key;
$client_res = ProtemosAction($url, false);
print_r($proj);

Полученный ответ с API, преобразованный в массив:

Array (
[0] => Array (
[user_id] => 20118
[type_id] => 2
[is_assignable] => 1
[company_name] =>
[website] =>
[country_id] => 233
[zip_code] =>
[city] =>
[address] =>
[tax_number] =>
[note] =>
[default_quote_manager_id] =>
[default_project_manager_id] =>
[default_branch_id] => 2725
[default_currency_id] => 141
[default_payment_method_id] =>
[default_payment_terms] =>
[inherits_account_taxes] => 1
[pdf_locale] => en_US
[proz_blueboard_id] =>
[proz_blueboard_manual_entry] => 0
[user] => Array (
[id] => 23118
[time_zone] => Europe/Kiev
[group_id] =>
[can_login] => 0
[first_name] => First_Name
[last_name] => Last_Name
[gender_id] =>
[phone] =>
[skype] =>
[email] => xxx@gmail.com
[email_lang] => en
[login_ip] =>
[login_at] =>
[registered_at] =>
[last_invited_at] =>
[last_request_at] =>
[proz_profile_uuid] =>
[proz_enable_notifications] => 1
[has_accepted_terms_of_service] => 0
[created_by] => 21511
[created_at] => 2017-11-16 09:30:08
)
)
[1] => Array (
. . .
)
. . .
)

Создание проекта (project/create)

Метод запроса: POST

Параметры:
«name» — название проекта (string)
«descr» — описание проекта (string)
«langPairIds[]» — ID языковой пары
«spec_id» — ID специализации
«client_id» — ID клиента
«primary_manager_id» — ID основного менеджера
«secondary_manager_id» — ID менеджера
«formStartAt» — начало проекта (datetime)
«deadline_at» — сдать не позднее, дата сдачи проекта (datetime)
«free_of_charge» — бесплатный проект (boolean)

Возвращаемые данные: json

Скриншот с оригинальной документации.

А теперь самое интересное, как этим пользоваться?

Пример кода по отправке запроса.

$key = 'ваш апи ключ';
$url = 'https://api.protemos.com/v1/project/create?api_key='.$key;

$deadline = new DateTime('2020-02-28 11:00:00');

$fields = array(
 'name'=> 'тестовый проект',
 'client_id' => 1,
 'primary_manager_id' => 20,
 'formDeadlineAt' => $deadline->format('Y-m-d H:i:s'),
 'langPairIds[0]' => 5,
 'langPairIds[1]' => 6,
 'langPairIds[3]' => 7
);

$proj = ProtemosAction($url, $fields);

print_r($proj);