The document describes the technical information about API «Ferma» service.
The «Ferma» service works with the fiscal data format (FFD) version 1.2.
Requests are executed in accordance with the HTTP protocol over an encrypted channel. Requests and responses are submitted in JSON format.
The documentation describes the requests of the «Ferma» service.
Picture 1 shows the requests in the «Ferma» service.
Requests and responses in the «Ferma» service are executed in UTF-8 encoding. In the «Ferma» service, requests are executed by POST and GET methods.
The server sends the responses in JSON format. The code of the successful response, according to the HTTP protocol, is 200.
A successful response has the following form:
{
"Status": "Success",
"Data": {}
}
Description of response parameters:
If the response to the request is unsuccessful,
the response code in accordance with the HTTP protocol is not equal to 200 and has the following form:
{
"Status": "Failed",
"Error": {
Code: 0,
Message: "string"
}
}
Description of response parameters:
To access the «Ferma» service multiple times, you need an authentication key. You can get an authentication key using a POST request. In the request, you pass the authorization parameters of the «Ferma» service.
The following parameters are passed in the request body:
The parameter values can be obtained in the client's personal account in the «Ferma» section, after paying for the «Ferma» service, or find out from your manager.
Request:
POST https://ferma.ofd.ru/api/Authorization/CreateAuthToken
Request body:
{
"Login": "12345","Password": "56789"
}
A successful request will have a code equal to 200.
Example of a successful response to an authentication key request:
{
"Status": "Success",
"Data": {
"AuthToken": "f3accdfda7574736ba94a78d00e974f4",
"ExpirationDateUtc": "2017-01-24T14:44:21"
}
}
The response contains the following parameters:
The received authentication key is required in «Ferma» service requests.
Example of a request using an authentication key:
POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken={Code1}
The section presents a general JSON schema, a description of the parameters, and also describes how to work with the «Ferma» API.
Attention. The «Ferma» service is asynchronous, sending a receipt by the “Receipt” method and successfully obtaining a transaction ID is not a successful completion of the formation of a cash receipt. To complete the operation, you need to configure the correct processing of Callback responses and configure receipt of receipt data through the methods "Status", "list", "list2". If a value with a URL was filled in in the «CallbackUrl» parameter, then after sending a request for the formation of a cash receipt (successful or unsuccessful), a POST response will be sent to the URL specified in the «callbackUrl» parameter. The description of the parameters of the response to the «CallbackUrl» value is presented in chapter 3.9 If no response has been received within 300 seconds, you need to execute the request checking the status of the cash receipt.
The section presents a general JSON scheme of the request for the formation of fiscal documents in the «Ferma» service, as well as a description of all the request parameters. The section contains examples of JSON schemes for requesting the formation of fiscal documents in the «Ferma» service.
A general scheme with parameters is presented, the diagram shows all the parameters for working with the API.
To correctly configure your information system with the «Ferma» API, use examples of JSON schemas. Examples of JSON schemas are presented in section 3.2.5.
JSON schema:
{
"Request":
{
"Inn": "string",
"Type": "string",
"InvoiceId": "string",
"CallbackUrl": "string",
"CustomerReceipt":
{
"CheckMcMode": "string",
"TaxationSystem": "string",
"Email": "string",
"Phone": "string",
"PaymentType": integer,
"KktFA": boolean,
"AutomatNumber": "string",
"BillAddress": "string",
"CustomUserProperty":
{
"Name": "string",
"Value": "string"
},
"PaymentAgentInfo":
{
"AgentType": "string",
"TransferAgentPhone": "string",
"TransferAgentName": "string",
"TransferAgentAddress": "string",
"TransferAgentINN": "string",
"PaymentAgentOperation": "string",
"PaymentAgentPhone": "string",
"ReceiverPhone": "string",
"SupplierInn": "string",
"SupplierName": "string",
"SupplierPhone": "string"
},
"CorrectionInfo":
{
"Type": "string",
"Description": "string",
"ReceiptDate": "string",
"ReceiptId": "string"
},
"ClientInfo":
{
"Name": "string",
"Inn": "string",
"Birthday": "string",
"Citizenship": "string",
"IdDocType": "string",
"IdDocData": "string",
"Address": "string"
},
"IndustryRequisite":
{
"FoivId": "string",
"DocDate": "string",
"DocNumber": "string",
"Value": "string"
},
"OperationRequisite":
{
"Id": "string",
"Details": "string",
"DateTime" : "string"
},
"Items":
[
{
"Label": "string",
"Price": floating point,
"Quantity": floating point,
"Amount": floating point,
"Vat": "string",
"Excise": floating point,
"Measure": "string",
"PaymentMethod": integer,
"IndustryRequisite":
{
"FoivId": "string",
"DocDate": "string",
"DocNumber": "string",
"Value": "string"
},
"AdditionalRequisite": "string",
"OriginCountryCode": "string",
"CustomsDeclarationNumber": "string",
"PaymentType": integer,
"MarkingCodeData":
{
"Type": "string",
"Code": "string",
"PlannedStatus": "string",
"Fractional":
{
"Numerator": integer,
"Denominator": integer
}
},
"PaymentAgentInfo":
{
"AgentType": "string",
"TransferAgentPhone": "string",
"TransferAgentName": "string",
"TransferAgentAddress": "string",
"TransferAgentINN": "string",
"PaymentAgentOperation": "string",
"PaymentAgentPhone": "string",
"ReceiverPhone": "string",
"SupplierInn": "string",
"SupplierName": "string",
"SupplierPhone": "string"
}
}
],
"PaymentItems":
[
{
"PaymentType": integer,
"Sum": floating point
}
],
"AdditionalReceiptProp":
},
"Cashier":
{
"Name": "string",
"Inn": "string"
}
}
}
The tables show the parameters of their type and format of values, a description of the values, as well as a sign of the need for a query.
In table 3.1. the description of the parameter necessity attribute in the request is presented
Value | Description |
---|---|
1 | The parameter must be part of the request |
2 | The parameter must be part of the request, in the cases specified in the order of the Federal Tax Serviceот 14.09.2020г. № ЕД-7-20/662@the note to the specified details may not include the composition of the request |
3 | The parameter may not be included in the request |
The description of the request parameters are presented in the Table table 3.2.
Parameter | Parameter | Value format | Description | TAG3) | Required4) |
---|---|---|---|---|---|
Inn | String | Identification number of the taxpayer's organization | 1018 | 1 | |
Type | String | Type fiscal document (cash receipt). The type can have the following values: | 1054 | 1 | |
– «Income» — receiving funds from the buyer; | |||||
– «IncomeReturn» — refund of funds received from the buyer; | |||||
– «IncomePrepayment» — advance payment from the buyer; | |||||
– «IncomeReturnPrepayment» — refund of the advance payment; | |||||
– «IncomeCorrection» — correction receipt/income; | |||||
– «BuyCorrection» — correction receipt/expense; | |||||
– «IncomeReturnCorrection» - чcorrection receipt/Return of income; | |||||
– «ExpenseReturnCorrection» - чек коррекции/Return of expense; | |||||
– «Expense» — disbursement of funds to the buyer; | |||||
– «ExpenseReturn» — refund of funds issued to the buyer. | |||||
InvoiceId | String | The identifier assigned by your information system in the request for the formation of a cash receipt. The use of the identifier prevents the formation of duplicate checks Attention! Change the value of the «InvoiceId» to resend the request for receipts with the status «3» | |||
CallbackUrl | String | URL. The parameter specifies the URL value. If the field is filled in correctly, then after processing the document (successful or unsuccessful finalization in the KKT: status «CONFIRMED» or «KKT_ERROR»), The response will be sent by POST request to the URL specified in this field. The correctness of the filled field is determined by the regular expression:^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([a-zA-Z0-9а-яА-Я\-\.\?\,\'\/\\\+&=%\$#_]*)?$\\. The description of the parameters of the response to the «СallbackUrl» value is presented in section 3.9. | |||
CustomerReceipt | Object | Contents of the customer receipt. Description of the parameter «CustomerReceipt» are shown in the table 3.3. | |||
Cashier 5) | Object | Information about the cashier | |||
Name | String | Name cashier | 1021 | 2 | |
Inn | String | Cashier's Tax Identification number | 1203 | 3 |
Parameter | Parameter | Value format | Description | TAG6) | Required7) |
---|---|---|---|---|---|
CheckMcMode | String | Marking Code Verification parameter The parameter in the request is optional. Before punching the receipt, the cashier will automatically check the marking code. If you did not specify the «CheckMcMode» parameter in the request, the check will break through with any result of checking the marking code in the CRPT. If you passed one of the following values: | |||
- IGNORE_ANY_ERRORS - regardless of the result of the check, it is set by default, a cash receipt will be generated | |||||
- REQUIRE_NO_M_MINUS - the cashier will generate a receipt if the result of checking the KKM in the CRPT is not equal to the value [М-]. If the result of the code check turns out to be equal to the value [М-] the cash register will not generate a cash receipt | |||||
TaxationSystem | String | Taxation system. Attention! The list of application values of taxation systems is formed at the stage of registration of the cash register. To change the list of acceptable values, you need to re-register the cash register. The parameter of the taxation system can take the following values: | 1055 | 1 | |
– «Common» or «0» — general taxation system; | |||||
– «SimpleIn» or «1» — simplified taxation system (income); | |||||
– «SimpleInOut» or «2» — simplified taxation system (income minus expense); | |||||
– «UnifiedAgricultural» or «4» — unified agricultural tax; | |||||
– «Patent» or «5» — patent taxation system. | |||||
Email 8) | String | Customer's email address | 1008 | 2 | |
Phone 9) | String | Customer's contact phone number | 1008 | 2 | |
PaymentType | Integer | Indication of the subject of calculation for the entire receipt. Attention! If the value is not specified by the client in this field, the default value is used, which is set by default when setting up a «Ferma» service account. The list of possible values is listed in the section 3.1.4. | 1212 | 1 | |
KktFA | Boolean | If the FA cash register is used in the «Ferma» service, you must set the value to true. If you use the FS cash register, you must set the value to false. Касса ФА может применятся для: – vending machine, when making payments for goods or services; – making payments for travel in automated mode (through a validator) or making payments through the conductor's terminal. | |||
AutomatNumber | String | Automatic device number | 1036 | 2 | |
BillAddress | String | Place of settlement | 1187 | 1 | |
CustomUserProperty | Object | Additional user details, taking into account the specifics of the field of activity in which the calculations are carried out | 1084 | 3 | |
Name | String | The name of the additional user details, taking into account the specifics of the field of activity in which the calculations are carried out | 1085 | 3 | |
Value | String | The value of the user's additional details, taking into account the specifics of the field of activity in which the calculations are carried out | 1086 | 3 | |
PaymentAgentInfo 10) | Object | The parameter contains the data of the payment agent | 1223 | 2 | |
AgentType 11) | String | Type (attribute) of the payment agent. Possible values: | 1057 | 3 | |
BANK_PAYMENT_AGENT — bank payment agent; | |||||
BANK_PAYMENT_SUBAGENT — bank payment subagent; | |||||
PAYMENT_AGENT — payment agent; | |||||
PAYMENT_SUBAGENT — payment subagent; | |||||
CONFIDANT — attorney; | |||||
COMMISSIONER — commission agent; | |||||
AGENT — agent. | |||||
TransferAgentPhone 12) | String | Phone number of the money transfer operator | 1075 | 3 | |
TransferAgentName 13) | String | Agent's name | 1026 | 2 | |
TransferAgentAddress 14) | String | Agent's address | 1005 | ||
TransferAgentINN 15) | String | Taxpayer identification number of the agent | 1016 | 2 | |
PaymentAgentOperation 16) | String | Payment Agent operation | 1044 | 2 | |
PaymentAgentPhone 17) | String | Phone number of the payment agent | 1073 | 2 | |
ReceiverPhone 18) | String | Consumer's phone number | 1074 | 3 | |
SupplierInn 19) | String | Taxpayer identification number of the supplier | 1226 | 2 | |
SupplierName 20) | String | Name of the supplier | 1225 | 2 | |
SupplierPhone 21) | String | Supplier's phone number | 1171 | 3 | |
CorrectionInfo | Object | Parameter with the data structure for the correction receipt. Attention! The structure is present in the data only if a correction receipt is generated. To generate a regular receipt, this structure is not needed. | 1174 | 1 | |
Description | String | Description of correction and reasons for correction | 1 | ||
Type | String | Type of correction: SELF — the correction is made independently; INSTRUCTION — the correction is made according to the order of the tax department | 1173 | 3 | |
ReceiptDate | String | The date of the check breakdown to which the correction check is applied. In the format «DD.MM.YY», where DD — day, MM — month, YY — year. | 1178 | 3 | |
ReceiptId | String | Number of the order of the tax agency | 1179 | 3 | |
ClientInfo | Object | Customer data | 1256 | 2 | |
Name | String | Full name or name of the organization, if the client is a legal entity. No more than 256 characters in the field | 1227 | 2 | |
Inn | String | The taxpayer identification number of the buyer. Length 10-12 numbers | 1228 | 2 | |
Birthday | String | Date of birth of the buyer (client). In the format «DD.MM.YY», where DD — day, MM — month, YY — year. | 1243 | 2 | |
Citizenship | String | Nationality of the buyer (client) | 1244 | 3 | |
IdDocType | String | The code of the type of the identity document of the buyer (client). The values are described in the section 3.1.3. | 1245 | 2 | |
IdDocData | String | Data of the identity document of the buyer (client) | 1246 | 2 | |
Address | String | Address of the buyer (client) | 1254 | 3 | |
IndustryRequisite | Object | Industry details of the receipt | 1261 | 2 | |
FoivId | String | ID of THE FOIV (FEDERAL EXECUTIVE AUTHORITIES). It can take values from 001 to 072. The values are described in the section 3.1.5. | 1262 | 3 | |
DocDate | String | Date of the foundation document. The format is «DD.MM.YY», where DD is the day, MM is the month, YY is the year. | 1263 | 3 | |
DocNumber | String | Number of the foundation document | 1264 | 3 | |
Value | String | The value of industry props | 1265 | 3 | |
OperationRequisite | Object | Operational details of the receipt | 1270 | 2 | |
Id | String | Operation ID | 1271 | 2 | |
Details | String | Operation data | 1272 | 2 | |
DateTime | String | The date and time are set in unix timestamp format | 1273 | 2 | |
Items | Object | Commodity items purchased by the client. The parameters of the elements of the Items structure are given in Table 3.4. | 1059 | 1 | |
PaymentItems | Object | Amounts by payment type | |||
PaymentType | Integer | Payment type: | |||
0 – in cash; | 1031 | 1 | |||
1 – cashless; | 1081 | 1 | |||
2 – advance payment (advance payment); | 1215 | 1 | |||
3 – advance payment (credit); | 1216 | 1 | |||
4 – other form of payment. | 1217 | 1 | |||
Sum | Float | Amount by type, in rubles | 1020 | 1 | |
AdditionalReceiptProp | String | Additional details of the receipt (BSO). It is used as part of a cash receipt (BSO). The maximum length is 16 characters. | 1192 | 3 |
Parameter | Parameter | Value format | Description | TAG22) | Required23) |
---|---|---|---|---|---|
Label | String | The values are passed in text form. There may be a description of the product or a description of the service. The parameter is always required in the request for the formation of a fiscal document. If the «PaymentMethod» parameter has a value equal to 3 – advance, then the Label parameter may not be included in the request. | 1030 | 2 | |
Price | Float | The price of a commodity item in rubles. | 1079 | 2 | |
Quantity | Float | Quantity of product in the item | 1023 | 2 | |
Amount | Float | The total cost of the goods in the commodity item in rubles. The rounding rules for the cost of goods depend on the type of cash register. At the ticket offices of the type «Efir Pro FS» and «Efir Pro FA», the cost is rounded according to the mathematical rules of rounding. The result of multiplying the values of the «Price» and «Quantity» parameters should be equal to the value of the «Amount» parameter | 1043 | 1 | |
Excise | Float | The amount of excise tax, including kopecks. Participates in the request if the subject of calculation is recognized as an object of taxation by excise taxes | 1229 | 2 | |
Vat | String | Type of calculated VAT. Required field for correction checks if Items is not NULL. The parameter can take the following values: | 1199 | 2 | |
- «VatNo» — value added tax without VAT; | |||||
- «Vat10» — value added tax (VAT) 10%; | |||||
- «Vat20» — VAT 20%; | |||||
- «Vat0» — VAT 0%; | |||||
- «CalculatedVat10110» — calculated VAT of 10% of 110% of the amount; | |||||
- «CalculatedVat20120» — calculated VAT 20% of 120% of the amount. | |||||
MarkingCodeData | Object | Product item marking code. The parameters of the marking code are described in Table 3.5. | 1163 | 2 | |
Measure | String | The tag contains the units of measurement of the quantity of the object of calculation and can take the values described in the section3.1.6. | 2108 | 2 | |
PaymentMethod | Integer | Indication of the calculation method: | 1214 | 1 | |
- 1 — prepayment 100%; | |||||
- 2 — prepayment; | |||||
- 3 — prepaid expense; | |||||
- 4 — full calculation; | |||||
- 5 — partial calculation; | |||||
- 6 — transfer on credit; | |||||
- 7 — payment on credit. | |||||
IndustryRequisite | Object | Industry details of the receipt | 1261 | 2 | |
FoivId | String | ID of THE FOIV (FEDERAL EXECUTIVE AUTHORITIES). It can take values from 001 to 072. The values are described in the section 3.1.5. | 1262 | 3 | |
DocDate | String | Date of the foundation document. The format is «DD.MM.YY», where DD is the day, MM is the month, YY is the year. | 1263 | 3 | |
DocNumber | String | Number of the foundation document | 1264 | 3 | |
Value | String | The value of industry props | 1265 | 3 | |
AdditionalRequisite | String | Additional details of the subject of calculation (Maximum length of 64 characters) | 1191 | 2 | |
OriginCountryCode | String | The code of the country of origin of the goods. No more than 3 numbers. 24) | 1230 | 2 | |
CustomsDeclarationNumber | String | The number of the customs declaration. Maximum of 32 characters | 1231 | 2 | |
PaymentType | Integer | Indication of the subject of calculation for the entire receipt. Attention! If the value is not specified by the client in this field, the default value is used, which is set by default when setting up a «Ferma» service account. The list of possible values is listed in the section 3.1.4. | 1212 | 1 | |
PaymentAgentInfo 25) | Object | The description of the parameters is presented inTable 3.6. | 1223 | 2 |
Parameter | Parameter | Value format | Description | TAG26) | Required27) |
---|---|---|---|---|---|
Type | String | Marking code format It can take the following values: | |||
- UNKNOWN_PRODUCT_CODE | 1300 | ||||
- EAN8 — the value of the marking code in the format EAN-8 | 1301 | ||||
- EAN13 — the value of the marking code in the format EAN-13 | 1302 | ||||
- ITF14 — the value of the marking code in the format ITF-14 | 1303 | ||||
- GS1 — the value of the marking code in the format GS1 | 1304 | ||||
- GS1M | 1305 | ||||
- SHORT_MC | 1306 | ||||
- FUR — Control and identification mark of a fur product | 1307 | ||||
- EGAIS20 — the value of the marking code in the format EGAIS-2.0. | 1308 | ||||
- EGAIS30 — the value of the marking code in the format EGAIS-3.0. | 1309 | ||||
- KTF1 — Determined by the Federal Tax Service of Russia | 1320 | ||||
- KTF2 — Determined by the Federal Tax Service of Russia | 1321 | ||||
- KTF3 — Determined by the Federal Tax Service of Russia | 1322 | ||||
- KTF4 — Determined by the Federal Tax Service of Russia | 1323 | ||||
- KTF5 — Determined by the Federal Tax Service of Russia | 1324 | ||||
- KTF6 — Determined by the Federal Tax Service of Russia | 1325 | ||||
Code | String | Marking code. The parameter passes the value received by the barcode scanner | |||
PlannedStatus | String | If in the parameter «PlannedStatus» the value was not set, then the default value is set to «PIECE_PRODUCT_INCOME» (piece goods). The planned status of the goods with marking code can take the following values: | 2003 | 3 | |
- PIECE_PRODUCT_INCOME — Piece goods subject to mandatory marking by means of identification have been sold; | |||||
- MEASURED_PRODUCT_INCOME — Dimensional goods subject to mandatory labeling by means of identification, under implementation; | |||||
- PIECE_PRODUCT_RETURN — Piece goods subject to mandatory marking by means of identification have been returned; | |||||
- MEASURED_PRODUCT_RETURN — Part of the goods subject to mandatory identification marking has been returned; | |||||
- PRODUCT_STATUS_NOT_CHANGED — The status of the goods subject to mandatory marking by means of identification has not changed. | |||||
Fractional | Object | The tag contains a fractional amount of the marked product | 1291 | 2 | |
Numerator | Integer | Numerator (the value must be strictly less than the value of the tag 1294) | 1293 | 1 | |
Denominator | Integer | Denominator | 1294 | 1 |
Attention! Tag 1224 is not transmitted as part of the cash receipt, only tags from its composition are transmitted, namely tag 1225 and 1171. Tags are passed as part of the tag 1223.
Parameter | Parameter | Value format | Description | TAG28) | Required29) |
---|---|---|---|---|---|
PaymentAgentInfo 30) | Object | The parameter contains the data of the payment agent | 1223 | 2 | |
AgentType 31) | String | Type (attribute) of the payment agent. Possible values: | 1057 | 3 | |
BANK_PAYMENT_AGENT — bank payment agent; | |||||
BANK_PAYMENT_SUBAGENT — bank payment subagent; | |||||
PAYMENT_AGENT — payment agent; | |||||
PAYMENT_SUBAGENT — payment subagent; | |||||
CONFIDANT — attorney; | |||||
COMMISSIONER — commission agent; | |||||
AGENT — agent. | |||||
TransferAgentPhone 32) | String | Phone number of the money transfer operator | 1075 | 3 | |
TransferAgentName 33) | String | Agent's name | 1026 | 2 | |
TransferAgentAddress 34) | String | Agent's address | 1005 | ||
TransferAgentINN 35) | String | Taxpayer identification number of the agent | 1016 | 2 | |
PaymentAgentOperation 36) | String | Payment Agent operation | 1044 | 2 | |
PaymentAgentPhone 37) | String | Phone number of the payment agent | 1073 | 2 | |
ReceiverPhone 38) | String | Consumer's phone number | 1074 | 3 | |
SupplierInn 39) | String | Taxpayer identification number of the supplier | 1226 | 2 | |
SupplierName 40) | String | Name of the supplier | 1225 | 2 | |
SupplierPhone 41) | String | Supplier's phone number | 1171 | 3 |
Параметр/AgentType | BANK_PAYMENT_AGENT | BANK_PAYMENT_SUBAGENT | PAYMENT_AGENT | PAYMENT_SUBAGENT | CONFIDANT | COMMISSIONER | AGENT |
---|---|---|---|---|---|---|---|
TransferAgentPhone | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
TransferAgentName | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
TransferAgentAddress | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
TransferAgentINN | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
PaymentAgentOperation | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
PaymentAgentPhone | 1 | 1 | 1 | 1 | 0 | 0 | 0 |
ReceiverPhone | 0 | 0 | 1 | 1 | 0 | 0 | 0 |
SupplierInn | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
SupplierName | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
SupplierPhone | 1 | 1 | 1 | 1 | 0 | 0 | 0 |
The «IdDocType» parameter can take the following values:
Attention! Some combinations of calculation items and taxation systems may cause an error. This is due to the features of the cash registers.
The «FoivId» parameter can take the following values:
The «Measure» parameter can take the following values:
Parameters described in the section 3.1. Description of request parameters required for the formation of a request for the formation of a fiscal document. Depending on the required fiscal document and the fiscalization of the CCT, the composition of the parameters is always different. The exception is the Email and Phone parameters, the request must contain one of the parameters.
You can use examples of JSON schemes to request the formation of a fiscal document, in section 3.2.5.
Successful response:
{
"Status": "Success",
"Data": {
"ReceiptId": "string"
}
}
The «Reciptid» parameter is a unique identifier assigned by the «Ferma» service.
The request for the formation of a fiscal document is executed by the POST method.
Request:
POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken={Code1}
An example of a request for the formation of a simple receipt is given
Example of a JSON scheme for a request to generate a simple receipt for receiving funds in the «Ferma» service:
{
"Request":
{
"Inn": "0123456789",
"Type": "Income",
"InvoiceId": "6f000fee-bbac-4444-bda1-e9ce9999fcc7",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@ya.ru",
"Phone": "+79000000001",
"PaymentType": 4,
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 5328.53,
"Quantity": 1.0,
"Amount": 5328.53,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Example of a successful response:
{
"Status": "Success",
"Data": {
"ReceiptId": "655bf554-a003-47a1-b558-e861ffca2b76"
}
}
The generated receipt will be considered correct if it meets the following conditions:
In API Ferma, you can create a receipt without a limit on the number of products.
If the request for the formation of a cash receipt exceeds the threshold of 20,000 characters (~ = 200 items), then Ferma divides the request into several checks that can be stamped at different customer cash desks.
The mechanics of splitting checks are only available for sales paid by non-cash payment method.
To enable mechanics, contact support OFD.ru.
A receipt with a large number of positions is formed by the method "Receipt". The description of the parameters of the cash register formation request is presented in the section "3.1. Description of request parameters"
Request:
POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken=Code1
Request body:
{
"Request": {
"Inn": "7718221538",
"Type": "Income",
"InvoiceId": "229244shfjhfkidu144",
"CustomerReceipt": {
"TaxationSystem": 0,
"Email": "scijkinkjcvnskl@gmail.ru",
"PaymentType": 1,
"KktFA": false,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"TransferAgentINN": "5047063929"
},
"Items": [
{
"Label": "Наколенник эластичный \"Серебряный верблюд\", 4 размер",
"Price": 259.57,
"Quantity": 2.0,
"Amount": 519.14,
"Vat": "VatNo",
"PaymentMethod": 4,
"PaymentType": 1,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"SupplierInn": "7718221538",
"SupplierName": "ООО «Фитосила»",
"SupplierPhone": "+74959613411"
}
},
{
"Label": "Налокотник эластичный \"Серебряный верблюд\", 1 размер",
"Price": 218.37,
"Quantity": 1.0,
"Amount": 218.37,
"Vat": "VatNo",
"PaymentMethod": 4,
"PaymentType": 1,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"SupplierInn": "7718221538",
"SupplierName": "ООО «Фитосила»",
"SupplierPhone": "+74959613411"
}
},
{
"Label": "Носки из шерсти альпака, р. 25",
"Price": 191.47,
"Quantity": 1.0,
"Amount": 191.47,
"Vat": "VatNo",
"PaymentMethod": 4,
"PaymentType": 1,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"SupplierInn": "7718221538",
"SupplierName": "ООО «Фитосила»",
"SupplierPhone": "+74959613411"
}
},
...........
}
],
"PaymentItems": null
}
},
"Cashier": {}
}
In response, Ferma will return an array of receipts:
{
"Status": "Success",
"DataList": [
{
"ReceiptId": "400dcca2-d15b-48ff-9ec5-71eb6c04c741"
},
{
"ReceiptId": "40651553-d8ad-49eb-9376-af37ac8ca74f"
},
{
"ReceiptId": "e0276498-17bf-4b69-98af-31b50a998e09"
},
{
"ReceiptId": "c6188fcd-b744-4409-b276-b50c8372e5e9"
},
{
"ReceiptId": "1223f1d7-2771-4dac-a067-9c400327a767"
}
]
}
When checking the status of the receipt by the «InvoiceId» parameter, an array of receipts with statuses is returned. Checking the receipt status by the «ReciptId» parameter returns the status of one receipt from the list. The description of the method for checking the status of a cash receipt is presented in the section "3.4. Description of method get verification status fiscal document"
Example of checking the status of a receipt by the «InvoiceId» parameter:
{
"Status": "Success",
"DataList": [
{
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2021-11-18T15:51:09",
"ReceiptDateUtc": "2021-11-18T15:51:09",
"ModifiedDateTimeIso": "2021-11-18T15:51:09+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2021-11-18T15:51:09+03:00[Europe/Moscow]",
"ReceiptId": "9528b5ac-5197-4f70-b7d7-1a57bfa78d7c",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "78224",
"FPD": "1599519205",
"ShiftNumber": null,
"ReceiptNumInShift": 289,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78224/1599519205"
}
},
{
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2021-11-18T15:51:19",
"ReceiptDateUtc": "2021-11-18T15:51:19",
"ModifiedDateTimeIso": "2021-11-18T15:51:19+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2021-11-18T15:51:19+03:00[Europe/Moscow]",
"ReceiptId": "ed748298-8450-4563-8564-ba5660bb2e30",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "78227",
"FPD": "2919427768",
"ShiftNumber": null,
"ReceiptNumInShift": 292,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78227/2919427768"
}
},
{
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2021-11-18T15:51:15",
"ReceiptDateUtc": "2021-11-18T15:51:15",
"ModifiedDateTimeIso": "2021-11-18T15:51:15+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2021-11-18T15:51:15+03:00[Europe/Moscow]",
"ReceiptId": "c54fc696-c36c-4039-8f75-bf0bbf6167a2",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "78226",
"FPD": "3192423269",
"ShiftNumber": null,
"ReceiptNumInShift": 291,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78226/3192423269"
}
},
{
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2021-11-18T15:51:22",
"ReceiptDateUtc": "2021-11-18T15:51:22",
"ModifiedDateTimeIso": "2021-11-18T15:51:22+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2021-11-18T15:51:22+03:00[Europe/Moscow]",
"ReceiptId": "aa6e916c-2e9e-4fa4-94d4-8b8dd92c636a",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "78228",
"FPD": "3629293526",
"ShiftNumber": null,
"ReceiptNumInShift": 293,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78228/3629293526"
}
},
{
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2021-11-18T15:51:05",
"ReceiptDateUtc": "2021-11-18T15:51:05",
"ModifiedDateTimeIso": "2021-11-18T15:51:05+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2021-11-18T15:51:05+03:00[Europe/Moscow]",
"ReceiptId": "ea0aa3ab-47de-4fae-b360-72ee28320dcc",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "78223",
"FPD": "678189693",
"ShiftNumber": null,
"ReceiptNumInShift": 288,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78223/678189693"
}
}
]
}
Receipt of funds with information about the client:
{
"Request": {
"Inn": "2465165753",
"Type": "Income",
"InvoiceId": "qyqg3456789_u12",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@yandex.ru",
"Phone": "+79000000000",
"AutomaticDeviceNumber": null,
"PaymentType": 1,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo": {
"Name": "Иванов Иван Иванович",
"Inn": "5645645319"
},
"Items": [
{
"Label": "Апартамент A005 с 21.08 по 25.08",
"Price": 7600.0,
"Quantity": 1.0,
"Amount": 7600.0,
"Vat": "VatNo",
"MarkingCodeStructured": null,
"MarkingCode": null,
"PaymentMethod": 3,
"PaymentType": 4,
"OriginCountryCode": "643",
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Correction receipt/income:
{
"Request": {
"Inn": "0123456789",
"Type": "IncomeCorrection",
"InvoiceId": "test2_8744273567_u12",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": null,
"CorrectionInfo": {
"Type": "SELF",
"Description": "l",
"ReceiptDate": "15.08.19",
"ReceiptId": "_"
},
"Items": [
{
"Label": "Расходы",
"Price": 1,
"Quantity": 1,
"Amount": 1,
"Vat": "CalculatedVat20120",
"PaymentMethod": 4,
"PaymentType": 4
}
]
}
}
}
A simple receipt for receiving funds:
{
"Request": {
"Inn": "0123456789",
"Type": "Income",
"InvoiceId": "6f000fee-bbac-4444-bda1-8888_u22",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@ya.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 5328.53,
"Quantity": 1.0,
"Amount": 5328.53,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Simple receipt of funds with customs information:
{
"Request": {
"Inn": "0123456789",
"Type": "Income",
"InvoiceId": "6f110fee-bbac-7777-bda1-e9555996fcc7_1",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Таблетки от кашля иностранные",
"Price": 10.00,
"Quantity": 1.0,
"Amount": 10.00,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0,
"OriginCountryCode": "398",
"CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
"PaymentType": 10
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
A simple receipt for receiving funds with different characteristics of the subject of payment (PaymentType):
{
"Request": {
"Inn": "5319782640",
"Type": "Income",
"InvoiceId": "6f110fee-bbac-4446-bda1-e9ce2996fcc0_12",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 10.00,
"Quantity": 1.0,
"Amount": 10.00,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0,
"PaymentType": 10
},
{
"Label": "Услуга по страхованию.",
"Price": 100.00,
"Quantity": 1.0,
"Amount": 100.00,
"Vat": "Vat20",
"MarkingCode": null,
"PaymentMethod": 0,
"PaymentType": 3
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Simple receipt of funds with different suppliers (Supplier):
{
"Request": {
"Inn": "5645648283",
"Type": "Income",
"InvoiceId": "6f000fee-bbac-4444-bda1-e9111111fcc0_u1",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@yandex.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo": null,
"Items": [
{
"Label": "Таблетки от кашля иностранные",
"Price": 10.00,
"Quantity": 1.0,
"Amount": 10.00,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0,
"OriginCountryCode": "398",
"CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
"PaymentType": 10,
"PaymentAgentInfo": {
"AgentType": "PAYMENT_SUBAGENT",
"TransferAgentPhone": "+79000000002",
"TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
"TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
"TransferAgentINN": "7984798465",
"PaymentAgentOperation": "Оплата по лицевому счету",
"PaymentAgentPhone": "+79000000003",
"ReceiverPhone": "",
"SupplierInn": "1739818379",
"SupplierName": "Купец Иванов",
"SupplierPhone": "+79000000004"
}
},
{
"Label": "Таблетки от жадности иностранные",
"Price": 10.00,
"Quantity": 1.0,
"Amount": 10.00,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0,
"OriginCountryCode": "398",
"CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
"PaymentType": 10,
"PaymentAgentInfo": {
"AgentType": "PAYMENT_SUBAGENT",
"TransferAgentPhone": "+79000000002",
"TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
"TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
"TransferAgentINN": "7984798465",
"PaymentAgentOperation": "Оплата по лицевому счету",
"PaymentAgentPhone": "+79000000003",
"ReceiverPhone": "",
"SupplierInn": "2839172837",
"SupplierName": "ООО Медсерв и Ко",
"SupplierPhone": "+79000000005"
}
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
A simple receipt for receiving funds with a sample of the payment agent:
{
"Request": {
"Inn": "4613794639",
"Type": "Income",
"InvoiceId": "1256_u1",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@yahoo.ru",
"PaymentType": 0,
"CustomUserProperty": null,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"TransferAgentPhone": "+79000000001",
"TransferAgentName": "ПАО Сбербанк",
"TransferAgentAddress": "г. Екатеринбург, ул.Московская 11",
"TransferAgentINN": "1346976431",
"PaymentAgentOperation": "Оплата по лицевому счету",
"PaymentAgentPhone": "+79000000002"
},
"Items": [
{
"Label": "Услуги ЖКХ по л/с 4340119233",
"Price": 889.00,
"Quantity": 1.0,
"Amount": 889.00,
"Vat": "VatNo",
"PaymentMethod": 4,
"PaymentType": 4
}
],
"PaymentItems": [
{
"PaymentType": 1,
"Sum": 889.00
}
]
}
}
}
A simple receipt for receiving funds with the supplier's data:
{
"Request": {
"Inn": "1739284652",
"Type": "Income",
"InvoiceId": "6f330fee-bbac-6661-bda1-e8111886fcc8_u12",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": {
"AgentType": "AGENT",
"TransferAgentPhone": "+79000000002",
"TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
"TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
"TransferAgentINN": "5456232189",
"PaymentAgentOperation": "Оплата по лицевому счету",
"PaymentAgentPhone": "+79000000003",
"ReceiverPhone": "",
"SupplierInn": "7898654512",
"SupplierName": "АО РЦ Урала",
"SupplierPhone": "+79000000004"
},
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Таблетки от кашля иностранные",
"Price": 10.00,
"Quantity": 1.0,
"Amount": 10.00,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0,
"OriginCountryCode": "398",
"CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
"PaymentType": 10
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Simple receipt with additional receipt details (BSO) (AdditionalReceiptProp):
{
"Request": {
"Inn": "1739284652",
"Type": "Income",
"InvoiceId": "6f222fee-bbac-4444-bda1-e9ce2442fc",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46222",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : {
"Name": "Тестов Тест Тестович",
"Inn": "123456789102"
},
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 5328.53,
"Quantity": 1.0,
"Amount": 5328.53,
"Vat": "VatNo",
"MarkingCode": null,
"PaymentMethod": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null,
"AdditionalReceiptProp": "1234567890"
}
}
}
Correction receipt in the presence of commodity items (Items) and the type of calculated VAT (Vat):
{
"Request": {
"Inn": "1739284652",
"Type": "BuyCorrection",
"InvoiceId": "2f222fee-bbac-4444-bda9-e9ce99996",
"CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": {
"Type": "INSTRUCTION",
"Description": "Коррекция",
"ReceiptDate": "12.06.2019",
"ReceiptId": "123"
},
"ClientInfo": null,
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 150,
"Quantity": 1.0,
"Amount": 150,
"Vat": "Vat10",
"MarkingCode": null,
"PaymentMethod": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Correction receipt, for an erroneous generated receipt:
{
"Request": {
"Inn": "781148191912",
"Type": "IncomeCorrection",
"InvoiceId": "ffb7fc5e-fe96-4f8f-900c-e88d8c27",
"CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": null,
"Phone": null,
"InstallmentPlace": null,
"InstallmentAddress": null,
"BillAddress": null,
"KktFA": false,
"AutomatNumber": null,
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": {
"Type": "SELF",
"Description": "Ошибочный чек",
"ReceiptDate": "17.01.21",
"ReceiptId": "3144062149"
},
"ClientInfo": null,
"Items": [
{
"Label": "Отмена оплаты подписки",
"Price": 2000,
"Quantity": 1,
"Amount": 2000,
"Vat": "VatNo",
"MarkingCodeStructured": null,
"MarkingCode": null,
"PaymentMethod": 0,
"MeasurementUnit": null,
"PaymentType": 0,
"OriginCountryCode": null,
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null,
"UserProperty1080": null
}
],
"PaymentItems": null,
"Vat": null,
"CustomUserProperty": null,
"AdditionalReceiptProp": 3144062149
}
}
}
A simple receipt for receiving funds with a marking code (MarkingCodeData):
{
"Request": {
"Inn": "0258469137",
"Type": "Income",
"InvoiceId": "6f290fee-bbac-111-bda1-e1131",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Тестотвый товар",
"Price": 50.0,
"Quantity": 1.0,
"Amount": 50.0,
"Vat": "CalculatedVat20120",
"PaymentMethod": 3,
"Measure": "PIECE",
"OriginCountryCode": 46,
"CustomsDeclarationNumber": 4567896,
"IndustryItemRequisite": {
"FoivId": "046",
"DocDate": "01.01.2021",
"DocNumber": "123",
"Value": "456"
},
"MarkingCodeData": {
"Code": "00000046210654mT/hXgcAAPidGVz",
"Type": "UNKNOWN_PRODUCT_CODE",
"PlannedStatus": "PRODUCT_STATUS_NOT_CHANGED",
"Fractional": {
"Numerator": 1,
"Denominator": 10
}
},
"PaymentType": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
A simple receipt for receiving funds with the «Excise» parameter:
{
"Request": {
"Inn": "0123456789",
"Type": "Income",
"InvoiceId": "6f000fee-bbac-4444-bda1-e9ce9999f676",
"CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@ya.ru",
"Phone": "+79000000001",
"AutomaticDeviceNumber": "46204",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"Items": [
{
"Label": "Оплата услуг по страхованию.",
"Price": 5328.53,
"Quantity": 1.0,
"Amount": 5328.53,
"Vat": "VatNo",
"Excise": 50.47,
"MarkingCode": null,
"PaymentMethod": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Simple advance receipt:
{
"Request": {
"Inn": "0258469137",
"Type": "IncomePrepayment",
"InvoiceId": "6f2966789fee-bb23ac-111-b555a1-e1138881",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"PaymentType": 1,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Тестотвый товар",
"Price": 50.0,
"Quantity": 1.0,
"Amount": 50.0,
"Vat": "CalculatedVat20120",
"PaymentMethod": 3,
"Measure": "OTHER",
"PaymentType": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
A simple check offsetting an advance:
{
"Request": {
"Inn": "0258469137",
"Type": "Income",
"InvoiceId": "6f2966789fee-bb23ac-111-b555a1-e1138881",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"PaymentType": 1,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Тестотвый товар",
"Price": 50.0,
"Quantity": 1.0,
"Amount": 50.0,
"Vat": "CalculatedVat20120",
"PaymentMethod": 4,
"Measure": "OTHER",
"PaymentType": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Customers of the connected Ferma service have access to cash registers in the format of fiscal documents version 1.2.
Since August 6, 2021, the Federal Tax Service of Russia has introduced a new format of fiscal documents — FFD 1.2. You can learn more about the FFD 1.2 format in the order of the Federal Tax Service from 14.09.2020г. № ЕД-7-20/662@.
In FFD version 1.2, the value of the marking code is passed in the «Marking Code Data» parameter, as part of the «Items» parameter (Tag 1059).
If no value was set in the «MarkingCodeData» parameter in the Type parameter when generating the receipt, the value «UNKNOWN_PRODUCT_CODE» is set by default
The product marking code is transmitted in the receipt as part of the Items parameter (tag 1059). To transmit the marking code in accordance with FFD 1.2, the «MarkingCodeData» parameter has been developed at «Ferma» service.
The choice of the «Type» parameter value depends on the format of the marking code. A description of the marking code formats is provided in the order of the Federal Tax Service от 14.09.2020г. № ЕД-7-20/662@. The marking code read by the scanner is transmitted in the «Code» parameter.
The parameter for checking the marking code «CheckMcMode» is optional in request for the formation of a fiscal document . Before forming the receipt, the cashier will automatically check the marking code.
If you did not specify the «CheckMcMode» parameter in the request, a check will be generated with any result of checking the marking code in the CRPT.
If you passed one of the following values:
one of the following values: | | |
If you could not determine the format of the marking code, specify the value «UNKNOWN_PRODUCT_CODE» in the «Type» parameter. The cashier will automatically check the marking code in the CRPT and determine the format.
Параметр «MarkingCodeData» содержит в своем составе параметры описанные в Table 3.7.
Parameter | Parameter | Value format | Description | TAG42) | Required43) |
---|---|---|---|---|---|
Type | String | Marking code format It can take the following values: | |||
- UNKNOWN_PRODUCT_CODE | 1300 | ||||
- EAN8 — the value of the marking code in the format EAN-8 | 1301 | ||||
- EAN13 — the value of the marking code in the format EAN-13 | 1302 | ||||
- ITF14 — the value of the marking code in the format ITF-14 | 1303 | ||||
- GS1 — the value of the marking code in the format GS1 | 1304 | ||||
- GS1M | 1305 | ||||
- SHORT_MC | 1306 | ||||
- FUR — Control and identification mark of a fur product | 1307 | ||||
- EGAIS20 — the value of the marking code in the format EGAIS-2.0. | 1308 | ||||
- EGAIS30 — the value of the marking code in the format EGAIS-3.0. | 1309 | ||||
- KTF1 — Determined by the Federal Tax Service of Russia | 1320 | ||||
- KTF2 — Determined by the Federal Tax Service of Russia | 1321 | ||||
- KTF3 — Determined by the Federal Tax Service of Russia | 1322 | ||||
- KTF4 — Determined by the Federal Tax Service of Russia | 1323 | ||||
- KTF5 — Determined by the Federal Tax Service of Russia | 1324 | ||||
- KTF6 — Determined by the Federal Tax Service of Russia | 1325 | ||||
Code | String | Marking code. The parameter passes the value received by the barcode scanner | |||
PlannedStatus | String | If in the parameter «PlannedStatus» the value was not set, then the default value is set to «PIECE_PRODUCT_INCOME» (piece goods). The planned status of the goods with marking code can take the following values: | 2003 | 3 | |
- PIECE_PRODUCT_INCOME — Piece goods subject to mandatory marking by means of identification have been sold; | |||||
- MEASURED_PRODUCT_INCOME — Dimensional goods subject to mandatory labeling by means of identification, under implementation; | |||||
- PIECE_PRODUCT_RETURN — Piece goods subject to mandatory marking by means of identification have been returned; | |||||
- MEASURED_PRODUCT_RETURN — Part of the goods subject to mandatory identification marking has been returned; | |||||
- PRODUCT_STATUS_NOT_CHANGED — The status of the goods subject to mandatory marking by means of identification has not changed. | |||||
Fractional | Object | The tag contains a fractional amount of the marked product | 1291 | 2 | |
Numerator | Integer | Numerator (the value must be strictly less than the value of the tag 1294) | 1293 | 1 | |
Denominator | Integer | Denominator | 1294 | 1 |
A simple receipt for receiving funds with a marking code (MarkingCodeData):
{
"Request": {
"Inn": "0258469137",
"Type": "Income",
"InvoiceId": "6f290fee-bbac-111-bda1-e1131",
"CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "example@mail.ru",
"Phone": "+79000000001",
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo" : null,
"Items": [
{
"Label": "Тестотвый товар",
"Price": 50.0,
"Quantity": 1.0,
"Amount": 50.0,
"Vat": "CalculatedVat20120",
"PaymentMethod": 3,
"Measure": "PIECE",
"OriginCountryCode": 46,
"CustomsDeclarationNumber": 4567896,
"IndustryItemRequisite": {
"FoivId": "046",
"DocDate": "01.01.2021",
"DocNumber": "123",
"Value": "456"
},
"MarkingCodeData": {
"Code": "00000046210654mT/hXgcAAPidGVz",
"Type": "UNKNOWN_PRODUCT_CODE",
"PlannedStatus": "PRODUCT_STATUS_NOT_CHANGED",
"Fractional": {
"Numerator": 1,
"Denominator": 10
}
},
"PaymentType": 0
}
],
"PaymentItems": null,
"CustomUserProperty": null
}
}
}
Attention! Information about the status of the cash receipt is stored in the RAM of the Ferma service for only a day. After the expiration of the day, when the status of the cash receipt is requested again, the error «The receipt was not found» will be displayed in response. After the expiration of the day, information about the status of the cash receipt can be obtained in request for the register of cash receipts.
Request:
POST https://ferma.ofd.ru/api/kkt/cloud/status?AuthToken={Code1}
You can check the status of the receipt after the following parameters:
Request body by parameter «ReceiptId»:
{
"Request": {
"ReceiptId": "string"
}
}
Request body by parameter «InvoiceId»:
{
"Request": {
"InvoiceId": "string"
}
}
The parameters are described in the table 3.8.
Parameter | Parameter | Value format | Description |
---|---|---|---|
Request | Object | Параметры запроса статуса кассового документа | |
ReceiptId | String | ID assigned by the «Ferma» service | |
InvoiceId | String | The identifier assigned by your information system in the request for the formation of a cash receipt. |
Successful response:
{
"Status": "Success",
"Data": {
"StatusCode": 1,
"StatusName": "PROCESSED",
"StatusMessage": "Чек сформирован на кассе",
"ModifiedDateUtc": "2020-09-15T17:37:00",
"ReceiptDateUtc": "2020-09-15T17:37:00",
"ModifiedDateTimeIso": "2020-09-15T17:37+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2020-09-15T17:37+03:00[Europe/Moscow]",
"Device": {
"DeviceId": "string",
"RNM": "string",
"ZN": "string",
"FN": "string",
"FDN": "string",
"FPD": "string"
"ShiftNumber": null,
"ReceiptNumInShift": 1,
"DeviceType": null,
"OfdReceiptUrl": "string"
}
}
}
The description of the response parameters is given in Table 3.9.
Parameter | Parameter | Value format | Description |
---|---|---|---|
StatusCode | Integer | Status code | |
StatusName | String | Status name | |
StatusMessage | String | Optional parameter, contains additional information about the current state | |
ModifiedDateUtc | String44) | Date and time of the last update of the receipt information in Moscow time | |
ReceiptDateUtc | String45) | The date and time specified in the receipt in Moscow time | |
ModifiedDateTimeIso | String46) | Date and time of the last update of the receipt information in Moscow time | |
ReceiptDateTimeIso | String47) | The date and time specified in the receipt in Moscow time | |
Device | Object | Device Information (KKT) | |
DeviceId | String | Device Service ID | |
RNM | String | Registration number of the cash register | |
ZN | String | The factory number of the cash register | |
FN | String | Fiscal device number | |
FDN | String | Number of the fiscal document | |
FPD | String | Fiscal feature of the document | |
ShiftNumber | Integer | Shift number | |
ReceiptNumInShift | Integer | The number of the check in the shift | |
DeviceType | String | Cash register model | |
OfdReceiptUrl | String | Link to the receipt |
Values:
If the receipt did not pass the FLK when forming at the checkout, the response has the following form:
{
"Status": "Success",
"Data": {
"StatusCode": 3,
"StatusName": "KKT_ERROR",
"StatusMessage": "Ошибка пробития чека на кассе",
"Description": "[-3975] Некорректное значение параметров команды ФН",
"ModifiedDateUtc": "2020-07-25T12:08:00",
"ReceiptDateUtc": null,
"ModifiedDateTimeIso": "2020-07-25T12:08:00+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": null,
"Device": null
}
}
The description of the error response parameters is given in Table 3.10.
Parameter | Value format | Description |
---|---|---|
StatusCode | Integer | Error code |
StatusName | String | Error name |
StatusMessage | String | Error Description |
Description | String | Detailed description of the error |
ModifiedDateUtc | String48) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateUtc | String49) | The date and time specified in the receipt in Moscow time |
ModifiedDateTimeIso | String50) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateTimeIso | String51) | The date and time specified in the receipt in Moscow time |
Device | Object | Device Information (ККТ) |
When receiving the values of «StatusCode»: 0,1,3, the following actions should be performed:
If an error is received, it is necessary to check the entered data and correct them in accordance with the system message. Then re-execute the transaction request. A list of all possible errors is provided here.
If you can't figure out the problem yourself, then contact technical support «OFD.ru ».
The register of cash receipts can be queried using two different methods:
When using the list method, the response returns information about the server processing time of the receipt. See Table 3.11.
POST https://ferma.ofd.ru/api/kkt/cloud/list?AuthToken={Code1}
When using the list2 method, the response returns information about the time when the receipt was punched at the checkout (checkout time). See Table 3.11.
POST https://ferma.ofd.ru/api/kkt/cloud/list2?AuthToken={Code1}
Request body:
{
"Request": {
"ReceiptId": "e0d1122f-4e88-777a-8e8e-c333f333e4d4",
"StartDateUtc": "2020-01-24T14:13:24",
"EndDateUtc": "2020-01-24T14:13:24",
"StartDateLocal": "2020-01-24T14:13:24",
"EndDateLocal": "2020-01-24T14:13:24"
}
}
The parameters of the «Request» structure are given in Table 3.11.
Parameter | Value format | Description | Required |
---|---|---|---|
ReceiptId | String | The ID of the receipt assigned by the «Ferma» service | No |
StartDateUtc | String52) | Date and time of the start of the interval in Moscow time | No |
EndDateUtc | String53) | Date and time of the end of the interval in Moscow time | No |
StartDateLocal | String54) | Local date and time of the start of the interval | Yes |
EndDateLocal | String55) | Local date and time of the end of the interval | Yes |
Successful response:
{
"Status": "Success",
"Data": [
{
"ReceiptId": "44ff3d74-7414-4f71-ac5e-80242914be8a",
"StatusCode": 2,
"StatusName": "Чек передан в ОФД",
"StatusMessage": "CONFIRMED",
"ModifiedDateUtc": "2020-09-15T17:37:52",
"ReceiptDateUtc": "2020-09-15T17:37:52",
"ModifiedDateTimeIso": "2020-09-15T17:37:52+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2020-09-15T17:37:52.437+03:00[Europe/Moscow]",
"InvoiceId": "a011y93242ab11623abdd",
"Receipt": {
"cashboxInfoHolder": {
"checkNumInShift": "2",
"shiftNum": "15",
"totalSum": 4000,
"DeviceId": 6608,
"RNM": "0000000001017018",
"ZN": "00107601637967",
"FN": "9999078902005984",
"FDN": "0000000208",
"FPD": "3649802185"
},
"Inn": "3245001416",
"Type": "Income",
"InvoiceId": "a011y93242ab11623abdd",
"CustomerReceipt": {
"TaxationSystem": "0",
"Email": "dbaigozin@oooinex.ru",
"Phone": null,
"BillAddress": "Тестируем маркировку табака",
"KktFA": true,
"PaymentType": 4,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo": null,
"Items": [
{
"Label": "Табак с кодом маркировки",
"Price": 1000.0,
"Quantity": 1.0,
"Amount": 1000.0,
"Vat": "Vat20",
"MarkingCodeStructured": {
"markingCodeHex": "000346BD0CD0DC7152585757575252525252525252",
"codeCorrect": true,
"gtinHex": "46BD0CD0DC71",
"serialHex": "52585757575252525252525252",
"typeHex": "0003",
"Gtin": "77777777777777",
"Serial": "RXWWWRRRRRRRR",
"Type": "MEDICINES"
},
"MarkingCode": null,
"PaymentMethod": 4,
"PaymentType": 4,
"OriginCountryCode": null,
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null
},
{
"Label": "Табак с кодом маркировки",
"Price": 1000.0,
"Quantity": 1.0,
"Amount": 1000.0,
"Vat": "Vat20",
"MarkingCodeStructured": {
"markingCodeHex": "000346BD0CD0DC7152585757575252525252525253",
"codeCorrect": true,
"gtinHex": "46BD0CD0DC71",
"serialHex": "52585757575252525252525253",
"typeHex": "0003",
"Gtin": "77777777777777",
"Serial": "RXWWWRRRRRRRS",
"Type": "MEDICINES"
},
"MarkingCode": null,
"PaymentMethod": 4,
"PaymentType": 4,
"OriginCountryCode": null,
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null
},
{
"Label": "Табак с кодом ма12154215ркировки",
"Price": 1000.0,
"Quantity": 1.0,
"Amount": 1000.0,
"Vat": "Vat20",
"MarkingCodeStructured": {
"markingCodeHex": "000300000000000752585757575252525252525252",
"codeCorrect": true,
"gtinHex": "000000000007",
"serialHex": "52585757575252525252525252",
"typeHex": "0003",
"Gtin": "7",
"Serial": "RXWWWRRRRRRRR",
"Type": "MEDICINES"
},
"MarkingCode": null,
"PaymentMethod": 4,
"PaymentType": 4,
"OriginCountryCode": null,
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null
},
{
"Label": "Табак с кодом марк2222ировки",
"Price": 1000.0,
"Quantity": 1.0,
"Amount": 1000.0,
"Vat": "Vat20",
"MarkingCodeStructured": null,
"MarkingCode": null,
"PaymentMethod": 4,
"PaymentType": 4,
"OriginCountryCode": null,
"CustomsDeclarationNumber": null,
"PaymentAgentInfo": null
}
],
"PaymentItems": [
{
"PaymentType": 1,
"Sum": 4000.0
}
],
"Vat": null,
"CustomUserProperty": null,
"AdditionalReceiptProp": null
},
"Cashier": {}
}
}
...
]
}
The description of the «Data» parameter is given in Table 3.12.
Parameter | Value format | Description |
---|---|---|
ReceiptId | String | The ID of the receipt assigned by the «Ferma» service |
StatusCode | Integer | Status code |
StatusName | String | Status name |
StatusMessage | String | Optional parameter, contains additional information about the current state. |
ModifiedDateUtc | String56) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateUtc | String57) | The date and time specified in the receipt in Moscow time. When using the list method, the server time of receipt processing is returned, when using list2, it returns the time of receipt formation at the checkout (checkout time) |
ModifiedDateTimeIso | String58) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateTimeIso | String59) | The date and time specified in the receipt in Moscow time. When using the list method, the server time of receipt processing is returned, when using list2, it returns the time of receipt formation at the checkout (checkout time) |
InvoiceId | String | The identifier assigned by your information system in the request for the formation of a cash receipt. |
Receipt | Object | The contents of the customer receipt. The parameters of the elements of the «Receipt» structure are given in Table 3.13. |
Parameter | Parameter | Parameter | Value format | Description |
---|---|---|---|---|
cashboxInfoHolder | Object | Information about the cash register | ||
checkNumInShift | Integer | The number of the check in the shift | ||
shiftNum | Integer | Shift number | ||
totalSum | Integer | Total amount on the receipt | ||
cashboxType | Integer | Type of cash register | ||
DeviceId | String | Device Service ID | ||
RNM | String | Registration number of the cash register | ||
ZN | String | The factory number of the cash register | ||
FN | String | Fiscal device number | ||
FDN | String | Number of the fiscal document | ||
FPD | String | Fiscal feature of the document | ||
Inn | String | Identification number of the taxpayer's organization | ||
Type | String | Type fiscal document (cash receipt). The type can have the following values: |
||
– «Income» — receiving funds from the buyer; | ||||
– «IncomeReturn» — refund of funds received from the buyer; | ||||
– «IncomePrepayment» — advance payment from the buyer; | ||||
– «IncomeReturnPrepayment» — refund of the advance payment; | ||||
– «IncomeCorrection» — correction receipt/income; | ||||
– «BuyCorrection» — correction receipt/expense; | ||||
– «IncomeReturnCorrection» - чcorrection receipt/Return of income; | ||||
– «ExpenseReturnCorrection» - чек коррекции/Return of expense; | ||||
– «Expense» — disbursement of funds to the buyer; | ||||
– «ExpenseReturn» — refund of funds issued to the buyer. | ||||
InvoiceId | String | The identifier assigned by your information system in the request for the formation of a cash receipt. | ||
CustomerReceipt | Object | Contents of the customer receipt. | ||
TaxationSystem | String | Taxation system. The parameter of the taxation system can take the following values: |
||
– «Common» or «0» — general taxation system; | ||||
– «SimpleIn» or «1» — simplified taxation system (income); | ||||
– «SimpleInOut» or «2» — simplified taxation system (income minus expense); | ||||
– «UnifiedAgricultural» or «4» — unified agricultural tax; | ||||
– «Patent» or «5» — patent taxation system. | ||||
String | Customer's email address | |||
Phone | String | Customer's contact phone number | ||
BillAddress | String | Place of settlement | ||
KktFA | Boolean | If the FA cash register is used in the Ferma service, you must set the value to true. If you use the FS cash register, you must set the value to false. The FA cash register can be used for: – vending machine, when making payments for goods or services; – making payments for travel in automated mode (through a validator) or making payments through the conductor's terminal. |
||
PaymentType | Integer | Indication of the subject of calculation for the entire receipt. Attention! If the value is not specified by the client in this field, the default value is used, which is set by default when setting up a «Ferma» service account. The list of possible values is listed in the section 3.1.4. |
||
PaymentAgentInfo | Object | The parameter contains the data of the payment agent | ||
AgentType | String | Type (attribute) of the payment agent. Possible values: | ||
BANK_PAYMENT_AGENT — bank payment agent; | ||||
BANK_PAYMENT_SUBAGENT — bank payment subagent; | ||||
PAYMENT_AGENT — payment agent; | ||||
PAYMENT_SUBAGENT — payment subagent; | ||||
CONFIDANT — attorney; | ||||
COMMISSIONER — commission agent; | ||||
AGENT — agent. | ||||
CorrectionInfo | Object | Parameter with the data structure for the correction receipt. | ||
Description | String | Description of correction and reasons for correction | ||
Type | String | Type of correction: SELF — the correction is made independently; INSTRUCTION — the correction is made according to the order of the tax department |
||
ReceiptDate | String | The date of the check breakdown to which the correction check is applied. In the format «DD.MM.YY», where DD — day, MM — month, YY — year. | ||
ReceiptId | String | Number of the order of the tax agency | ||
ClientInfo | Object | Customer data | ||
Name | String | Full name or name of the organization, if the client is a legal entity. No more than 256 characters in the field | ||
Inn | String | The taxpayer identification number of the buyer. Length 10-12 numbers | ||
Items | Object | Commodity items purchased by the client. The description of the «Items» parameter is given in Table 3.14. | ||
PaymentItems | Object | Amounts by payment type | ||
PaymentType | Integer | Payment type: | ||
0 – in cash; | ||||
1 – cashless; | ||||
2 – advance payment (advance payment); | ||||
3 – advance payment (credit); | ||||
4 – other form of payment. | ||||
Sum | Float | Amount by type, in rubles | ||
Vat | String | Type of calculated VAT. Required field for correction checks if Items is not NULL. The parameter can take the following values: |
||
- «VatNo» — value added tax without VAT; | ||||
- «Vat10» — value added tax (VAT) 10%; | ||||
- «Vat20» — VAT 20%; | ||||
- «Vat0» — VAT 0%; | ||||
- «CalculatedVat10110» — calculated VAT of 10% of 110% of the amount; | ||||
- «CalculatedVat20120» — calculated VAT 20% of 120% of the amount. | ||||
CustomUserProperty | Object | Additional user details, taking into account the specifics of the field of activity in which the calculations are carried out | ||
Name | String | The name of the additional user details, taking into account the specifics of the field of activity in which the calculations are carried out | ||
Value | String | The value of the user's additional details, taking into account the specifics of the field of activity in which the calculations are carried out | ||
AdditionalReceiptProp | String | Additional details of the receipt (BSO). It is used as part of a cash receipt (BSO). The maximum length is 16 characters. | ||
Cashier | Object | Information about the cashier | ||
Name | String | Name cashier | ||
Inn | String | Cashier's Tax Identification number |
Parameter | Parameter | Parameter | Value format | Description |
---|---|---|---|---|
Label | String | Name of the subject of calculation | ||
Price | Float | The price of a commodity item in rubles | ||
Quantity | Float | Quantity of goods | ||
Amount | Float | The total cost of the goods in the commodity item in rubles | ||
Vat | String | Type of calculated VAT. Required field for correction checks if Items is not NULL. The parameter can take the following values: |
||
- «VatNo» — value added tax without VAT; | ||||
- «Vat10» — value added tax (VAT) 10%; | ||||
- «Vat20» — VAT 20%; | ||||
- «Vat0» — VAT 0%; | ||||
- «CalculatedVat10110» — calculated VAT of 10% of 110% of the amount; | ||||
- «CalculatedVat20120» — calculated VAT 20% of 120% of the amount. | ||||
MarkingCodeData | Object | Product item marking code. | ||
Type | String | Marking code format It can take the following values: |
||
- UNKNOWN_PRODUCT_CODE | ||||
- EAN8 — the value of the marking code in the format EAN-8 | ||||
- EAN13 — the value of the marking code in the format EAN-13 | ||||
- ITF14 — the value of the marking code in the format ITF-14 | ||||
- GS1 — the value of the marking code in the format GS1 | ||||
- GS1M | ||||
- SHORT_MC | ||||
- FUR — Control and identification mark of a fur product | ||||
- EGAIS20 — the value of the marking code in the format EGAIS-2.0. | ||||
- EGAIS30 — the value of the marking code in the format EGAIS-3.0. | ||||
- KTF1 — Determined by the Federal Tax Service of Russia | ||||
- KTF2 — Determined by the Federal Tax Service of Russia | ||||
- KTF3 — Determined by the Federal Tax Service of Russia | ||||
- KTF4 — Determined by the Federal Tax Service of Russia | ||||
- KTF5 — Determined by the Federal Tax Service of Russia | ||||
- KTF6 — Determined by the Federal Tax Service of Russia | ||||
Code | String | Marking code. The parameter passes the value received by the barcode scanner |
||
PlannedStatus | String | If in the parameter «PlannedStatus» the value was not set, then the default value is set to «PIECE_PRODUCT_INCOME» (piece goods). The planned status of the goods with marking code can take the following values: |
||
- PIECE_PRODUCT_INCOME — Piece goods subject to mandatory marking by means of identification have been sold; | ||||
- MEASURED_PRODUCT_INCOME — Dimensional goods subject to mandatory labeling by means of identification, under implementation; | ||||
- PIECE_PRODUCT_RETURN — Piece goods subject to mandatory marking by means of identification have been returned; | ||||
- MEASURED_PRODUCT_RETURN — Part of the goods subject to mandatory identification marking has been returned; | ||||
- PRODUCT_STATUS_NOT_CHANGED — The status of the goods subject to mandatory marking by means of identification has not changed. | ||||
Fractional | Object | The tag contains a fractional amount of the marked product | ||
Numerator | Integer | Numerator (the value must be strictly less than the value of the tag 1294) | ||
Denominator | Integer | Denominator | ||
PaymentMethod | Integer | Indication of the calculation method: | ||
- 1 — prepayment 100%; | ||||
- 2 — prepayment; | ||||
- 3 — prepaid expense; | ||||
- 4 — full calculation; | ||||
- 5 — partial calculation; | ||||
- 6 — transfer on credit; | ||||
- 7 — payment on credit. | ||||
PaymentType | Integer | Indication of the subject of calculation for the entire receipt. Attention! If the value is not specified by the client in this field, the default value is used, which is set by default when setting up a «Ferma» service account. The list of possible values is listed in the section 3.1.4. |
||
OriginCountryCode | Integer | The code of the country of origin of the goods. No more than 3 digits. 60) | ||
CustomsDeclarationNumber | String | The number of the customs declaration. Maximum of 32 characters | ||
PaymentAgentInfo | Object | The parameter contains the data of the payment agent | ||
AgentType | String | Type (attribute) of the payment agent. Possible values: | ||
BANK_PAYMENT_AGENT — bank payment agent; | ||||
BANK_PAYMENT_SUBAGENT — bank payment subagent; | ||||
PAYMENT_AGENT — payment agent; | ||||
PAYMENT_SUBAGENT — payment subagent; | ||||
CONFIDANT — attorney; | ||||
COMMISSIONER — commission agent; | ||||
AGENT — agent. | ||||
TransferAgentPhone | String | Phone number of the money transfer operator | ||
TransferAgentName | String | Agent's name | ||
TransferAgentAddress | String | Agent's address | ||
TransferAgentINN | String | Taxpayer identification number of the agent | ||
PaymentAgentOperation | String | Payment Agent operation | ||
PaymentAgentPhone | String | Phone number of the payment agent | ||
ReceiverPhone | String | Consumer's phone number | ||
SupplierInn | String | Taxpayer identification number of the supplier | ||
SupplierName | String | Name of the supplier | ||
SupplierPhone | String | Supplier's phone number |
Depending on which parameters were passed when forming the receipt, some elements may be missing or have the value «null».
In case the check did not pass the FLK when it was broken through at the checkout, the answer has the following form:
{
"Status": "Success",
"Data": {
"StatusCode": 3,
"StatusName": "KKT_ERROR",
"StatusMessage": "Ошибка пробития чека на кассе",
"Description": "[-3975] Некорректное значение параметров команды ФН",
"ModifiedDateUtc": "2020-07-25T12:08:00",
"ReceiptDateUtc": null,
"ModifiedDateTimeIso": "2020-07-25T12:08:00+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": null,
"Device": null
}
}
The description of the «Data» parameter when receiving an error response is given in Table 3.15.
Parameter | Value format | Description |
---|---|---|
StatusCode | Integer | Status code |
StatusName | String | Status name |
StatusMessage | String | Optional parameter, contains additional information about the current state |
Description | String | Detailed description of the error |
ModifiedDateUtc | String61) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateUtc | String62) | The date and time specified in the receipt in Moscow time |
ModifiedDateTimeIso | String63) | Date and time of the last update of the receipt information in Moscow time |
ReceiptDateTimeIso | String64) | The date and time specified in the receipt in Moscow time |
Device | Object | Device Information (KKT) |
If an error is received, it is necessary to check the entered data and correct them in accordance with the system message. After that, re-send the request for the formation of a cash receipt. A list of all possible errors is provided here. If you can't figure out the problem yourself, then contact your manager or our technical support.
Request:
GET https://ferma.ofd.ru/api/kkt/cloud/stats/fn/aggregates?dateFrom=Date1&dateTo=Date2&AuthToken={Code1}
Request Parameters:
Successful response:
{
"Status": "Success",
"Data": [
{
"fn": "9280440300111111",
"firstReceiptDate": "2019-07-16",
"lastReceiptDate": "2019-07-17"
},
{
"fn": "9280440300222222",
"firstReceiptDate": "2019-07-16",
"lastReceiptDate": "2019-07-17"
},
...
]
}
Request:
GET https://ferma.ofd.ru/api/kkt/cloud/stats/receipts/extended?AuthToken={Code1}&dateFromIncl={dateFromIncl}&dateToIncl={dateToIncl}&receiptId={receiptId}&zn={zn}&fn={fn}
Successful response:
Successful response:
{
"Status": "Success",
"Data": {
"Receipts": [
{
"Id": "XXXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXXXX",
"Tag": 3,
"TotalSumm": 1000,
"CashSumm": 0,
"ECashSumm": 1000,
"Nds00_TotalSumm": 0,
"NdsNA_TotalSumm": 0,
"PrepaidSumm": 0,
"ProvisionSumm": 0,
"DocDateTime": "2020-11-05 00:00:00Z",
"OperationType": "Income",
"DocNumber": XXXXXXXX,
"KktRegNumber": "XXXXXXXX",
"FnNumber": "XXXXXXXX",
"DocShiftNumber": XXXXXXXX,
"ReceiptNumber": "XXXXXXXX",
"DecimalFiscalSign": "XXXXXXXX",
"CDateUt": "2020-11-05 00:01:47Z",
"Items": [
{
"Name": "XXXXXXXX",
"Quantity": 1,
"Total": 1000,
"CalculationMethod": 3,
"SubjectType": "0A",
"Nds10_TotalSumm": 0,
"Nds18_TotalSumm": 0,
"Barcode": null,
"NdsCalculated10": 0,
"NdsCalculated18": 167
}
]
},
......
{
"Id": "XXXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXXXX",
"Tag": 3,
"TotalSumm": 10000,
"CashSumm": 0,
"ECashSumm": 10000,
"Nds00_TotalSumm": 0,
"NdsNA_TotalSumm": 0,
"PrepaidSumm": 0,
"ProvisionSumm": 0,
"DocDateTime": "2020-11-05 00:00:00Z",
"OperationType": "Income",
"DocNumber": XXXXXXXX,
"KktRegNumber": "XXXXXXXX",
"FnNumber": "XXXXXXXX",
"DocShiftNumber": XXXXXXXX,
"ReceiptNumber": "XXXXXXXX",
"DecimalFiscalSign": "XXXXXXXX",
"CDateUt": "2020-11-05 00:00:16Z",
"Items": [
{
"Name": "XXXXXXXX",
"Quantity": 1,
"Total": 10000,
"CalculationMethod": 3,
"SubjectType": "0A",
"Nds10_TotalSumm": 0,
"Nds18_TotalSumm": 0,
"Barcode": null,
"NdsCalculated10": 0,
"NdsCalculated18": 1667
}
]
}
]
}
}
Вид запроса:
GET https://ferma.ofd.ru/api/kkt/cloud/stats/cashboxes/extended?AuthToken={Code1}&deviceId={deviceId}&rnm={rnm}&zn={zn}&fn={fn}
Здесь:
Successful response:
{
"Status": "Success",
"Data": [
{
"deviceId": 12135,
"fn": "9280440300750000",
"zn": "9944254000",
"rnm": "0004939230052000",
"kktModel": "Эфир Pro ФС",
"kktState": "Готова к работе",
"tariffType": "Стоимость за 1 месяц",
"tariffEndDate": "2021-01-03",
"tariffChecksCnt": null,
"fnName": "Шифровальное (криптографическое) средство защиты фискальных данных фискальный накопитель «ФН-1.1» исполнение Ав15-2",
"fnModelName": "FN15",
"checksCnt": 66,
"fnVolumePercent": 0.03,
"projectedFnReplaceDate": "2022-03-19",
"projectedFnFilledDate": "2022-03-19",
"fnLastChangeDate": "2021-07-09"
},
.....
]
}
Parameter | Value format | Description |
---|---|---|
deviceId | String | Device Service ID |
fn | String | Fiscal device number |
zn | String | The factory number of the cash register |
rnm | String | Registration number of the cash register |
kktModel | String | Name of the cash register model |
kktState | String | The status of the cash register in the «Ferma» service |
tariffType | String | Type of fare at the checkout |
tariffEndDate | String | The end date of the paid period according to the tariff |
tariffChecksCnt | String | The number of checks available for punching on the check type of the tariff |
fnName | String | Name of the fiscal device model |
fnModelName | String | Type of fiscal device |
checksCnt | String | The number of punched checks in the fiscal device |
fnVolumePercent | String | Percentage of fiscal device memory filling |
projectedFnReplaceDate | String | Projected replacement date by the expiration date of the fiscal device |
projectedFnFilledDate | String | Projected replacement date for filling the fiscal device |
fnLastChangeDate | String | Date of the last replacement of the fiscal drive |
The «CallbackUrl» parameter is passed as part of a request to generate a receipt in the «Ferma» service. The parameter accepts url/ipaddress of the callback handler client. После сформирования чека на кассе («StatusCode»: 2/3), the response will be sent by POST to url/ip address specified in the «CallbackUrl» parameter.
If no response has been received within 300 seconds, you need to execute the request checking the status of the cash receipt.
For the «CallbackUrl» parameter to work correctly in the settings of your information system, you need to add the following IP addresses to the trust list:
An example of a response sent to the specified URL in the «CallbackUrl» parameter is given:
{
"receiptId": "47975e7d-ebb4-4906-83e2-e4244f56ecca",
"invoiceId": "7899we45453477798989363776e55",
"orgId": 1,
"callbackUrl": "https://hookb.in/037ryxqe6pH3J0ooJ9dE",
"payload": {
"Status": "Success",
"Data": {
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "Чек передан в ОФД",
"ModifiedDateUtc": "2022-02-09T10:36:38",
"ReceiptDateUtc": "2022-02-09T10:36:38",
"ModifiedDateTimeIso": "2022-02-09T10:36:38+03:00[Europe/Moscow]",
"ReceiptDateTimeIso": "2022-02-09T10:36:38+03:00[Europe/Moscow]",
"ReceiptId": "47975e7d-ebb4-4906-83e2-e4244f56ecca",
"InvoiceId": "7899we45453477798989363776e55",
"Device": {
"DeviceId": 7405,
"RNM": "0000000010053286",
"ZN": "9985857579",
"FN": "9999078902001735",
"FDN": "121453",
"FPD": "1298875598",
"ShiftNumber": null,
"ReceiptNumInShift": 524,
"DeviceType": "Эфир Pro ФС",
"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/121453/1298875598"
}
}
}
}
Parameter | Parameter | Parameter | Parameter | Value format | Description |
---|---|---|---|---|---|
receiptId | String | ID assigned by the Ferma service | |||
invoiceId | String | The identifier assigned by your information system in the request for the formation of a cash receipt. | |||
orgId | Integer | Organization ID | |||
callbackUrl | String | URL. The parameter specifies the URL value. If the field is filled in correctly, then after processing the document (successful or unsuccessful fiscalization in the KKT: status «CONFIRMED» or «KKT_ERROR»), the response will be sent by POST request to the URL specified in this field. The correctness of the filled field is determined by the regular expression:^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([a-zA-Z0-9а-яА-Я\-\.\?\,\'\/\\\+&=%\$#_]*)?$ |
|||
payload | Object | Structure of the response with data | |||
Status | String | Request processing status | |||
Data | Object | Data of the generated receipt | |||
StatusCode | Integer | Status code. | |||
- 0 - the request for the receipt was accepted by the «Ferma» service; | |||||
- 1 - the receipt is generated at the checkout; | |||||
- 2 - the receipt has been transferred to the OFD; | |||||
- 3 - the receipt has not been transferred to the OFD, you need to send it again | |||||
StatusName | String | The name of the status. Has the following values: |
|||
- «NEW» - the request for the receipt was accepted by the «Ferma» service | |||||
- «PROCESSED» - the receipt is generated at the checkout | |||||
- «CONFIRMED» - the receipt has been transferred to the OFD | |||||
- «KKT_ERROR» - the receipt has not been transferred to the OFD, you need to send it again | |||||
StatusMessage | String | The parameter contains additional information about the current state. Has the following values: |
|||
- «запрос на чек принят Фермой» the request for the receipt was accepted by the «Ferma» service | |||||
- «чек сформирован на кассе» - the receipt is generated at the checkout | |||||
- «чек передан в ОФД» - the receipt has been transferred to the OFD | |||||
ModifiedDateUtc | String68) | Date and time of the last update of the receipt information in Moscow time | |||
ReceiptDateUtc | String69) | Date and time specified in the receipt in Moscow time | |||
ModifiedDateTimeIso | String70) | Date and time of the last update of the receipt information in Moscow time | |||
ReceiptDateTimeIso | String71) | Date and time specified in the receipt in Moscow time | |||
ReceiptId | String | The ID of the receipt assigned by the «Ferma» service | |||
InvoiceId | String | The ID of the receipt assigned by your information system in the request for the formation of a cash receipt. | |||
Device | Object | Device Information | |||
DeviceId | Integer | Device Service ID | |||
RNM | String | Registration number of the cash register | |||
ZN | String | The factory number of the cash register | |||
FN | String | Fiscal device number | |||
FDN | String | Number of the fiscal document | |||
FPD | String | Fiscal feature of the document | |||
ShiftNumber | Integer | Shift number | |||
ReceiptNumInShift | Integer | The number of the check in the shift | |||
DeviceType | String | Cash register model | |||
OfdReceiptUrl | String | Link to the receipt |
Table 4.1. Lists the code and descriptions of errors received in the response to the request.
HTTP Code | Error Code | Error description |
---|---|---|
401 | 1001 | The client is not authorized |
500 | 1002 | Unexpected error |
400 | 1003 | Invalid request format |
404 | 1004 | Object not found |
500 | 1 | Unknown error |
500 | 2 | Invalid login, password |
500 | 3 | No cash registers available |
500 | 4 | No authorization |
400 | 1005 | The «Request» parameter is empty |
400 | 1006 | The «CustomerReceipt» parameter is empty |
400 | 1007 | Incorrect taxpayer identification number |
400 | 1008 | Incorrect type of the generated receipt (Type) |
400 | 1009 | Invalid account ID (InvoiceId) |
400 | 1010 | Incorrect type of taxation (TaxationSystem) |
400 | 1011 | Contacts are filled in incorrectly (Email, Phone) |
400 | 1012 | Invalid email address |
400 | 1013 | Incorrect phone number |
400 | 1014 | Incorrectly filled positions (Items) |
400 | 1015 | The price and total cost should not be negative |
400 | 1016 | The number of products in the position should not be negative |
400 | 1017 | The VAT of the position is filled in incorrectly (Vat) |
400 | 1018 | The total sum of positions must be non-negative |
400 | 1019 | The account ID already exists (InvoiceId, ReceiptId) |
400 | 1020 | Exceeded the maximum number of requests |
400 | 1021 | The phone number of the payment agent is specified incorrectly |
400 | 1022 | The supplier's phone number is specified incorrectly |
400 | 1023 | The phone number of the transfer operator is specified incorrectly |
400 | 1024 | The taxpayer identification number of the transfer operator is incorrect |
400 | 1025 | The payment agent attribute is specified incorrectly |
400 | 1026 | The length of the PaymentAgentInfo.TransferAgentName field exceeds the maximum length of 64 characters |
400 | 1027 | The length of the PaymentAgentInfo.TransferAgentAddress field exceeds the maximum length of 256 characters |
400 | 1028 | The length of the PaymentAgentInfo.PaymentAgentOperation field exceeds the maximum length of 24 characters |
400 | 1029 | There are no cash registers corresponding to the transferred type of payment agent |
400 | 1030 | Correction description is not specified (CorrectionInfo.Description) |
400 | 1031 | Incorrect format of the date of the corrected calculation |
400 | 1032 | The correction type is specified incorrectly (CorrectionInfo.Type) |
400 | 1049 | The machine number is specified incorrectly (AutomatNumber). The maximum length is 20 characters |
400 | 1056 | The receipt ID is incorrect or missing |
400 | 1058 | The correction receipt contains more than one position |
400 | 1063 | The machine number (AutomatNumber) is specified together with the KktFA = false flag |
400 | 1064 | The correction receipt contains an incorrect calculation attribute (тег 1054) |
400 | 1065 | VAT rates are filled in incorrectly. More than 1 type of bid per check is specified |
400 | 1066 | Invalid tag length 1191 (additional payment item details). Maximum length 64 characters |
400 | 1067 | The name of the subject of calculation (Items.Label) must not be empty or exceed the length of 128 characters |
400 | 1068 | The number of the tax authority's prescription for the correction receipt is incorrect (tag 1179). The prescription number cannot be empty. The maximum length is 32 characters. |
400 | 1069 | The number of marking codes exceeds the permissible number of 128, within one check |
400 | 1070 | There is no cash register with FFD 1.2 |
400 | 1071 | There is no cash register with FFD below 1.2 to generate a cash receipt with data on marking codes in MarkingCode/MarkingCodeStructured |
400 | 1085 | Error in the values of input parameters for generating a receipt in the Ferma service |
Table 4.2. lists error messages and descriptions of messages received in response to the request.
Error message | Error Code | Error description |
---|---|---|
CASHBOX_NOT_FISCALIZED | 1070 | The cash register is not fiscalized. Go to your personal account OFD.ru and complete the registration of the cash register in the «Ferma» section |
CASHBOX_REQUIRES_REGISTRATION_COMPLETION | 1071 | At the checkout, completion of registration with the Federal Tax Service is required. Registration with the Federal Tax Service has not been completed at the Ferma cash register. Go to your personal account OFD.ru , complete the registration of the cash register in the Ferma section |
CASHBOX_TO_ARCHIVING | 1072 | The cash register is being prepared for archiving. It is necessary to replace the fiscal drive. Go to your personal account OFD.ru , check the availability of prepaid fiscal documents |
CASHBOX_ARCHIVED | 1073 | The cash register is archived. It is necessary to replace the fiscal drive. Go to your personal account OFD.ru , check the availability of prepaid fiscal documents |
CASHBOX_REREGISTRATION_REQUIRED | 1074 | At the checkout, completion of re-registration with the Federal Tax Service is required. At the Ferma cash register, re-registration with the Federal Tax Service has not been completed. Go to your personal account OFD.ru , sign the application for re-registration of the cash register with the electronic signature key |
CASHBOX_REQUIRES_REREGISTRATION_COMPLETION | 1076 | Completion of re-registration is required at the checkout. According to the cash desk of the Firm, re-registration with the Federal Tax Service has not been completed |
CASHBOX_REMOVED_FROM_BALANCING | 1075 | The cash register has been removed from balancing. Temporary technical works are carried out at the checkout |
CASHBOX_WITHDRAWN_FOR_NONPAYMENT | 1079 | The cash register was withdrawn for non-payment. Ferma cash register has not been paid. Pay for Ferma services |
This section describes how to test the «Ferma» service. Formation of cash receipts and their viewing. For testing, the client's demo personal account is used, as well as a cash register with a test fiscal drive (FN MGM) installed, which is connected to the Ferma test information system.
All the queries described in the instructions are collected in a collection for Postman. You can download the collection and make sure that all methods are working. The collection will help you to customize the Ferma service to your needs.
In order to punch the receipts at the Ferma test checkout, use the domain 72) ferma-test.ofd.ru,for the FFD 1.2 version of the cash register, use the following data:
Login and password are used in the API request to get the authorization code (AuthToken).
To log into the demo personal account of the client for further viewing of receipts, you need to perform the following actions:
After you have entered the demo LKK, to view the punched receipts at the checkout, you need to:
Version 1.0
08 august 2022 г.
First version.