# Самозанятые
# Точки входа
Боевое (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
# Подключение
Что нужно сделать для работы сервиса:
- Самозанятый скачивает приложение "Мой налог" в AppStore (opens new window), Google Play (opens new window) или регистрируется на сайте ФНС (opens new window).
- Вы по API направляете запрос в Mandarin с ИНН самозанятого, для получения согласия от самозанятого на следующие действия:
"Корректировка сведений о моих доходах, поданных партнером" - передача в ФНС информации о полученном доходе.
"Получение информации по моим доходам" - получение информации от ФНС об общей сумме дохода за период для контроля лимита в 2,4 млн.руб в год.
"Отражение дохода от моего имени" - передача кассового чека от самозанятого вам (компании-плательщику).
- Самозанятый в разделе "Партнеры" утверждает ваш запрос на действия из предыдущего пункта.
# Подключение самозанятого по ИНН
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
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"
}'
В случае успешного выполнения, ответ будет включать в себя:
| Параметр | Описание |
|---|---|
inn | ИНН самозанятого |
id | уникальный идентификатор запроса |
Синхронный ответ:
{
"id": "3ab4e73d-a197-4a2f-9b92-69ef07468b04",
"inn": "185796979287"
}
Callback:
{
"id": "80cf6b02-795f-486f-a515-562a41a87429",
"inn": "123456789012",
"status": "ACTIVE"
}
Параметры Callback:
| Параметр | Описание |
|---|---|
id | уникальный идентификатор запроса |
inn | ИНН самозанятого |
status | Статус самозанятого, см. список статусов |
# Список статусов
| Статус | Описание |
|---|---|
| ACTIVE | Является активным подтвержденным самозанятым |
| NOT_SELF_EMPLOYEE | Не является самозанятым |
| REVOKED_EXPLICITLY | Самозанятый отвязан |
| BINDING_IN_PROGRESS | В процессе подтверждения статуса самозанятого и выдачи разрешения нашей системе в "Мой налог" |
| BINDING_IN_PROGRESS | В процессе отзыва "статуса самозанятого" и разрешений нашей системе в "Мой налог" |
| INITIAL | Пользователь системе не известен, операций по привязке этого пользователя ранее не производилось. |
# Отключение самозанятого
Метод позволяет отменить привязку идентификационного номера налогоплательщика (ИНН) самозанятого.
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
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"
}
]
}