Перейти к содержимому
AISARAISAR
REST API

Организации

Организация — карточка компании-клиента в CRM: название, юридическое название, БИН/ИИН или ИНН, страна, тип отношений, реквизиты (организационно-правовая форма, коды, руководитель), банковские счета, телефон, e-mail, сайт, адрес, ответственный и свои поля. К организации привязываются контакты и сделки (у контакта и у сделки не больше одной организации). API покрывает список с поиском и фильтрами, подбор по названию или БИН, карточку, создание, правку, удаление, свои поля, привязку контактов, список сделок организации, справочник типов отношений и банковские счета.

Доступность и права

Организации есть только у компаний типа «бизнес»: в Kids любой эндпоинт группы отвечает 403. Токены встроенных виджетов (embed) тоже получают 403. Права проверяются раньше поиска записи, поэтому без права ответ 403 для любого id, а 404 возможен только у того, кому право выдано.

ДействиеНужные права
Список, подбор, карточкаorganization.view
Созданиеorganization.view + organization.create
Правкаorganization.view + organization.update
Удалениеorganization.view + organization.delete
Свои поля организацииorganization.view + organization.update + custom_field_value.update
Контакты организации: списокorganization.view + contact.view
Привязка и отвязка контактовorganization.view + contact.update
Сделки организацииorganization.view + deal.view, тариф с функцией сделок
Справочник типов отношений: чтение; подсказки организационно-правовой формыorganization.view
Справочник типов отношений: создание, правка, архив, удаление, порядокorganization.view + organization_relation_type.manage
Банковские счета в карточкеorganization.view + organization_bank_account.view
Банковские счета: добавление, правка, удалениеorganization.view + organization.update + organization_bank_account.view

По умолчанию у администратора все четыре права organization.*, у менеджера view, create и update, у оператора только view; удаление доступно только администратору. Своим ролям, у которых было право contact.view, при выкладке выдано organization.view.

organization_relation_type.manage и organization_bank_account.view по умолчанию есть у администратора и менеджера. Оператор номеров счетов не видит никогда: карточка у него приходит без ключа bank_accounts. Своим ролям эти права автоматически не выдавались: администратор отмечает их в редакторе ролей (две отдельные ячейки раздела организаций). Запись счёта требует права на просмотр счетов, потому что в ответе приходит полный номер.

Поля организации

ПолеОписание
nameНазвание, обязательно, до 255 символов. Не уникально.
legal_nameЮридическое название, до 255 символов.
tax_idНалоговый номер (БИН/ИИН, ИНН и т. п.), до 64 символов на входе. Пробелы, дефисы и точки убираются, буквы переводятся в верхний регистр; после этого 3–32 латинские буквы и цифры. Уникален среди неудалённых организаций компании.
country_codeКод страны ISO из двух букв, хранится в верхнем регистре. Если при создании не передан, берётся страна компании.
relation_type_idТип отношений (id из справочника компании) или null. Чужой, неизвестный или неверный id: 422 relation_type_not_found; архивный тип: 422 relation_type_archived, кроме случая, когда организация уже стоит на этом же типе. В ответе рядом приходит relation_type ({id, name, color, system_key, is_archived} или null).
legal_formОрганизационно-правовая форма (ТОО, ИП, ОсОО, LLC и т. п.), свободная строка до 50 символов, без справочника и без привязки к стране. Подсказки: GET /organizations/legal-forms.
registration_codeРегистрационный код (ОКПО и т. п.), до 32 символов, формат не проверяется. Только в карточке.
extra_codesПрочие коды одной строкой (КБе, КПП, код налогового органа), до 255 символов. Только в карточке.
signatory_nameФИО руководителя или подписанта, до 255 символов. Персональные данные. Только в карточке.
signatory_positionДолжность подписанта, до 255 символов. Только в карточке.
signatory_basisНа каком основании действует подписант («Устава», «Доверенности № … от …»), до 255 символов. Только в карточке.
bank_accountsТолько чтение, только в карточке и только при праве organization_bank_account.view: массив счетов (см. «Банковские счета»), счёт по умолчанию первым. Пишется отдельными эндпоинтами, не через POST/PATCH организации.
phoneТелефон, до 40 символов на входе, хранится в формате E.164 (национальный номер читается по country_code). Нечитаемый номер: 422, код phone_invalid.
emailE-mail до 254 символов, хранится в нижнем регистре.
websiteАдрес http:// или https://, до 255 символов.
addressАдрес, до 500 символов.
commentsКомментарий, до 5000 символов. В списке обрезается до 300 символов.
responsible_user_idОтветственный, участник текущей компании, иначе 422. В ответе рядом приходит responsible_user ({id, name} или null).
sourceТолько чтение: manual (кабинет), api (API-токен интегратора), backfill (перенос из текстового поля «Компания» контактов), import (создана импортом контактов из CSV, с 2026-11-17); bitrix24, amocrm зарезервированы.
custom_fieldsЗначения своих полей организации ({ключ: значение}), см. группу «Свои поля» с entity_type=organization.

Пустая строка в любом текстовом поле сохраняется как null. В PATCH передаются только меняемые поля. Счётчики приходят, только когда сервер их посчитал: contacts_count (привязанные контакты без объединённых) в списке и карточке; open_deals_count в списке и карточке и open_deals_amount (массив {currency, amount}, сумма открытых сделок по валютам, amount строкой) в карточке. Счётчики сделок есть только у пользователя с правом deal.view на тарифе со сделками и учитывают лишь сделки, которые ему видны, без лидов из «Неразобранного». Отсутствие ключа означает «не запрашивалось», а не ноль.

В строке списка из новых полей приходят только relation_type_id, relation_type и legal_form; registration_code, extra_codes, signatory_* и bank_accounts есть лишь в карточке (GET, а также ответы POST и PATCH). Ответ PUT /organizations/{id}/custom-fields содержит реквизиты, но без bank_accounts. Отсутствие ключа bank_accounts в карточке означает, что у пользователя нет права на счета, а не что счетов нет.

Проверка БИН/ИНН

  • Формат один для всех стран и от country_code не зависит: после удаления пробелов, точек и дефисов и перевода букв в верхний регистр остаётся от 3 до 32 латинских букв и цифр. Иначе 422, tax_id_invalid_format. Контрольная цифра БИН и длина номера для конкретной страны не проверяются: у казахстанской компании можно сохранить, например, российский ИНН.
  • Номер проверяется при каждой передаче tax_id; смена country_code его не перепроверяет. Если тот же номер (после такой же нормализации) уже есть у другой неудалённой организации компании: 409 с кодом organization_tax_id_taken и existing_organization_id. У удалённой организации номер освобождается.

Список и подбор

GET /organizations постраничный: page, perPage от 1 до 100 (по умолчанию 25), ответ data.items + data.pagination (page, perPage, total, lastPage). Фильтры комбинируются по И: search (до 100 символов; вхождение без учёта регистра в name, legal_name, email, phone либо начало tax_id после нормализации), responsible_user_id (id или none — без ответственного), has_tax_id (true/false), relation_type_id (id типа отношений из справочника компании или none — без типа; чужой или неизвестный id: 422 relation_type_not_found), country (код из двух букв, регистр не важен), cf[N][key|op|value] — до 5 фильтров по своим полям организации в том же формате, что у контактов. Сортировка: sortBy — name, created_at (по умолчанию), updated_at, contacts_count, relation_type (по порядку типа в справочнике; организации без типа в конце при любом направлении) или cf:<key>; sortDir — asc/desc (по умолчанию desc). Неизвестный ключ своего поля: 422, unknown_field.

GET /organizations/lookup?q= — подбор для карточки контакта или сделки: до 20 записей {id, name, tax_id} в data.items, без пагинации. Сначала точное совпадение БИН/ИНН, затем названия, начинающиеся с q, затем остальные совпадения, внутри групп по названию. Без q отдаются первые 20 организаций по названию.

GET /organizations/legal-forms — подсказки для поля legal_form: до 20 самых частых значений среди неудалённых организаций компании, по убыванию частоты, в data.items массивом строк (только значения, без id организаций).

Справочник типов отношений

У каждой компании свой справочник «Тип отношений» (/organization-relation-types). Новая компания получает шесть стартовых типов с постоянным system_key: customer (Клиент), prospect (Потенциальный клиент), partner (Партнёр), supplier (Поставщик), competitor (Конкурент), other (Другое). Их можно переименовать, перекрасить и архивировать, но не удалить (422 relation_type_system); system_key не меняется и в запросах не принимается (422), поэтому по нему удобно писать условия в интеграции. У своих типов system_key равен null.

  • Тип: id, name (до 100 символов, уникально без учёта регистра среди неархивных, иначе 422 relation_type_name_taken), color (green, blue, violet, amber, red, gray), system_key, position, is_archived, organizations_count (неудалённые организации этого типа; приходит в ответах списка и смены порядка), created_at, updated_at.
  • GET — типы по порядку в data.items, без архивных; include_archived=true добавляет архивные. POST с name и color — 201, в data созданный тип. Неархивных типов не больше 50: 422 relation_types_limit.
  • PATCH /organization-relation-types/{id} — name, color, is_archived (архив и возврат из архива). Архивный тип нельзя назначить новой организации, но у тех, кто уже на нём стоит, он остаётся.
  • DELETE — 204. Тип, который стоит хотя бы у одной организации (включая удалённые), не удаляется: 409 с кодом relation_type_in_use и organizations_count; такой тип архивируют.
  • PUT /organization-relation-types/order с ids — все id справочника компании, включая архивные, каждый по одному разу, в новом порядке. Неполный, лишний или чужой набор: 422 relation_type_order_mismatch на поле ids. Ответ: весь справочник с архивными в data.items.
  • Тип другой компании или id в неверном формате: 404 {"data": {"message": "Relation type not found."}}. Правка справочника событий вебхуков не отправляет; смена типа у организации приходит в organization.updated с changed_fields: ["relation_type_id"].

Банковские счета

Счета организации пишутся через /organizations/{id}/bank-accounts, а читаются в карточке (bank_accounts); отдельного эндпоинта списка счетов нет. Счёт: id, bank_name (до 255 символов), bank_bik (БИК или SWIFT банка), bank_account (полный номер счёта или IBAN), currency (KZT, KGS, RUB, USD, EUR; если не передана, берётся валюта сделок компании), is_default, position (0–1000; по умолчанию в конец), created_at, updated_at. Номер хранится зашифрованным и в журнал аудита попадают только последние четыре символа.

  • В bank_account и bank_bik убираются пробелы, точки и дефисы, буквы переводятся в верхний регистр. После этого номер — 8–34 латинские буквы и цифры (иначе 422 bank_account_invalid_format), код банка — 6–11 (иначе 422 bank_bik_invalid_format). Значения в тексте ошибок не возвращаются.
  • POST (bank_account обязателен) — 201, в data созданный счёт; PATCH .../bank-accounts/{account} — только переданные поля, в data счёт; DELETE — 204. Не больше 20 счетов у организации: 422 bank_accounts_limit.
  • Счёт по умолчанию у организации один. Первый счёт становится им сам; is_default: true снимает флаг с прежнего; is_default: false у единственного счёта ничего не меняет, а у одного из нескольких передаёт флаг самому раннему из оставшихся (по position, затем id); при удалении счёта по умолчанию флаг тоже переходит к самому раннему. Если два запроса одновременно меняют счёт по умолчанию, проигравший получает 409 bank_account_default_conflict; запрос можно повторить.
  • Организация не найдена: 404 Organization not found.; счёт другой организации, другой компании или id в неверном формате: 404 Bank account not found..
  • Каждое изменение счёта отправляет organization.updated с changed_fields: ["bank_accounts"]. Сами счета в тело вебхука не входят: интегратор с правом на счета дозапрашивает карточку.

Удаление

Удаление мягкое. Привязки контактов и сделок сохраняются, но пока организация удалена, у этих контактов и сделок organization и organization_id равны null, а сама организация отвечает 404. Эндпоинта восстановления в API нет. Ответ: {"data": {"message": "Organization deleted."}}.

Контакты и сделки организации

GET /organizations/{id}/contacts — привязанные контакты (page, perPage от 1 до 100, по умолчанию 20; порядок по имени), элементы в формате ресурса контакта. POST /organizations/{id}/contacts с contact_ids (от 1 до 100 разных id неудалённых и необъединённых контактов компании, иначе 422 на contact_ids.N) привязывает контакты пачкой; контакт другой организации переносится. Ответ {"data": {"message": "Contacts linked.", "linked_contact_ids": [...]}} перечисляет только контакты, у которых организация действительно поменялась. По каждому из них уходит contact.updated с data.changed_fields: ["organization_id"]; привязка пачкой не запускает сценарии и не синхронизирует контакты с Bitrix24/amoCRM. DELETE /organizations/{id}/contacts/{contact} отвязывает один контакт как обычную правку контакта; контакт не из этой организации или недоступный пользователю: 404.

GET /organizations/{id}/deals — сделки организации, видимые пользователю по его уровню доступа, без лидов из «Неразобранного»: status (open, won, lost), page, perPage от 1 до 100 (по умолчанию 20), порядок по updated_at по убыванию, элементы в формате ресурса сделки.

Свои поля организации пишутся через PUT /organizations/{id}/custom-fields с телом custom_fields в том же формате, что у контакта. Ответ: {"data": {"message": "Custom fields updated.", "organization": {...}}}. Изменение уходит событием organization.updated с changed_fields вида custom.<key>.

Экспорт, импорт, сценарии и MCP

С 2026-11-17: выгрузка организаций — POST /exports с type=organizations (фильтры как у GET /organizations, банковских счетов в файле нет; см. группу «Экспорт»). В импорте контактов из CSV колонки organization и organization_tax_id находят или создают организацию и привязывают к ней контакт (см. «Импорт контактов из CSV» в группе «Контакты»). В сценариях есть блок crm-find-organization и сущность organization в блоке «Получить значение поля». Через MCP организации создаются, правятся и привязываются к контактам инструментами create_organization, update_organization и link_contact_to_organization (см. руководство по MCP); банковские счета MCP не читает и не пишет.

Ошибки и лимиты

  • 403 — нет права, компания не типа «бизнес» или embed-токен.
  • 404 {"data": {"message": "Organization not found."}} — организация другой компании, удалённая или id в неверном формате.
  • 409 organization_tax_id_taken — БИН/ИНН занят другой организацией компании, в ответе existing_organization_id.
  • 409 relation_type_in_use — удаляемый тип отношений стоит у организаций, в ответе organizations_count; 409 bank_account_default_conflict — одновременная смена счёта по умолчанию.
  • 422 — ошибки валидации в формате {"data": {"message", "errors": {поле: [код]}}}: tax_id_invalid_format, phone_invalid, ответственный не из компании, неверные contact_ids, relation_type_not_found, relation_type_archived, relation_type_name_taken, relation_types_limit, relation_type_order_mismatch, relation_type_system, bank_account_invalid_format, bank_bik_invalid_format, bank_accounts_limit.
  • 429 — список, подбор, подсказки формы, справочник типов (чтение), контакты и сделки организации: 120 запросов в минуту на пользователя; создание, правка, удаление, привязка и отвязка, запись справочника типов и счетов: 60 в минуту; карточка: общий лимит тяжёлых запросов API-токена (120 в минуту); свои поля: лимит записи значений своих полей.

Эндпоинты

МетодПуть
GET/v1/organizations

Список организаций компании (query: page, perPage 1–100, search, responsible_user_id = id|none, has_tax_id, relation_type_id = id|none, country, sortBy = name|created_at|updated_at|contacts_count|relation_type|cf:<key>, sortDir, cf[N][key|op|value]). Ответ: data.items + data.pagination.

GET/v1/organizations/lookup

Подбор организации по названию или БИН/ИНН (query: q до 100 символов). Ответ: data.items — до 20 записей {id, name, tax_id}.

GET/v1/organizations/legal-forms

Подсказки организационно-правовой формы: до 20 самых частых значений legal_form в компании. Ответ: data.items — массив строк.

POST/v1/organizations

Создать организацию (body: name, legal_name?, tax_id?, country_code?, relation_type_id?, legal_form?, registration_code?, extra_codes?, signatory_name?, signatory_position?, signatory_basis?, phone?, email?, website?, address?, comments?, responsible_user_id?) — 201, data — карточка. 409 organization_tax_id_taken.

GET/v1/organizations/{organization}

Карточка организации: поля и реквизиты, relation_type, свои поля с custom_fields_meta, contacts_count, (при праве deal.view) open_deals_count и open_deals_amount, (при праве organization_bank_account.view) bank_accounts.

PATCH/v1/organizations/{organization}

Изменить поля организации (только переданные). Ответ — карточка. 409 organization_tax_id_taken.

DELETE/v1/organizations/{organization}

Удалить организацию (мягко; привязки сохраняются, но читаются как null).

PUT/v1/organizations/{organization}/custom-fields

Записать значения своих полей организации (body: custom_fields). Ответ: data.message и data.organization.

GET/v1/organizations/{organization}/contacts

Контакты организации (query: page, perPage 1–100). Ответ: data.items + data.pagination. Нужно ещё право contact.view.

POST/v1/organizations/{organization}/contacts

Привязать контакты пачкой (body: contact_ids — 1–100 id). Ответ: data.linked_contact_ids. Нужно ещё право contact.update.

DELETE/v1/organizations/{organization}/contacts/{contact}

Отвязать один контакт от организации. Нужно ещё право contact.update.

GET/v1/organizations/{organization}/deals

Сделки организации, видимые пользователю (query: status = open|won|lost, page, perPage 1–100). Ответ: data.items + data.pagination. Нужны право deal.view и тариф со сделками.

POST/v1/organizations/{organization}/bank-accounts

Добавить банковский счёт (body: bank_account, bank_name?, bank_bik?, currency?, is_default?, position?) — 201, data — счёт. Нужны ещё organization.update и organization_bank_account.view.

PATCH/v1/organizations/{organization}/bank-accounts/{account}

Изменить банковский счёт (только переданные поля). Ответ: data — счёт. 409 bank_account_default_conflict. Нужны ещё organization.update и organization_bank_account.view.

DELETE/v1/organizations/{organization}/bank-accounts/{account}

Удалить банковский счёт — 204; флаг «по умолчанию» переходит к самому раннему из оставшихся. Нужны ещё organization.update и organization_bank_account.view.

GET/v1/organization-relation-types

Справочник типов отношений по порядку (query: include_archived). Ответ: data.items с organizations_count.

POST/v1/organization-relation-types

Создать тип отношений (body: name, color) — 201, data — тип. 422 relation_type_name_taken, relation_types_limit.

PUT/v1/organization-relation-types/order

Новый порядок справочника (body: ids — все id компании, включая архивные). Ответ: data.items. 422 relation_type_order_mismatch.

PATCH/v1/organization-relation-types/{relationType}

Переименовать, перекрасить, архивировать или вернуть из архива (body: name?, color?, is_archived?). Ответ: data — тип.

DELETE/v1/organization-relation-types/{relationType}

Удалить тип отношений — 204. 409 relation_type_in_use (с organizations_count), 422 relation_type_system для стартового типа.

Примеры

Создание организации

Запрос

bash
curl -X POST "https://api.aisar.app/v1/organizations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Альфа Трейд",
    "legal_name": "ТОО «Альфа Трейд»",
    "tax_id": "1203 4056 7891",
    "country_code": "KZ",
    "relation_type_id": 31,
    "legal_form": "ТОО",
    "signatory_name": "Иван Петров",
    "signatory_position": "Директор",
    "signatory_basis": "Устава",
    "email": "Office@Example.com",
    "website": "https://example.com",
    "responsible_user_id": 7
  }'

Ответ

json
{
  "data": {
    "id": 12,
    "name": "Альфа Трейд",
    "legal_name": "ТОО «Альфа Трейд»",
    "tax_id": "120340567891",
    "country_code": "KZ",
    "relation_type_id": 31,
    "relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
    "legal_form": "ТОО",
    "registration_code": null,
    "extra_codes": null,
    "signatory_name": "Иван Петров",
    "signatory_position": "Директор",
    "signatory_basis": "Устава",
    "phone": null,
    "email": "office@example.com",
    "website": "https://example.com",
    "address": null,
    "comments": null,
    "responsible_user_id": 7,
    "responsible_user": { "id": 7, "name": "Anna Smith" },
    "source": "api",
    "contacts_count": 0,
    "open_deals_count": 0,
    "open_deals_amount": [],
    "bank_accounts": [],
    "custom_fields": {},
    "custom_fields_meta": {},
    "created_at": "2026-11-17T09:30:00.000000Z",
    "updated_at": "2026-11-17T09:30:00.000000Z"
  }
}

БИН/ИНН уже занят

Запрос

bash
curl -X POST "https://api.aisar.app/v1/organizations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Альфа", "tax_id": "120340567891", "country_code": "KZ" }'

Ответ

json
{
  "data": {
    "message": "An organization with this tax id already exists.",
    "code": "organization_tax_id_taken",
    "existing_organization_id": 12
  }
}

Список с фильтром и сортировкой

Запрос

bash
curl "https://api.aisar.app/v1/organizations?search=%D0%B0%D0%BB%D1%8C%D1%84%D0%B0&has_tax_id=true&sortBy=name&sortDir=asc&perPage=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "items": [
      {
        "id": 12,
        "name": "Альфа Трейд",
        "legal_name": "ТОО «Альфа Трейд»",
        "tax_id": "120340567891",
        "country_code": "KZ",
        "relation_type_id": 31,
        "relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
        "legal_form": "ТОО",
        "phone": "+12025550142",
        "email": "office@example.com",
        "website": "https://example.com",
        "address": null,
        "comments": "Оптовый клиент, договор до конца года",
        "responsible_user_id": 7,
        "responsible_user": { "id": 7, "name": "Anna Smith" },
        "source": "manual",
        "contacts_count": 3,
        "open_deals_count": 2,
        "custom_fields": { "segment": "wholesale" },
        "created_at": "2026-11-17T09:30:00.000000Z",
        "updated_at": "2026-11-17T10:05:00.000000Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 25, "total": 1, "lastPage": 1 }
  }
}

Привязка контактов

Запрос

bash
curl -X POST "https://api.aisar.app/v1/organizations/12/contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": [45, 46, 47] }'

Ответ

json
{
  "data": {
    "message": "Contacts linked.",
    "linked_contact_ids": [45, 47]
  }
}

Банковский счёт

Запрос

bash
curl -X POST "https://api.aisar.app/v1/organizations/12/bank-accounts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_name": "Example Bank",
    "bank_bik": "EXMPKZKA",
    "bank_account": "KZ00 0000 0000 0000 0001",
    "currency": "KZT"
  }'

Ответ

json
{
  "data": {
    "id": 5,
    "bank_name": "Example Bank",
    "bank_bik": "EXMPKZKA",
    "bank_account": "KZ000000000000000001",
    "currency": "KZT",
    "is_default": true,
    "position": 1,
    "created_at": "2026-11-17T09:40:00.000000Z",
    "updated_at": "2026-11-17T09:40:00.000000Z"
  }
}

Свой тип отношений

Запрос

bash
curl -X POST "https://api.aisar.app/v1/organization-relation-types" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Дистрибьютор", "color": "blue" }'

Ответ

json
{
  "data": {
    "id": 37,
    "name": "Дистрибьютор",
    "color": "blue",
    "system_key": null,
    "position": 7,
    "is_archived": false,
    "created_at": "2026-11-17T09:45:00.000000Z",
    "updated_at": "2026-11-17T09:45:00.000000Z"
  }
}

Тип отношений используется

Запрос

bash
curl -X DELETE "https://api.aisar.app/v1/organization-relation-types/37" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "message": "The relation type is used by organizations; archive it instead.",
    "code": "relation_type_in_use",
    "organizations_count": 4
  }
}

Подбор по названию или БИН/ИНН

Запрос

bash
curl "https://api.aisar.app/v1/organizations/lookup?q=120340567891" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "items": [
      { "id": 12, "name": "Альфа Трейд", "tax_id": "120340567891" }
    ]
  }
}

Подсказки организационно-правовой формы

Запрос

bash
curl "https://api.aisar.app/v1/organizations/legal-forms" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "items": ["ТОО", "ИП", "АО"]
  }
}

Карточка организации

Запрос

bash
curl "https://api.aisar.app/v1/organizations/12" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "id": 12,
    "name": "Альфа Трейд",
    "legal_name": "ТОО «Альфа Трейд»",
    "tax_id": "120340567891",
    "country_code": "KZ",
    "relation_type_id": 31,
    "relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
    "legal_form": "ТОО",
    "registration_code": null,
    "extra_codes": null,
    "signatory_name": "Иван Петров",
    "signatory_position": "Директор",
    "signatory_basis": "Устава",
    "phone": "+12025550142",
    "email": "office@example.com",
    "website": "https://example.com",
    "address": null,
    "comments": "Оптовый клиент, договор до конца года",
    "responsible_user_id": 7,
    "responsible_user": { "id": 7, "name": "Anna Smith" },
    "source": "manual",
    "contacts_count": 3,
    "open_deals_count": 2,
    "open_deals_amount": [
      { "currency": "KZT", "amount": "1500000.00" }
    ],
    "bank_accounts": [
      {
        "id": 5,
        "bank_name": "Example Bank",
        "bank_bik": "EXMPKZKA",
        "bank_account": "KZ000000000000000001",
        "currency": "KZT",
        "is_default": true,
        "position": 1,
        "created_at": "2026-11-17T09:40:00.000000Z",
        "updated_at": "2026-11-17T09:40:00.000000Z"
      }
    ],
    "custom_fields": { "segment": "wholesale" },
    "custom_fields_meta": {
      "segment": { "updated_at": "2026-11-17T10:05:00.000000Z", "source": "manual", "updated_by": { "id": 7, "name": "Anna Smith" } }
    },
    "created_at": "2026-11-17T09:30:00.000000Z",
    "updated_at": "2026-11-17T10:05:00.000000Z"
  }
}

Изменить организацию

Запрос

bash
curl -X PATCH "https://api.aisar.app/v1/organizations/12" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+12025550143", "address": "Example street 1" }'

Ответ

json
{
  "data": {
    "id": 12,
    "name": "Альфа Трейд",
    "phone": "+12025550143",
    "address": "Example street 1",
    "...": "...",
    "updated_at": "2026-11-17T11:00:00.000000Z"
  }
}

Удалить организацию

Запрос

bash
curl -X DELETE "https://api.aisar.app/v1/organizations/12" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "message": "Organization deleted."
  }
}

Записать свои поля организации

Запрос

bash
curl -X PUT "https://api.aisar.app/v1/organizations/12/custom-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "segment": "retail" } }'

Ответ

json
{
  "data": {
    "message": "Custom fields updated.",
    "organization": {
      "id": 12,
      "name": "Альфа Трейд",
      "...": "...",
      "custom_fields": { "segment": "retail" },
      "custom_fields_meta": {
        "segment": { "updated_at": "2026-11-17T11:10:00.000000Z", "source": "api", "updated_by": { "id": 7, "name": "Anna Smith" } }
      }
    }
  }
}

Контакты организации

Запрос

bash
curl "https://api.aisar.app/v1/organizations/12/contacts?page=1&perPage=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "items": [
      {
        "id": 45,
        "displayName": "Ivan Petrov",
        "firstName": "Ivan",
        "lastName": "Petrov",
        "organization_id": 12,
        "organization": { "id": 12, "name": "Альфа Трейд" },
        "phones": [{ "phone": "+12025550143", "type": "mobile" }],
        "...": "..."
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "lastPage": 1 }
  }
}

Отвязать контакт

Запрос

bash
curl -X DELETE "https://api.aisar.app/v1/organizations/12/contacts/45" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "message": "Contact unlinked."
  }
}

Открытые сделки организации

Запрос

bash
curl "https://api.aisar.app/v1/organizations/12/deals?status=open&perPage=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "items": [
      {
        "id": 301,
        "contact_id": 45,
        "organization_id": 12,
        "organization": { "id": 12, "name": "Альфа Трейд" },
        "funnel_id": 3,
        "funnel_stage_id": 11,
        "title": "Поставка оборудования",
        "amount": "1500000.00",
        "currency": "KZT",
        "status": "open",
        "contact": { "id": 45, "display_name": "Ivan Petrov", "avatar": null },
        "responsible_user": { "id": 7, "name": "Anna Smith" },
        "...": "..."
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 2, "lastPage": 1 }
  }
}

Изменить банковский счёт

Запрос

bash
curl -X PATCH "https://api.aisar.app/v1/organizations/12/bank-accounts/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "bank_name": "Example Bank Central", "currency": "USD" }'

Ответ

json
{
  "data": {
    "id": 5,
    "bank_name": "Example Bank Central",
    "bank_bik": "EXMPKZKA",
    "bank_account": "KZ000000000000000001",
    "currency": "USD",
    "is_default": true,
    "position": 1,
    "created_at": "2026-11-17T09:40:00.000000Z",
    "updated_at": "2026-11-17T11:20:00.000000Z"
  }
}

Удалить банковский счёт (204)

Запрос

bash
curl -X DELETE "https://api.aisar.app/v1/organizations/12/bank-accounts/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Справочник типов отношений

Запрос

bash
curl "https://api.aisar.app/v1/organization-relation-types?include_archived=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json
{
  "data": {
    "items": [
      { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "position": 1, "is_archived": false, "organizations_count": 18, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T09:00:00.000000Z" },
      { "id": 32, "name": "Потенциальный клиент", "color": "blue", "system_key": "prospect", "position": 2, "is_archived": false, "organizations_count": 6, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T09:00:00.000000Z" },
      { "id": 37, "name": "Дистрибьютор", "color": "blue", "system_key": null, "position": 7, "is_archived": true, "organizations_count": 0, "created_at": "2026-11-17T09:45:00.000000Z", "updated_at": "2026-11-17T12:00:00.000000Z" },
      { "...": "..." }
    ]
  }
}

Порядок типов отношений

Запрос

bash
curl -X PUT "https://api.aisar.app/v1/organization-relation-types/order" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [32, 31, 33, 34, 35, 36, 37] }'

Ответ

json
{
  "data": {
    "items": [
      { "id": 32, "name": "Потенциальный клиент", "color": "blue", "system_key": "prospect", "position": 1, "is_archived": false, "organizations_count": 6, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T12:10:00.000000Z" },
      { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "position": 2, "is_archived": false, "organizations_count": 18, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T12:10:00.000000Z" },
      { "...": "..." }
    ]
  }
}

Архивировать тип отношений

Запрос

bash
curl -X PATCH "https://api.aisar.app/v1/organization-relation-types/37" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "is_archived": true }'

Ответ

json
{
  "data": {
    "id": 37,
    "name": "Дистрибьютор",
    "color": "blue",
    "system_key": null,
    "position": 7,
    "is_archived": true,
    "created_at": "2026-11-17T09:45:00.000000Z",
    "updated_at": "2026-11-17T12:00:00.000000Z"
  }
}