Описание

Шлюз представляет собой информационную систему для выполнения 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

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

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

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

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

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

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

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

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

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

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

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

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

Для асинхронного получения изменения статуса ответа на входящий запрос должен быть установлен 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,
      "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,
  "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 Имя сервиса. Может быть задано через url +
request.payload Тело запроса +
request.callback_url Адрес для доставки результата 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,
  "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,
  "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,

  "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
}
  • Описание
  • Общее описание API
  • Коллекции
  • Пагинация
  • Callback/push
  • Формат PUSH-адреса
  • Проверка callback/push
  • API V1
  • Получение списка запросов
  • Просмотр состояния запроса
  • Создание запроса
  • Модификация шага запроса
  • Удаление запроса
  • Получение информации (JSON) о файле вложений
  • Получение содержимого файла вложений
  • Загрузка файла вложений в систему
  • Получение логов запроса
  • Статистика
  • Получение списка входящих запросов
  • Просмотр входящего запроса
  • Подтверждение о принятии входящего запроса
  • Получение логов входящего запроса
  • Получение списка ответов на входящий запрос
  • Просмотр состояния ответа на входящий запрос
  • Создание ответа на входящий запрос
  • API V0(совместимость)
  • Первичный, инициирующий запрос
  • Вторичный, проверочный запрос
  • Тестовые скрипты
  • Примеры
  • Сведения о наличии действующих решений о приостановлении операций по счетам налогоплательщика
  • Структуры данных
  • Коллекция объектов
  • Ошибка
  • Запрос
  • История запроса
    • Подавай заявку сейчас

    Оставьте свои контактные данные и наш менеджер свяжется с вами в ближайшее время