# Mandarin.Kassir (чеки)

# Начало работы

Mandarin поддерживает передачу фискальной информации в онлайн-кассы:

Для подключения необходимо выполнить следующие действия:


# Бифит Онлайн

Что необходимо иметь до начала интеграции:

Шаги для интеграции:

# Атол Онлайн

Что необходимо иметь до начала интеграции:

Шаги для интеграции:

# Агентская касса Мандарин

С Mandarin можно моментально и без затрат подключить онлайн-кассу по агентской схеме фискализации. При этом в кассовом чеке будет присутствовать информация об агенте (ООО “Мандарин” ИНН 7708816952) и о поставщике услуг (ваша компания). В кассовом чеке будет также отображаться вся необходимая информация: реквизиты чека (номер); сумма чека; дата покупки/продажи; тип операции (приход/расход/возврат) и другая информация. Для этого необходимо передавать в запросе блок fiscalInformation согласно инструкции, при этом в случае использования именно агентской кассы Мандарин, блок shipper не указывается, информация о конечном получателе указывается на стороне Мандарин.

Важно!

При использовании кассы Мандарина в параметре taxationSystem всегда указывается только Общая (ОСН) система налогообложения (Common), при указании других параметров чек не будет сформирован.

# Автоматическое формирование чека

Чеки могут создаваться для следующих видов операций:

  • платеж;
  • отмена платежа;
  • выплата.

В запрос платежа, отмены платежа или выплаты добавляется объект fiscalInformation, который содержит массив строк в чеке и выбранную систему налогообложения. Каждая строка включает в себя наименование, количество, сумму строки и ставку НДС.

Параметр Обязателен
fiscalInformation При необходимости
fiscalInformation.taxationSystem Да
fiscalInformation.items[] Да
fiscalInformation.items[].description Да
fiscalInformation.items[].quantity Да
fiscalInformation.items[].totalPrice Да
fiscalInformation.items[].vat Да
fiscalInformation.items[].calculationMethod Нет
fiscalInformation.items[].paymentSubject Нет

Поле taxationSystem указывается один раз и содержит систему налогообложения, общую для всего чека. Возможные значения:

  • Common - Общая (ОСН);
  • Simplified - Упрощенная (УСН) "Доходы";
  • SimplifiedMinusOutlay - Упрощенная (УСН) "Доходы минус расходы";
  • UnifiedImputedIncome - Единый налог на вмененный доход (ЕНВД);
  • UnifiedAgricultural - Единый сельскохозяйственный налог (ЕСХН);
  • Patent - Патентная (ПСН).

Поле vat указывается в каждой строке и содержит ставку НДС. Возможные значения:

  • None - Без НДС;
  • Vat0 - НДС по ставке 0%;
  • vat5 - НДС по ставке 5%;
  • vat7 - НДС по ставке 7%;
  • Vat10 - НДС по ставке 10%;
  • Vat20 - НДС по ставке 20%;
  • vat105 - НДС по расчетной ставке 5/105;
  • vat107 - НДС по расчетной ставке 7/107.

Поле calculationMethod опционально указывается в каждой строке и содержит способ расчетов (по умолчанию FULL_PAY). Возможные значения:

  • PREPAY_FULL - Полная предварительная оплата до момента передачи предмета расчёта;
  • PREPAY_PARTIAL - Частичная предварительная оплата до момента передачи предмета расчёта;
  • AVANS - Аванс;
  • FULL_PAY - Полная оплата, в том числе с учётом аванса (предварительной оплаты) в момент передачи предмета расчёта;
  • PARTIAL_SETTLEMENT_AND_CREDIT - Частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит;
  • TRANSFER_ON_CREDIT - Передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит;
  • CREDIT_PAYMENT - Оплата предмета расчёта после его передачи с оплатой в кредит (оплата кредита).

Поле paymentSubject опционально указывается в каждой строке и содержит предмет расчета (по умолчанию SERVICE). Возможные значения:

  • AGENCY - Агентское вознаграждение;
  • COMPOUND_SUBJECT - Составной предмет расчета;
  • EXCISABLE_PRODUCT - Подакцизный товар;
  • GAMBLING_RATE - Ставка азартной игры;
  • GAMBLING_WIN - Выигрыш азартной игры;
  • INSURANCE_CONTRIBUTIONS - Страховые взносы;
  • JOB - Работа;
  • LOTTERY_TICKET - Лотерейный билет;
  • LOTTERY_WIN - Выигрыш лотереи;
  • NON_OPERATING_INCOME - Внереализационный доход;
  • OTHER_SUBJECT - Иной предмет расчета;
  • PAYMENT - Платеж;
  • PLEDGE – Залог;
  • PRODUCT - Товар;
  • PROPERTY_LAW - Имущественное право;
  • PROVISION_RID - Представление РИД;
  • RESORT_FEE - Курортный сбор;
  • SERVICE - Услуга;
  • TRADE_FEE - Торговый сбор.

Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос платежа

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	},
	"fiscalInformation": {
		"taxationSystem": "Common",
		"items": [{
			"quantity": 10,
			"vat": "Vat20",
			"description": "Товар",
			"totalPrice": "800.00",
			"calculationMethod": "AVANS",
			"paymentSubject": "PRODUCT"
		}, {
			"quantity": 1,
			"vat": "Vat20",
			"description": "Доставка",
			"totalPrice": "200.00",
			"calculationMethod": "PREPAY_FULL",
			"paymentSubject": "SERVICE"
		}]
	}
}

Ответ в случае успешного создания транзакции (200 ОК)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
	"jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (400 Bad request)

{
	"error": "Invalid request"  
}

# Автоматическое формирование агентского чека

Чеки могут создаваться для следующих видов операций:

  • платеж;
  • отмена платежа;
  • выплата.

В запрос платежа, отмены платежа или выплаты добавляется объект fiscalInformation, который содержит массив строк в чеке и выбранную систему налогообложения. Каждая строка включает в себя наименование, количество, сумму строки и ставку НДС. Внутрь объекта items для каждого элемента вы можете поместить объект shipper, содержащий информацию о конечном получателе средств. В случае использовании агентской кассы мандарин, объект shipper не указывается.

Параметр Обязателен
fiscalInformation При необходимости
fiscalInformation.taxationSystem Да
fiscalInformation.items[] Да
fiscalInformation.items[].description Да
fiscalInformation.items[].quantity Да
fiscalInformation.items[].totalPrice Да
fiscalInformation.items[].vat Да
fiscalInformation.items[].calculationMethod Нет
fiscalInformation.items[].paymentSubject Нет
fiscalInformation.items[].agentType Нет
fiscalInformation.items[].shipper При необходимости
fiscalInformation.items[].shipper.name Да
fiscalInformation.items[].shipper.inn Да
fiscalInformation.items[].shipper.phones[] Да

Поле agentType опционально указывается в каждой строке и содержит тип контрагента для агентских чеков (по умолчанию AGENT). Возможные значения:

  • AGENT;
  • BANK_PAYMENT_AGENT BANK_PAYMENT_SUBAGENT PAYMENT_AGENT;
  • PAYMENT_SUBAGENT;
  • ATTORNEY;
  • COMMISSIONER.

Объект shipper содержит следующие обязательные поля:

  • name - название конечного получателя;
  • inn - ИНН конечного получателя;
  • phones - массив номеров телефонов, передаваемых в виде строк.

Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [{
			"name": "first parameter to save and show",
			"value": "p1"
		},
		{
			"name": "second parameter to save and show",
			"value": "p2"
		}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	},
	"fiscalInformation": {
		"taxationSystem": "Common",
		"items": [{
				"quantity": 1,
				"vat": "none",
				"description": "Оплата",
				"totalPrice": "600.00",
				"calculationMethod": "FULL_PAY",
				"paymentSubject": "SERVICE",
				"agentType": "AGENT",
				"shipper": {
					"name": "ООО Ромашка",
					"inn": "1234567890",
					"phones": [
						"+79111111111"
					]
				}
			},
			{
				"quantity": 1,
				"vat": "none",
				"description": "Оплата",
				"totalPrice": "400.00",
				"calculationMethod": "FULL_PAY",
				"paymentSubject": "SERVICE",
				"agentType": "AGENT",
				"shipper": {
					"name": "ООО Лютик",
					"inn": "0987654321",
					"phones": [
						"+79222222222"
					]
				}
			}
		]
	}
}

Ответ в случае успешного создания транзакции (200 ОК)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
	"jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (400 Bad request)

{
	"error": "Invalid request"  
}

# Самостоятельное формирование чека

С Mandarin можно формировать чеки даже после операции, не привязывая блок fiscalInformation к запросу платежа, отмены платежа или выплаты.

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

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Для выполнения требуется скоуп receipts:public_receipts.write, который необходимо запросить при аутентификации.

Параметр Обязателен Описание
taxSystem Да Виды систем налогооблажения
cashierName Нет Имя кассира
cashierInn Нет Инн кассира
customerPhone Нет, если указан customerEmail Номер клиента
customerEmail Нет, если указан customerPhone Почта клиента
clientId Да Client Id
merchantId Да Merchant Id
mandarinId Да Mandarin Id. Id для идентификации чека по которому выполнена операция, например TransactionId или OperationId
items.calculationMethod Да Метод расчета
items.agentType Нет Агентский тип, использовать AGENT
items.shipper.name Да, если указан agentType Имя агента
items.shipper.inn Да, если указан agentType Инн агента
items.shipper.phones Да, если указан agentType Массив номеров агента
items.paymentSubject Да Тип покупки, например УСЛУГА(SERVICE)
items.name Да Наименование продукта/услуги
items.price Да Стоимость продукта/услуги, ограничение 2 символа после запятой, например : 123.45
items.quantity Да Количество товаров, допустимо использовать дробные числа, например 0.5
items.vat Да Тип НДС

Запрос

POST https://api.psp.io/receipts/public/receipts 
{
    "taxSystem": "Common",
    "cashierName": "Mandarin",
    "cashierInn": "1234567890",
    "customerPhone": "+79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
        {
            "calculationMethod": "FULL_PAY",
            "paymentSubject": "SERVICE",
            "name": "Комиссия за ИТО при оплата по транзакции 23071572 в пользу Клиента 1234",
            "price": 200.00,
            "quantity": 1,
            "vat": "Vat20"
        }
    ]
}

Ответ в случае успешного создания запроса (200 ОК)

{
  "data": {
    "id": 139
  }
}

Пример агентского чека

POST https://api.psp.io/receipts/public/receipts
{
   "taxSystem":"COMMON",
   "cashierName":"Иванов И.И.", //Если кассира нет то просто не указываем cashierName и cashierInn
   "cashierInn":"1234567890",
   "customerPhone":"79999999999", //Можно указать либо телефон, либо email, если передается и телефон и email то в приоритете отправка чека на email
   "customerEmail":"test@test.ru",
   "clientId":"1234",
   "merchantId": "1234",
   "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
   "items":[
      {
         "calculationMethod":"FULL_PAY",
         "agentType": "AGENT", //Информация о агенте, если чек НЕ агентский то просто не отправляем shipper и agentType
         "shipper":{
            "name":"БИФИТ",
            "inn":"7724923302",
            "phones":[
               "+79001234567"
            ]
         },
         "paymentSubject":"SERVICE",
         "name":"Услуга",
         "price":100,
         "quantity":1,
         "vat": "None"
      }
   ]
}

Пример не агентского чека

POST https://api.psp.io/receipts/public/receipts
{
   "taxSystem":"Common", 
   "cashierName":"Иванов И.И.", //Если кассира нет то просто не указываем cashierName и cashierInn
   "cashierInn":"1234567890",
   "customerPhone":"79001234567", //Можно указать либо телефон, либо email, если передается и телефон и email то в приоритете отправка на email
   "customerEmail":"user@example.com",
   "clientId":"1234",
   "merchantId": "1234",
   "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
   "items":[
      {
         "calculationMethod":"FULL_PAY",
         "paymentSubject":"SERVICE",
         "name":"Услуга",
         "price":100,
         "quantity":1,
         "vat": "None"
      }
   ]
}

# Получение статуса чека

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

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Для выполнения требуется скоуп receipts:public_receipts.read, который необходимо запросить при аутентификации.

Метод дает возможность по идентификатору операции получить статус чека.

Параметр Обязателен Описание
mandarinId Да Mandarin Id. Id для идентификации чека, по которому выполнена операция, например TransactionId или OperationId

Запрос

GET https://api.psp.io/receipts/public/receipts/43913ddc000c4d3990fddbd3980c1111/status

Ответ в случае успешного создания запроса (200 ОК)

{
  "data": {
    "status": "SUCCESS"
  },
  "error": null
}

# Получение списка чеков

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

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Для выполнения требуется скоуп receipts:public_receipts.read, который необходимо запросить при аутентификации.

Метод позволяет по указанным фильтрам получить список чеков с подробным описанием. Фильтрация сделана на основе filter_by, где мы передаем в QueryParameters фильтры. Выглядит это следующем образом, в запросе передаем объект filter_by, в качестве значения передаются фильтры.

Параметр Обязателен Описание
mandarinId нет Mandarin Id. Id для идентификации чека, по которому выполнена операция, например TransactionId или OperationId.
provider_id Provider Id. Идентификатор чека у провайдера.
mandarin_status Стандартизированный статус чека. New, Success, Fail.
created_start_date From date. Дата создания чека в формате 2023-09-08T10:53:47.748839Z.
created_end_date To date. Дата создания чека в формате 2023-09-08T10:53:47.748839Z.
action_type Тип чека. Receipt, Refund, Purchase, PurchaseRefund
limit_to Limit to. По умолчанию 20.
cursor Cursor. для пагинации prev/next

Запрос

GET https://api.psp.io/receipts/public/receipts?filter_by=mandarin_status=New%26created_start_date>2023-09-08T10:53:47.748839Z%26created_end_date<2023-09-08T10:55:47.748839Z

Ответ в случае успешного создания запроса (200 ОК)

{
    "receipts": [
        {
            "mandarinId": "11913ddc000c4d3990fddbd3980c1111",
            "providerId": "486179",
            "providerType": "Bifit",
            "actionType": "Receipt",
            "updatedAt": "2023-10-18T19:00:08.466157Z",
            "status": "SUCCESS",
            "mandarinStatus": "Success",
            "amount": 200.00,
            "customerEmail": "user@example.com",
            "customerPhone": "+79001234567",
            "items": [
                {
                    "calculationMethod": null,
                    "paymentSubject": null,
                    "name": "Комиссия за ИТО при оплата по транзакции 23071572 в пользу Клиента 1234",
                    "price": 200.00,
                    "quantity": 1.0,
                    "vat": "VAT20",
                    "total": 0.0,
                    "agentType": null,
                    "shipperId": null,
                    "shipper": null,
                    "receiptId": 714010,
                    "isMandarinAgent": false,
                    "id": 741755,
                    "createdAt": "2023-10-18T18:59:55.641373Z"
                }
            ],
            "taxationSystem": "Common",
            "clientId": "033861",
            "merchantId": "7429",
            "isSandbox": true,
            "isMandarinAgent": false,
            "extra": "{\"Id\": 486179, \"Kkm\": {\"Id\": 50, \"Inn\": \"772351116121\", \"Model\": \"БФР-112ФС\", \"Vendor\": \"БИФИТ\", \"FdNumber\": \"9999078902002260\", \"FdStatus\": null, \"TaxSystems\": [\"COMMON\", \"SIMPLIFIED\", \"SIMPLIFIED_WITH_EXPENSE\", \"ENVD\", \"COMMON_AGRICULTURAL\", \"PATENT\"], \"BrokerVersion\": \"3.46\", \"FactoryNumber\": \"98065732341002\", \"LastDocumentDate\": 1614173792888, \"RegistrationNumber\": \"0000000017017401\"}, \"Type\": \"RECEIPT\", \"KkmId\": 50, \"status\": \"SUCCESS\", \"Changed\": 1697655597239, \"Created\": 1697655595614, \"Request\": {\"type\": \"SALE\", \"items\": [{\"vat\": \"VAT_20\", \"name\": \"Комиссия за ИТО при оплата по транзакции 23071572 в пользу Клиента 1234\", \"price\": 200.0, \"total\": 200.0, \"quantity\": 1.0, \"paymentSubject\": \"SERVICE\", \"calculationMethod\": \"FULL_PAY\"}], \"print\": false, \"total\": 200.0, \"client\": {\"address\": \"user@example.com\"}, \"cashier\": {\"name\": \"Mandarin-test\"}, \"payments\": {\"CARD\": 200.0}, \"taxSystem\": \"COMMON\"}, \"Response\": {\"Raw\": \"--------------------------------\\n          Кассовый чек          \\n             ПРИХОД             \\n     ИП ПИВОВАРОВ АЛЕКСАНДР     \\n105203 г.Москва, Первомайская Ни\\nжн. ул., 46., помещ. XIII, ком. \\n               52               \\n         18:10:23 21:59         \\n--------------------------------\\nКомиссия за ИТО при оплата по тр\\nанзакции 23071572 в пользу Клиен\\nта 1234                         \\n1 * 200.00              = 200.00\\nНДС 20%                         \\nУСЛУГА             ПОЛНЫЙ РАСЧЕТ\\n--------------------------------\\nИТОГ                    = 200.00\\nБЕЗНАЛИЧНЫМИ            = 200.00\\nСУММА НДС 20%            = 33.33\\nЭЛ.АДР.ПОКУПАТЕЛЯ               \\n                user@example.com\\nЭЛ.АДР.ОТПРАВИТЕЛЯ              \\n            pivovarov2@bifit.com\\nКАССИР             Mandarin-test\\nЧЕК                         2805\\nСМЕНА                        415\\nСНО                          ОСН\\nИНН                 772351116121\\nРН ККТ          0000000017017401\\nФН              9999078902002260\\nФД                        226936\\nФП                    2479791443\\n\", \"ShiftNumber\": 415, \"ReceiptNumber\": 2805}, \"ExecutorId\": 1, \"FiscalSign\": \"2479791443\", \"FiscalTime\": 1697655540000, \"FiscalDrive\": \"9999078902002260\", \"ExecutorType\": \"CONNECTOR\", \"FiscalAmount\": 200.00, \"FiscalDocument\": 226936, \"IdempotencyKey\": \"cd5511ed-3a4c-4618-bf21-5c7908fbb19f\"}",
            "extraData": {
                "Id": 486179,
                "Kkm": {
                    "Id": 50,
                    "Inn": "772351116121",
                    "Model": "БФР-112ФС",
                    "Vendor": "БИФИТ",
                    "FdNumber": "9999078902002260",
                    "FdStatus": null,
                    "TaxSystems": [
                        "COMMON",
                        "SIMPLIFIED",
                        "SIMPLIFIED_WITH_EXPENSE",
                        "ENVD",
                        "COMMON_AGRICULTURAL",
                        "PATENT"
                    ],
                    "BrokerVersion": "3.46",
                    "FactoryNumber": "98065732341002",
                    "LastDocumentDate": 1614173792888,
                    "RegistrationNumber": "0000000017017401"
                },
                "Type": "RECEIPT",
                "KkmId": 50,
                "status": "SUCCESS",
                "Changed": 1697655597239,
                "Created": 1697655595614,
                "Request": {
                    "type": "SALE",
                    "items": [
                        {
                            "vat": "VAT_20",
                            "name": "Комиссия за ИТО при оплата по транзакции 23071572 в пользу Клиента 1234",
                            "price": 200.0,
                            "total": 200.0,
                            "quantity": 1.0,
                            "paymentSubject": "SERVICE",
                            "calculationMethod": "FULL_PAY"
                        }
                    ],
                    "print": false,
                    "total": 200.0,
                    "client": {
                        "address": "user@example.com"
                    },
                    "cashier": {
                        "name": "Mandarin-test"
                    },
                    "payments": {
                        "CARD": 200.0
                    },
                    "taxSystem": "COMMON"
                },
                "Response": {
                    "Raw": "--------------------------------\n          Кассовый чек          \n             ПРИХОД             \n     ИП ПИВОВАРОВ АЛЕКСАНДР     \n105203 г.Москва, Первомайская Ни\nжн. ул., 46., помещ. XIII, ком. \n               52               \n         18:10:23 21:59         \n--------------------------------\nКомиссия за ИТО при оплата по тр\nанзакции 23071572 в пользу Клиен\nта 1234                         \n1 * 200.00              = 200.00\nНДС 20%                         \nУСЛУГА             ПОЛНЫЙ РАСЧЕТ\n--------------------------------\nИТОГ                    = 200.00\nБЕЗНАЛИЧНЫМИ            = 200.00\nСУММА НДС 20%            = 33.33\nЭЛ.АДР.ПОКУПАТЕЛЯ               \n                user@example.com\nЭЛ.АДР.ОТПРАВИТЕЛЯ              \n            pivovarov2@bifit.com\nКАССИР             Mandarin-test\nЧЕК                         2805\nСМЕНА                        415\nСНО                          ОСН\nИНН                 772351116121\nРН ККТ          0000000017017401\nФН              9999078902002260\nФД                        226936\nФП                    2479791443\n",
                    "ShiftNumber": 415,
                    "ReceiptNumber": 2805
                },
                "ExecutorId": 1,
                "FiscalSign": "2479791443",
                "FiscalTime": 1697655540000,
                "FiscalDrive": "9999078902002260",
                "ExecutorType": "CONNECTOR",
                "FiscalAmount": 200.0,
                "FiscalDocument": 226936,
                "IdempotencyKey": "cd5511ed-3a4c-4618-bf21-5c7908fbb19f"
            },
            "id": 714010,
            "createdAt": "2023-10-18T18:59:55.641495Z"
        }
    ],
    "cursor": {
        "count": 1,
        "total": 1,
        "next": null,
        "prev": null
    }
}