.. _Integration_Common_GettingStarted:

Приступая к работе
##################

| Для интеграции TerraLink xDE Pro и внешних систем используется набор API.
| В поставку Продукта включены:

* Integration API. Основной API Продукта. Предназначен для работы с документами и контрагентами.
* Archive API. Вспомогательный API. Предназначен для сохранения файлов в электронный архив и получения их из архива.
* Crypto API. Вспомогательный API. Предназначен для работы с сертификатами и подписями, шифрования и расшифровки данных.
* Prinforms API. Вспомогательный API. Предназначен для генерации печатных форм.

| Каждый API - это отдельный HTTP-сервис со своим URL.
| URL сервиса задается при установке компонентов Продукта.

.. warning::
   Не используйте HTTP-подключение к API в продуктивной среде.
   Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям.
   Используйте HTTPS-подключение.

REST и форматы данных
*********************

API Продукта основан на принципах REST. В качестве формата данных для тел запросов и ответов используется JSON.
В отдельных случаях тело запроса или ответа может быть составным (JSON плюс двоичные данные) либо содержать только двоичные данные.

URL ресурсов в документации
***************************

Все URL ресурсов, указанные в документации, относительные. 
Для выполнения запросов к ресурсам из HTTP-клиентов к URL ресурсов нужно добавлять абсолютный URL одного из развернутых сервисов.

Например, если указан запрос ``POST /token``, а абсолютный URL развернутого сервиса равен ``http://localhost:6001``, то полный URL запроса будет таким:

.. code-block::

    http://localhost:6001/token

Версионность
************

Для всех публичных и документированных версий API Продукта заявляется обратная совместимость.
Это означает, что при создании новой версии API старая версия не исчезает и не меняет свой контракт, если иное не указано в Release Notes к версии Продукта.

Новая версия API начинается с префикса ``vN``, например:

* ``/resourcename`` - исходная (первая) версия;
* ``/v2/resourcename`` - вторая версия;
* ``/v3/resourcename`` - третья версия, и т. д.

.. note::
   Версия API - это версия определенного запроса к какому-то конкретному ресурсу (``resourcename`` в примере).
   Версия API не имеет отношения к версии Продукта.