Создание или обновление контрагента

Параметры запроса#

Отправьте полный набор реквизитов записи. По новому source_id метод создаст запись; по существующему — обновит её. В каждом запросе передавайте API-токен в заголовке Authorization.

Адрес: https://app.zaezdo.pro/api/v1/counterparties/{source_id}. Параметр source_id обязателен, передаётся в URL; ограничения указаны в таблице ниже. Query-параметры не используются.

Тело запроса — объект JSON. Параметры ниже передаются как при создании, так и при обновлении.

* ИНН и КПП можно не передавать вместе. При ИНН из 10 цифр КПП обязателен. При ИНН из 12 цифр КПП должен быть пустым. КПП без ИНН не допускается.

Пример запроса#

PUT /api/v1/counterparties/CP-0042 HTTP/1.1
Host: app.zaezdo.pro
Authorization: Bearer ВАШ_API_ТОКЕН
Content-Type: application/json

{
  "name": "ООО «Пример Логистика»",
  "inn": "7701234560",
  "kpp": "770101001",
  "comment": "Поставщик"
}

{
  "name": "ООО «Пример Логистика»",
  "inn": "7701234560",
  "kpp": "770101001",
  "comment": "Поставщик"
}

curl --request PUT \
  --url "https://app.zaezdo.pro/api/v1/counterparties/CP-0042" \
  --header "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "ООО «Пример Логистика»",
  "inn": "7701234560",
  "kpp": "770101001",
  "comment": "Поставщик"
}'

Успешные ответы#

{
  "id": "CP-EXAMPLE001",
  "source_id": "CP-0042",
  "created": true,
  "is_active": true
}

{
  "id": "CP-EXAMPLE001",
  "source_id": "CP-0042",
  "created": false,
  "is_active": true
}

Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false.

Создание, обновление и повторы#

PUT передаёт полное состояние полей, перечисленных в описании метода. При повторе с тем же source_id данные этих полей заменяются значениями из запроса. Поэтому в каждом запросе передавайте все значения, которые нужно сохранить.

Для обычных строк убираются пробелы по краям; пустая строка после этого считается незаполненным значением. Для source_id пробелы не исправляются автоматически. Необязательные поля принимают строку или null; у обязательных полей тип — string.

Активность и повторные запросы

Новая запись активна. При обновлении сохраняется её текущая активность: отключённая запись автоматически не включается. Поле is_active возвращается в ответе, но не принимается для изменения через PUT. Настройки, не входящие в метод, остаются без изменений.

Первая запись возвращает 201 и created: true. Обновление или повтор — 200 и created: false. Повтор одинакового запроса не создаёт новую запись.

Правила для этого справочника

Обновляются только name, inn, kpp и comment. Активность и контактные лица не изменяются.

Для совпадений проверяется пара ИНН + КПП у организаций либо ИНН из 12 цифр у ИП. Если эти реквизиты принадлежат другой записи, возвращается 409: автоматического объединения нет.

При отсутствии ИНН поиск по наименованию не выполняется. Чтобы не создать дубликаты, используйте неизменный source_id; одинаковые названия сами по себе не доказывают совпадение контрагентов.

Идентификатор ответственного менеджера в этом методе не передаётся. При создании визита 1С отдельно указывает responsible_user_source_id своего ответственного за контрагента.

Проверка ИНН и КПП

Если формат ИНН некорректен, проверка контрольного числа не выполняется. Условия КПП, зависящие от длины ИНН, проверяются после определения его типа. Для одного КПП возвращается одна причина: отсутствие, неверный формат либо запрет для ИП.

Порядок проверки запроса#

После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания.

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

При HTTP 409 и 422 конкретные причины возвращаются в errors[]. Ниже приведены все коды этого метода и точные тексты сообщений.

Для BODY_MUST_BE_OBJECT поле field содержит "$" — весь JSON. Для UNKNOWN_FIELD в field возвращается фактически переданное лишнее имя, например is_active.

REQUIRED возвращается, когда обязательного поля нет либо оно равно null или пустой строке. Если поле заполнено, но имеет неверный тип или длину, возвращается соответствующий код INVALID_… . Две ошибки об одном и том же нарушении не дублируются.

Как разрешить конфликт 409

Если другая запись имеет те же реквизиты, по которым проверяются совпадения, метод не объединяет записи автоматически и не меняет их source_id. Критерии совпадения указаны для каждого справочника. Отключённые записи участвуют в проверке конфликтов.

Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:

ПРИМЕР ОТВЕТА · HTTP 409

{
  "code": "RESOURCE_CONFLICT",
  "message": "Невозможно сохранить запись из-за конфликта данных.",
  "errors": [
    {
      "field": "inn",
      "code": "COUNTERPARTY_DETAILS_CONFLICT",
      "message": "Контрагент с указанными ИНН и КПП либо ИНН ИП уже существует, но не сопоставлен с переданным source_id."
    }
  ],
  "request_id": "req-counterparties-conflict"
}

1. Проверьте, не существует ли соответствующая запись в справочнике Заездо.
2. Если запись существует и соответствует объекту внешней системы, укажите в её карточке правильный «Идентификатор для синхронизации с 1С».
3. Повторите исходный PUT-запрос с тем же source_id.

Пример ошибки параметров

HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных справочника.",
  "errors": [
    {
      "field": "name",
      "code": "REQUIRED",
      "message": "Укажите наименование контрагента."
    },
    {
      "field": "kpp",
      "code": "KPP_REQUIRED",
      "message": "Требуется указать КПП."
    }
  ],
  "request_id": "req-counterparties-validation"
}

Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы.

Повтор после временной ошибки

При 429 учитывайте Retry-After. При 500, 503 или потере ответа повторите тот же PUT после паузы. Если вместо JSON получен ответ сетевого шлюза, ориентируйтесь на HTTP-статус; request_id в таком ответе может отсутствовать.

Пример использования для 1С#

Перед передачей заявки выполните PUT /api/v1/counterparties/CP-0042 с реквизитами контрагента. После успешного ответа и is_active: true используйте "CP-0042" в визите. При 409 сначала разрешите сопоставление, не создавая новый внешний идентификатор.

ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits

{
  "counterparty_source_id": "CP-0042"
}

При изменении наименования или реквизитов в 1С отправьте полный набор полей на тот же URL. Чтобы удалить комментарий, передайте comment: "". Если нужно сохранить ИНН и КПП, их необходимо повторить в запросе.