Self-employed

Entry points

Production environment for authorization: https://accounts.mandarin.io/ (opens new window)
Production environment for API requests: https://api.psp.io/ (opens new window)

TESTING

For testing, use the data from the Self-employed section.

Authentication

All requests to the Self-Employed API are authenticated using the OAuth 2.0 (Bearer) protocol. Token generation is in the Request Authentication.

client_idAndclient_secretissued by Support Service (opens new window).

The examples below use the template--header 'Authorization: Bearer '.

Request for a token

curl --request POST \
  --url https://accounts.mandarin.io/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'

In the parameterscopepass rights for called API methods separated by a space. Example:self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel.

Connection

What you need to do for the service to work:

1. A self-employed person downloads the “My Tax” application in AppStore (opens new window), Google Play (opens new window) or register on the Federal Tax Service website (opens new window).

2. Using the API, you send a request to Mandarin with the TIN of the self-employed person to obtain consent from the self-employed person for the following actions:

• “Adjusting information about my income submitted by a partner” - transferring information about income received to the Federal Tax Service.

• “Receiving information on my income” - receiving information from the Federal Tax Service about the total amount of income for the period to control the limit of 2.4 million rubles per year.

• “Reflection of income on my behalf” - transfer of a cash receipt from a self-employed person to you (the paying company).

3. The self-employed person in the “Partners” section approves your request for action from the previous paragraph.

Connecting a self-employed person using TIN

Request parameters:

Parameter	Obligation	Description
inn	Yes	Self-employed Taxpayer Identification Number
callback_url	Yes	The URL to which the response will be sent.

Query example:

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"
}'

If successful, the response will include:

Parameter	Description
inn	Self-employed Taxpayer Identification Number
id	unique request identifier

Synchronous response:

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

```json
{
   "id": "80cf6b02-795f-486f-a515-562a41a87429",
   "inn": "123456789012",
   "status": "ACTIVE"
}
```**Callback parameters:**

| Parameter | Description |
|--------------|----------------------------------------------------------------|
|`id`| unique request identifier |
|`inn`| Self-employed Taxpayer Identification Number |
|`status`| Self-employed status, see list of statuses |

### List of statuses

| Status | Description |
|---------------------|------------------------------------------------------------------------------------------------|
| ACTIVE | Is an active verified self-employed |
| NOT_SELF_EMPLOYEE | Not self-employed |
| REVOKED_EXPLICITLY | Self-employed untied |
| BINDING_IN_PROGRESS | In the process of confirming self-employed status and issuing permission to our system in “My Tax” |
| BINDING_IN_PROGRESS | In the process of revoking “self-employed status” and permissions from our system in “My Tax” |
| INITIAL | The user is unknown to the system; no operations to bind this user have been performed previously.  |

### Disabling self-employed

The method allows you to unlink the taxpayer identification number (TIN) of a self-employed person.

**Request parameters:**

| Parameter | Obligation | Description |
|----------------|----------------|------------------------------------------------------------|
|`inn`| Yes | Self-employed Taxpayer Identification Number |
|`callback_url`| Yes | The URL to which the response will be sent.                |

**Query example:**

```bash
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"
}'

Synchronous response:

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

Callback:

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

Response Options

Parameter	Description
id	unique request identifier
inn	Self-employed Taxpayer Identification Number
status	Self-employed status, see list of statuses

Checking self-employed status

The method allows you to obtain information about self-employed people based on their taxpayer identification number (TIN).

Query example:

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

Synchronous response:

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

Response options:

Parameter	Description
id	unique request identifier
inn	Self-employed Taxpayer Identification Number
status	Self-employed status, see list of statuses

Checks

Formation of a check

Method for creating a receipt in the SMZ service.

Request parameters:

Parameter	Obligation	Description
inn	Yes	Self-employed Taxpayer Identification Number
цена	Yes	Price of goods/services
title	Yes	Name of the product/service in the receipt (no more than 160 characters)
external_id	Yes	Unique receipt identifier

Query example:

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"
}'

Synchronous response:

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

Response Options

Parameter	Description
cheque_id	Unique identifier of the created check
inn	Self-employed Taxpayer Identification Number
message	Additional information or error message
session_id	id of the created check
status	Request status, see list of statuses
url	URL to print the generated receipt
title	Name of product/service specified in the request
external_id	Unique receipt identifier

List of check statuses:

Status	Description
success	The check was successfully created
failed	Failed to create check. The details of the error can be checked in the response received (message).

Canceling a check

Method for canceling a previously created check.

Query example:

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"
}'

Synchronous response

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

Receiving information on a check

Request for check data by its ID, which was received during creation.

Query example:

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

Synchronous response:

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

Answer if the check is not found:

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