Mandarin

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

# Точки входа

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

ТЕСТИРОВАНИЕ

Для тестирования используйте данные из раздела Самозанятые.

# Аутентификация

Все запросы к API самозанятых аутентифицируются по протоколу OAuth 2.0 (Bearer). Формирование токена — в разделе Аутентификация запросов.

client_id и client_secret выдает Служба поддержки (opens new window).

В примерах ниже используется шаблон --header 'Authorization: Bearer '.

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

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

В параметре scope передайте права для вызываемых методов API через пробел. Пример: self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel.

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

Что нужно сделать для работы сервиса:

  1. Самозанятый скачивает приложение "Мой налог" в AppStore (opens new window), Google Play (opens new window) или регистрируется на сайте ФНС (opens new window).

Приложение, страница 1

  1. Вы по API направляете запрос в Mandarin с ИНН самозанятого, для получения согласия от самозанятого на следующие действия:

  • "Корректировка сведений о моих доходах, поданных партнером" - передача в ФНС информации о полученном доходе.

  • "Получение информации по моим доходам" - получение информации от ФНС об общей сумме дохода за период для контроля лимита в 2,4 млн.руб в год.

  • "Отражение дохода от моего имени" - передача кассового чека от самозанятого вам (компании-плательщику).

  1. Самозанятый в разделе "Партнеры" утверждает ваш запрос на действия из предыдущего пункта.

Приложение, страница 2

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

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

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

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

curl --request POST \
  --url https://api.psp.io/self-employed-2/v1/tin/bind \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}' \
--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 --request POST \
  --url https://api.psp.io/self-employed-2/v1/tin/unbind \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}' \
--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 --request GET \
  --url https://api.psp.io/self-employed-2/v1/tin/123456789012 \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}'

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

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

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

Параметр Описание
id уникальный идентификатор запроса
inn ИНН самозанятого
status Статус самозанятого, см. список статусов

# Чеки

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

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

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

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

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

curl --request POST \
  --url https://api.psp.io/self-employed-2/v1/receipts \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "inn": "123456789012",
    "price": 100,
    "title": "Оплата заказа №1234",
    "external_id": "order-12345"
}'

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

{
  "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 Название товара/услуги, указанные в запросе
external_id Уникальный идентификатор чека

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

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

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

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

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

curl --request PATCH \
  --url https://api.psp.io/self-employed-2/v1/receipts \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}' \
--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, который был получен при создании.

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

curl --request GET \
  --url https://api.psp.io/self-employed-2/v1/receipts/{cheque_id} \
--header 'MID: {{mid}}' \
--header 'Authorization: Bearer {{access_token}}'

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

{
    "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"
        }
    ]
}

← Custom Form →