Для разработчиков

Документация API Car2B

Публичные API для компаний с собственной автоматизацией: 1С, CRM, учётные системы. Доступ ко всем API устроен одинаково — ключ в личном кабинете, обмен на короткоживущий токен, вебхуки с подписью.

Доступные API

Ключи и доступ

Ключ доступа выпускает организация в личном кабинете: Профиль → Интеграции → «Создать ключ». Раздел доступен владельцу и администраторам верифицированной компании. При создании задаются название, назначение ключа и, при желании, список разрешённых IP-адресов.

• После создания вы увидите client_id и секрет. Секрет показывается один раз — сохраните его в настройках вашей системы. Дальше в кабинете виден только префикс ключа.
• «Перевыпустить» создаёт новый секрет; старый действует ещё 24 часа, чтобы обновить настройки без простоя.
• «Отозвать» останавливает ключ: новые токены не выдаются, уже выданный перестаёт приниматься не позже чем через 30 секунд.
• Адрес вебхука и секрет подписи задаются в карточке ключа (см. ниже).

Назначение ключа и скоупы

Один ключ — одно назначение. Назначение выбирается при создании и определяет, какие скоупы получит токен и какое API доступно ключу. Чтобы работать и организатором, и агентом, выпустите отдельные ключи.

Скоуп write не включает read: для сценария «прочитать и изменить» нужны оба; ключ создаётся сразу с парой скоупов своего назначения.

Обмен на токен

Стандартный OAuth 2.0 client_credentials. Секрет передаётся только в этом запросе, в заголовке HTTP Basic (base64 от строки client_id:секрет). Все остальные вызовы идут с полученным Bearer-токеном.

curl -X POST https://car2b.ru/api/v1/identity/oauth/token \
  -u "c2b_7Q4KJX2P9LMN3RTV8WQZ5M2:cs_live_4nR8vK2pQ7xL9mW3tY6bH1jF5dS0aG2c" \
  -d "grant_type=client_credentials"

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9…",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "remote-sales:agent.read remote-sales:agent.write"
}

• Токен живёт 300 секунд. Кэшируйте его и обновляйте за минуту до истечения.
• На 401 token_expired обновите токен и повторите запрос один раз.
• refresh_token не выдаётся: у системы есть секрет, она просто обменивает его снова.
• Ошибки обмена: 401 invalid_client (неизвестный ключ, отозван или неверный секрет), 403 organization_not_verified, 429 при более чем 10 обменах в минуту.

Разрешённые IP

В карточке ключа можно задать до 20 адресов или подсетей (CIDR). Тогда обмен ключа на токен и каждый вызов API с другого адреса отклоняются: 401 invalid_client на обмене, 403 ip_not_allowed на запросе. Пустой список — вызовы принимаются откуда угодно.

Вебхуки и подпись

Вместо опроса API Car2B может сам сообщать о событиях. Адрес (только https и публичный домен) и секрет подписи задаются в карточке ключа; секрет показывается один раз, перевыпуск делает старую подпись недействительной. Ключ получает события тех ролей, чьи скоупы у него есть; события адресуются организации-участнику.

Тело — { "id", "type", "occurred_at", "data" }. Ответьте любым 2xx в течение 10 секунд — обрабатывать событие можно после ответа. Иначе доставка повторяется до 5 раз с интервалами 1, 5, 15, 60 и 300 секунд. Возможны повторные доставки — обработчик должен быть идемпотентным по id.

Проверка подписи — всегда по сырому телу, до разбора JSON, сравнение за постоянное время:

import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# raw_body — тело запроса как пришло, до разбора JSON

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return expected.length === signatureHeader.length
    && timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Журнал доставок виден в карточке ключа и доступен по API: GET /import/webhooks/deliveries у Import API, GET /remote-sales/webhooks/deliveries у Remote Sales API.

Лимиты ключей

Лимит в 5 активных ключей действует отдельно на каждое назначение: пять ключей для импорта, пять для организатора и пять для агента — всего до 15 активных ключей на организацию. Ключ принадлежит компании, а не сотруднику. Остальные лимиты каждого API — в его описании.

Вопросы по интеграции: контакты Car2B.