Кабинет

#API

Чужая программа может читать и писать справочники сайта по HTTP. Так подключают склад, 1С, мобильное приложение или свой скрипт выгрузки.

Адрес один на все справочники:

https://ваш-сайт.ru/api/v1/lists/…
Почему так

Почему один адрес, а не свой на каждый справочник.

Справочник — это и статьи, и товары, и заявки. Заводить отдельный адрес под каждый значило бы переписывать API всякий раз, когда владелец сайта заводит новый справочник. Поэтому справочник называется номером в адресе, а работа с ним одна и та же.

#Что умеет

МетодАдресЧто делает
GET/api/v1/lists/перечень справочников
GET/api/v1/lists/{id}/fields/поля справочника
GET/api/v1/lists/{id}/records/записи
POST/api/v1/lists/{id}/records/завести запись
GET/api/v1/lists/{id}/records/{rid}/одна запись
PATCH/api/v1/lists/{id}/records/{rid}/правка
DELETE/api/v1/lists/{id}/records/{rid}/удалить

PUT работает наравне с PATCH — оба правят только присланные поля.

#Чего не умеет намеренно

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

#Что нужно для начала

  1. Завести ключ в разделе Настройки → Ключи API.
  2. Узнать номер справочника — он виден в адресе панели и в ответе GET /api/v1/lists/.
  3. Слать запросы с заголовком Authorization: Bearer <ключ>.
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
     https://ваш-сайт.ru/api/v1/lists/
<?php
$ch = curl_init('https://ваш-сайт.ru/api/v1/lists/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ВАШ_КЛЮЧ'],
]);
$answer = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($answer['lists'] as $list) {
    echo $list['id'], ' — ', $list['title'], PHP_EOL;
}
import requests

r = requests.get(
    'https://ваш-сайт.ru/api/v1/lists/',
    headers={'Authorization': 'Bearer ВАШ_КЛЮЧ'},
    timeout=15,
)
r.raise_for_status()

for item in r.json()['lists']:
    print(item['id'], '—', item['title'])
const res = await fetch('https://ваш-сайт.ru/api/v1/lists/', {
  headers: { Authorization: 'Bearer ВАШ_КЛЮЧ' },
});
if (!res.ok) throw new Error('HTTP ' + res.status);

const { lists } = await res.json();
for (const list of lists) console.log(list.id, '—', list.title);
{
  "ok": true,
  "lists": [
    {"id": 1, "name": "pages", "title": "Страницы"},
    {"id": 4, "name": "blog", "title": "Записи блога"}
  ]
}
Совет

Не хотите набирать это руками — откройте песочницу: там запрос собирается полями, выполняется прямо со страницы, а код на всех четырёх языках получается сам.

#Как устроен ответ

У любого ответа есть поле ok.

{"ok": true,  "records": []}
{"ok": false, "error": "Справочника нет."}

Ответы не кешируются и отдаются как application/json; charset=utf-8.

Важно

Завершающий слеш в адресе обязателен.

Веб-сервер приводит адрес без слеша к адресу со слешем постоянным перенаправлением. GET это переживает, а PATCH и DELETE — плохо: клиент по умолчанию повторяет их методом GET и без тела. Запрос формально «проходит», а запись остаётся нетронутой.

#Дальше

КлючиЗавести, отозвать, где хранится и что делать, если потерян ЧтениеЗаписи, поля, страницы, порядок и фильтр по публикации ЗаписьСоздание, правка, удаление и что происходит с лишними полями ОшибкиКоды ответов и разбор частых случаев ПесочницаСобрать запрос полями, выполнить его и забрать готовый код
НазадНейросетьДальшеКлючи