Агредатор | Описание

Описание

Шлюз представляет собой информационную систему для выполнения http запросов к платформе «Агредатор».

Возможности:

несколько клиентов
возможность настраивать несколько сервисов
возможность предоставлять права доступа к сервисам различным клиентам
статистика запросов для клиента
асинхронная работа
возможность доставлять ответ или входящий запрос до клиента при получении (callback/push)

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

В данном руководстве будет рассмотрен пример с использованием сервиса fns-so.

Общее описание API

Существует две версии API:

v1 - для новых клиентов. Поддерживает запросы к любым сервисам агредатора.
v0 - слой совместимости с УПРИД/УПРИД-Шлюз. Поддерживает запросы только к сервису УПРИД/DI

Параметры и данные в запрос могут быть переданы как в строке так и в теле запроса. Поддерживаемые форматы(Content-Type) данных в теле запроса:

application/x-www-form-urlencoded
multipart/form-data
application/json

Коллекции

Все коллекции возвращаются виде:

{
  "has_next": "Признак присутствия следущей страницы для текущего фильтра",
  "current_page": "текущая страница",
  "per_page": "число документов включенных в элемент 'collection'",
  "collection":[
    {/элемент запрашиваемой коллекции/}
  ]
}

Пагинация

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

параметр	описание	по умолчанию
limit	количество элементов в списке ответа	50
page	элементы с данной страницы	1

Callback/push

Для возможности выполнения асинхронной обработки результатов запросов существует возможность получать POST-колбэки. Этот механизм позволяет избежать постоянного опроса результатов и существенно повысить скорость обработки результатов. Для доставки результатов используются HTTP POST-запросы в формате content-type: application/json, тело которых совпадает с результатом, получаемым при обычном опросе результата.

При невозможности доставить результат по указанному адресу будет выполнено несколько попыток переотправки с постепенно увеличивающимися интервалами между собой.

Внимание

Если указанный адрес принимающей стороны будет полностью недоступен в течение длительного времени, то такой адрес (его домен) будет временно заблокирован для избежания перегрузки системы. Полностью недоступным считается адрес, на который более половины запросов (при числе не менее 30 за минуту) завершаются ошибкой. Заблокированный домен клиента на 5 минут выводится из процедуры доставки POST-колбэков, при этом клиент всегда может получить результат обработки по схеме Просмотр состояния запроса.

Варианты использования доставки с помощью callback/push

1. Ответ на запрос

Для асинхронного получения ответа на запрос должен быть установлен PUSH-адрес для клиента¹ или для каждого запроса².

1 Установить PUSH-адрес для клиента можно через техподдержку или в Кабинете клиента в разделе Данные ИС.

2 Установить PUSH-адрес для запроса можно при создании запроса через API (в параметре request.callback_url).

Приоритеты: PUSH-адрес в запросе, но если его нет, то PUSH-адрес клиента.

2. Входящий запрос

Для асинхронного получения входящего запроса должен быть установлен PUSH-адрес (входящий) для клиента¹ или для конкретного входящего сервиса².

1 Установить PUSH-адрес (входящий) для клиента можно через техподдержку или в Кабинете клиента в разделе Данные ИС.

2 Установить PUSH-адрес (входящий) для конкретного входящего сервиса можно через техподдержку или в Кабинете клиента в разделе Доступы, выбрав нужный сервис.

Приоритеты: PUSH-адрес (входящий) сервиса, но если его нет, то PUSH-адрес (входящий) клиента.

3. Изменение статуса ответа на входящий запрос

Для асинхронного получения изменения статуса ответа на входящий запрос должен быть установлен PUSH-адрес (входящий) при создании ответа на входящий запрос через API (в параметре response.callback_incoming_url).

Формат PUSH-адреса

PUSH-адрес — это URL к информационной системе, которая обработает событие. Формат URL:

<схема>:[//[<логин>[:<пароль>]@]<хост>[:<порт>]][/<URL‐путь>]

где схема — это протокол передачи данных, который должен быть только HTTPS.

Примеры:

https://www.example.com:8080/my/api/path

https://login:password@www.example.com:8080/my/api/path (с указанием имени и пароля)

Проверка callback/push

Для проверки Вашего PUSH-адреса (любого из трех) воспользуйтесь встроенными в Кабинет клиента возможностями тестирования. Сохраните PUSH-адрес для нужного Вам варианта оповещения и нажмите на кнопку «Протестировать». По указанному адресу будет отправлено тестовое сообщение.

API V1

Endpoint: /api/v1

Для авторизации используется basic access authentication. Это значит что username и password для доступа передаются в открытом виде. Для доступа настоятельно рекомендуется использовать SSL-терминацию.

В качестве username передается идентификатор(identifier) клиента, в качестве password передается секрет(secret):

  curl -u identifier:secret https://agredator.ru/

Пример ошибки:

{
  "error": true,
  "status": "400",
  "code": "api_client_no_access",
  "title": "Client unauthorized to access service: fns-so",
  "meta": {
    "errors": {
      "client": ["unauthorized to access service: fns-so"]
    }
  }
}

Получение списка запросов

Endpoint: /api/v1(/:service)/requests(.json)
Method: GET

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

Получить список последних запросов ко всем сервисам

  curl -u identifier:secret https://agredator.ru/api/v1/requests?limit=2

Получить список последних запросов к конкретному сервису(fns-so):

  curl -u identifier:secret https://agredator.ru/api/v1/fns-so/requests?limit=2

Пример ответа:

{
  "has_next":true,
  "current_page":1,
  "per_page":2,
  "collection":[
    {
      "id":6363,
      "status":200,
      "client":"4cc8d2deeb876add50cac888cbeb195c",
      "info":"success result",
      "service":"echo",
      "created_at":"2019-07-23T15:06:31.692+03:00",
      "response":{/service-response/},
      "ticket":"0f5dcdc7-1621-437e-8ed6-1d26e6c6d8df",
      "callback_url":null,
      "external_id":"6363",
      "histories":[
        {
          "id":11674,
          "request_id":6363,
          "from":100,
          "to":102,
          "message":"processing",
          "created_at":"2019-07-23T15:06:31.818+03:00",
          "updated_at":"2019-07-23T15:06:31.818+03:00"
        },
        {
          "id":11675,
          "request_id":6363,
          "from":102,
          "to":200,
          "message":"success result",
          "created_at":"2019-07-23T15:06:31.946+03:00",
          "updated_at":"2019-07-23T15:06:31.946+03:00"
        }
      ]
    }
  ]
}

Просмотр состояния запроса

Endpoint: /api/v1(/:service)/requests/:id(.json)
Method: GET

Возвращает полную информацию по запросу. Доступен фильтр по сервису.

Просмотреть запрос:

  curl -u identifier:secret https://agredator.ru/api/v1/requests/6363

Пример ответа:

{
  "id":6363,
  "status":200,
  "client":"4cc8d2deeb876add50cac888cbeb195c",
  "info":"success result",
  "service":"echo",
  "created_at":"2019-07-23T15:06:31.692+03:00",
  "response":{/service-response/},
  "ticket":"0f5dcdc7-1621-437e-8ed6-1d26e6c6d8df",
  "callback_url":null,
  "external_id":"6363",
  "histories":[
    {
      "id":11674,
      "request_id":6363,
      "from":100,
      "to":102,
      "message":"processing",
      "created_at":"2019-07-23T15:06:31.818+03:00",
      "updated_at":"2019-07-23T15:06:31.818+03:00"
    },
    {
      "id":11675,
      "request_id":6363,
      "from":102,
      "to":200,
      "message":"success result",
      "created_at":"2019-07-23T15:06:31.946+03:00",
      "updated_at":"2019-07-23T15:06:31.946+03:00"
    }
  ]
}

Создание запроса

Endpoint: /api/v1(/:service)/requests(.json)
Method: POST

При создании запроса необходимо указать следующие параметры:

параметр	описание	обязательный
request	Объект обертка	+
request.service	[`String`] Имя сервиса. Может быть задано через url	+
request.external_id	[`String`] Произвольный идентификатор запроса, со стороны клиента. Будет возвращён в ответе	-
request.payload	[`Object`] Тело запроса	+
request.callback_url	[`String`] Адрес для доставки результата POST-запросом. Если не задан, берется из настроек всего клиента	-

Создание запроса с указанием сервиса в строке запроса:

curl -u identifier:secret \
  -H "Content-Type: application/json; charset=utf-8" \
  -X POST \
  -d '{"request": {"payload": {"data": 111}}}' \
  https://agredator.ru/api/v1/fns-so/requests

Создание запроса с указанием сервиса в теле запроса:

curl -u identifier:secret \
  -H "Content-Type: application/json; charset=utf-8" \
  -X POST \
  -d '{"request": {"service": "echo", "payload": {"data": 111}}}' \
  https://agredator.ru/api/v1/requests

Пример ответа:

{
  "id": 6365,
  "status": 100,
  "client": "identifier",
  "info": null,
  "service": "fns-so",
  "created_at": "2019-07-23T17:21:02.483+03:00",
  "response": {},
  "ticket": null,
  "callback_url": null,
  "external_id":"6365",
  "histories": []
}

После получения ответа на запрос, если callback_url задан (для запроса или для всего клиента), POST-запросом будет доставлено состояние запроса (см. пример ответа).

Модификация шага запроса

Endpoint: /api/v1(/:service)/requests/:id/triggers/:trigger(.json)
Method: GET|POST|PUT

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

Отправить код подтвержlения на ранее отправленный запрос:

  curl -u identifier:secret "https://agredator.ru/api/v1/requests/6363/triggers/verify?payload\[code\]=12345"

Пример ответа (тело ответа может меняться в зависимости от конкретного шага и сервиса):

{
  "verification": "failed",
  "details": "{\"result\":{\"valid\":false},\"status\":\"success\",\"id\":\"814b4133-82a8-4be8-a186-6b088b3ae9d2\",\"service\":\"contact-verifier\"}",
  "success": true
}

Удаление запроса

Endpoint: /api/v1(/:service)/requests/:request_id
Method: DELETE
Params:
- request_id: идентификатор удаляемого запроса

Удаляет запрос по указанному request_id. В случае успешного выполнения возвращается пустой ответ с 202 статусом.

Пример запроса:

  curl -u identifier:secret -X DELETE https://agredator.ru/api/v1/requests/115

Получение информации (JSON) о файле вложений

Endpoint: /api/v1(/:service)/requests/:request_id/attachments/:uuid.json
Method: GET
Params:
- request_id: идентификатор запроса, в рамках которого существует файл
- uuid: идентификатор вложения

Возвращает полную информацию по файлу вложения в виде JSON.

Просмотреть информацию:

  curl -u identifier:secret https://agredator.ru/api/v1/requests/116/attachments/e49d01071fafef980fd2a305896032d.json

Пример ответа (status=200):

{
  "uuid":"e49d01071fafef980fd2a305896032d",
  "checksum":"e6156f5514d53ca19512a8fc6c62f692943e980e336de1bd0dbfaff60ee0ef21",
  "created_at":"2021-11-18T19:30:55.136+03:00",
  "tags":["123123"],
  "filename":"photo.jpg",
  "mime_type": "image/jpeg"
}

Пример ошибки (status=404):

{
  "error":true,
  "status":"404",
  "code":"not_found",
  "title":"Couldn't find Request with 'id'=116",
  "meta":{
    "model":"request",
    "id":"116"
  }
}

Получение содержимого файла вложений

Endpoint: /api/v1(/:service)/requests/:request_id/attachments/:uuid
Method: GET
Params:
- request_id: идентификатор запроса, в рамках которого существует файл
- uuid: идентификатор вложения

Возвращает содержимое файла вложения.

Просмотреть информацию:

  curl -u identifier:secret https://agredator.ru/api/v1/requests/116/attachments/e49d01071fafef980fd2a305896032d > /tmp/photo.jpg

Пример ошибки (status=500):

{
  "error":true,
  "status":"500",
  "code":"filator_stream_error",
  "title":"Failed to open TCP connection to 172.22.4.314:32773 (getaddrinfo: Name or service not known)",
  "meta":{}
}

Загрузка файла вложений в систему

Endpoint: /api/v1(/:service)/attachments/
Method: POST
Params:
- body: файл вложения

Производит загрузку файла в систему и возвращает полную информацию по файлу вложения в виде JSON.

Пример:

  curl -u identifier:secret \
  -X POST \
  -F "body=@/path/to/photo.jpg" \
  https://agredator.ru/api/v1/attachments/

Пример ответа (status=200):

{
  "uuid":"e49d01071fafef980fd2a305896032d",
  "checksum":"e6156f5514d53ca19512a8fc6c62f692943e980e336de1bd0dbfaff60ee0ef21",
  "created_at":"2021-11-18T19:30:55.136+03:00",
  "tags": [],
  "filename":"photo.jpg",
  "mime_type": "image/jpeg"
}

Получение логов запроса

Endpoint: /api/v1(/:service)/requests/:request_id/logs(.json)
Method: GET
Params:
- request_id: идентификатор запроса, в рамках которого существует файл

Возвращает архив, содержащий файлы xml взаимодействия и файл metadata.json, содержащий служебные данные, связанные с запросом. В случае указания формата json - возвращает json, содержащий xml логи взаимодействия.

Пример запроса:

curl -u identifier:secret https://agredator.ru/api/v1/requests/116/logs > /tmp/logs.zip 

Пример запроса с json форматом ответа:

curl -u identifier:secret https://agredator.ru/api/v1/requests/116/logs.json > /tmp/logs.zip 

Пример ответа:

{
  "request_id": 116,
  "service": "uprid3",
  "target": "uprid3",
  "ticket": "51ccdd21-642f-4770-8885-64757c906b90",
  "created_at": "2021-12-06T11:45:44.013+03:00",
  "updated_at": "2021-12-06T11:46:05.858+03:00",
  "logs": [
    {
      "type": "sendRequest",
      "request": "...",
      "response": "..."
    },
    {
      "type": "getResponse",
      "request": "...",
      "response": "..."
    },
    {
      "type": "ack",
      "request": "...",
      "response": "..."
    }
  ]
}

Статистика

Клиенты

Endpoint: /api/v1/admin/statistics/clients
Method: GET

При создании запроса можно указать следующие параметры:

Поле	Тип	Описание
name	текст	имя клиента
status	число	статус запросов
period	текст	период времени, когда были созданы запросы. Возможные значения: daily, weekly, monthly, annualy, custom
from	дата	дата начала периода. Используется при `period = custom`
to	дата	дата конца периода. Используется при `period = custom`

Создание запроса:

curl -u LOGIN:PASSWORD \
     http://agredator.ru/api/v1/admin/statistics/clients

Пример ответа:

{
  "from": "2020-04-01T00:00:00.000+03:00", // если в запросе есть параметр period
  "to": "2020-05-01T00:00:00.000+03:00", // если в запросе есть параметр period
  "total": 8,
  "clients": [
    {
      "name": "exampleClient",
      "total": 8,
      "services": [
        {
          "name": "exampleService",
          "statuses": [
            {
              "status": 480,
              "count": 1
            },
            {
              "status": 102,
              "count": 1
            },
            {
              "status": 100,
              "count": 6
            }
          ]
        }
      ]
    },
  ]
}

Статистика

Endpoint: /api/v1/admin/statistics/services
Method: GET

При создании запроса можно указать следующие параметры:

Поле	Тип	Описание
name	текст	имя клиента
status	число	статус запросов
period	текст	период времени, когда были созданы запросы. Возможные значения: daily, weekly, monthly, annualy, custom
from	дата	дата начала периода. Используется при `period = custom`
to	дата	дата конца периода. Используется при `period = custom`

Создание запроса:

curl -u LOGIN:PASSWORD \
     http://agredator.ru/api/v1/admin/statistics/services

Пример ответа:

{
  "from": "2020-04-01T00:00:00.000+03:00", // если в запросе есть параметр period
  "to": "2020-05-01T00:00:00.000+03:00", // если в запросе есть параметр period
  "total": 8,
  "services": [
    {
      "name": "exampleService",
      "total": 8,
      "clients": [
        {
          "name": "exampleClient",
          "statuses": [
            {
              "status": 480,
              "count": 1
            },
            {
              "status": 102,
              "count": 1
            },
            {
              "status": 100,
              "count": 6
            }
          ]
        }
      ]
    },
  ]
}

Получение списка входящих запросов

Endpoint: /api/v1/:service/incomings?last_id=:last_id(.json)
Method: GET

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

параметр	описание	обязательный
last_id	Идентификатор последнего обработанного потребителем запроса	-

При указазании в запросе last_id в ответ будет возвращён список новых входящих запросов, если они есть.

Получить список последних входящих запросов по сервису fns-nalflproc:

  curl -u identifier:secret https://agredator.ru/api/v1/fns-nalflproc/incomings?last_id=12

Пример ответа:

{
  "last_id": 12,
  "has_next": false,
  "current_page": 1,
  "per_page": 15,
  "collection": [
    {
      "id": 13,
      "status": 103,
      "client": "i1",
      "info": "response 44 successed",
      "service": "fns-nalflproc",
      "created_at": "2022-02-15T14:36:11.150+03:00",
      "identifier": "3bb85b05-77f1-4072-8dfc-6fd1d78b5bf6-d41d8cd98f00b204",
      "request": {/incoming-request/},
      "histories": [
        {
          "id": 8,
          "historyable_type": "Incoming",
          "historyable_id": 13,
          "from": 100,
          "to": 103,
          "message": "waiting for delivery of response 44",
          "created_at": "2022-02-15T14:36:43.044+03:00",
          "updated_at": "2022-02-15T14:36:43.044+03:00"
        },
        {
          "id": 10,
          "historyable_type": "Incoming",
          "historyable_id": 13,
          "from": 103,
          "to": 103,
          "message": "response 44 successed",
          "created_at": "2022-02-15T14:42:27.292+03:00",
          "updated_at": "2022-02-15T14:42:27.292+03:00"
        }
      ],
      "responses": [
        {
          "id": 44,
          "status": 200,
          "incoming_id": 13,
          "info": "send successed",
          "created_at": "2022-02-15T14:36:41.799+03:00",
          "callback_incoming_url": null,
          "histories": [
            {
              "id": 7,
              "historyable_type": "Incoming::Response",
              "historyable_id": 44,
              "from": 100,
              "to": 102,
              "message": "waiting for send",
              "created_at": "2022-02-15T14:36:42.940+03:00",
              "updated_at": "2022-02-15T14:36:42.940+03:00"
            },
            {
              "id": 9,
              "historyable_type": "Incoming::Response",
              "historyable_id": 44,
              "from": 102,
              "to": 200,
              "message": "send successed",
              "created_at": "2022-02-15T14:42:27.238+03:00",
              "updated_at": "2022-02-15T14:42:27.238+03:00"
            }
          ]
        }
      ]
    }
  ]
}

Просмотр входящего запроса

Endpoint: /api/v1/:service/incomings/:id(.json)
Method: GET

Возвращает полную информацию по запросу.

Просмотреть запрос:

  curl -u identifier:secret https://agredator.ru/api/v1/fns-nalflproc/incomings/13

Пример ответа:

{
  "id": 13,
  "status": 103,
  "client": "i1",
  "info": "response 44 successed",
  "service": "fns-nalflproc",
  "created_at": "2022-02-15T14:36:11.150+03:00",
  "identifier": "3bb85b05-77f1-4072-8dfc-6fd1d78b5bf6-d41d8cd98f00b204",
  "request": {/incoming-request/},
  "histories": [
    {
      "id": 8,
      "historyable_type": "Incoming",
      "historyable_id": 13,
      "from": 100,
      "to": 103,
      "message": "waiting for delivery of response 44",
      "created_at": "2022-02-15T14:36:43.044+03:00",
      "updated_at": "2022-02-15T14:36:43.044+03:00"
    },
    {
      "id": 10,
      "historyable_type": "Incoming",
      "historyable_id": 13,
      "from": 103,
      "to": 103,
      "message": "response 44 successed",
      "created_at": "2022-02-15T14:42:27.292+03:00",
      "updated_at": "2022-02-15T14:42:27.292+03:00"
    }
  ],
  "responses": [
    {
      "id": 44,
      "status": 200,
      "incoming_id": 13,
      "info": "send successed",
      "created_at": "2022-02-15T14:36:41.799+03:00",
      "callback_incoming_url": null,
      "histories": [
        {
          "id": 7,
          "historyable_type": "Incoming::Response",
          "historyable_id": 44,
          "from": 100,
          "to": 102,
          "message": "waiting for send",
          "created_at": "2022-02-15T14:36:42.940+03:00",
          "updated_at": "2022-02-15T14:36:42.940+03:00"
        },
        {
          "id": 9,
          "historyable_type": "Incoming::Response",
          "historyable_id": 44,
          "from": 102,
          "to": 200,
          "message": "send successed",
          "created_at": "2022-02-15T14:42:27.238+03:00",
          "updated_at": "2022-02-15T14:42:27.238+03:00"
        }
      ]
    }
  ]
}

Подтверждение о принятии входящего запроса

Endpoint: /api/v1/:service/incomings/:id/acknowledge(.json)
Method: PUT

Подтверждение со стороны клиента об успешном принятии запроса. При этом происходит изменение статуса всех неподтверждённых запросов с идентификатором меньше или равным переданному :id. Возвращает число подтверждённых данной операцией запросов и дополнительную информацию.

  curl -X PUT -u identifier:secret https://agredator.ru/api/v1/fns-nalflproc/incomings/13/acknowledge

Пример ответа:

{
  "last_id":13,
  "acknowledged_id":13,
  "updated":5,
  "success":true
}

Получение логов входящего запроса

Endpoint: /api/v1/:service/incomings/:incoming_id/logs(.json)
Method: GET
Params:
- incoming_id: идентификатор входящего запроса, в рамках которого существует файл

Возвращает архив, содержащий файлы xml взаимодействия и файл metadata.json, содержащий служебные данные, связанные с входящим запросом. В случае указания формата json возвращает json, содержащий xml логи взаимодействия.

Пример запроса:

curl -u identifier:secret https://agredator.ru/api/v1/fssp-execution-documents/incomings/116/logs > /tmp/logs.zip 

Пример запроса с json форматом ответа:

curl -u identifier:secret https://agredator.ru/api/v1/fssp-execution-documents/incomings/logs.json > /tmp/logs.zip 

Пример ответа:

{
  "incoming_id": 116,
  "service": "fssp-execution-documents",
  "source": "fssp-execution-documents",
  "identifier": "51ccdd21-642f-4770-8885-64757c906b90",
  "created_at": "2021-12-06T11:45:44.013+03:00",
  "updated_at": "2021-12-06T11:46:05.858+03:00",
  "logs": [
    {
      "type": "getRequest",
      "request": "...",
      "response": "..."
    },
    {
      "type": "sendResponse",
      "request": "...",
      "response": "..."
    },
    {
      "type": "ack",
      "request": "...",
      "response": "..."
    }
  ]
}

Получение списка ответов на входящий запрос

Endpoint: /api/v1/:service/incomings/:incoming_id/responses(.json)
Method: GET

Возвращает список всех ответов на данный входящий запрос. Доступна фильтрация и пагинация.

Получить список ответов:

  curl -u identifier:secret https://agredator.ru/api/v1/fns-nalflproc/incomings/13/responses

Пример ответа:

{
  "has_next": false,
  "current_page": 1,
  "per_page": 15,
  "collection": [
    {
      "id": 44,
      "status": 200,
      "incoming_id": 13,
      "info": "send successed",
      "created_at": "2022-02-15T14:36:41.799+03:00",
      "callback_incoming_url": null,
      "histories": [
        {
          "id": 7,
          "historyable_type": "Incoming::Response",
          "historyable_id": 44,
          "from": 100,
          "to": 102,
          "message": "waiting for send",
          "created_at": "2022-02-15T14:36:42.940+03:00",
          "updated_at": "2022-02-15T14:36:42.940+03:00"
        },
        {
          "id": 9,
          "historyable_type": "Incoming::Response",
          "historyable_id": 44,
          "from": 102,
          "to": 200,
          "message": "send successed",
          "created_at": "2022-02-15T14:42:27.238+03:00",
          "updated_at": "2022-02-15T14:42:27.238+03:00"
        }
      ]
    }
  ]
}

Просмотр состояния ответа на входящий запрос

Endpoint: /api/v1/:service/incomings/:incoming_id/responses/:id(.json)
Method: GET

Возвращает полную информацию по данному ответу.

Просмотреть ответ:

  curl -u identifier:secret https://agredator.ru/api/api/v1/fns-nalflproc/incomings/13/responses/44

Пример ответа:

{
  "id": 44,
  "status": 200,
  "incoming_id": 13,
  "info": "send successed",
  "created_at": "2022-02-15T14:36:41.799+03:00",
  "callback_incoming_url": null,
  "histories": [
    {
      "id": 7,
      "historyable_type": "Incoming::Response",
      "historyable_id": 44,
      "from": 100,
      "to": 102,
      "message": "waiting for send",
      "created_at": "2022-02-15T14:36:42.940+03:00",
      "updated_at": "2022-02-15T14:36:42.940+03:00"
    },
    {
      "id": 9,
      "historyable_type": "Incoming::Response",
      "historyable_id": 44,
      "from": 102,
      "to": 200,
      "message": "send successed",
      "created_at": "2022-02-15T14:42:27.238+03:00",
      "updated_at": "2022-02-15T14:42:27.238+03:00"
    }
  ]
}

Создание ответа на входящий запрос

Endpoint: /api/v1/:service/incomings/:incoming_id/responses(.json)
Method: POST

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

параметр	описание	обязательный
response	Объект обертка	+
response.payload	Тело ответа	+
response.callback_incoming_url	Адрес для доставки изменения статуса POST-запросом	-

Создание ответа:

curl -u identifier:secret \
  -H "Content-Type: application/json; charset=utf-8" \
  -X POST \
  -d '{"response": {"payload": {"data": 111}}}' \
  https://agredator.ru/api/v1/fns-nalflproc/incomings/13/responses

Пример ответа:

{
  "id":45,
  "status":100,
  "incoming_id":13,
  "info":null,
  "created_at":"2022-02-17T18:43:33.606+03:00",
  "histories":[]
}

После получения подтверждения доставки ответа на входящий запрос (response successed) и/или ошибки, если callback_incoming_url задан, POST-запросом будет доставлено состояние ответа на входящий запрос (см. пример ответа).

API V0(совместимость)

Endpoint: /api/v0

Запрос к API представляет собой POST HTTP-запрос с передачей в теле запроса JSON-структуры и указанием заголовка:

Content-Type: application/json; charset=utf-8

К каждому запросу добавляются параметры:

client_id — идентификатор клиента
timestamp — содержит Unix Timestamp. Должен быть не старше 1 минуты от текущего времени сервера API. Например, 1473167919 означает 16:18:39 06.09.2016.
sign — значение подписи, вычисляемое как SHA256 (client_id + timestamp + secret). Например, client_id=test_client, secret=test_secret, timestamp=1473167919, SHA256("test_client1473167919test_secret") = 1ed686d71ca0be5e2cb16d5d2c88402ef64a4eb61295d36e80803453b906a0ea

Первичный, инициирующий запрос

Клиентская ИС отправляет API первичный, инициирующий запрос, в котором передаются данные пользователя. В ответ API возвращает уникальный идентификатор запроса, присвоенный СМЭВ-сервисом.

Пример тела запроса:

{
  "type": "VerifyRequest",
  "request": {
    "passportSeries": "1111",
    "passportNumber": "111111",
    "lastname": "Иванов",
    "firstname": "Иван",
    "middlename": "Иванович",
    "snils": "111-111-111 11",
    "inn": "111111111111"
  },
  "timestamp": "1495022010",
  "sign": "706f7f77bae5786dd014d746d4bc3f29c9c9d0235e6a43d562761944ae7fc072"
}

Пример ответа:

{
  "success": true,
  "response": {
    "code": "PROCESSING",
    "description": "В процессе обработки",
    "requestId": "295150771"
  }
}

Пример ответа с ошибкой:

{
  "success": false,
  "response": {
    "fault": {
      "faultCode": "Unauthorized request",
      "faultString": "ESIA-005008"
    }
  }
}

Вторичный, проверочный запрос

Клиентская ИС периодически вызывает API и передает полученный ранее идентификатор запроса. API отвечает либо статусом обработки запроса, либо ответом СМЭВ-сервиса, если он был получен.

Пример тела запроса:

{
  "type": "VerifyRequest",
  "request": {
    "requestId": "295150771"
  },
  "timestamp": "1495022521",
  "sign": "ce938fea966cbd61cea55ed51e47743ce02f4cf9c20a8c8a8ea4ac5a5bc5fad7"
}

Пример ответа:

{
  "success": true,
  "response": {
    "code": "VALID",
    "description": "Данные корректны"
  }
}

Пример ответа с ошибкой:

{
  "success": true,
  "response": {
    "code": "INVALID",
    "description": "Данные некорректны"
  }
}

Тестовые скрипты

Первичный, инициирующий запрос:

#!/bin/bash
timestamp=`date +%s`
secret=test_secret
client_id=test_client
sign=`echo -n $client_id$timestamp$secret | sha256sum | awk '{print $1}'`
server=localhost:3000

curl -iv \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"request": {"passportSeries": "1111", "passportNumber": "111111",
    "lastname": "Иванов", "firstname": "Иван", "middlename": "Иванович",
    "snils": "111-111-111 11", "inn": "111111111111"}, "type": "VerifyRequest",
    "timestamp": "'$timestamp'", "sign": "'$sign'"}' \
  "http://$server/api/v0/$client_id/uprid/uprid.json"

Вторичный запрос для получения результата. Идентификатор задается первым аргументом скрипта:

#!/bin/bash
timestamp=`date +%s`
secret=test_secret
client_id=test_client
sign=`echo -n $client_id$timestamp$secret | sha256sum | awk '{print $1}'`
server=localhost:3000

curl -iv \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"request": {"requestId": "'$1'"}, "type": "VerifyRequest",
    "timestamp": "'$timestamp'", "sign": "'$sign'"}' \
  "http://$server/api/v0/$client_id/uprid/uprid.json"

Примеры

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

Сведения о наличии действующих решений о приостановлении операций по счетам налогоплательщика

Документация: https://docs.agredator.ru/docs/services/fns/so/

Создание запроса:

curl -u identifier:secret \
  -H "Content-Type: application/json; charset=utf-8" \
  -X POST \
  -d '{"request": {"payload": {"bik": "041203729", "request_identity":
    "000000000000000000000000000000000001", "identity_type": "ИННЮЛ", "identity_value": "6321137880"}}}' \
  https://agredator.ru/api/v1/fns-so/requests

Пример ответа:

{
  "id": 6399,
  "status": 100,
  "client": "identifier",
  "info": null,
  "service": "fns-so",
  "created_at": "2019-07-29T10:27:51.440+03:00",
  "response": {},
  "ticket": null,
  "callback_url": null,
  "external_id": "6399",
  "histories": []
}

Проверка запроса:

  curl -u identifier:secret https://agredator.ru/api/v1/requests/6363

Пример ответа:

{

  "id": 6399,
  "status": 200,
  "client": "identifier",
  "info": "success result",
  "service": "fns-so",
  "created_at": "2019-07-29T10:27:51.440+03:00",

  "response": {
    "org_info": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ \"АВТО-ДОРСТРОЙ\"",
    "decision_info": {
      "bik": "041203729",
      "request_result": "1",
      "request_date_time": "2017-06-27T09:30:47"
    },
    "exchange_logs": [
      {
        "type": "sendRequest",
        "request": "\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003csoap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/...",
        "response": "\u003csoap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"\u003e\u003csoap:Body..."
      },
      {
        "type": "getResponse",
        "request": "\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003csoap:Envelope...",
        "response": "\u003csoap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"\u003e\u003csoap:Body..."
      }
    ],
    "identity_type": "ИННЮЛ",
    "identity_value": "6321137880",
    "decision_details": [
      {
        "bik": "042202803",
        "num": "3443/1334Р",
        "code": "3443",
        "date": "2017-02-12",
        "info_date": "2017-02-12T12:35:47"
      },
      {
        "bik": "042202824",
        "num": "702",
        "code": "6320",
        "date": "2017-02-09",
        "info_date": "2017-02-10T12:35:47"
      }
    ],
    "request_identify": "000000000000000000000000000000000001"
  },

  "ticket": "f547854f-3730-4894-9a72-684ff7ef45dc",
  "callback_url": null,
  "external_id": "6399",

  "histories": [
    {
      "id": 11739,
      "request_id": 6399,
      "from": 100,
      "to": 102,
      "message": "processing",
      "created_at": "2019-07-29T10:32:11.500+03:00",
      "updated_at": "2019-07-29T10:32:11.500+03:00"
    },
    {
      "id": 11742,
      "request_id": 6399,
      "from": 102,
      "to": 200,
      "message": "success result",
      "created_at": "2019-07-29T10:33:35.518+03:00",
      "updated_at": "2019-07-29T10:33:35.518+03:00"
    }
  ]
}

Структуры данных

Описание структур данных

Коллекция объектов

Схема:

{
  "type": "object",
  "properties": {
    "collection": {
      "$comment": "Коллекция запрашиваемых объектов",
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "current_page": {
      "$comment": "Текущая позиция выборки",
      "type": ["string", "integer"]
    },
    "per_page": {
      "$comment": "Количество элементов для построения выборки",
      "type": ["string", "integer"]
    },
    "total_count": {
      "$comment": "DEPRECATED: Общее число элементов в базе",
      "type": ["string", "integer"]
    },
    "has_next": {
      "$comment": "Признак присутствия следущей страницы",
      "type": "boolean"
    }
  },
  "required": ["collection", "current_page", "per_page", "has_next"]
}

Ошибка

Схема:

{
  "type": "object",
  "properties": {
    "error": {
      "$comment": "Обязательный признак ошибки",
      "type": "boolean",
      "enum": [true]
    },
    "status": {
      "$comment": "HTTP-статус ошибки",
      "type": "string"
    },
    "code": {
      "$comment": "Уникальный идентификатор ошибки",
      "type": "string"
    },
    "title": {
      "$comment": "Краткое описание ошибки",
      "type": "string"
    },
    "meta": {
      "$comment": "Дополнительная информация по ошибке",
      "type": ["object", null]
    }
  },
  "required": ["error", "status", "code", "title"],
  "additionalProperties": false
}

Запрос

Возможные статусы:

STATUS_CODE_100_NEED_REQUEST      = 100  # WAITING: [STATUS_CODE_100_NEED_REQUEST, STATUS_CODE_102_NEED_RESPONSE]
STATUS_CODE_102_NEED_RESPONSE     = 102

STATUS_CODE_200_COMPLETED         = 200  # COMPLETED: (200..299)

STATUS_CODE_400_BAD_REQUEST       = 400  # ERROR: (300..699)
STATUS_CODE_480_RESULT_ERROR      = 480
STATUS_CODE_490_RUNTIME_ERROR     = 490
STATUS_CODE_491_OLD_ERROR         = 491
STATUS_CODE_500_ERROR             = 500

Схема:

{
  "type": "object",
  "properties": {
    "id": {
      "$comment": "Идентификатор запроса. Уникален в рамках данного шлюза",
      "type": "integer"
    },
    "status": {
      "$comment": "Состояние обработки запроса. Аналогично HTTP-кодам",
      "type": "integer"
    },
    "client": {
      "$comment": "Идентификатор клиента, сделавшего запрос",
      "type": "string"
    },
    "service": {
      "$comment": "Имя сервиса, к которому направлен запрос",
      "type": "string"
    },
    "ticket": {
      "$comment": "Назначенный системой идентификатор запроса. Уникален в рамках всей системы",
      "type": ["string", "null"]
    },
    "response": {
      "$comment": "Ответ от запрашиваемого сервиса, специфичен для каждого сервиса",
      "type": "object"
    },
    "callback_url": {
      "$comment": "Адрес, на который необходимо доставить результат POST-запросом",
      "type": ["string", "null"]
    },
    "histories": {
      "$comment": "История изменения статуса запроса",
      "type": "array",
      "items": { "$ref": "/schemas/api/v1/request/history.json" }
    },
    "info": {
      "$comment": "Текущий статус запроса (из истории)",
      "type": ["string", "null"]
    },
    "created_at": {
      "$comment": "Дата создания запроса",
      "type": "string"
    }
  },
  "required": [
    "id", "status", "client", "histories",
    "info", "created_at", "ticket",
    "callback_url", "response"
  ],
  "additionalProperties": false
}

История запроса

Схема:

{
  "type": "object",
  "properties": {
    "id": {
      "$comment": "Идентификатор записи",
      "type": "integer"
    },
    "historyable_type": {
      "$comment": "Тип объекта истории (Ex. Incoming, Incoming::Response...).",
      "type": "string"
    },
    "historyable_id": {
      "$comment": "Идентификатор объекта истории.",
      "type": "integer"
    },
    "from": {
      "$comment": "Предыдущий статус",
      "type": "integer"
    },
    "to": {
      "$comment": "Новый статус",
      "type": "integer"
    },
    "message": {
      "$comment": "Коментарий",
      "type": ["string", "null"]
    },
    "created_at": {
      "$comment": "Дата создания",
      "type": "string"
    },
    "updated_at": {
      "$comment": "Дата изменения",
      "type": "string"
    }
  },
  "required": ["id", "historyable_type", "historyable_id", "from", "to", "message", "created_at"],
  "additionalProperties": false
}

Коллекции

Пагинация

Callback/push

Формат PUSH-адреса

Проверка callback/push

Подавай заявку сейчас