Mandarin

# Самозанятые

# Точки входа

Боевое (production) окружение для авторизации: https://accounts.mandarinbank.com/ (opens new window)
Боевое (production) окружение для запросов: https://api.psp.io/ (opens new window)

# Аутентификация запросов

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Токен действует в течение 36 000 секунд (10 часов). Если срок действия истек, токен нужно запросить еще раз.

Обратитесь в Службу поддержки (opens new window), чтобы узнать ваш client_id и client_secret, чтобы получить access_token.

Запрос на получение токена

Включает в себя обязательные form-data параметры, которые передаются в теле запроса (параметры application.client_id и application.client_secret неизменны для приложения и хранятся на стороне клиента).

Параметр Описание Пример
grant_type Грант авторизации (всегда равен client_credentials). client_credentials
client_id Идентификатор клиента (равен значению application.client_id, предоставленному Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret Секретный ключ-пароль клиента (равен значению application.client_secret, предоставленному Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope Запрашиваемые скоупы (области доступа):
например, self-employed:cheques.register - "Регистрация".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel

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

curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel'

Ответ:

Параметр Описание Пример
access_token Токен (ключ доступа). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in Срок действия токена (в секундах). Всегда равен 36 000 секунд (10 часов). 36000
token_type Тип токена (всегда равен Bearer). Bearer
scope Разрешенные скоупы (области доступа): например, self-employed:cheques.register - "Регистрация".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 self-employed:cheques.register
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "scope=self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel"
}

Использование токена

Указывается в headers каждого запроса, в поле Authorization, после зарезервированного слова Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Подключение

# Список статусов

Статус Описание
ACTIVE Является активным подтвержденным самозанятым
NOT_SELF_EMPLOYEE Не является самозанятым
REVOKED_EXPLICITLY Самозанятый отвязан
BINDING_IN_PROGRESS В процессе подтверждения статуса самозанятого и выдачи разрешения нашей системе в "Мой налог"
BINDING_IN_PROGRESS В процессе отзыва "статуса самозанятого" и разрешений нашей системе в "Мой налог"
INITIAL Пользователь системе не известен, операций по привязке этого пользователя ранее не производилось.
                                      |

# Подключение самозанятого по ИНН

В процессе выполнения запроса от мерчанта к Mandarin, осуществляется запрос в сервис Самозанятых (СМЗ), в котором передается ИНН. СМЗ на этот запрос отдает идентификатор (для асинхронного взаимодействия) запроса, который сохраняется в системе Mandarin. После того, как СМЗ асинхронно обработает запрос от Mandarin, осуществляется обратный запрос (callback) от СМЗ в Mandarin с результатами обработки. После обработки запроса callback на стороне Mandarin, формируется обратный запрос (callback) к мерчанту с результатом обработки переданного ИНН.

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

Параметр Обязательность Описание
inn Да Идентификационный номер налогоплательщика физического лица.
callback_url Да URL-адрес, на который будет отправлен ответ.

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

curl --location 'https://api.psp.io/self-employed/v1/tin/bind' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "callback_url": "https://webhook.site/28b30c34-9fbd-4e98-b1b7-e20a999d530b"
}'

В случае успешного выполнения, ответ будет включать в себя:

  • id: уникальный идентификатор запроса.
  • inn: привязанный идентификационный номер налогоплательщика.

Синхронный ответ:

{
  "id": "3ab4e73d-a197-4a2f-9b92-69ef07468b04",
  "inn": "185796979287"
}

Callback:

ОБРАТИТЕ ВНИМАНИЕ!

Необходимо заранее сообщить url для отправки коллбэков в Mandarin!

{
   "id": "80cf6b02-795f-486f-a515-562a41a87429",
   "inn": "123456789012",
   "status": 0,
   "message": null
}

Параметры Callback:

Параметр Тип Описание
id uuid Идентификатор запроса
inn string ИНН
status integer Статус ответа от СМЗ, возможные варианты:
0 - успех;
1 - завершен с ошибкой;
8 - окончен срок перманентного запроса в ФНС;
408 - ошибка timeout (долгий ожидание ответа от ФНС)
message string Текст ошибки на статусы: 1, 8, 408

# Отключение самозанятого

Метод позволяет отменить привязку идентификационного номера налогоплательщика (ИНН) самозанятого.

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

Параметр Обязательность Описание
inn Да Идентификационный номер налогоплательщика физического лица.
callback_url Да URL-адрес, на который будет отправлен ответ.

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

curl --location 'https://api.psp.io/self-employed/v1/tin/unbind' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "callback_url": "https://webhook.site/28b30c34-9fbd-4e98-b1b7-e20a999d530b"
}'

Синхронный ответ:

{
  "id": "1b45f664-337c-4441-8f9b-ad018a9508c6",
  "inn": "185796979287"
}

Callback:

{
    "id": "9a79c2a6-d9f7-4613-a1ae-c31981e61eb9",
    "inn": "185796979287",
    "status": "REVOKED_EXPLICITLY"
}

Параметры ответа

  • id: идентификатор процесса отмены привязки.
  • inn: идентификационный номер налогоплательщика.
  • status: статус самозанятого

# Проверка статуса самозанятого

Метод позволяет получить сведения о самозанятых на основе идентификационного номера налогоплательщика (ИНН).

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

curl --location -g 'https://api.psp.io/self-employed/v1/tin/123456789012' \
--header 'MID: 1234' \
--header 'Authorization: Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data ''

Синхронный ответ:

{
  "id": "9a79c2a6-d9f7-4613-a1ae-c31981e61eb9",
  "inn": "123456789012",
  "status": "ACTIVE"
}

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

  • id - идентификатор процесса отмены привязки.
  • inn - идентификационный номер налогоплательщика.
  • status - статус самозанятого.

# Чеки

# Формирование чека

Метод для создания чека в сервисе СМЗ.

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

Параметр Обязательность Описание
inn Да ИНН (идентификационный номер налогоплательщика), связанный с чеком.
цена Да Цена товара/услуги
title Да Название товара/услуги в чеке

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

curl --location 'https://api.psp.io/self-employed/v1/receipts' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "price": 100,
    "title": "Оплата заказа №1234"
}'

Синхронный ответ:

{
  "cheque_id": "20172zyc8z",
  "inn": "123456789012",
  "message": "",
  "session_id": "edccadd7-e5f9-4de2-8088-64e6adf0959b",
  "status": "success",
  "url": "https://lknpd.nalog.ru/api/v1/receipt/623406197779/20172zyc8z/print",
  "title": "Оплата заказа №1234"
}

Параметры ответа

  • cheque_id - уникальный идентификатор созданного чека.
  • inn - ИНН, связанный с чеком.
  • message - дополнительная информация или сообщение об ошибке.
  • session_id - id созданного чека.
  • status - статус запроса, см. список статусов ниже.
  • url - URL-адрес для печати созданного чека.
  • title - Название товара/услуи, указанные в запросе.

Список статусов:

Статус Описание
success Чек успешно создан
failed Не удалось создать чек. Подробности ошибки можно проверить в полученном ответе (message).

# Аннулирование чека

Метод для отмены созданного чека.

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

curl --location --request PATCH 'https://api.psp.io/self-employed/v1/receipts' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "cheque_id": "20172zyc8z",
    "inn": "123456789012",
    "code": "REFUND"
}'

Синхронный ответ

{
  "cheque_id": "20172zyc8z",
  "inn": "123456789012",
  "status": "cancelled",
  "url": "https://lknpd.nalog.ru/api/v1/receipt/623406197779/20172zyc8z/print"
}

# Получение информации по чеку

Запрос данных чека по его ID, который был получен при создании.

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

GET https://api.psp.io/self-employed/v1/receipts/<cheque_id>

Синхронный ответ:

{
    "cheque_id": "test-123456789012-cheque-id",
    "inn": "123456789012",
    "message": null,
    "session_id": "0c518aea-2807-406a-830d-959b55a05c3e",
    "status": "success",
    "url": null,
    "title": "Оплата заказа №1234"
}

Ответ в случае, если чек не найден:

{
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "cheque_id",
            "description": "R\ne\nc\ne\ni\np\nt\n \nn\no\nt\n \nf\no\nu\nn\nd\n \nt\ne\ns\nt\n-\n1\n2\n3\n4\n5\n6\n7\n8\n9\n0\n1\n2\n-\nc\nh\ne\nq\nu\ne\n-\ni\nd"
        }
    ]
}

← Пользовательский интерфейс →