Как получить данные контрагента из СБИС API в JSON

Если нужно автоматически получить данные контрагента из СБИС, проверить ИНН и КПП, найти идентификатор участника ЭДО или передать реквизиты в 1С, удобнее работать через API. В этой статье разбираем метод «СБИС.ИнформацияОКонтрагенте», формат JSON-RPC, структуру запроса и ответа, авторизацию и типовую архитектуру интеграции СБИС с 1С.

Один из самых частых сценариев интеграции СБИС с учётной системой выглядит просто: в 1С появляется контрагент, а системе нужно автоматически получить его реквизиты и понять, как он представлен в СБИС.

Делать это вручную неудобно. Пользователь открывает карточку организации, ищет контрагента в СБИС, сверяет ИНН и КПП, проверяет состояние ЭДО и затем переносит данные обратно в 1С.

Через API этот процесс можно превратить в обычный машинный обмен:

Данные контрагента: СБИС → 1С: 1С → Integration Service → СБИС API → JSON → 1С
Данные контрагента: СБИС → 1С. Нажмите на схему, чтобы увеличить.
Для получения информации о контрагенте в API СБИС используется команда «СБИС.ИнформацияОКонтрагенте». Она позволяет получить данные контрагента по реквизитам и, в том числе, идентификатор участника электронного документооборота.

Ниже будем использовать название «СБИС», потому что именно так называется API-команда и по этому запросу чаще всего ищут информацию. В актуальной документации сервис также называется Saby.

Что можно получить из СБИС API по контрагенту

Метод «СБИС.ИнформацияОКонтрагенте» предназначен для получения информации о контрагенте. В зависимости от переданных параметров и режима вывода можно получить реквизиты организации и идентификатор участника ЭДО.

ИНН

ИНН юридического лица или соответствующий реквизит для другого типа контрагента.

КПП

КПП юридического лица, если он применяется для конкретного контрагента.

Название

Наименование организации, которое можно использовать при сопоставлении с карточкой в 1С.

ID участника ЭДО

Идентификатор участника электронного документооборота, необходимый в ряде интеграционных сценариев.

Официальная документация СБИС описывает этот метод как способ получить информацию о контрагенте по ИНН и КПП, в том числе идентификатор участника документооборота. При отсутствии карточки по переданным реквизитам сервис может создать запись контрагента и заполнить реквизиты данными сервиса проверки партнёров.

Как устроен СБИС API

API СБИС использует JSON-RPC. Для запросов к API передаётся JSON-объект, содержащий версию протокола, название метода, параметры и идентификатор запроса.

Для рассмотренной команды ЭДО документация указывает сервисный JSON-RPC endpoint:

https://online.sbis.ru/service/?srv=1

В заголовке передаётся токен доступа:

X-SBISAccessToken: YOUR-TOKEN

У других API Saby могут быть другие endpoint и контракты. Здесь используется конкретно СБИС.ИнформацияОКонтрагенте; адрес команды нужно брать из её документации, а не из примера произвольного API Gateway.

Авторизация в СБИС API

Для нового API Gateway Saby документация описывает сервисную авторизацию: приложению выдаются app_client_id, app_secret и secret_key, после чего выполняется запрос на получение токена.

curl -X POST 'https://online.saby.ru/oauth/service/' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "app_client_id": "your_app_client_id",
    "app_secret": "your_app_secret",
    "secret_key": "your_secret_key"
  }'

В ответе возвращается токен доступа, который затем используется при вызовах API. Токен не стоит хранить в коде 1С, репозитории или конфигурационном файле, доступном всем пользователям.

На практике для интеграции с 1С лучше вынести секреты и работу с авторизацией в отдельный интеграционный сервис.

Запрос данных контрагента по ИНН и КПП

Для юридического лица в запросе передаются реквизиты блока СвЮЛ. В типовом сценарии это ИНН, КПП и название организации.

Упрощённая структура JSON выглядит так:

{
  "jsonrpc": "2.0",
  "method": "СБИС.ИнформацияОКонтрагенте",
  "params": {
    "Участник": {
      "СвЮЛ": {
        "ИНН": "7701234567",
        "КПП": "770101001",
        "Название": "ООО «Пример»"
      }
    }
  },
  "id": 1
}

Это именно пример структуры запроса. Набор обязательных и дополнительных параметров нужно сверять с актуальной документацией конкретной команды и используемой версией API.

Что приходит в ответе

API возвращает JSON-RPC-ответ. При успешном выполнении результат находится в поле result.

Упрощённо ответ можно представить так:

{
  "jsonrpc": "2.0",
  "result": {
    "СвЮЛ": {
      "ИНН": "7701234567",
      "КПП": "770101001",
      "Название": "ООО «Пример»"
    },
    "Идентификатор": "2BE-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "id": 1
}

Точный состав возвращаемого объекта зависит от параметров запроса. Например, документация описывает дополнительные режимы получения идентификаторов участников ЭДО.

Не стоит проектировать интеграцию вокруг одного поля «Идентификатор». Сначала определите, зачем он нужен вашему бизнес-процессу и как вы будете обрабатывать изменение или отсутствие идентификатора.

Что такое идентификатор участника ЭДО

Идентификатор участника электронного документооборота — это не ИНН и не КПП. Это отдельный идентификатор участника ЭДО, который используется при обмене электронными документами.

В документации Saby приведён формат, в котором идентификатор содержит префикс оператора и уникальную часть. Например:

2BE-c662b8816e224776a9b8517b9bacc8b4

Именно поэтому при интеграции нельзя использовать ИНН как замену ID участника ЭДО. ИНН идентифицирует организацию в налоговом контуре, а идентификатор ЭДО используется для адресации участника электронного документооборота.

Как получить ID ЭДО контрагента по ИНН

Типовой сценарий выглядит следующим образом:

  1. В 1С появляется или изменяется карточка контрагента.
  2. Интеграционный сервис получает ИНН и КПП.
  3. Сервис вызывает «СБИС.ИнформацияОКонтрагенте».
  4. СБИС возвращает реквизиты и доступную информацию об участнике ЭДО.
  5. Интеграционный слой сохраняет необходимые данные в 1С.
  6. При отправке документа 1С использует сохранённые данные в соответствии с логикой интеграции.
Получение ID ЭДО по ИНН и КПП: 1С → Integration Service → Saby / СБИС → Integration Service → 1С
Получение ID ЭДО по ИНН и КПП. Нажмите на схему, чтобы увеличить.

В таком варианте 1С не должна самостоятельно заниматься всеми деталями HTTP, авторизации, retry и обработки ошибок. Это особенно важно, если интеграция постепенно расширяется и начинает работать не только с контрагентами.

Как обработать ответ в PHP

Если между 1С и СБИС используется Symfony-сервис, JSON можно обработать обычным HTTP-клиентом. Например, минимальная структура запроса в PHP может выглядеть так:

$payload = [
    'jsonrpc' => '2.0',
    'method' => 'СБИС.ИнформацияОКонтрагенте',
    'params' => [
        'Участник' => [
            'СвЮЛ' => [
                'ИНН' => $inn,
                'КПП' => $kpp,
                'Название' => $name,
            ],
        ],
    ],
    'id' => 1,
];

$response = $httpClient->request('POST', $url, [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-SBISAccessToken' => $token,
    ],
    'json' => $payload,
]);

$data = $response->toArray();

После получения ответа не стоит сразу записывать весь JSON в 1С. Лучше преобразовать его во внутренний DTO или нормализованный объект интеграционного слоя.

Почему лучше делать нормализацию между СБИС и 1С

Прямая схема:

Обмен JSON между 1С и СБИС: 1С → JSON СБИС → 1С
Обмен JSON между 1С и СБИС. Нажмите на схему, чтобы увеличить.

подходит для небольшого скрипта. Но в рабочей интеграции быстро появляются дополнительные требования: логирование, повторные запросы, маппинг идентификаторов, обработка филиалов, разные форматы данных и контроль ошибок.

Поэтому лучше:

Нормализация ответа Saby для 1С: 1С → Integration Layer → Saby Adapter → Saby API → Saby Adapter → Normalized Contractor DTO → 1С
Нормализация ответа Saby для 1С. Нажмите на схему, чтобы увеличить.

Например, внутренний объект приложения может содержать:

{
  "inn": "7701234567",
  "kpp": "770101001",
  "name": "ООО «Пример»",
  "edoId": "2BE-xxxxxxxx",
  "source": "saby",
  "receivedAt": "2026-09-18T10:00:00+03:00"
}

Тогда остальная система не зависит от конкретного JSON-формата внешнего API.

Что делать, если контрагент не найден

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

По документации СБИС, если контрагент не найден по переданным реквизитам кроме идентификатора, сервис может создать его в списке контрагентов и заполнить реквизиты данными сервиса проверки партнёров.

В интеграции всё равно стоит разделить несколько случаев:

  • контрагент найден и идентификатор ЭДО получен;
  • контрагент найден, но идентификатор отсутствует;
  • контрагент найден, но данные требуют дополнительной обработки;
  • контрагент не найден;
  • СБИС вернул ошибку авторизации или параметров;
  • внешний сервис временно недоступен.

Что делать, если у контрагента нет ID ЭДО

Наличие карточки организации и наличие активного участия в ЭДО — разные вещи. Поэтому пустой идентификатор нельзя автоматически трактовать как ошибку API.

В документации СБИС отдельно описан сценарий, когда идентификатор отсутствует, например если контрагент не подключён к электронному документообороту.

Для 1С это означает, что состояние нужно хранить явно:

Контрагент: идентификация и статус ЭДО. ИНН, КПП, название, Saby ID и варианты статуса ЭДО: active, not_found, not_connected, error
Контрагент: идентификация и статус ЭДО. Нажмите на схему, чтобы увеличить.

Почему нельзя просто каждый раз запрашивать СБИС из 1С

На маленьком объёме это может работать. Но при росте количества документов и контрагентов такой подход создаёт лишнюю связанность.

Например, при проведении каждого документа 1С может начать делать внешний HTTP-запрос. Если СБИС отвечает медленно или временно недоступен, это уже влияет на пользовательский процесс.

Для критичных операций лучше разделять синхронную и асинхронную работу:

Событие 1С → очередь → СБИС: Создание / изменение контрагента → 1С событие → Queue / Job → Saby Integration Service → СБИС.ИнформацияОКонтрагенте → Normalize → 1С
Событие 1С → очередь → СБИС. Нажмите на схему, чтобы увеличить.

Пользователь продолжает работать в 1С, а внешний обмен выполняется отдельно.

Retry: что делать при временной ошибке СБИС API

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

Ситуация Что делать
Неверные параметры Не повторять автоматически, исправить запрос
Ошибка авторизации Обновить токен/проверить credentials
Временная ошибка сервиса Retry с backoff
Timeout Повторить ограниченное число раз и отправить в очередь ошибок
Неожиданный JSON Залогировать ответ и остановить автоматическую обработку

Как не сломать интеграцию из-за идентификаторов

В документации СБИС есть важное замечание: идентификатор участника ЭДО может изменяться в процессе работы. Поэтому архитектура не должна относиться к нему как к вечному неизменяемому первичному ключу контрагента.

Надёжнее разделять:

ИНН + КПП → актуальный ID ЭДО: ИНН + КПП → Идентификация организации → Получение актуального ID ЭДО → Использование ID в конкретной операции
ИНН + КПП → актуальный ID ЭДО. Нажмите на схему, чтобы увеличить.

То есть ИНН/КПП остаются частью бизнес-идентификации организации, а ID участника ЭДО рассматривается как технический идентификатор внешнего контура.

Интеграция СБИС API с 1С: правильная архитектура

Если задача ограничивается одним запросом, отдельный сервис может показаться избыточным. Но в реальном проекте вокруг СБИС обычно быстро появляются другие операции: отправка документов, получение статусов, обработка ошибок, сопоставление контрагентов, работа с ЭДО и интеграция с несколькими системами.

1С → Saby Adapter → Saby API: 1С → Integration API → Saby / СБИС Adapter → Saby API
1С → Saby Adapter → Saby API. Нажмите на схему, чтобы увеличить.

Такой слой позволяет не размазывать интеграционную логику по формам и обработкам 1С. При необходимости его можно реализовать на Symfony/PHP или Go.

Как связать получение контрагента с ЭДО

Один из практических сценариев — автоматическая подготовка контрагента к отправке электронного документа.

  1. В 1С создаётся или выбирается контрагент.
  2. Система получает ИНН и КПП.
  3. Integration Layer запрашивает данные в СБИС.
  4. Проверяется наличие идентификатора участника ЭДО.
  5. Результат сохраняется в 1С.
  6. При отправке документа используется актуальная информация о получателе.

Сам метод «СБИС.ИнформацияОКонтрагенте» также используется как часть сценариев подготовки электронных документов: официальная документация указывает, что через него можно получить идентификатор участника ЭДО.

Чего не стоит делать

Не хранить токен в открытом коде

Секреты должны храниться в защищённом конфигурационном хранилище или окружении сервиса.

Не делать бесконечный retry

Количество повторов должно быть ограничено, а ошибки — попадать в наблюдаемый контур.

Не смешивать внешний JSON с моделью 1С

Лучше иметь отдельный слой преобразования и явный mapping.

Не терять аудит

Для интеграции полезно хранить факт запроса, результат и ошибку без сохранения лишних секретов.

Минимальный MVP интеграции СБИС и 1С

Если задача — быстро проверить гипотезу интеграции, не нужно сразу строить весь универсальный коннектор.

Минимальный контур может состоять из пяти частей:

  1. Авторизация — получение и безопасное хранение токена.
  2. Contractor Client — вызов «СБИС.ИнформацияОКонтрагенте».
  3. DTO / mapping — преобразование JSON СБИС во внутреннюю модель.
  4. 1С adapter — чтение и запись реквизитов.
  5. Logging — журнал запросов и ошибок.

После этого можно добавлять очередь, retry, мониторинг, кэширование, другие методы API и полноценную панель состояния интеграции.

Итог

Получить данные контрагента из СБИС API в JSON технически несложно: используется JSON-RPC, передаются реквизиты контрагента, а в ответ приходит структурированный JSON.

Основной метод для этого сценария — «СБИС.ИнформацияОКонтрагенте». Он позволяет получать сведения о контрагенте по реквизитам и использовать результат, в том числе для работы с идентификатором участника ЭДО.

Но в production главная задача находится не в самом HTTP-запросе. Нужно правильно организовать авторизацию, mapping, обработку отсутствующего контрагента, retry, аудит и связь с 1С.

Хорошая интеграция СБИС и 1С — это не «отправили JSON и получили JSON». Это контролируемый контур, в котором 1С отвечает за учёт, СБИС — за внешний ЭДО, а Integration Layer связывает эти системы и управляет ошибками, данными и повторными запросами.

По теме: посмотрите также СБИС API: OAuth2, retry и что не написано в официальной документации, Как мы автоматизировали отправку УПД из 1С в СБИС через cron и материалы про интеграцию 1С с внешними системами.

Что проверить на пилоте

Условия применимости. Команда информации о контрагенте может создать отсутствующую карточку. Поэтому её нельзя считать безусловно чистой операцией чтения при проектировании автоматических проверок.

Проверочный сценарий. Проверьте организацию с несколькими КПП, неизвестного контрагента и отсутствие действующего ID ЭДО. Пример ответа упрощён; необязательное поле нельзя считать всегда заполненным.

Как оценить результат. Считайте долю однозначных соответствий с 1С и число ручных проверок. ID участника может меняться: фиксируйте момент проверки и обновляйте его по правилам оператора.

Проверка источников: . Проверенные интерфейсы и условия: Saby: СБИС.ИнформацияОКонтрагенте — параметры и результат.

ModernERP Integration Monitor

Узнавайте о сбоях обменов раньше, чем о них сообщат сотрудники

Ошибки, задержки и история обменов между 1С, CRM, WMS и API — в одном сервисе. Контролируйте критичные интеграции с Integration Monitor.

Посмотреть Integration Monitor ↗

Работает на наших серверах · До 15 интеграций · 90 дней истории