О платформе FinTrack

Идея платформы

Объединить информацию о движении товара и денег в цепочке поставок на единой платформе через интеграции с участниками
Зафиксировать на платформе договоренности между кредиторами и заемщиками по условиям финансирования
На основании данных полученных от участников контролировать процесс поставки на соответствие договоренностям
Реализовать предварительный контроль и акцепт действий участников (банков, логистов и складов) с товаром и деньгами в соответствии с договоренностями.
Снизить риски за счет контроля движения товара и денег в цепочке поставок
Создать IT платформу - единого хранителя и контроллера исполнения контракта.

Aрхитектура

Общие принципы интеграции

Для интеграции с внешними системами используются следующие решения:

REST API, предоставляемое платформой FinTrack - наиболее приоритетный способ интеграции.
Реализация клиента для интеграции с конкретной внешней системой - может быть использован при наличии у внешней системы стандартизованного API или при невозможности реализации API FinTrack на стороне внешней системы.
Загрузка и выгрузка документов через интерфейс платформы FinTrack - может использоваться для интеграционных задач, требующих ручного контроля и/или подтверждения со стороны оператора, либо как в рамках пилотных интеграций на этапе отработки технологии.

В соответствии с сервисной архитектурой платформы интеграционные API реализуются отдельными приложениями (сервисами) шлюзов:

Шлюз API контроля товара на складе.
Шлюз API контроля товара в пути.
Шлюз информации о распределении платежей.
Шлюз документооборота и др.

Принципы интеграции с использованием REST API FinTrack

При интеграции с внешней системой при помощи REST API платформа FinTrack выполняет функции сервера.
Данные предаются с использованием протокола HTTP с обязательным применением шифрования TLS версии не ниже 1.2.
Для получения данных от платформы используются GET-запросы. Критерии запроса задаются в виде query-параметров. Ответ передается в формате JSON.
Для передачи данных на платформу используются POST-запросы. Данные передаются в теле запроса в формате JSON.
Для аутентификации клиента и авторизации используется API-ключ, передаваемый в HTTP-заголовке X-Api-Key.
Для передачи информации во внешнюю систему со стороны платформы может использоваться один из следующих способов или их комбинация:
- Short polling - внешняя система опрашивает платформу с некоторой периодичностью и получает данные в ответах на отправляемые запросы (либо пустой ответ, если данных для передачи нет).
- Webhook - внешняя система сообщает платформе URL, на который платформа отправляет запросы при наличии данных для передачи, после чего внешняя система обращается на платформу за данными аналогично механизму short polling. Webhook вызывается без авторизации сторон и не передает данные. Авторизация происходит при обращении внешней системы за данными.
В зависимости от характера информации, бизнес-требований к интеграции и планируемой нагрузки устанавливаются параметры взаимодействия:
- Максимальный период для polling’а.
- Максимальное время ожидания запроса после вызова webhook.
- Максимальное число запросов в единицу времени.
- Максимальный таймаут ожидания ответа.
- Максимальный объем одного сообщения.

Принципы интеграции с использованием клиента для внешней системы

Интеграция с использованием клиента не является приоритетным способом.
В случае реализации такой интеграции по возможности следует использовать наиболее стандартные протоколы взаимодействия, предпочтительным являются протоколы на базе HTTP.
Клиент для внешней системы реализуется в приложении соответствующего шлюза.

API распределения платежей

Цели и задачи

Целью интеграции с факторинговой системой Банка является обмен информацией о расчетах при распределении платежей, при финансировании сделок через платформу FinTrack. Платформа FinTrack при этом выполняет информационные функции, не является транзакционной и не обрабатывает персональные или иные защищаемые законом данные.

Интеграционный сервис

Для интеграции с АС Фактора платформа FinTrack предоставляет сервис с REST API. Подключение к сервису производится через следующие адреса в сети Интернет:

рабочий (production) сервис: bankgw.ru.fintrack.tech
промежуточный (staging) сервис: bankgw.staging.fintrack.tech
сервис для тестирования и отладки: bankgw.test.fintrack.tech

Подключение к сервису производится с использованием протокола HTTPS (с шифрованием трафика по стандартному протоколу TLS версии не ниже 1.2).

Аутентификация клиента производится при помощи API-ключа, передаваемого в заголовке X-API_KEY HTTP-пакетов.

Спецификация API

API, предоставляемый интеграционным сервисом спроектирован с учетом принципов REST и позволяет организовать как передачу информации в АС Банка, так и получение информации из АС Банка в формате JSON.

API поддерживает версионирование. Версия включается в URL каждого метода.

Детальная спецификация API в формате OpenAPI (Swagger) для тестирования отладки доступна по следующему адресу: bankgw.test.fintrack.tech.

Поля, содержащие дату и время, передаются в соответствии со стандартом ISO 8601.

Поля, содержащие информацию о валюте, передаются в соответствии со стандартом ISO 4217.

В описании объектов запросов и ответов обязательные поля обозначены “*”.

При успешном выполнении запроса возвращается HTTP-код 200. В случае ошибки, возвращаемый код из диапазонов 4xx или 5xx указывает на характер ошибки.

Передача информациии о планируемых платежах

POST /api/v1/payments

При наличии у Фактора реестра денежных требований к договору факторинга, по которому подписано дополнительное соглашение, информация о планируемых платежах передается на платформу в виде запроса PaymentsRequest. В ответ платформа возвращает объект PaymentsResponse, который содержит следующие данные в зависимости от предыдущих запросов: 1. Если в очереди не находится ни одного запроса, он ставится в очередь по нему возвращается список распределенных платежей с указанием сумм и получателей (бенефициаров) (status=success). 2. Если в очереди есть запросы, он ставится в очередь следующим, а список распределенных платежей не может быть сформирован до исполнения платежей по предыдущим запросам в очереди (status=pending).

Передача информации об исполненных платежах

POST /api/v1/payments/actual

После проведения платежа Фактором информация о фактически выплаченных суммах передается на платформу в виде запроса ActualPaymentsRequest. При этом все ранее поставленные в очередь запросы, по которым исполнены все платежи удаляются из очереди. В ответ возвращается HTTP код 200 в случае успешного выполнения, либо соответствующий HHTP-код ошибки.

Получение информации по ранее отправленнму запросу

GET /api/v1/payments/{id}

Получение информации по ранее отправленному запросу на распределение платежей с идентификатором id. В ответ возвращается объект PaymentsResponse или ошибка с соответствующим HTTP-кодом.

Удаление ранее отправленного запроса из очереди

DELETE /api/v1/payments/{id}

Удаление из очереди ранее отправленного запроса на распределение платежей с идентификатором id. В ответ возвращается HTTP код 200 в случае успешного выполнения, либо соответствующий HHTP-код ошибки.

Время ожидания запроса в очереди составляет 5 дней. После этого он удаляется из очереди автоматически.

Модели данных запросов и ответов

Запрос PaymentsRequest

Наименование	Тип	Описание
id*	string(uuid)	Идентификатор запроса
contractNumber	string	Номер договора факторинга (справочно)
contractDate	DateTime with timezone	Дата договора факторинга (справочно)
payments	Payment[]	Массив платежей

Объект Payment

Наименование	Тип	Описание
id*	string	Идентификатор платежа (глобально уникальный, например UUID)
clientName*	string	Наименование клиента (получателя платежа)
clientTaxId*	string	ИНН клиента (получателя платежа)
clientTaxpayerCode	string	КПП клиента (для юридических лиц)
customerName*	string	Наименование дебитора (заказчика)
customerTaxId*	string	ИНН дебитора (заказчика)
customerTaxpayerCode	string	КПП дебитора (для юридических лиц)
value*	decimal	Сумма платежа
currency*	string	Код валюты по ISO 4217
paymentDate*	DateTime with timezone	Планируемая дата платежа
waybillNumber	string	Номер накладной/акта
waybillDate	DateTime with timezone	Дата накладной/акта
invoiceNumber	string	Номер счета-фактуры
invoiceDate	DateTime with timezone	Дата счета-фактуры
description	string	Произвольный текст, например текстовое описание назначения платежа

Запрос ActualPaymentsRequest

Наименование	Тип	Описание
id*	string(uuid)	Идентификатор запроса
payments	ActualPayment[]	Массив платежей

Объект ActualPayment

Наименование	Тип	Описание
id*	string	Идентификатор платежа, соответствующий PaymentDistribution.PaymentItem.id
date*	DateTime with timezone	Дата (и время при возможности) выполнения платежа

Ответ PaymentsResponse

Наименование	Тип	Описание
id*	string(uuid)	Идентификатор запроса
status*	enum	Результат выполнения запроса: success - запрос выполнен успешно (распределение проведено, он находится первым в очереди); pending - запрос находится в очереди; сancelled - запрос был отменен (удален из очереди); executed - платежи по данному запросы были исполнены фактически; error - запрос не может быть обработан из-за ошибки.
data	string	Объект PaymentsDistribution в формате JSON закодированный в Base64. Заполняется только для запроса с типом planned и status = success.
signature	string	Отсоединенная электронная подпись для объекта в поле data, закодированная в Base64. Заполняется только для запроса с типом planned и status = success.
blockingRequests	string[]	массив идентификаторов запросов, которые находятся в очереди перед данным (при status = pending)
errorDescription	string	Описание ошибки (при status = error)

Объект PaymentDistribution

Наименование	Тип	Описание
request*	PaymentsRequest	Исходный запрос на распределение (для обеспечения юридической значимости ответа)
payments*	PaymentItem[]	Список распределенных платежей.

Объект PaymentItem

Наименование	Тип	Описание
id*	string	Уникальный идентификатор распределенного платежа (должен быть глобально уникальным, в случае не распределяемого платежа может повторять originalPaymentId)
originalPaymentId*	string	Идентификатор планового платежа, из которого был распределен текущий платеж (PaymentRequest.Payment.id)
distributed*	bool	true – если платеж был распределен различным бенефициарам false – если платеж не распределяется и может быть выполнен без изменений
Последующие параметры заполняются только для распределяемых платежей (distributed=true):
beneficiarName	string	Наименование получателя платежа
beneficiarTaxId	string	ИНН получателя платежа
beneficiarTaxpayerCode	string	КПП получателя платежа (для юридических лиц)
beneficiarAccountNumber	string	Номер счета получателя платежа
beneficiarBankName	string	Наименование банка получателя платежа
beneficiarBankId	string	БИК банка получателя платежа
beneficiarCorrespondentAccount	string	Корреспондентский счет банка получателя платежа
value	decimal	Сумма платежа
currency	string	Код валюты по ISO 4217

Обработка ошибок

В случае ошибочных ситуаций (неверный формат запроса, отсутствие необходимых данных в запросе и т.п.) возвращается структурированный ответ, содержащий информацию об ошибке. Тип ошибки определяется по стандартным HTTP-кодам ответа.

ErrorResponse

Наименование	Тип	Описание
requestId*	string(uuid)	Идентификатор запроса
description*	string	Описание ошибки

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

API контроля товара на складе

Цели и задачи

API контроля товара на складе предназначено для интеграции с системами управления складом (Warehouse Management Systems, WMS) и решения следующих задач:

контроль наличия определенных товаров на складе
контроль отношения залога к долгу
информирование кредитора о движении товара, находящегося в залоге (мониторинг)
акцепт отгрузок товара, находящегося в залоге

Интеграционный сервис

Для интеграции с системами управления складом (WMS) платформа FinTrack предоставляет сервис с REST API. Подключение к сервису производится через следующие адреса в сети Интернет:

рабочий (production) сервис: wmsgw.fintrack.tech
промежуточный (staging) сервис: wmsgw.staging.fintrack.tech
сервис для тестирования и отладки: wmsgw.test.fintrack.tech

Аутентификация клиента производится при помощи API-ключа, передаваемого в заголовке X-API-KEY HTTP-пакетов.

Информация в запросах и ответах передается в формате JSON.

API поддерживает версионирование. Версия включается в URL каждого метода.

Поля содержащие дату и/или время и помеченные типом DateTime передаются в соответствии со стандартом ISO 8601.

Поля, содержащие информацию о валюте, передаются в соответствии со стандартом ISO 4217.

В описании объектов запросов и ответов обязательные поля обозначены “*”. Необязательные поля могут содержать значение null или не включаться в объекты (допустимы оба варианта).

Получение информации о клиентах

GET /api/v1/clients

WMS периодически должна получать информацию о клиентах платформы, имеющих сделки с данным оператором складов. Рекомендуемый период запроса - 1-2 раза в сутки, перед передачей данных об остатках.

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера

Ответ StockClientResponse

// StockClientResponse
{
    "stockClients": [
        {
            "id": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
            "name": "ООО \"ФИНТРЕК\"",
            "country": "RUS",
            "registrationNumber": "1225000143334",
            "taxId": "5040182733",
            "taxpayerCode": "504001001",
            "monitoringEnabled": true
        }
    ]
}

В ответ на запрос возвращается объект StockClientResponse содержащий массив объектов StockClient в единственном атрибуте stockClients. В случае ошибки возвращается один из кодов:

Объект StockClient

Наименование	Тип	Описание
id*	string(uuid)	Уникальный идентификатор клиента платформы
name*	string	Наименование клиента
country*	string	3-буквенный код страны в соответсвии с ISO 3166
registrationNumber	string	Регистрационный номер юридического лица (для РФ: ОГРН)
taxId	string	Налоговый номер/идентификатор (для РФ: ИНН)
taxpayerCode	string	Дополнительный налоговый идентификатор (для РФ: КПП)
monitoringEnabled*	bool	Наличие мониторинга по данному клиенту (необходимость периодической передачи остатков по нему)

Для любой записи гарантированно будет заполнено одно из полей registrationNumber или taxId. Для юридических лиц из РФ гарантированно заполняются поля registrationNumber, taxId и taxpayerCode.

Передача информации об остатках товаров

POST /api/v1/stock

WMS периодически должна передавать информацию о состоянии остатков товаров на складе по всем клиентам, зарегистрированным на платформе. Рекомендуемый период передачи - 1-2 раза в сутки.

Информация передается в виде массива объектов StockItem, содержащих данные об артикулах и количестве товара на складе, доступного для отгрузки.

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

Запрос StockRequest

// StockRequest
[
    {
        "clientId": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
        "code": "VPMSNITROX7",
        "title": "Портативная аудиосистема Vipe NITRO X7",
        "quantity": 237
    },
    {
        "clientId": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
        "code": "VPMSNITROX1",
        "title": "Портативная аудиосистема Vipe NITRO X1",
        "quantity": 124,
        "price": 15000,
        "currency": "rub"
    }
]

Запрос представляет собой массив объектов StockItem. При отсутствии товара на складе необходимо передавать соответсвующий объект с quantity: 0. При отсутсвии в запросе информации по какому-либо товару, данные о его количестве на платформе не изменятся, а актуальность этой информации будет снижена.

Объект StockItem

Наименование	Тип	Описание
clientId*	string(uuid)	Уникальный идентификатор клиента платформы
code*	string	Уникальный артикул товара
title	string	Наименование товара (если доступно)
description	string	Описание товара (если доступно)
price	decimal	Цена единицы товара по данным WMS (если доступно)
currency	string	Код валюты по ISO 4217 (обязательно при наличии значения в `price`)
quantity*	integer	Количество единиц товара в наличии на складе, потенциально доступных для отгрузки (>= 0)

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят
400 - ошибка в формате запроса
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера

Передача заявок на отгрузку

POST /api/v1/shipment-requests

При появлении заявки (заявок) на отгрузку по компаниям-клиентам платформы FinTrack, WMS должна запрашивать их акцепт. Для этого она передает массив объектов StockShipmentOrder, содержащих сведения об отгрузках.

Допускается передавать заявки на отгрузку, как по одной, так и одним запросом по клиенту или группируя все заявки в один запрос.

Допускается передавать заявки на отгрузку повторно с тем же идентификатором (поле id объекта StockShipmentOrder). При этом такие заявки будут рассматриваться как повторные. Если ранее на платформу была передана другая заявка с тем же идентификатором, то она будет рассматриваться как повторная. Например, если по данной заявке уже была разрешена отгрузка, а новый ее вариант содержит другой состав товаров, то платформа вернет статус Conflict по данной заявке.

Запрос StockShipmentRequest

// StockShipmentRequest
[
    {
        "id": "de3270f3-8871-41c2-8add-0af24917878c",
        "clientId": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
        "items": [
            {
                "code": "VPMSNITROX7",
                "quantity": 120
            },
            {
                "code": "VPMSNITROX1",
                "quantity": 55
            }
        ],
        "address": "г. Москва, 1-я Фрезерная улица, 2/1с1"
    }
]

Запрос представляет собой массив объектов StockShipmentOrder. В одном запросе не допускается наличие объектов с одинаковым id.

Объект StockShipmentOrder

Наименование	Тип	Описание
id*	string	Глобально уникальный идентификатор заявки на отгрузку
clientId*	string(uuid)	Уникальный идентификатор клиента платформы
items*	StockShipmentItem[]	Массив данных о товарах, заявленных к отгрузке
address	string	Адрес склада, с которого осуществляется отгрузка (если известно)
consigneeName	string	Наименование грузополучателя (если известно)
consigneeTaxId	string	ИНН грузополучателя (если известно)
description	string	Дополнительные сведения об отгрузке

Объект StockShipmentItem

Наименование	Тип	Описание
code*	string	Уникальный артикул товара
quantity*	integer	Количество единиц товара
unit	string	Единицы измерения, если известны (например: шт., т и т.п.)

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят и обработан
400 - ошибка в формате запроса
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера

При успешной обработке запроса вместе с кодом 200 платформа вернет ответ типа StockShipmentResponse.

Ответ StockShipmentResponse

// StockShipmentResponse
[
    {
        "id": "de3270f3-8871-41c2-8add-0af24917878c",
        "status": "Approved"
    }
]

В ответ на запрос возвращается массив объектов StockShipmentOrderResponse. Ответ должен содержать по одному объекту StockShipmentOrderResponse на каждый StockShipmentOrder переданный в запросе.

Объект StockShipmentOrderResponse

Наименование	Тип	Описание
id*	string	Уникальный идентификатор заявки на отгрузку
status*	string(enum)	Статус обработки заявки на отгрузку
description	string	Дополнительная информация (например пояснение причины запрета)

Возможные значения статуса

Значение	Описание
Approved	Отгрузка разрешается
Rejected	Отгрузка запрещена
Recieved	Заявка на отгрузку получена и не требует акцепта
Conflict	Повторная заявка, которая была разрешена с другим составом товаров
Error	Другая ошибка обработки (см. `description`)

Передача информации о поступлении на склад

POST /api/v1/arrival-notifications

При появлении информации о поступлении товаров по компаниям-клиентам платформы FinTrack, WMS должна передавать информацию об этом на платформу. Для этого она передает массив объектов StockArrival, содержащих сведения о поступлениях.

Допускается передавать сообщения о поступлении, как по одному, так и одним запросом по клиенту или группируя все сообщения в один запрос.

Метод является идемпотентным. Допускается передавать сообщения повторно с тем же идентификатором (поле id объекта StockArrival). При этом такие сообщения будут рассматриваться как повторные и информация об этих поступлениях на платформе будет обновлена.

Запрос StockArrivalNotification

// StockArrivalNotification
[
    {
        "id": "de3270f3-8871-41c2-8add-0af24917878c",
        "clientId": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
        "items": [
            {
                "code": "VPMSNITROX7",
                "quantity": 120
            },
            {
                "code": "VPMSNITROX1",
                "quantity": 55
            }
        ],
        "date": "2024-09-18",
        "address": "г. Москва, 1-я Фрезерная улица, 2/1с1"
    }
]

Запрос представляет собой массив объектов StockArrival. В одном запросе не допускается наличие объектов с одинаковым id.

Объект StockArrival

Наименование	Тип	Описание
id*	string	Глобально уникальный идентификатор сообщения
clientId*	string(uuid)	Уникальный идентификатор клиента платформы
items*	StockShipmentItem[]	Массив данных о товарах, поступивших на склад
date	DateTime	Дата и время поступления (поддерживатется как дата и время, так и только дата)
address	string	Адрес склада, на которые поступил товар (если известно)
consignorName	string	Наименование грузоотправителя (если известно)
consignorTaxId	string	ИНН грузоотправителя (если известно)
description	string	Дополнительные сведения об отгрузке

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят и обработан
400 - ошибка в формате запроса
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера

API контроля товара в пути

Цели и задачи

API контроля товара в пути предназначено для интеграции с информационными системами логистических провайдеров и решения задачи мониторинга и контроля местонахождения товара при его перевозке.

Интеграционный сервис

Для интеграции с системами логистических провайдеров платформа FinTrack предоставляет сервис с REST API. Подключение к сервису производится через следующие адреса в сети Интернет:

рабочий (production) сервис: lpgw.fintrack.tech
промежуточный (staging) сервис: lpgw.staging.fintrack.tech
сервис для тестирования и отладки: lpgw.test.fintrack.tech

Аутентификация клиента производится при помощи API-ключа, передаваемого в заголовке X-API-KEY HTTP-пакетов.

Информация в запросах и ответах передается в формате JSON.

API поддерживает версионирование. Версия включается в URL каждого метода.

Поля содержащие дату и/или время и помеченные типом DateTime передаются в соответствии со стандартом ISO 8601.

Поля, содержащие информацию о валюте, передаются в соответствии со стандартом ISO 4217.

Получение информации о клиентах

GET /api/v1/clients

Логистический провайдер периодически должен получать информацию о клиентах платформы, имеющих сделки с данным логичтическим провайдером. Рекомендуемый период запроса - 1 раза в сутки, перед передачей данных о трекинге грузов.

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера

Ответ LogisticsClientResponse

// LogisticsClientResponse
[
    {
        "id": "5b8751f9-cd68-469c-96c3-066a5d7c660f",
        "name": "ООО \"ФИНТРЕК\"",
        "country": "RUS",
        "registrationNumber": "1225000143334",
        "taxId": "5040182733",
        "taxpayerCode": "504001001",
        "monitoringEnabled": true
    }
]

В ответ на запрос возвращается массив объектов LogisticsClient. В случае ошибки возвращается один из кодов:

Объект LogisticsClient

Наименование	Тип	Описание
id*	string(uuid)	Уникальный идентификатор клиента платформы
name*	string	Наименование клиента
country*	string	3-буквенный код страны в соответсвии с ISO 3166
registrationNumber	string	Регистрационный номер юридического лица (для РФ: ОГРН)
taxId	string	Налоговый номер/идентификатор (для РФ: ИНН)
taxpayerCode	string	Дополнительный налоговый идентификатор (для РФ: КПП)
monitoringEnabled*	bool	Наличие мониторинга по данному клиенту (необходимость периодической передачи остатков по нему)

Передача информации о трекинге грузов

POST /api/v1/tracking

Логистический провайдер периодически должен передавать информацию о трекинге товаров по всем клиентам, зарегистрированным на платформе. Рекомендуемый период передачи - 1 раз в сутки.

Информация передается в виде массива объектов TrackingItem, содержащих данные об артикулах и количестве товара на складе, доступного для отгрузки.

Запрос TrackingRequest

// TrackingRequest
[
    {
        "clientId": "ded6ca96-02b0-4bc8-8559-968d15c16dc2",
        "containerId": "BICU1234567",
        "containerType": "Iso830",
        "events": [
            {
                "country": "RUS",
                "carrier": "ARTT",
                "carrierType": "Ship",
                "status": "InTransit",
                "timestamp": "2024-04-01T20:28:00+07:00"
            },
            {
                "country": "RUS",
                "city": "Vladivostok",
                "status": "Arrived",
                "timestamp": "2024-04-02T13:23:00+07:00",
                "counterparty": {
                    "name": "ООО \"ДНС Ритейл\"",
                    "registrationId": "1102540008230",
                    "taxId": "2540167061",
                    "country": "RUS",
                    "address": "690068, Приморский кр., г. Владивосток, проспект 100-Летия Владивостока, д. 155"
                }
            }
        ],
        "trackingEnabled": true
    }
]

Запрос представляет собой массив объектов TrackingItem, содержащих массив событий TrackingEvent, накопленных с момента передачи предыдущего трекинга.

Объект TrackingItem

Наименование	Тип	Описание
clientId*	string(uuid)	Уникальный идентификатор клиента платформы
containerId*	string	Уникальный идентификатор контейнера
containerType*	string(enum)	Тип контейнера (физического или виртуального)
events*	TrackingEvent[]	Массив событий типа TrackingEvent
trackingEnabled	bool	Состояние контроля

Объект TrackingEvent

Наименование	Тип	Описание
country*	string	3-буквенный код страны в соответсвии с ISO 3166
region	string	Регион внутри страны
city	string	Название города местонахождения груза
terminal	string	Название терминала местонахождения груза
address	string	Адрес местонахождения груза
latitude	decimal	Широта
longitude	decimal	Долгота
carrier	string	Название перевозчика или SCAC код
carrierType	string(enum)	Тип перевозчика
status*	string(enum)	Статус события
timestamp*	DateTime	Временная метка события (дата и время с привязкой к часовому поясу)
counterparty	EntityData	Данные отправителя, получателя или перевозчика груза

Поле counterparty может быть заполнено для некоторых статусов события и собержать следующую информацию:

Статус	Значение поля counterparty
Departed	Сведения об отправителе груза
Arrived	Сведения о получателе груза
InTransit	Сведения о перевозчике

Объект EntityData

Наименование	Тип	Описание
name*	string	Название компании
registrationId	string	Регистрационный номер компании (ОГРН, USCC, LEI)
taxId	string	Налоговый регистрационный номер (ИНН, VAT ID)
taxpayerCode	string	Дополнительный налоговый идентификатор (для РФ: КПП)
country*	string	3-буквенный код страны в соответсвии с ISO 3166
address	string	Адрес местонахождения компании

При заполнении EntityData обязательно должны быть заполнено хотя бы одно из полей registrationId или taxId.

Возможные значения СontainerType

Значение	Описание
Iso830	Физический контейнер одного из типов по ISO 830
Virtual	Виртуальный контейнер - единица учета в системе
Material	Физический контейнер произвольного типа

Возможные значения типа перевозчика СarrierType

Значение	Описание
Air	Авиалиния
Ship	Морской или речной транспорт
Rail	Железнодорожный транспорт
Truck	Грузовой автотранспорт

Возможные значения статуса события Status

Значение	Описание
Departed	Отправление
Arrived	Прибытие
InTransit	Перевозка
ArrivedAtCustoms	Поступил на таможню
LeftCustoms	Вышел с таможни
AtCustoms	На таможенном оформлении

В ответ платформа возвращает HTTP-код, определяющий результат выполнения запроса:

200 - запрос успешно принят
400 - ошибка в формате запроса
401 - ошибка авторизации
404 - ошибка в формате пути
5xx - ошибка на стороне сервера