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

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

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

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

1С
 ↓
Integration Service
 ↓
СБИС API
 ↓
JSON
 ↓
1С

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

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

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

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

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

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

В современной документации Saby для API Gateway используется POST-запрос на адрес вида:

https://online.saby.ru/apigate/v1/

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

X-SBISAccessToken: YOUR-TOKEN

При этом для отдельных API ЭДО в документации СБИС встречается сервисный интерфейс с адресом https://online.sbis.ru/service/?srv=1 и JSON-RPC. Поэтому перед реализацией конкретного метода важно сверять актуальный раздел документации и используемый контур API, а не переносить URL из старого примера в production без проверки.

Авторизация в СБИС 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С использует сохранённые данные в соответствии с логикой интеграции.

1С
 │
 │ ИНН + КПП
 ▼
Integration Service
 │
 │ СБИС.ИнформацияОКонтрагенте
 ▼
Saby / СБИС
 │
 │ JSON
 ▼
Integration Service
 │
 │ нормализация
 ▼
1С

В таком варианте 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С

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

1С → JSON СБИС → 1С

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

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

1С
 ↓
Integration Layer
 ↓
Saby Adapter
 ↓
Saby API
 ↓
Saby Adapter
 ↓
Normalized Contractor DTO
 ↓
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С событие
            ↓
      Queue / Job
            ↓
  Saby Integration Service
            ↓
    СБИС.ИнформацияОКонтрагенте
            ↓
       Normalize
            ↓
            1С

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

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

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

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

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

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

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

ИНН + КПП
      ↓
идентификация организации
      ↓
получение актуального ID ЭДО
      ↓
использование ID в конкретной операции

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

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

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

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

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

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

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

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

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

Минимальный 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С.