Программный интерфейс приложений (API) для работы с сервисом «Мой.ОФД»

Общая информация

Введение

Сервис Мой.ОФД предоставляет доступ к данным о фискальных документах и контрольно-кассовой технике для сторонних клиентских приложений.
Для взаимодействия с сервисом используйте следующий базовый URL: https://api.my-ofd.ru/.

Обратите внимание на ограничение по частоте запросов: для каждого ключа доступа разрешено не более 1000 запросов в час.

Авторизация запросов

Для авторизации при обращении к сервису Мой.ОФД необходимо добавить следующие заголовки к каждому запросу:

"Authorization": "{Ваш ключ доступа}"
"X-Source": "{Источник}"

"Authorization" - должен содержать ваш ключ доступа, предоставленный сервисом Мой.ОФД. Обратите внимание что для каждого личного кабинета каждого конкретного ОФД (X-Source) ключ доступа будет свой.

"X-Source" - источник данных. В настоящий момент поддерживаются 13 источников :

Коды состояния

Код Сообщение Описание
200 OK Возвращается при успешном выполнении запроса.
401 Unauthorized Возвращается при ошибке авторизации.
404 Not Found Возвращается если запрашиваемый ресурс не найден.
429 Rate Limit Exceeded Возвращается при превышении максимального количества запросов в текущем периоде.
500 Internal Server Error Возвращается когда сервер столкнулся с неожиданной ошибкой, которая помешала ему выполнить запрос.

Методы

Кассы

Возвращает массив с информацией о всех кассах пользователя.

GET /ofd/devices

Заголовки:

  • Authorization – ключ доступа
  • X-Source – источник

Пример : Запрос Ответ

curl --location 'https://api.my-ofd.ru/ofd/devices' \
--header 'Authorization: bdb75030-cc21-11ed-afa1-0242ac120002' \
--header 'X-Source: taxcom-ofd'

{
  "items": [{
    "id": "1a0310c2-cbfa-11ed-afa1-0242ac120002",
    "parentId": "f2c2fa04-cbf9-11ed-afa1-0242ac120002",
    "name": "Касса 1",
    "address": "236016, г. Калининград, ул. Боткина д.2а",
    "model": "АТОЛ 11Ф",
    "regNum": "0003868015411763",
    "serialNum": "",
    "active": true,
    "ofd_key": "76",
    "inn": "3908032891",
    "kpp": "390601001"
  },{
    "id": "1a0310c2-cbfa-11ed-afa1-0242ac120002",
    "parentId": "f2c2fa04-cbf9-11ed-afa1-0242ac120002",
    "name": "Касса интернет магазина",
    "address": "236016, г. Калининград, ул. Боткина д.2а",
    "model": "АТОЛ 55Ф"",
    "regNum": "0003868015411764",
    "serialNum": "",
    "active": true,
    "ofd_key": "78",
    "inn": "3908032891",
    "kpp": "390601001"
  }]
}

Таблица 1. Параметры ответа метода "Кассы"

Параметр Вид значения Описание
Id String Уникальный идентификатор ККТ
parentId String Уникальный идентификатор магазина
name String Название кассы
address String Адрес регистрации ККТ
model String Модель ККТ
regNum String Регистрационный номер ККТ
serialNum String Серийный номер ККТ
active Boolean Признак активации сервиса Мой.ОФД на кассу
ofd_key String Служебный идентификатор области ОФД
inn String ИНН организации кассы
kpp String КПП Организации кассы

Магазины

Возвращает массив с информацией о всех магазинах пользователя.

GET /ofd/shops

Заголовки:

  • Authorization – ключ доступа
  • X-Source – источник

Пример : Запрос Ответ

curl --location 'https://api.my-ofd.ru/ofd/shops' \
--header 'Authorization: bdb75030-cc21-11ed-afa1-0242ac120002' \
--header 'X-Source: taxcom-ofd'

{
  "items": [
    {
	"id": "f2c2fa04-cbf9-11ed-afa1-0242ac120002"
	"parentId": "",
	"name": "Офис",
	"address": "236016, г. Калининград, ул. Боткина д.2а"
    }
  ]
}

Таблица 2. Параметры ответа метода "Магазины"

Параметр Вид значения Описание
Id String Уникальный идентификатор объекта
parentId String Уникальный идентификатор родителя
name String Название объекта
address String Адрес объекта

Документы

Возвращает массив документов.

GET /ofd/documents

Параметры:

  • kkt – Уникальный идентификатор ККТ
  • ofd_key – Служебный идентификатор области ОФД
  • from – Начальная точка временного диапазона для выборки документов. Используйте формат ISO 8601: YYYY-MM-DDTHH:mm:ss.SSS+HH:mm (например, 2023-03-17T00:00:00.000+00:00)
  • to – Конечная точка временного диапазона для выборки документов. Используйте формат ISO 8601: YYYY-MM-DDTHH:mm:ss.SSS+HH:mm (например, 2023-04-17T00:00:00.000+00:00)

Заголовки:

  • Authorization – ключ доступа
  • X-Source – источник

Пример : Запрос Ответ

curl "https://api.my-ofd.ru:443/ofd/documents?ofd_key=1634189c-d412-fd0c-7c9a-9e0d3ba9e321&kkt=0002605697015581&from=2023-03-20T00%3A00%3A00.000%2B00%3A00&to=2023-03-30T23%3A59%3A59.000%2B00%3A00" -X GET 
 -H "X-Source: taxcom-ofd"
 -H "Authorization: 948a0c92-bf39-40b1-a39f-a7f7ce3e6f0b"

{
  "items": [
    {
      "id": "063f1e9f-eb4d-7e47-7256-ff6bac742363"
      "shiftId": "20e6efd6-c71b-9076-27d4-c90812434b76",
      "ofd_key": "0",
      "regNum": "0002605697015581",
      "fiscalDocumentDate": "2023-03-18T10:42:00Z",
      "fiscalDocumentType": 3,
      "fiscalSign": 2430045838,
      "fnNum": "1160440321780316",
      "operationType": 1,
      "documentNumber": 12,
      "taxationType": 32,
      "operator": {
        "inn": "273302793141",
        "name": "Кассир"
      },
	  "items": [
        {
          "code": "",
          "measure": "шт",
          "ndsSum": 0,
          "сalculationMethod": 0,
          "quantity": 4.3,
          "ndsType": 6,
          "price": 1000,
          "sum": 4300,
          "name": "Масло моторное Shell Helix SAE Synthetic HX8 5W30 ",
          "subjectType": 1
        },
        {
          "code": "",
          "measure": "шт",
          "ndsSum": 0,
          "сalculationMethod": 0,
          "quantity": 1,
          "ndsType": 6,
          "price": 500,
          "sum": 500,
          "name": "Авторабота Замена масла в двигателе",
          "subjectType": 3
        }
      ],
      "payments": [
        {
          "sum": 500,
          "type": "cash"
        },
        {
          "sum": 4300,
          "type": "ecash"
        }
      ],
      "fiscalDocumentNumber": 18737,
      "documentLink": "https://lk.platformaofd.ru/web/noauth/cheque/id?id=1822155396&date=1679100805000&fp=2430045838",
      "kktId": "0002607697026683",
      "receiveDate": "2023-03-18T03:53:25Z",
      "fiscalShiftNumber": 369,
      "extras": null,
	  "totalSum": 4800,
    },
    {
      "id": "257cab29-08b7-bbe8-2f08-15b608b19891",
      "ofd_key": "0",
      "operationType": 6,
      "fnNum": "1160440321780316",
      "fiscalSign": 31292751411,
      "fiscalShiftNumber": 376,
      "fiscalDocumentDate": "2023-03-24T19:38:00Z",
      "open": "2023-03-24T07:56:00Z",
      "close": "2023-03-24T19:38:00Z",
      "regNum": "0002605697015581",
      "refundExpenseSumm": 0,
      "incomeSumm": 165565,
      "refundIncomeSumm": 2650,
      "expenseSumm": 0,
      "fiscalDocumentNumber": 0,
      "documentLink": "https://lk.platformaofd.ru/web/noauth/cheque/id?id=18439679971&date=1679651374000&fp=31292751411",
      "kktId": "0002607697026683"
    }
  ]
}

Таблица 3. Параметры ответа метода "Документы"

Параметр Вид значения Описание
Id String Уникальный идентификатор чека
organization String Организации
inn String ИНН организации
shiftId String Уникальный идентификатор кассовой смены
ofd_key String Служебный идентификатор области ОФД
regNum String Регистрационный номер ККТ
fiscalDocumentDate String Дата чека
fiscalDocumentType Integer Тип документа (3 - Кассовый чек, 4 - Бланк строгой отчетности, 31 - Кассовый чек коррекции, 41 - Бланк строгой отчетности коррекции)
fiscalSign Integer Фискальный признак чека
fnNum String Номер фискального накопителя
operationType Integer Тип операции (1 - Продажа, 2 - Возврат, 3 - Покупка, 4 - Возврат покупки, 6 - Z отчет)
documentNumber Integer Номер чека в смене
taxationType Integer Система налогообложения (1 - ОСНО, 2 - УСН доход, 4 - УСН доход-расход, 8 - ЕНВД, 16 - ЕСН, 32 - Патент
operator Struct Структура, описывающая кассира, пробившего чек
buyerInfo Struct Структура, описывающая покупателя
machineNumber String Номер автомата
items Array Массив, содержащий описание позиций чека
payments Array Массив, содержащий описание способов расчета по чеку
fiscalDocumentNumber Integer Номер фискального документа
documentLink String Ссылка на чек
kktId String Идентификатор кассы
receiveDate String Дата получения чека оператором фискальных данных
fiscalShiftNumber Integer Номер кассовой смены
extras Array Массив типа "ключ - значение", может содержать дополнительные сведения о чека. Набор сведений зависит от конкретного источника
totalSum Float Общая сумма чека
address String Адрес места расчетов
place String Название торговой точки
fns_result String Статус обработки чека ФНС

Описание кассира

Параметр Вид значения Описание
inn String ИНН кассира
name String Имя кассира

Описание покупателя

Параметр Вид значения Описание
PhoneOrAddress String Телефон или адрес покупателя
name String Имя покупателя
Inn String ИНН покупателя (При наличии)

Таблица товарных позиций

Параметр Вид значения Описание
code String Код товара
measure String Единица измерения товара
ndsSum Float Сумма НДС
сalculationMethod Integer Признак способа расчета (1 - Предоплата 100%, 2 - Предоплата, 3 - Аванс, 4 - Полный расчет, 5 - Частичный расчет и кредит, 6 - Передача в кредит, 7 - Оплата кредита)
quantity Float Количество
ndsType Integer Ставка НДС ( 1 - 20%, 2 - 10%, 3 - 20/120, 4 - 10/110, 5 - 0%, 6 - Без НДС)
price Float Цена позиции
sum Float Сумма позиции
name String Название позиции
subjectType Integer Признак предмета расчета (1 - ТОВАР, 2 - ПОДАКЦИЗНЫЙ ТОВАР, 3 - РАБОТА, 4 - УСЛУГА, 10 - ПЛАТЕЖ, 11 - АГЕНТСКОЕ ВОЗНАГРАЖДЕНИЕ ... | Полный список)
agentData Struct Реквизиты агента

Таблица оплат

Параметр Вид значения Описание
sum Float Сумма оплаты
type String Тип оплаты ("cash" - Наличные, "ecash" - Безналичные, "credit" - Кредит, "prepaid" - Гашение аванса, "provision" - Встречное представление )

Реквизиты агента

Параметр Вид значения Описание
agentType Integer Признак агента
agentOperation String Операция
agentPhone String Телефон агента
supplierName String Название поставщика
supplierPhone String Телефон поставщика
supplierInn String ИНН поставщика
moneyTransferName String Наименование оператора перевода
moneyTransferAddress String Место нахождения оператора по переводу денежных средств
moneyTransferInn String ИНН оператора перевода
receivePaymentsPhone String Телефон получателя перевода
Параметр Вид значения Описание
Id String Уникальный идентификатор документа
ofd_key String Служебный идентификатор области ОФД
operationType Integer Тип операции (1 - Продажа, 2 - Возврат, 3 - Покупка, 4 - Возврат покупки, 6 - Z отчет)
fnNum String Номер фискального накопителя
fiscalSign Integer Фискальный признак чека
fiscalShiftNumber Integer Номер кассовой смены
fiscalDocumentDate String Дата документа
open String Дата открытия смены
close String Дата закрытия смены
regNum String Регистрационный номер ККТ
refundExpenseSumm Float Сумма возвратов покупок
incomeSumm Float Сумма продаж
refundIncomeSumm Float Сумма возвратов продаж
expenseSumm Float Сумма покупок
fiscalDocumentNumber Integer Номер чека
documentLink String Ссылка на чек
kktId String Идентификатор кассы