Интеграция с сервисами Наложка

Начало работы

Для работы с любым из предоставляемых сервисов необходимо получить ключ доступа (токен), который представляет собой строку из букв латиницы и цифр длиной 32 символа. Токен должен передаваться в с каждым запросом к API в виде HTTP-заголовка X-Nalogka-Auth-Token или в строке запроса параметром auth_token (этот способ менее предпочтителен, т.к. токен может остаться в логах прокси-серверов).

Как получить ключи доступа к API

Для получения ключей доступа необходимо заполнить заявку на странице https://наложка.рф/integration.

Мы предоставляем два ключа доступа к API (один для работы в тестовом режиме, а второй — боевой). Сохранность тестовых данных не гарантирована. Периодически, в ночное время по MSK, пользовательские тестовые данные очищаются.

Внимание!

Пожалуйста, храните ключи безопасно. Контролируйте круг лиц, имеющих к ним доступ. Создатели сервиса «Наложка» не несут ответственности за вред, причиненный в следствие “утечки” выданных вам ключей.

В случае компрометации ключа необходимо срочно написать email на адрес integration@nalogka.com с объяснением ситуации и просьбой сгенерировать новый ключ.

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

Сервис получает и отдает данные в формате JSON.

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

GET /delivery/cities?filter=name=Улья
Host: delivery.api.nalozhka.ru
Accept: application/json
X-Nalogka-Auth-Token: wbdryC97s5OczyoySDyFLhJJmLlFJGen

В результате может прийти один из ответов, описанных в документации метода.

Пример заголовков успешного ответа:

HTTP/1.1 200 OK
Server: nginx/1.13.7
Date: Sat, 17 Mar 2018 05:38:08 GMT
Content-Type: application/json
Content-Length: 2356

Ошибка при неуказанном ключе аутентификации:

HTTP/1.1 401 Unauthorized
Server: nginx/1.13.7
Date: Sat, 17 Mar 2018 05:51:50 GMT
Content-Type: application/json
Content-Length: 180

{
   "~type" : "AuthenticationRequiredError",
   "message" : "Необходима авторизация."
}

Ошибка при получении недействительного ключа аутентификации:

HTTP/1.1 403 Forbidden
Server: nginx/1.13.7
Date: Sat, 17 Mar 2018 05:48:15 GMT
Content-Type: application/json
Content-Length: 79

{
   "~type" : "AuthenticationFailureError",
   "message" : "Username could not be found."
}

Работа со списками

В описании ресурсов, возвращающих списки, вы можете видеть перечисление полей данных, по которым допустима фильтрация. В таких запросах фильтр передается параметром запроса filter и содержит список условий, отделенных друг от друга символом ;. Каждое условие состоит из трех элементов (именно в нижеприведенном порядке):

  • имя поля — из списка допустимых для фильтрации,
  • операция — одна из операций сравнения =, !=, >, <, <= или >=,
  • значение — число или строка (в том числе и пустая).

Если в одном из условий будет использовано имя поля, недопустимое для фильтрации, то статус ответа сервера будет 400 с текстом ошибки "Недопустимые параметры фильтрации".

Для операции = особое значение имеет символ *, стоящий в начале или в конце значения. Он говорит о том, что сравнение должно производиться на частичное совпадение (совпадение подстроки). Например, под условие field=val* попадут все данные, у которых значение поля field начинается с "val", а под field=*ue попадут данные, у которых значение field заканчивается на "ue".

← Безопасные Сделки →