CRM customers

Создать клиента CRM

Создаёт карточку клиента CRM. Живая карточка того же вида с теми же ИНН и КПП уже есть — отказ 409 crm.customer_inn_taken без обхода. Совпал телефон или почта с живой карточкой — отказ 409 crm.customer_possible_duplicate со списком похожих; повтор с confirm_duplicate: true создаёт карточку. Читает Idempotency-Key — повтор того же запроса с тем же ключом отдаёт созданную карточку, а не вторую.

post/api/v1/crm/customers

Request

  • Base URL: https://erp.akeda.ru
  • URL: https://erp.akeda.ru/api/v1/crm/customers
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key
    • OAuth 2 (authorization code, authorization URL https://erp.akeda.ru/oauth2/authorize, token URL https://erp.akeda.ru/oauth2/token, scopes: akeda:delegate)

Headers

X-Tenantstring required

Slug выбранного кабинета; кабинет не является юрлицом

Idempotency-Keystring

Ключ одной логической попытки команды. Единственная форма идемпотентности на уровне HTTP; читают его только операции, у которых этот параметр объявлен.

Повтор ТОГО ЖЕ запроса (метод, адрес с параметрами, тело) с тем же ключом не выполняет команду второй раз, а отдаёт первый успешный ответ с заголовком Idempotent-Replay: true. Тот же ключ с другим запросом — отказ 422 idempotency.key_mismatch, а не чужой ответ. Пока первая попытка ещё выполняется, повтор получает 409 idempotency.in_progress и Retry-After: он не ждёт и не выполняется второй раз.

Ключ принадлежит предъявителю в кабинете: человеку, кабинетному API-ключу или установке приложения. Одинаковый ключ у соседа — другая попытка.

Отказ 4xx ключ ОСВОБОЖДАЕТ: запрос отклонён до работы, в кабинете не изменилось ничего, и исправленный запрос с тем же ключом выполняется. Отказ 5xx ключ ЗАПИРАЕТ: записалось или нет — неизвестно, коммит мог случиться, а ответ до вас не доехать. Повтор с тем же ключом получает тот же статус и тот же машинный код, а команда второй раз не выполняется. Чтобы попробовать снова, прочитайте отдельным запросом, появился ли результат, и возьмите НОВЫЙ ключ.

И ответ, и запомненный отказ живут сутки; после этого тот же ключ — новая попытка, и команда выполняется заново. Ответы, несущие секрет (выдача токена, аренда секрета настройки), заголовок не читают: секрет отдаётся ровно один раз. Хранилище недоступно — 503 idempotency.unavailable, команда без защиты не выполняется; этот отказ приходит ДО заявки на ключ и потому ключ не тратит.

Для естественного ключа интеграции годится любая строка вида crm:order:123:create; UUID не обязателен.

Request body

kind'person' | 'company' | 'sole_prop'
namestring required
legal_namestring
innstring

ИНН: 10 цифр у организации, 12 у предпринимателя, с верной контрольной цифрой

kppstring

КПП: девять знаков, только вместе с ИНН из 10 цифр

phonestring

Телефон; несколько номеров можно перечислить через запятую. Не читается, если передан channels

emailstring

Почта; не читается, если передан channels

messengersobject nullable

Мессенджеры объектом «сеть → ник»; не читаются, если передан channels

tagsstring[] nullable
sourcestring
owner_idinteger nullable
notestring
customobject nullable

Дополнительные поля кабинета: состав задаёт «Настройки → Поля»

confirm_duplicateboolean

Это правда новый клиент: создать, хотя телефон или почта совпали с живой карточкой. Совпадение ИНН и КПП так не обходится

Response

Созданный клиент

idstring uuid required
kind'person' | 'company' | 'sole_prop' required
namestring required
legal_namestring required
innstring required

ИНН без пробелов; пустая строка - не указан

kppstring required

КПП в верхнем регистре; бывает только при ИНН из 10 цифр

phonestring required

Основной телефон — значение основного канала phone

emailstring required

Основная почта — значение основного канала email

messengersobject nullable required

Ник или номер клиента по мессенджерам

tagsstring[] nullable required
sourcestring required
owner_idinteger
owner_namestring
notestring required
core_contact_idstring uuid
promoted_atstring date-time

Момент переноса в справочник контрагентов ERP

archived_atstring date-time
merged_into_customer_idstring uuid
open_dealsinteger required
customobject nullable

Дополнительные поля кабинета: состав задаёт «Настройки → Поля»

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.