Обзор возможностей¶
API Контур.ОФД дает возможность пользователю получать фискальные данные, переданные через Контур.ОФД в ФНС. Вы можете получать данные:
- с ваших касс (например, для их импорта в товаро-учетную систему)
- с касс других организаций, пользователи которых согласятся на передачу данных. Например, с касс ваших арендаторов, если вы представляете торговый центр или с ККТ дочерних организаций в группе компаний.
Другой пример: получение банком данных для оценки/скоринга платежеспособности клиентов и мониторинга доходов клиента.
Работая с данными через API, вы можете получать фискальные данные в удобном для обработки в вашей учетной системой виде. Это дает возможность считать обобщенные значения выручки и других показателей за любой промежуток времени, отслеживать открытия и закрытия смен, собирать аналитику и статистику по продажам на ваших кассах или кассах ваших арендаторов.
Порядок работы с API¶
В каждом запросе к API необходимо передавать следующие данные:
- auth.sid с идентификатором пользовательской сессии, полученному по алгоритму, описанному в разделе Аутентификация,
- ключ интегратора. Получение ключа описано в разделе Получение ключа интегратора.
Когда истечет срок действия пользовательской сессии, в ответ на любой запрос интегратора к API Контур.ОФД будет возвращаться ошибка HTTP с кодом 401, в теле ответа будет содержаться поле «errorCode»: 401002. В этом случае необходимо получить новый идентификатор пользовательской сессии по алгоритму, описанному в разделе Аутентификация.
Чтобы получать данные по «своим» кассам (пользователь ККТ и интегратор - один ИНН) оплата и дополнительные документы не требуются.
Чтобы получать данные по «чужим» кассам (например, по арендаторам торгового центра) необходимо:
- Получить и оплатить счет на доступ к API. Тарификация и условия зависят от количества касс. Отправить заявку на подключение вы можете на почту ofd@skbkontur.ru
- Получить согласие от владельца ККТ на передачу его фискальных данных. Порядок работы с согласием пользователя описан в разделе Согласие пользователя ККТ на передачу фискальных данных.
Адреса и описание площадок¶
Контур.ОФД API работает на двух площадках - «тестовой» и «боевой». Используйте соответствующие адреса (endpoint) при выполнении запросов.
Боевая площадка содержит фискальные данные и кассы, подключенные к Контур.ОФД и передающие данные в ФНС.
Адрес площадки (endpoint): https://ofd-api.kontur.ru/
На тестовой площадке нет боевых (реальных) данных, но есть демо-организация с тестовыми кассами, которые формируют фискальные данные в автоматическом режиме. На этих данных вы можете протестировать работу с API и настроить интеграцию до подключения к боевой площадке.
Адрес площадки (endpoint): https://ofd-project.kontur.ru:11002/
Доступ к тестовой площадке осуществляется аналогично боевой, но не требует оплаты. При выдаче ключа интеграции, мы сообщим вам все необходимые для работы на площадке реквизиты. Получение ключа описано в разделе Получение ключа интегратора.
Точка входа для прохождения аутентификации (для работы на тестовой и боевой площадках один адрес): https://api.kontur.ru/
Согласие пользователя ККТ на передачу фискальных данных¶
Данные по кассам «чужого» ИНН будут доступны интегратору после того, как от владельца кассы будет получено согласие на передачу его фискальных данных. Для этого, владельцу необходимо настроить доступ в Личном Кабинете пользователя Контур.ОФД по инструкции, доступной в справке Личного Кабинета Контур.ОФД.
Это необходимо для обеспечения юридической возможности передачи данных с ККТ третьим лицам.
Примечание
Для доступа к данным касс своего ИНН (владелец ККТ и пользователь API - один ИНН) согласие не требуется.
Получение ключа интегратора¶
Для того, чтобы получить ключ интегратора, необходимый для доступа к API:
- Перейдите по ссылке
- Выберите сертификат электронной подписи (может быть использован только КЭП), выданный на организацию–интегратора, и нажмите «Войти». Вход по сертификату необходим для подтверждения доступа интегратора.
- Передайте через вашего менеджера или отправьте на почту ofd@kontur.ru (с пометкой «доступ к API Контур.ОФД») следующие данные:
- отпечаток сертификата, использованного для входа на шаге 2;
- логин, если вы будете пользоваться аутентификацией по логину и паролю (подробнее про настройку логина описано в разделе Аутентификация с использованием логина и пароля). Логин должен быть зарегистрирован на портале kontur.ru
- ИНН вашей организации;
- наименование организации;
- тип подключения – к тестовому API или к боевому;
- тип доступа (только для боевой площадки) - свои кассы (список или все) или кассы других организаций;
- если ранее вы уже работали с API Контур.ОФД, укажите, необходимо ли выдать новый ключ интегратора или нужно изменить настройку доступа для текущего ключа интегратора;
- ФИО, электронную почту и номер телефона двух контактных лиц организации – интегратора, ответственных за интеграцию и ее поддержку;
Если вы планируете получать данные по кассам с ИНН, отличным от ИНН вашей организации, по каждому ИНН необходимо получить согласие владельца кассы. Подробнее этот процесс описан в разделе Согласие пользователя ККТ на передачу фискальных данных.
Примечание
Обратите внимание, ключ интегратора является конфиденциальной информацией, не передавайте его третьим лицам.
Ключ интегратора получается один раз, доступ по ключу определяется исходя из настроенных разрешений на организации и их кассы и, при необходимости, может быть изменен по запросу интегратора.
После получения всех необходимых данных на стороне Контур.ОФД будет настроен доступ интегратора к данным указанных касс или касс, для которых их владельцы настроят разрешения. Когда настройки будут произведены, мы отправим ключ интегратора на указанную вами почту или на адрес, с которого вы отправляли запрос.
Использование полученного ключа описано в разделе Авторизация.
Аутентификация¶
Для доступа к API необходима аутентификация в домене .kontur.ru. Получив сессию по алгоритму, описанному ниже, необходимо во всех запросах к API передавать auth.sid со значением полученной сессии.
Есть 2 способа передачи:
HTTP-заголовок Authorization
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
HTTP-заголовок Cookie
Cookie: auth.sid=77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D; path=/; domain=kontur.ru;
Аутентификация с использованием сертификата¶
- Используйте метод authenticate-by-cert в API авторизации для получения токена (EncryptedKey).
- Расшифруйте EncryptedKey с помощью закрытого ключа, соответствующего сертификату, использованного на шаге 1. Для работы с сертификатом и расшифровки ключа могут быть использованы общедоступные классы и библиотеки, например, EnvelopedCms, X509Certificate2, BouncyCastle, OpenSSL и т.д.
- Используйте метод approve-cert для получения идентификатора сессии
- Полученный идентификатор используйте в качестве значения auth.sid
Для выполнения запросов, помимо идентификатора сессии вам необходимо передавать ключ интегратора. Подробнее в разделе Авторизация.
Аутентификация с использованием логина и пароля¶
- Используйте метод authenticate-by-pass в API авторизации для получения токена идентификатора сессии.
- Полученный идентификатор используйте в качестве значения auth.sid
Примечание
Auth.sid имеет ограниченный срок действия на стороне сервера. По-умолчанию, он истекает через 30 дней после его формирования, но, по разным причинам, может быть сброшен ранее.
Для выполнения запросов, помимо идентификатора сессии вам необходимо передавать ключ интегратора. Подробнее в разделе Авторизация.
Авторизация¶
Авторизация при доступе к API осуществляется по ключу интегратора, который необходимо передавать в заголовке X-Kontur-Ofd-ApiKey во время выполнения запросов.
Пример:
X-Kontur-Ofd-ApiKey: 031cg5h0-4d1e-135e-nh59-kuy61b12d71d
Если вы уже получили ключ интегратора - используйте его в качестве значения заголовка X-Kontur-Ofd-ApiKey. Если ключа у вас нет - смотрите раздел Получение ключа интегратора.
Доступные методы¶
authenticate-by-cert¶
Метод используется для получения зашифрованного на сертификат пользователя токена, необходимого для проверки доступа к закрытому ключу.
В теле запроса (Body) необходимо передать сертификат электронной подписи (в кодировке Base-64, подробнее в разделе Преобразование сертификатов), использованный для Получение ключа интегратора.
Запрос:
POST /auth/authenticate-by-cert?free=false HTTP/1.1
Host: api.kontur.ru
Cache-Control: no-cache
\-----BEGIN CERTIFICATE-----
MIIJtTCCCWSgAwIBAgIRAPNJ4HrEDMeA5xFQIzonz4UwCAYGKoUDAgIDMIIBezEe
MBwGCSqGSIb3DQEJARYPY2FAc2tia29udHVyLnJ1MRgwFgYFKoUDZAESDTEwMjY2
\......
MDAwMDAxMjEaMBgGCCqFAwOBAwEBEgw2NjI5NDE2NTg3NjAxIDAeBgkqhkiG9w0B
\-----END CERTIFICATE-----
Если запрос будет выполнен успешно, вернется ответ со статусом 200. В ответе будет содержаться JSON-объект с полем EncryptedKey - строкой, зашифрованной на сертификат пользователя:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: xxxx Server: xxxx
{
"EncryptedKey": "", //String, ключ: строка, зашифрованная на сертификат интегратора в кодировке Base-64
"Link": {
"Rel": "", //String, комментарий
"Href": "" //String, ссылка, которую необходимо использовать на следующем шаге
}
}
Примечание
Полученный от сервера ключ шифруется по алгоритму ГОСТ 28147-89.
Пример ответа:
{
"EncryptedKey": "MIIDsQYJKoZIhvcNAQcDoIIDoj……………M3UkvLVglQZdWlmdA==",
"Link": {
"Rel": "Send decrypted key to this link",
"Href": "https://api.kontur.ru/auth/v5.9/approve-cert?thumbprint=F757JY230G5G5755B5664ЗC870371V1G871012AA"
}
}
Возможные ответы, их коды и описание:
{
"HTTP response":
{
"200 OK", //Запрос выполнен успешно
"400 Bad Request", //Отсутствуют необходимые параметры
"403 Forbidden", //Описание содержится в теле ответа
"406 Not Acceptable", //Один из сертификатов цепочки имеет неверную подпись. Истек либо не наступил срок действия сертификата. Цепочка сертификатов основана на не доверенном корневом сертификате
"500 InternalServerError" //Внутренняя ошибка сервера
}
}
approve-cert¶
Метод используется для проверки расшифрованного токена и получения идентификатора пользовательской сессии (auth.sid).
Принимает параметр thumbprint, содержащий отпечаток сертификата, использованного для получения зашифрованного токена.
В теле запроса (Body) необходимо передать строку, полученную при расшифровке токена в байтовом представлении.
Запрос:
POST /auth/v5.9/approve-cert HTTP/1.1
Host: api.kontur.ru
Cache-Control: no-cache
thumbprint=F75741230A1CA755BHU64ЗC870372VFG871012AA
3082 03a7 0609 2a86 4886 f70d 0107 03a0
8203 9830 8203 9402 0100 3182 025b 3082
...
9ec7 b7a0 8470 f271 2a11 d1c8 007e be42
b128 17d1 852b 8edf de3f 7b
Если запрос будет выполнен успешно, вернется ответ со статусом 200. В ответе будет содержаться JSON-объект с полем Sid - session ID созданной сессии:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: xxxx
Server: xxxx
{
"Sid": "", //String, Session ID созданной сессии
"RefreshToken": "" //String, Refresh Token для созданной сессии (не используется в дальнейшем)
}
Пример ответа:
{
"Sid": "77F9456D0CF33BJK86C612D7B9B00013D93C433E4418EAA8L9166FF8D7E",
"RefreshToken": "77F9086D0CF33B4086C8EAA032A64370CF33EE3113B265C7ECC"
}
Возможные ответы, их коды и описание:
{
"HTTP response":
{
"200 OK", //Запрос выполнен успешно
"400 Bad Request", //Отсутствует thumbprint
"403 Forbidden", //Описание содержится в теле ответа
"500 InternalServerError" //Внутренняя ошибка сервера
}
}
authenticate-by-pass¶
Метод используется для получения идентификатора пользовательской сессии, используя логин и пароль пользователя.
В параметрe запроса login необходимо передать логин (электронную почту), используемую для аутентификации. В теле запроса (Body) передается пользовательский пароль в виде строки в кодировке UTF-8.
Пример запроса:
POST /auth/authenticate-by-pass?login=testlogin@testDomain.net HTTP/1.1
Host: api.kontur.ru
Body: myPassword
Cache-Control: no-cache
Если запрос будет выполнен успешно, вернется ответ со статусом 200. В ответе будет содержаться JSON-объект с полем Sid - session ID созданной сессии.
Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: xxxx
Server: xxxx
{
"Sid": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
Возможные ответы, их коды и описание:
{
"HTTP response":
{
"200 OK", //Запрос выполнен успешно
"400 Bad Request", //Отсутствуют необходимые параметры
"403 Forbidden", //Описание содержится в теле ответа
"500 InternalServerError" //Внутренняя ошибка сервера
}
}
documents/by-period¶
Метод возвращает все фискальные документы, полученные Контур.ОФД от кассы в заданном периоде времени. За один запрос можно получить не более 1000 документов. Для получения полного списка документов за период с постраничной выдачей нужно использовать параметры и структуру метода, описанные ниже.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>/documents/by-period?dateFrom=<dateFrom>&dateTo=<dateTo>&types=<documentsType>&offset=<currentOffset>&limit=<limit>
В запросе должны быть переданы следующие параметры:
- organizationId: string, обязательный, уникальный идентификатор организации, документы которой необходимо получить
- kktRegId: string, обязательный, РН ККТ кассы, документы которой необходимо получить
- dateFrom: string, обязательный, дата, начиная с которой необходимо получить документы.
- dateTo: string, обязательный, дата, по которую (включительно) необходимо получить документы.
- types: string, необязательный, типы фискальных документов, которые нужно получить
- currentOffset: string, необязательный, указатель на получение следующей страницы документов в периоде. В качестве указателя выступает последний документ на предыдущей странице. Этот документ не будет присутствовать на новой странице.
- limit: number, необязательный, количество возвращаемых документов в ответе на один запрос, т.е. на одной странице.
Допустимые форматы для параметра dateFrom и dateTo: yyyy-MM-ddTHH:mm:ss.
Типы фискальных документов для параметра types:
- fiscalReport - отчет о регистрации,
- fiscalReportCorrection - отчет об изменении параметров регистрации,
- currentStateReport - отчет о текущем состоянии расчетов,
- openShift - отчет об открытии смены,
- closeShift - отчет о закрытии смены,
- receipt - чеки,
- bso- бсо,
- receiptCorrection - чеки коррекции,
- bsoCorrection - бсо коррекции,
- closeArchive - отчет о закрытии фискального накопителя.
Есть возможность указывать несколько типов фискальных документов в одном запросе через запятую. Если этот параметр не указывать, то по умолчанию в ответе будут все типы фискальных документов.
Информация про limit:
- Значение limit по умолчанию – 1000.
- Max значение limit, которое можно указать: 1000.
- Min значение limit, которое можно указать: 1.
Пример запроса:
GET v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000000003065868/documents/by-period?dateFrom=2019-03-25T00:00:00&dateTo=2019-03-25T23:59:59&types=receipt&offset=T2MbygVny1CAWaPZI1NarQ%3D%3D&limit=1000
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
В теле ответа возвращается список фискальных документов от касс, к которым у интегратора есть доступ. Список возвращается в виде массива JSON-объектов следующей структуры:
{
"documents":[ //список документов
{
Тип ФД:
{
Данные ФД
}
},
{
Тип ФД:
{
Данные ФД
}
},
…
],
"paging": {
"nextOffset":"" //string, значение offset для получения данных на следующей странице
}
}
Как определить, все ли документы получены
Для получения первой страницы документов offset можно не указывать. Документы берем с начала заданного периода. Для следующих страниц в этом периоде нужно указать в offset значение nextOffset, полученное в предыдущем ответе на запрос. Необходимо настроить цикл запросов с параметром offset, который будет работать до тех пор, пока значение offset в запросе не будет равно значению nextOffset в ответе. В ответе будет пустой массив документов. Это значит, что все документы за период на текущий момент получены или, возможно, еще новые документы не пришли с кассы.
{
"documents":[],
"paging": {
"nextOffset":"T1NbygNby1CAWaPZI1NarQ%3D%3D"
}
}
Это справедливо и для offset=null. Если в запросе не указали offset и документов нет в периоде, то получим пустой список документов и «nextOffset»:null.
{
"documents":[ ],
"paging":{ }
}
Особенности
limit – максимальное возможное количество документов, которое вернется в ответе на один запрос. Допустим, вы хотите получать не все типы документов, а сделать фильтр на определенные типы. В этом случае есть особенности архитектуры нашей системы. Количество документов в ответе может быть в некоторых случаях меньше, чем указан limit в запросе. Это верно даже, если количество документов равно или больше limit.
Если указать limit положительный и больше 1000, то вернем в ответе количество документов равное значению по умолчанию 1000.
Документы в периоде сгенерированы в рамках определенных ФН-ов. Если offset не принадлежит указанному периоду и offset относится к документу, который был сгенерирован в рамках этих ФН-ов:
Если offset раньше указанного периода, то получите список документов с начала периода.
Если offset позже указанного периода, то в ответе будет пустой массив документов:
{
"documents":[],
"paging": {
"nextOffset":"" //string, offset того документа, который был указан в запросе
}
}
Пример ответа:
{
"documents":[
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-08-27T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000
}
},
{
"receipt": {
"receiptCode": 3,
"user": "ООО Золотой пятачок",
"userInn": "6699009482",
"requestNumber": 1,
"dateTime": "2018-08-27T10:13:51",
"shiftNumber": 367,
"operationType": 1,
"taxationType": 1,
"operator": "Герман Илья",
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5",
"items": [
{
"name": "Ассорти овощное помидоры,огурцы ст/б \"Золотая Долина\" 720 гр",
"price": 5668,
"quantity": 2,
"sum": 11336
}
],
"nds18": 1234,
"totalSum": 11336,
"cashTotalSum": 11336,
"ecashTotalSum": 0,
"fiscalDocumentNumber": 39090,
"fiscalSign": 3635260533,
"id": "00000000-0000-0000-0000-000000000000
}
}
],
"paging": {
"nextOffset":"T1MbygVby1CAWaPZI1NarQ%3D%3D"
}
}
Набор полей для каждого типа фискальных документов приведен в разделе Структуры данных.
Для получения реквизитов фискального документа по его номеру используйте метод tickets/<documentId> и documents/<documentId>
documents¶
Метод возвращает все фискальные документы, полученные Контур.ОФД от кассы, на заданную дату.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>/documents?date=<date>&types=<documentsType>
В запросе должны быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации, документы которой необходимо получить
- kktRegId: обязательный, РН ККТ кассы, документы которой необходимо получить
- date: обязательный, дата формирования фискальных документов, за которую необходимо получить документы
- types: необязательный, типы фискальных документов, которые нужно получить
Допустимые форматы для параметра date: гггг-мм-дд, гггг.мм.дд, дд-мм-гггг, дд.мм.гггг.
Типы фискальных документов для параметра types:
- fiscalReport - отчет о регистрации,
- fiscalReportCorrection - отчет об изменении параметров регистрации,
- currentStateReport - отчет о текущем состоянии расчетов,
- openShift - отчет об открытии смены,
- closeShift - отчет о закрытии смены,
- receipt - чеки,
- bso- бсо,
- receiptCorrection - чеки коррекции,
- bsoCorrection - бсо коррекции,
- closeArchive - отчет о закрытии фискального накопителя.
Есть возможность указывать несколько типов фискальных документов в одном запросе через запятую. Если этот параметр не указывать, то по умолчанию в ответе будут все типы фискальных документов.
Пример запроса:
GET T v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000000003065868/documents?date=27.08.2018types=fiscalReport,fiscalReportCorrection,currentStateReport,openShift,closeShift,receipt,receiptCorrection,closeArchive HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
В теле ответа возвращается список фискальных документов от касс, к которым у интегратора есть доступ. Список возвращается в виде массива JSON-объектов следующей структуры:
[
{
Тип ФД:
{
Данные ФД
}
},
{
Тип ФД:
{
Данные ФД
}
}
]
Пример ответа:
[
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-08-27T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000"
}
},
{
"receipt": {
"receiptCode": 3,
"user": "ООО Золотой пятачок",
"userInn": "6699009482",
"requestNumber": 1,
"dateTime": "2018-08-27T10:13:51",
"shiftNumber": 367,
"operationType": 1,
"taxationType": 1,
"operator": "Герман Илья",
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5",
"items": [
{
"name": "Ассорти овощное помидоры,огурцы ст/б \"Золотая Долина\" 720 гр",
"price": 5668,
"quantity": 2,
"sum": 11336
}
],
"nds18": 1234,
"totalSum": 11336,
"cashTotalSum": 11336,
"ecashTotalSum": 0,
"fiscalDocumentNumber": 39090,
"fiscalSign": 3635260533,
"id": "00000000-0000-0000-0000-000000000000"
}
}
]
Набор полей для каждого типа фискальных документов приведен в разделе Структуры данных.
Если на указанную дату нет документов, то в ответе будет пустой массив.
Для получения реквизитов фискального документа по его номеру используйте метод tickets/<documentId> и documents/<documentId>.
documents/<documentId>¶
С помощью метода интегратор может получить отдельный фискальный документ в формате JSON-объекта.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>/documents/<documentId>
В запросе должны быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации, документы которой необходимо получить
- kktRegId: обязательный, РН ККТ кассы, документы которой необходимо получить
- documentId: обязательный, уникальный идентификатор документа
Пример запроса:
GET v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000000003065868/documents/00000000-0000-0000-0000-000000000000 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
Для получения идентификатора документа необходимо использовать методы получения фискальных документов documents/by-period и documents. Нужно смотреть поле «id»: «00000000-0000-0000-0000-000000000000».
Тело ответа содержит JSON-объект с реквизитами, соответствующими фискальному документу и указанными в разделе Структуры данных.
{
Тип ФД:
{
Данные ФД
}
}
Пример ответа:
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-04-05T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000"
}
}
Возможные значения типов ФД¶
{
"fiscalReport", //Отчет о регистрации
"fiscalReportCorrection", //Отчёт об изменении параметров регистрации
"openShift", //Отчет об открытии смены
"currentStateReport", //Отчёт о текущем состоянии расчетов
"receipt", //Кассовый чек
"receiptCorrection", //Кассовый чек коррекции
"bso", //БСО
"bsoCorrection", //Бланк строгой отчетности коррекции
"closeShift", //Отчёт о закрытии смены
"closeArchive" //Отчёт о закрытии фискального накопителя
}
Набор полей для каждого типа фискальных документов приведен в разделе Структуры данных.
tickets/<documentId>¶
С помощью метода интегратор может получить отдельный фискальный документ в формате JSON-объекта.
GET <endpoint>/v1/integration/inns/<inn>/kkts/<kktRegId>/fss/<fsId>/tickets/<documentId>
В запросе должны быть переданы следующие параметры:
- inn: обязательный, ИНН организации, документы которой необходимо получить
- kktRegId: обязательный, РНМ кассы, документы которой необходимо получить
- fsId: обязательный, заводской номер фискального накопителя (ФН)
- documentId: обязательный, порядковый номер фискального документа, который необходимо получить
Пример запроса:
GET /v1/integration/inns/6699009482/kkts/0000000003065868/fss/99990788607/tickets/39089 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
Тело ответа содержит JSON-объект с реквизитами, соответствующими фискальному документу и указанными в разделе Структуры данных.
{
Тип ФД:
{
Данные ФД
}
}
Пример ответа:
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-04-05T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000"
}
}
Возможные значения типов ФД¶
{
"fiscalReport", //Отчет о регистрации
"fiscalReportCorrection", //Отчёт об изменении параметров регистрации
"openShift", //Отчет об открытии смены
"currentStateReport", //Отчёт о текущем состоянии расчетов
"receipt", //Кассовый чек
"receiptCorrection", //Кассовый чек коррекции
"bso", //БСО
"bsoCorrection", //Бланк строгой отчетности коррекции
"closeShift", //Отчёт о закрытии смены
"closeArchive" //Отчёт о закрытии фискального накопителя
}
Набор полей для каждого типа фискальных документов приведен в разделе Структуры данных.
tickets (устарел)¶
Внимание
Метод tickets устарел, временно поддерживается. Используйте вместо него другие методы.
Метод возвращает все фискальные документы, полученные Контур.ОФД от кассы в заданном периоде времени.
GET <endpoint>/v1/integration/inns/<inn>/kkts/<kktRegId>/fss/<fsId>/tickets?dateFrom=<dateFrom>&dateTo=<dateTo>
В запросе должны быть переданы следующие параметры:
- inn: обязательный, ИНН организации, документы которой необходимо получить
- kktRegId: обязательный, РНМ кассы, документы которой необходимо получить
- fsId: обязательный, заводской номер фискального накопителя (ФН)
- dateFrom: обязательный, дата формирования фискальных документов, начиная с которой необходимо получить документы
- dateTo: обязательный, дата формирования фискальных документов, по которую (включительно) необходимо получить документы
Допустимые форматы для параметров dateFrom и dateTo: гггг-мм-дд, гггг.мм.дд, дд-мм-гггг, дд.мм.гггг.
Пример запроса:
GET /v1/integration/inns/6699009482/kkts/0000000003065868/fss/99990788607/tickets?dateFrom=27.08.2018&dateTo=28.08.2018 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
В теле ответа возвращается список фискальных документов от касс, к которым у интегратора есть доступ. Список возвращается в виде массива JSON-объектов следующей структуры:
[
{
Тип ФД:
{
Данные ФД
}
},
{
Тип ФД:
{
Данные ФД
}
}
]
Пример ответа:
[
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-08-27T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000"
}
},
{
"receipt": {
"receiptCode": 3,
"user": "ООО Золотой пятачок",
"userInn": "6699009482",
"requestNumber": 1,
"dateTime": "2018-08-27T10:13:51",
"shiftNumber": 367,
"operationType": 1,
"taxationType": 1,
"operator": "Герман Илья",
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5",
"items": [
{
"name": "Ассорти овощное помидоры,огурцы ст/б \"Золотая Долина\" 720 гр",
"price": 5668,
"quantity": 2,
"sum": 11336
}
],
"nds18": 1234,
"totalSum": 11336,
"cashTotalSum": 11336,
"ecashTotalSum": 0,
"fiscalDocumentNumber": 39090,
"fiscalSign": 3635260533,
"id": "00000000-0000-0000-0000-000000000000"
}
}
]
Возможные значения типов ФД¶
{
"fiscalReport", //Отчет о регистрации
"fiscalReportCorrection", //Отчёт об изменении параметров регистрации
"openShift", //Отчет об открытии смены
"currentStateReport", //Отчёт о текущем состоянии расчетов
"receipt", //Кассовый чек
"receiptCorrection", //Кассовый чек коррекции
"bso", //БСО
"bsoCorrection", //Бланк строгой отчетности коррекции
"closeShift", //Отчёт о закрытии смены
"closeArchive" //Отчёт о закрытии фискального накопителя
}
Набор полей для каждого типа фискальных документов приведен в разделе Структуры данных.
Если в указанном периоде не было документов, то в ответе будет пустой массив.
Для получения реквизитов фискального документа по его номеру, используйте метод tickets/<documentId>
cashboxes/statistics/by-days¶
Метод возвращает по кассе и временному периоду информацию в разрезе суток. В сутках хранится массив агрегированных данных.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>/statistics/cash-receipt/by-days?from=<dateFrom>&to=<dateTo>
В запросе должны быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации, информацию о которой необходимо получить
- kktRegId: обязательный, РНМ кассы, документы которой необходимо получить
- dateFrom: обязательный, дата формирования фискальных документов, начиная с которой необходимо получить документы
- dateTo: обязательный, дата формирования фискальных документов, по которую (включительно) необходимо получить документы
Допустимые форматы для параметров dateFrom и dateTo: гггг-мм-дд, гггг.мм.дд, дд-мм-гггг, дд.мм.гггг.
Пример запроса:
GET v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000000003065868/statistics/cash-receipt/by-days?from=2019-01-01&to=2019-03-01 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
В теле ответа возвращается информация в разрезе дней. Список возвращается в виде массива JSON-объектов следующей структуры:
{
items:
[
{
Информация по дню
},
{
Информация по дню
}
]
}
Пример ответа в разрезе двух дней:
{
"items": [
{
"date": "2019-11-05", //Дата и время агрегации данных. День первый
"buy": { //Покупка. Информация по чекам с признаком Расход
"cashlessTotal": 245754, //Сумма безналичными в копейках
"cashTotal": 360542, //Сумма наличными в копейках
"total": 606296, //Общая сумма в копейках
"totalWithNds0": 0, //Сумма НДС 0% в копейках
"totalWithNdsFree": 0, //Сумма без НДС в копейках
"count": 14, //Количество чеков
"nds": {
"rate10": 0, //Сумма НДС 10% в копейках
"calculatedWithRate10": 0, //Сумма НДС 10/110 в копейках
"rate18": 0, //Сумма НДС 18% в копейках
"calculatedWithRate18": 0, //Сумма НДС 18/118 в копейках
"rate20": 101051, //Сумма НДС 20% в копейках
"calculatedWithRate20": 0 //Сумма НДС 20/120 в копейках
}
},
"returnBuy": { //Возврат покупки. Информация по чекам с признаком Возврат расхода
"cashlessTotal": 37202,
"cashTotal": 132320,
"total": 169522,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 28253,
"calculatedWithRate20": 0
}
},
"sell": { //Продажа. Информация по чекам с признаком Приход
"cashlessTotal": 2862884,
"cashTotal": 3316499,
"total": 6179383,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 166,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1029913,
"calculatedWithRate20": 0
}
},
"returnSell": { //Возврат продажи. Информация по чекам с признаком Возврат прихода
"cashlessTotal": 414383,
"cashTotal": 171692,
"total": 586075,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 16,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 97681,
"calculatedWithRate20": 0
}
}
},
{
"date": "2019-11-06", //Дата и время агрегации данных. День второй
"buy": {
"cashlessTotal": 327200,
"cashTotal": 402772,
"total": 729972,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 18,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 121665,
"calculatedWithRate20": 0
}
},
"returnBuy": {
"cashlessTotal": 129720,
"cashTotal": 92343,
"total": 222063,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 37010,
"calculatedWithRate20": 0
}
},
"sell": {
"cashlessTotal": 3363914,
"cashTotal": 3010182,
"total": 6374096,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 160,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1062367,
"calculatedWithRate20": 0
}
},
"returnSell": {
"cashlessTotal": 303281,
"cashTotal": 357152,
"total": 660433,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 17,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 110074,
"calculatedWithRate20": 0
}
}
}
]
}
Если за весь выбранный период нет движений
- Если в какой-то день было открытие и/или закрытие смены и не было чеков (БСО), то день будет в ответе с нулевыми данными.
- Если не было даже открытия/закрытия смены за весь выбранный период, то придет:
{
"items": []
}
Если за выбранный период есть движения, но не во всех днях
- Если в какой-то день не было открытия и/или закрытия смены и чеков (БСО), то этого дня в ответе не будет.
- Если в какой-то день было открытие и/или закрытие смены и не было чеков (БСО), то день будет в ответе с нулевыми данными.
- Если были чеки (БСО), то будут ненулевые данные.
Для получения по кассе и периоду информации в разрезе смен используйте метод cashboxes/statistics/by-shifts
Для получения по организации и периоду информации в разрезе дней используйте метод organizations/statistics/by-days
cashboxes/statistics/by-shifts¶
Метод возвращает по кассе и периоду информацию в разрезе смен. В смене хранится массив агрегированных данных.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>/statistics/cash-receipt/by-shifts?from=<dateFrom>&to=<dateTo>
В запросе должны быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации, информацию о которой необходимо получить
- kktRegId: обязательный, РНМ кассы, документы которой необходимо получить
- dateFrom: обязательный, дата формирования фискальных документов, начиная с которой необходимо получить документы
- dateTo: обязательный, дата формирования фискальных документов, по которую (включительно) необходимо получить документы
Допустимые форматы для параметров dateFrom и dateTo: гггг-мм-дд, гггг.мм.дд, дд-мм-гггг, дд.мм.гггг.
Пример запроса:
GET v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000000003065868/statistics/cash-receipt/by-shifts?from=2019-01-01&to=2019-03-01 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций и касс, к которым у пользователя есть доступ, необходимо использовать методы organizations и cashboxes.
В теле ответа возвращается информация в разрезе смен. Список возвращается в виде массива JSON-объектов следующей структуры:
{
«shifts»:
[
{
Информация по смене
},
{
Информация по смене
}
]
}
Пример ответа в разрезе двух смен:
{
"shifts": [
{
"shiftNumber": 103, // Номер первой смены
"shiftOpen": "2019-11-19T10:00:00", // Дата и время открытия
"shiftClose": "2019-11-19T16:00:01", // Дата и время закрытия (только если смена закрыта)
"buy": { // Покупка. Информация по чекам с признаком Расход
"cashlessTotal": 245754, // Сумма безналичными в копейках
"cashTotal": 360542, // Сумма наличными в копейках
"total": 606296, // Общая сумма в копейках
"totalWithNds0": 0, // Сумма НДС 0% в копейках
"totalWithNdsFree": 0, // Сумма без НДС в копейках
"count": 14, // Количество чеков
"nds": {
"rate10": 0, // Сумма НДС 10% в копейках
"calculatedWithRate10": 0, // Сумма НДС 10/110 в копейках
"rate18": 0, // Сумма НДС 18% в копейках
"calculatedWithRate18": 0, // Сумма НДС 18/118 в копейках
"rate20": 101051, // Сумма НДС 20% в копейках
"calculatedWithRate20": 0 // Сумма НДС 20/120 в копейках
}
},
"returnBuy": { // Возврат покупки. Информация по чекам с признаком Возврат расхода
"cashlessTotal": 37202,
"cashTotal": 132320,
"total": 169522,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 28253,
"calculatedWithRate20": 0
}
},
"sell": { // Продажа. Информация по чекам с признаком Приход
"cashlessTotal": 2862884,
"cashTotal": 3316499,
"total": 6179383,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 166,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1029913,
"calculatedWithRate20": 0
}
},
"returnSell": { // Возврат продажи. Информация по чекам с признаком Возврат прихода
"cashlessTotal": 414383,
"cashTotal": 171692,
"total": 586075,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 16,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 97681,
"calculatedWithRate20": 0
}
}
},
{
"shiftNumber": 104, // Номер второй смены
"shiftOpen": "2019-11-19T16:01:00",
"shiftClose": "2019-11-19T22:00:01",
"buy": {
"cashlessTotal": 327200,
"cashTotal": 402772,
"total": 729972,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 18,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 121665,
"calculatedWithRate20": 0
}
},
"returnBuy": {
"cashlessTotal": 129720,
"cashTotal": 92343,
"total": 222063,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 37010,
"calculatedWithRate20": 0
}
},
"sell": {
"cashlessTotal": 3363914,
"cashTotal": 3010182,
"total": 6374096,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 160,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1062367,
"calculatedWithRate20": 0
}
},
"returnSell": {
"cashlessTotal": 303281,
"cashTotal": 357152,
"total": 660433,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 17,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 110074,
"calculatedWithRate20": 0
}
}
}
]
}
Особенности
- Если в течение смены не было чеков (БСО), то в смене будут указаны нулевые данные.
- Для переходящих смен (начало смены в один день, конец - в другой), если в период в запросе целиком смена не попала, то отдаем только суммы, попавшие в выбранный период. Суммы, приходящиеся на другой период, по этой смене не отдаем.
- Дату и время открытия смены в ответе отображаем только, когда клиент включил в период в запросе дату, когда приходил отчет об открытии смены. Аналогичная логика для даты и времени закрытия смены.
- Если документов в периоде не было, то в ответе будет:
{
"shifts":[]
}
Для получения по кассе и периоду информации в разрезе дней используйте метод cashboxes/statistics/by-days
Для получения по организации и периоду информации в разрезе дней используйте метод organizations/statistics/by-days
organizations/statistics/by-days¶
Метод возвращает по организации и временному периоду информацию в разрезе суток. В сутках хранится массив агрегированных данных.
Примечание
Метод могут использовать только интеграторы, у которых есть доступ на все кассы организации, в том числе будущие.
GET <endpoint>/v2/organizations/<organizationId>/statistics/cash-receipt/by-days?from=<dateFrom>&to=<dateTo>
В запросе должны быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации, информацию о которой необходимо получить
- dateFrom: обязательный, дата формирования фискальных документов, начиная с которой необходимо получить документы
- dateTo: обязательный, дата формирования фискальных документов, по которую (включительно) необходимо получить документы
Допустимые форматы для параметров dateFrom и dateTo: гггг-мм-дд, гггг.мм.дд, дд-мм-гггг, дд.мм.гггг.
Пример запроса:
GET v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/statistics/cash-receipt/by-days?from=2019-01-01&to=2019-03-01 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
Для получения списка организаций, к которым у пользователя есть доступ, необходимо использовать метод organizations.
В теле ответа возвращается информация в разрезе дней. Список возвращается в виде массива JSON-объектов следующей структуры:
{
items:
[
{
Информация по дню
},
{
Информация по дню
}
]
}
Пример ответа в разрезе двух дней:
{
"items": [
{
"date": "2019-11-05", //Дата и время агрегации данных. День первый
"buy": { //Покупка. Информация по чекам с признаком Расход
"cashlessTotal": 245754, //Сумма безналичными в копейках
"cashTotal": 360542, //Сумма наличными в копейках
"total": 606296, //Общая сумма в копейках
"totalWithNds0": 0, //Сумма НДС 0% в копейках
"totalWithNdsFree": 0, //Сумма без НДС в копейках
"count": 14, //Количество чеков
"nds": {
"rate10": 0, //Сумма НДС 10% в копейках
"calculatedWithRate10": 0, //Сумма НДС 10/110 в копейках
"rate18": 0, //Сумма НДС 18% в копейках
"calculatedWithRate18": 0, //Сумма НДС 18/118 в копейках
"rate20": 101051, //Сумма НДС 20% в копейках
"calculatedWithRate20": 0 //Сумма НДС 20/120 в копейках
}
},
"returnBuy": { //Возврат покупки. Информация по чекам с признаком Возврат расхода
"cashlessTotal": 37202,
"cashTotal": 132320,
"total": 169522,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 28253,
"calculatedWithRate20": 0
}
},
"sell": { //Продажа. Информация по чекам с признаком Приход
"cashlessTotal": 2862884,
"cashTotal": 3316499,
"total": 6179383,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 166,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1029913,
"calculatedWithRate20": 0
}
},
"returnSell": { //Возврат продажи. Информация по чекам с признаком Возврат прихода
"cashlessTotal": 414383,
"cashTotal": 171692,
"total": 586075,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 16,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 97681,
"calculatedWithRate20": 0
}
}
},
{
"date": "2019-11-06", //Дата и время агрегации данных. День второй
"buy": {
"cashlessTotal": 327200,
"cashTotal": 402772,
"total": 729972,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 18,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 121665,
"calculatedWithRate20": 0
}
},
"returnBuy": {
"cashlessTotal": 129720,
"cashTotal": 92343,
"total": 222063,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 4,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 37010,
"calculatedWithRate20": 0
}
},
"sell": {
"cashlessTotal": 3363914,
"cashTotal": 3010182,
"total": 6374096,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 160,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 1062367,
"calculatedWithRate20": 0
}
},
"returnSell": {
"cashlessTotal": 303281,
"cashTotal": 357152,
"total": 660433,
"totalWithNds0": 0,
"totalWithNdsFree": 0,
"count": 17,
"nds": {
"rate10": 0,
"calculatedWithRate10": 0,
"rate18": 0,
"calculatedWithRate18": 0,
"rate20": 110074,
"calculatedWithRate20": 0
}
}
}
]
}
Если за весь выбранный период нет движений
- Если в какой-то день было открытие и/или закрытие смены и не было чеков (БСО), то день будет в ответе с нулевыми данными.
- Если не было даже открытия/закрытия смены за весь выбранный период, то придет:
{
"items": []
}
Если за выбранный период есть движения, но не во всех днях
- Если в какой-то день не было открытия и/или закрытия смены и чеков (БСО), то этого дня в ответе не будет.
- Если в какой-то день было открытие и/или закрытие смены и не было чеков (БСО), то день будет в ответе с нулевыми данными.
- Если были чеки (БСО), то будут ненулевые данные.
Для получения по кассе и периоду информации в разрезе смен используйте метод cashboxes/statistics/by-shifts
Для получения по кассе и периоду информации в разрезе дней используйте метод cashboxes/statistics/by-days
organizations¶
Метод возвращает все организации, к которым у пользователя есть доступ.
GET <endpoint>/v2/organizations
Пример запроса:
GET /v2/organizations HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
В теле ответа возвращаются организации с их реквизитами в виде массива JSON-объектов следующей структуры:
[
{
"id": "", //идентификатор организации
"inn": "", //ИНН
"kpp": "", //КПП
"ogrn": "", //ОГРН
"shortName": "", //краткое наименование
"fullName": "" //полное наименование
}
]
Пример ответа:
[
{
"id": "c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6",
"inn": "6699000000",
"kpp": "669901001",
"ogrn": "000000000000000",
"shortName": "ООО Тестовая организация",
"fullName": "Общество с органиченной ответственностью Тестовая организация"
}
]
Если нет доступных организаций по ключу интегратора (см. раздел Авторизация) и auth.sid, то в ответе будет пустой массив.
Для получения реквизитов организации по её идентификатору, используйте метод organizations/<organizationId>
organizations/<organizationId>¶
Метод возвращает реквизиты организации по её идентификатору.
GET <endpoint>/v2/organizations/<organizationId>
В запросе должен быть передан один параметр:
- organizationId: обязательный, уникальный идентификатор организации
Пример запроса:
GET /v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
В теле ответа возвращаются реквизиты организации в виде JSON-объекта следующей структуры:
{
"id": "", //идентификатор организации
"inn": "", //ИНН
"kpp": "", //КПП
"ogrn": "", //ОГРН
"shortName": "", //краткое наименование
"fullName": "" //полное наименование
}
Пример ответа:
{
"id": "c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6",
"inn": "6699000000",
"kpp": "669901001",
"ogrn": "000000000000000",
"shortName": "ООО Тестовая организация",
"fullName": "Общество с органиченной ответственностью Тестовая организация"
}
cashboxes¶
Метод возвращает все кассы организации, к которым у пользователя есть доступ.
GET <endpoint>/v2/organizations/<organizationId>/cashboxes
Пример запроса:
GET /v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
В теле ответа возвращаются кассы организации с их реквизитами в виде массива JSON-объектов следующей структуры:
[
{
"regNumber": "", // регистрационный номер ККТ (РНМ)
"serialNumber": "", // заводской номер ККТ
"address": "", // текущий адрес размещения ККТ (адрес осуществления расчетов между пользователем и покупателем)
"addresses":[ // список всех адресов размещения ККТ, в том числе и текущий
{
"address":"", // адрес размещения ККТ
"startDate":"" // дата начала передачи документов по этому адресу
},
{
"address":"",
"startDate":""
},
...
],
"name": "", // наименование ККТ
"modelName": "", // модель ККТ
"kpp": "", // КПП, указанный при подключении кассы в ЛК, либо КПП организации (в остальных случаях)
"fiscalDrive": // текущий фискальный накопитель
{
"fiscalDriverNumber": "", // заводской номер фискального накопителя
"earliestDocumentTimestamp": "" // дата первого документа, который хранится у нас, для этого фискального накопителя
},
"fiscalDrives": // список всех фискальных накопителей для кассы, в том числе и текущий
[
{
"fiscalDriverNumber": "",
"earliestDocumentTimestamp": ""
},
{
"fiscalDriverNumber": "",
"earliestDocumentTimestamp": ""
},
...
],
"salesPointName": "", // название текущей точки продаж
"permissionFrom": "", // дата, с которой интегратор может получать документы
"permissionTo": "" // дата, по которую интегратор может получать документы
}
]
Пример ответа:
[
{
"regNumber": "0000800000000005",
"serialNumber": "00106700332501",
"address": "г. Екатеринбург. ул. Малопрудная 5",
"addresses":[
{
"address":"г.Москва Ул. победы д522,
"startDate":"2019-09-12T00:00:00"
},
{
"address":"г. Екатеринбург. ул. Малопрудная 5",
"startDate":"2020-01-19T00:00:00"
},
...
],
"name": "Касса 1",
"modelName": "АТОЛ 30Ф",
"kpp": "669901001",
"fiscalDrive":
{
"fiscalDriverNumber": "9492452823423233",
"earliestDocumentTimestamp": "2019-10-10T00:00:00"
},
"fiscalDrives":
[
{
"fiscalDriverNumber": "4393456832322943",
"earliestDocumentTimestamp": "2017-11-12T00:00:00"
},
{
"fiscalDriverNumber": "9492452823423233",
"earliestDocumentTimestamp": "2019-10-10T00:00:00"
}
],
"salesPointName": "Четвертая точка продаж",
"permissionFrom": "2018-12-12T00:00:00",
"permissionTo": "2018-12-14T14:14:41"
}
]
Для получения реквизитов кассы по её регистрационному номеру, используйте метод cashboxes/<kktRegId>
cashboxes/<kktRegId>¶
Метод возвращает реквизиты кассы по её регистрационному номеру (РНМ).
GET <endpoint>/v2/organizations/<organizationId>/cashboxes/<kktRegId>
В запросе должен быть переданы следующие параметры:
- organizationId: обязательный, уникальный идентификатор организации
- kktRegId: обязательный, регистрационный номер кассы (РНМ)
Пример запроса:
GET /v2/organizations/c2e3a34c-823f-4b1e-a9g1-d94fa40c22a6/cashboxes/0000800000000005 HTTP/1.1
Host: ofd-project.kontur.ru:11002
Cache-Control: no-cache
X-Kontur-Ofd-ApiKey: 031c1890-9hhe-435e-5h59-43091hhcd71d
Authorization: auth.sid 77F90D0CF33SEF67SWRG87B9BBA7139F0CD76GRTY00931F2E1F0D
В теле ответа возвращаются ревизиты кассы в виде JSON-объекта следующей структуры:
{
"regNumber": "", // регистрационный номер ККТ (РНМ)
"serialNumber": "", // заводской номер ККТ
"address": "", // текущий адрес размещения ККТ (адрес осуществления расчетов между пользователем и покупателем)
"addresses":[ // список всех адресов размещения ККТ, в том числе и текущий
{
"address":"", // адрес размещения ККТ
"startDate":"" // дата начала передачи документов по этому адресу
},
{
"address":"",
"startDate":""
},
...
],
"name": "", // наименование ККТ
"modelName": "", // модель ККТ
"kpp": "", // КПП, указанный при подключении кассы в ЛК, либо КПП организации (в остальных случаях)
"fiscalDrive": // текущий фискальный накопитель
{
"fiscalDriverNumber": "", // заводской номер фискального накопителя
"earliestDocumentTimestamp": "" // дата первого документа, который хранится у нас, для этого фискального накопителя
},
"fiscalDrives": // список всех фискальных накопителей для кассы, в том числе и текущий
[
{
"fiscalDriverNumber": "",
"earliestDocumentTimestamp": ""
},
{
"fiscalDriverNumber": "",
"earliestDocumentTimestamp": ""
},
...
],
"salesPointName": "", // название текущей точки продаж
"permissionFrom": "", // дата, с которой интегратор может получать документы
"permissionTo": "" // дата, по которую интегратор может получать документы
}
Пример ответа:
{
"regNumber": "0000800000000005",
"serialNumber": "00106700332501",
"address": "г. Екатеринбург. ул. Малопрудная 5",
"addresses":[
{
"address":"г.Москва Ул. победы д52",
"startDate":"2019-09-12T00:00:00"
},
{
"address":"г. Екатеринбург. ул. Малопрудная 5",
"startDate":"2020-01-19T00:00:00"
},
...
],
"name": "Касса 1",
"modelName": "АТОЛ 30Ф",
"kpp": "669901001",
"fiscalDrive":
{
"fiscalDriverNumber": "9492452823423233",
"earliestDocumentTimestamp": "2019-10-10T00:00:00"
},
"fiscalDrives":
[
{
"fiscalDriverNumber": "4393456832322943",
"earliestDocumentTimestamp": "2017-11-12T00:00:00"
},
{
"fiscalDriverNumber": "9492452823423233",
"earliestDocumentTimestamp": "2019-10-10T00:00:00"
}
],
"salesPointName": "Четвертая точка продаж",
"permissionFrom": "2018-12-12T00:00:00",
"permissionTo": "2018-12-14T14:14:41"
}
Коды и статусы ответов¶
При положительном результате обработки запроса возвращается HTTP-код ответа 200 ОК. В теле ответа содержатся данные, соответствующие запросу. В случае отсутствия данных в указанном периоде или с указанными параметрами возвращается пустое тело ответа.
При возникновении внутренней ошибки сервера во время обработки запроса возвращается ошибка 500 Internal Server Error.
При появлении иных ошибок в процессе обработки запроса могут быть возвращены коды ошибки 400, 401, 403. В этих случаях в теле ответа возвращается следующая структура:
{
"errorCodeId": "", // сообщение, конкретизирующее обнаруженную ошибку
"errorCode": "", // код, конкретизирующий обнаруженную ошибку, это поле устарело, временно поддерживается
"moreInfo": "", // ссылка на подробную документацию API
"userMessage": { // поясняющий текст на русском и английском языках
"ru": "",
"en": "",
}
}
Примечание
Поле errorCode устарело, временно поддерживается, используйте errorCodeId.
Возможные ответы, и соответствующие им errorCode¶
"HTTP response":
{
"400 Bad Request":
{
"errorCode": 400000,
"errorCodeId": "urn:error:request:invalid" // Некорректно указано значение параметра в запросе
},
{
"errorCode": 400000,
"errorCodeId": "urn:error:page-query:build:invalid" //Если значение limit 0/отрицательное или offset передали некорректный
},
{
"errorCode": 400000,
"errorCodeId": "urn:error:document-metas-service:get-document-ids:failed" //Документы в периоде сгенерированы в рамках определенных ФН-ов. Если offset не принадлежит указанному периоду и offset относится к документу, который был сгенерирован не в рамках этих ФН-ов
},
{
"errorCode": 400002,
"errorCodeId": "urn:error:request-parameter:period:invalid" // Неверный временной интервал: дата начала периода больше даты конца, либо даты заданы неверным форматом
},
{
"errorCode": 400007,
"errorCodeId": "urn:error:request-parameter:{имя параметра}:required" // Запрос должен содержать обязательный параметр
},
{
"errorCode": 400008,
"errorCodeId": "urn:error:request-parameter:date:invalid" // Переданная дата не соответствует формату
},
{
"errorCode": 400009,
"errorCodeId": "urn:error:request-parameter:datetime:invalid" //Если дата или время указаны не по формату
},
"401 Unauthorized":
{
"errorCode": 401002,
"errorCodeId": "urn:error:request-parameter:auth-sid:required:access-denied" // Не указан идентификатор пользовательской сессии (auth.sid); Срок действия пользовательской сессии истек; Переданный идентификатор не соответствует формату
},
{
"errorCode": 401003,
"errorCodeId": "urn:error:request-parameter:apikey:required:access-denied" // Не указан ключ интегратора
},
{
"errorCode": 401003,
"errorCodeId": "urn:error:request-parameter:apikey:unknown:access-denied" // Значение ключа интегратора не соответствует формату
},
"403 Forbidden":
{
"errorCode": 403000,
"errorCodeId": "urn:error:access:forbidden" // Нет доступа к запрошенным данным
},
{
"errorCode": 403000,
"errorCodeId": "urn:error:access-to:cashboxdocuments:forbidden" // Не предоставлен доступ к кассе с переданным РНМ или указан период, на который не предоставлен доступ
},
{
"errorCode": 403000,
"errorCodeId": "urn:error:access-to:organizationdocuments:forbidden" // Нет доступа к организации или указан период, на который не предоставлен доступ
},
{
"errorCode": 403002,
"errorCodeId": "urn:error:access-to:cashbox:forbidden" // Не предоставлен доступ к кассе с переданным РНМ
},
{
"errorCode": 403003
"errorCodeId": "urn:error:access-to:organization:forbidden" // Нет доступа к организации
},
"404 Not Found":
{
"errorCode": 404000,
"errorCodeId": "urn:error:organization:not-found" // Организация не найдена
},
{
"errorCode": 404001,
"errorCodeId": "urn:error:documents:document:not-found" // ФН с переданным номером не был установлен в кассу с переданным РНМ или документ не найден
}
}
Структуры данных¶
При положительном результате обработки запроса, в теле ответа содержатся данные, соответствующие запросу, если они существуют и были найдены. Данные в ответе представлены в виде JSON-объекта, или массива таких объектов. Объект состоит из полей и значений, которые соответствуют составу (реквизитам) переданных фискальных документов или структур, описанных ниже.
Дата и время возвращаются в формате ГГГГ-ММ-ДДTЧЧ:ММ:СС
Пример ответа (запрос на получение документа tickets/<documentId>)
{
"openShift": {
"code": 2,
"user": "",
"userInn": "6699009482",
"operator": "Герман Илья",
"retailPlaceAddress": "",
"dateTime": "2018-04-05T10:00:00",
"shiftNumber": 367,
"kktRegId": "0000000003065868 ",
"fiscalDriveNumber": "99990788607 ",
"fiscalDocumentNumber": 39089,
"fiscalSign": 2034496394,
"id": "00000000-0000-0000-0000-000000000000"
}
Отчет о регистрации¶
{
"fiscalReport": {
"code": 1, //number, обязательный - код документа, всегда равен 1
"user": "ООО \"Золотой пятачок\"", //string, обязательный - наименование пользователя
"userInn": "6699009482", //string, обязательный - ИНН пользователя
"taxationType": 1, //number, обязательный - системы налогообложения
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"offlineMode": 0, //number, обязательный - признак автономного режима
"bsoSign": 0, //number, обязательный - признак АС БСО
"serviceSign": 0, //number, необязательный - признак расчетов за услуги
"encryptionSign": 0, //number, обязательный - признак шифрования
"autoMode": 0, //number, обязательный - автоматический режим
"machineNumber": "1233456", //string, необязательный - номер автомата
"internetSign": 1, //number, обязательный - признак расчетов в Интернете
"fiscalDocumentNumber": 1, //number, обязательный - порядковый номер фискального документа
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"operator": "Иван Иванович", //string, обязательный - кассир
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5", //string, обязательный - адрес расчетов
"ofdInn": "6699009482", //string, обязательный - ИНН ОФД
"kktNumber": "1254893621836174", //string, необязательный - заводской номер ККТ
"fiscalSign": 0, //number, обязательный - фискальный признак документа
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип «системы налогообложения» кодируется целым числом, где первые пять бит указывают на применение перечисленных ниже систем в соответствии с таблицей:
| Номер бита | Тип системы налогообложения |
|---|---|
| 0 | Общая |
| 1 | Упрощенная Доход |
| 2 | Упрощенная Доход минус Расход |
| 3 | Единый налог на вмененный доход |
| 4 | Единый сельскохозяйственный налог |
| 5 | Патентная система налогообложения |
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя»:
{
"properties": [ //array of objects, необязательный - дополнительный реквизит пользователя
{
"key": "имя", //string, необязательный - наименование дополнительного реквизита пользователя
"value": "значение" //string, необязательный - значение дополнительного реквизита пользователя
}
]
}
«Признак автономного режима», «признак АС БСО», «признак расчетов за услуги», «признак шифрования», «автоматический режим», «признак расчетов в Интернете» включаются в состав фискальных документов с единичным значением при наличии соответствующих причин и с нулевым значением в случае отсутствия этих причин.
Отчет об изменении параметров регистрации¶
{
"fiscalReportCorrection": {
"code": 11, //number, обязательный - код документа, всегда равен 11
"user": "ООО \"Золотой пятачок\"", //string, обязательный - наименование пользователя
"userInn": "6699009482", //string, обязательный - ИНН пользователя
"taxationType": 1, //number, обязательный - системы налогообложения
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"offlineMode": 0, //number, обязательный - признак автономного режима
"bsoSign": 0, //number, обязательный - признак АС БСО
"serviceSign": 0, //number, необязательный - признак расчетов за услуги
"encryptionSign": 0, //number, обязательный - признак шифрования
"autoMode": 0, //number, обязательный - автоматический режим
"machineNumber": "1233456", //string, необязательный - номер автомата
"internetSign": 1, //number, обязательный - признак расчетов в Интернете
"fiscalDocumentNumber": 1, //number, обязательный - порядковый номер фискального документа
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"operator": "Иван Иванович", //string, обязательный - кассир
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5", //string, обязательный - адрес расчетов
"ofdInn": "6699009482", //string, обязательный - ИНН ОФД
"kktNumber": "1254893621836174", //string, необязательный - заводской номер ККТ
"fiscalSign": 0, //number, обязательный - фискальный признак документа
"correctionReasonCodes": [1], //array of numbers, обязательный, коды причин изменения сведений о ККТ
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя» и значения «системы налогообложения» аналогичны отчету о регистрации.
«Признак автономного режима», «признак АС БСО», «признак расчетов за услуги», «признак шифрования», «автоматический режим», «признак расчетов в Интернете» включаются в состав фискальных документов с единичным значением при наличии соответствующих причин и с нулевым значением в случае отсутствия этих причин.
Значения реквизита «Код причины перерегистрации»:
| Код | Причина перерегистрации |
|---|---|
| 1 | Замена ФН |
| 2 | Смена ОФД |
| 3 | Смена реквизитов пользователя |
| 4 | Смена настроек ККТ |
| 5 | Перевод ККТ в режим передачи данных |
| 6 | Перевод ККТ в автономный режим |
| 7 | Изменение версии модели ККТ |
| 8 | Смена СНО |
| 9 | Изменение номера автоматического устройства |
| 10 | Перевод ККТ из автоматического режима в неавтоматический (осуществление расчетов кассиром) |
| 11 | Перевод ККТ из неавтоматического режима (осуществление расчетов кассиром) в автоматический режим |
| 12 | Перевод ККТ в режим, позволяющий формировать БСО |
| 13 | Перевод ККТ в режим без БСО |
| 14 | Перевод ККТ из режима расчетов в сети Интернет в режим, позволяющий печатать чеки и БСО |
| 15 | Перевод ККТ из режима позволяющего печатать чеки и БСО в режим расчетов в сети Интернет |
| 16 | Перевод ККТ в режим, не позволяющий оказывать услуги платежного агента (субагента) или банковского платежного агента |
| 17 | Перевод ККТ в режим, позволяющий оказывать услуги платежного агента (субагента) или банковского платежного агента |
| 18 | Перевод ККТ в режим, не позволяющий применять ККТ при приеме ставок и выплате выигрыша (азартные игры) |
| 19 | Перевод ККТ в режим, позволяющий применять ККТ при приеме ставок и выплате выигрыша (азартные игры) |
| 20 | Перевод ККТ в режим, не позволяющий применять ККТ при приеме и выплате денежных средств (лотереи) |
| 21 | Перевод ККТ в режим, позволяющий применять ККТ при приеме и выплате денежных средств (лотереи) |
| 22 | Изменение версии ФФД |
| 23 | Изменение наименования организации |
| 24 | Изменение адреса и/или места установки ККТ |
| 32 | Иные причины |
Отчёт о текущем состоянии расчетов¶
{
"currentStateReport": {
"code": 21, //number, обязательный - код документа, всегда равен 21
"userInn": "6699009482", //string, необязательный - ИНН пользователя
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"shiftNumber": 3, //number, обязательный - номер смены
"offlineMode": 1, //number, необязательный - признак автономного режима
"notTransmittedDocumentNumber": 123, //number, обязательный - номер первого непереданного документа
"notTransmittedDocumentsQuantity": 2, //number, обязательный - кол-во непереданных ФД
"notTransmittedDocumentsDateTime": "2018-10-30T08:23:00", //string, необязательный - дата первого из непереданных ФД
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"fiscalDocumentNumber": 67, //number, обязательный - порядковый номер фискального документа
"fiscalSign": 1233453341, //number, обязательный - фискальный признак документа
"properties": [], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя» аналогичны отчету о регистрации.
«Признак автономного режима» включаются в состав фискальных документов с единичным значением при наличии соответствующих причин и с нулевым значением в случае отсутствия этих причин.
Отчет об открытии смены¶
{
"openShift": {
"code": 2, //number, обязательный - код документа, всегда равен 2
"user": "ООО \"Золотой пятачок\"", //string, обязательный - наименование пользователя
"userInn": "6699009482", //string, необязательный - ИНН пользователя
"operator": "Иван Петров", //string, обязательный - кассир
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5", //string, обязательный - адрес расчетов
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"shiftNumber": 3, //number, обязательный - номер смены
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"fiscalDocumentNumber": 34, //number, обязательный - порядковый номер фискального документа
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"message": [{}], //array of objects, необязательный - сообщение оператору
"fiscalSign": 1233453341, //number, обязательный - фискальный признак документа
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя» аналогичны отчету о регистрации.
Тип и формат реквизитов подструктуры «сообщение оператору»:
{
"message": [ //array objects, необязательный - сообщение оператору
{
"type": "", //string, обязательный - тип сообщения
"message": "" //string, обязательный - сообщение
}
],
}
Отчет о закрытии смены¶
{
"closeShift": {
"code": 5, //number, обязательный - код документа, всегда равен 5
"user": "ООО \"Золотой пятачок\"", //string, обязательный - наименование пользователя
"userInn": "6699009482", //string, необязательный - ИНН пользователя
"operator": "Иван Петров", //string, обязательный - кассир
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"shiftNumber": 3, //number, обязательный - номер смены
"receiptsQuantity": 3, //number, обязательный - количество кассовых чеков (БСО)/чеков коррекции (БСО коррекции) за смену
"documentsQuantity": 3, //number, обязательный - количество фискальных документов за смену
"notTransmittedDocumentsQuantity": 1, //number, обязательный - кол-во непереданных ФД
"notTransmittedDocumentsDateTime": "2018-10-30T09:00:00", //string, обязательный - дата первого из непереданных ФД
"ofdResponseTimeoutSign": 0, //number, обязательный - признак превышения времени ожидания ответа ОФД
"fiscalDriveReplaceRequiredSign": 0, //number, обязательный - признак необходимости срочной замены ФН
"fiscalDriveMemoryExceededSign": 1, //number, обязательный - признак заполнения памяти ФН
"fiscalDriveExhaustionSign": 1, //number, обязательный - признак исчерпания ресурса ФН
"kktRegId": "", //string, обязательный - регистрационный номер ККТ
"fiscalDocumentNumber": 34, //number, обязательный - порядковый номер фискального документа
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"fiscalSign": 3423453811, //number, обязательный - фискальный признак документа
"message": [{}], //array of objects, необязательный - сообщение оператору
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя» и «сообщение оператору» аналогичны отчету об открытии смены.
«Признак превышения времени ожидания ответа ОФД», «признак необходимости срочной замены ФН», «признак заполнения памяти ФН», «признак исчерпания ресурса ФН» включаются в состав фискальных документов с единичным значением при наличии соответствующих причин и с нулевым значением в случае отсутствия этих причин.
Кассовый чек, бланк строгой отчетности¶
{
"receipt": { //для бланка строгой отчетности - bso
"receiptCode": 3, //number, обязательный для кассового чека - код документа, всегда равен 3
"bsoCode": 4, //number, обязательный для БСО - код документа, всегда равен 4
"user": "ООО \"Золотой пятачок\"", //string, обязательный - наименование пользователя
"userInn": "6699009482", //string, обязательный - ИНН пользователя
"buyerInn": "6699000000", //string, необязательный - ИНН покупателя
"requestNumber": 45, //number, обязательный - номер чека за смену
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"shiftNumber": 8, //number, обязательный - номер смены
"operationType": 1, //number, обязательный - признак расчета
"taxationType": 1, //number, обязательный - применяемая система налогообложения
"operator": "Иван Петров", //string, обязательный - кассир
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5", //string, необязательный - адрес расчетов
"buyerAddress": "", //string, необязательный - телефон или электронный адрес покупателя
"senderAddress": "", //string, необязательный - адрес электронной почты отправителя
"addressToCheckFiscalSign": "", //string, необязательный - адрес сайта для проверки ФП
"items": [{}], //array of objects, необязательный - предметы расчета
"stornoItems": [{}], //array of objects, необязательный - сторно товара
"paymentAgentType": 1, //number, необязательный - признак агента
"paymentAgentRemuneration": "", //number, необязательный - размер вознаграждения платежного агента (субагента), в копейках
"paymentAgentPhone": "", //string, необязательный - телефон оператора по приему платежей
"paymentSubagentPhone": "", //string, необязательный - телефон платежного субагента
"operatorPhoneToReceive": "", //string, необязательный - телефон оператора по приему платежей
"operatorPhoneToTransfer": "", //string, необязательный - телефон оператора по переводу денежных средств
"bankAgentPhone": "", //string, необязательный - телефон платежного агента (субагента) и банковского платежного агента (субагента)
"bankSubagentPhone": "", //string, необязательный - телефон банковского субагента
"bankAgentOperation": "", //string, необязательный - операция банковского платежного агента (субагента)
"bankSubagentOperation": "", //string, необязательный - операция банковского субагента
"bankAgentRemuneration": 0, //number, необязательный - размер вознаграждения банковского агента (субагента)
"operatorName": "", //string, необязательный - наименование оператора по переводу денежных средств
"operatorAddress": "", //string, необязательный - адрес оператора по переводу денежных средств
"operatorInn": "", //string, необязательный - ИНН оператора по переводу денежных средств
"Modifiers": [{}], //array, необязательный - скидка/наценка
"nds20": 230, //number, необязательный - сумма НДС чека по ставке 20%, в копейках
"nds18": 100, //number, необязательный - сумма НДС чека по ставке 18%, в копейках
"nds10": 120, //number, необязательный - сумма НДС чека по ставке 10%, в копейках
"nds0": 140, //number, необязательный - сумма расчета по чеку с НДС по ставке 0%, в копейках
"ndsNo": 0, //number, необязательный - сумма расчета по чеку без НДС, в копейках
"ndsCalculated20": 120, //number, необязательный - сумма НДС чека по расч. ставке 20/120, в копейках
"ndsCalculated18": 100, //number, необязательный - сумма НДС чека по расч. ставке 18/118, в копейках
"ndsCalculated10": 120, //number, необязательный - сумма НДС чека по расч. ставке 10/110, в копейках
"totalSum": 1853, //number, обязательный - ИТОГ, в копейках
"cashTotalSum": 1853, //number, обязательный - сумма по чеку (БСО) наличными, в копейках
"ecashTotalSum": 0, //number, обязательный - сумма по чеку (БСО) безналичными, в копейках
"prePaymentTotalSum": 0, //number, необязательный - сумма по чеку (БСО) предоплатой (зачетом аванса и (или) предыдущих платежей), в копейках
"postPaymentTotalSum": 0, //number, необязательный - сумма по чеку (БСО) постоплатой (в кредит), в копейках
"considerationTotalSum": 0, //number, необязательный - сумма по чеку (БСО) встречным предоставлением, в копейках
"fiscalDocumentNumber": 544, //number, обязательный - порядковый номер фискального документа
"fiscalSign": 3423453811, //number, обязательный - фискальный признак документа
"cashReceiptProperty": "доп свойство", //string, необязательный - дополнительный реквизит чека (БСО)
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
В качестве возможных значений поля «признак расчета» могут выступать следующие:
| Значение поля | Описание |
|---|---|
| 1 | Приход |
| 2 | Возврат прихода |
| 3 | Расход |
| 4 | Возврат расхода |
«Система налогообложения» число типа byte, интерпретировать как битовую маску:
| Номер бита | Тип системы налогообложения |
|---|---|
| 0 | Общая |
| 1 | Упрощенная Доход |
| 2 | Упрощенная Доход минус Расход |
| 3 | Единый налог на вмененный доход |
| 4 | Единый сельскохозяйственный налог |
| 5 | Патентная система налогообложения |
«Признак агента» и «признак агента по предмету расчета» число типа byte, интерпретировать как битовую маску:
| Номер бита | Признак агента |
|---|---|
| 0 | Банковский платежный агент |
| 1 | Банковский платежный субагент |
| 2 | Платежный агент |
| 3 | Платежный субагент |
| 4 | Поверенный |
| 5 | Комиссионер |
| 6 | Агент |
Поля paymentAgentRemuneration - operatorInn применяются в случае применения контрольно-кассовой техники платежным агентом, платежным субагентом при осуществлении деятельности по приему платежей физических лиц в соответствии с Федеральным законом «О деятельности по приему платежей физических лиц, осуществляемой платежными агентами» и в случае законом «О деятельности по приему платежей физических лиц, осуществляемой платежными агентами» и в случае применения контрольно-кассовой техники банковским платежным агентом, банковским платежным субагентом при осуществлении деятельности в соответствии с Федеральным законом «О национальной платежной системе».
PaymentAgentRemuneration, paymentSubagentPhone, operatorPhoneToReceive, bankSubagentPhone, bankSubagentOperation, bankAgentRemuneration есть только в формате фискальных данных 1.0.
Примечание
В чеке допускается передача несколько ставок НДС, начисленные на позиции в чеке. В позиции допускается передать только одной ставки.
Тип и формат реквизитов подструктур items и stornoItems приведены ниже:
{
"items": [ //array of objects, необязательный - предметы расчета
{
"name": "Горошек вкусный", //string, обязательный - наименование товара
"barcode": "", //string, необязательный - штриховой код EAN13
"price": 9845, //number, обязательный - цена за единицу предмета расчета с учетом скидок и наценок, в копейках
"quantity": 1, //number, обязательный - количество
"paymentMode": 3, //number, необязательный - признак способа расчета
"paymentSubject": 3, //number, необязательный - признак предмета расчета
"modifiers": [{}], //array of objects, необязательный - скидка/наценка
"ndsCalculated20": 130, //number, необязательный - сумма НДС чека по расч. ставке 20/120, в копейках
"ndsCalculated18": 100, //number, необязательный - сумма НДС чека по расч. ставке 18/118, в копейках
"ndsCalculated10": 120, //number, необязательный - сумма НДС чека по расч. ставке 10/110, в копейках
"nds20": 230, //number, необязательный - сумма НДС чека по ставке 20%, в копейках
"nds18": 100, //number, необязательный - сумма НДС чека по ставке 18%, в копейках
"nds10": 120, //number, необязательный - сумма НДС чека по ставке 10%, в копейках
"nds0": 140, //number, необязательный - сумма расчета по чеку с НДС по ставке 0%, в копейках
"ndsNo": 0, //number, необязательный - сумма расчета по чеку без НДС, в копейках
"sum": 9845, //number, обязательный - стоимость предмета расчета с учетом скидок и наценок, в копейках
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"paymentAgentByProductType": 1, //number, необязательный - признак агента по предмету расчета
"additionalProperty": "" //string, необязательный - дополнительный реквизит предмета расчета
}
]
}
Ставка скидки или наценки передаются в процентах (12.5 - это 12,5% или в долях - 0,125 от первоначальной суммы).
Возможные значения поля «способ расчета»:
| Значение поля | Описание |
|---|---|
| 0 | Предоплата 100% |
| 1 | Предоплата |
| 2 | Аванс |
| 3 | Полный расчет |
| 4 | Частичный расчет и кредит |
| 5 | Передача в кредит |
| 6 | Оплата кредита |
Возможные значения поля «признак предмета расчета»:
| Значение поля | Описание |
|---|---|
| 0 | Товар |
| 1 | Подакцизный товар |
| 2 | Работа |
| 3 | Услуга |
| 4 | Ставка игры |
| 5 | Выигрыш |
| 6 | Лотерейный билет |
| 7 | Выигрыш лотереи |
| 8 | РИД |
| 9 | Платеж |
| 10 | Агентское вознаграждение |
| 11 | Выплата |
| 12 | Иной предмет расчета |
| 13 | Имущественное право |
| 14 | Внереализационный доход |
| 15 | Иные платежи и взносы |
| 16 | Торговый сбор |
| 17 | Курортный сбор |
| 18 | Залог |
| 19 | Расход |
| 20 | Взносы на ОПС ИП |
| 21 | Взносы на ОПС |
| 22 | Взносы на ОМС ИП |
| 23 | Взносы на ОМС |
| 24 | Взносы на ОСС |
| 25 | Платеж казино |
Тип и формат реквизитов подструктур «скидки/наценки» приведены ниже. Ставка налога передается в виде процента. Есть только в формате фискальных данных 1.0.
{
"modifiers": [ //array of objects, необязательный - скидка/наценка
{
"discountName": "Акция", //string, необязательный - наименование скидки
"markupName": , //string, необязательный - наименование наценки
"discount": 12.5, //number, необязательный - скидка (ставка)
"markup": 5.43, //number, необязательный - наценка (ставка)
"discountSum": 4563, //number, необязательный - скидка (сумма), в копейках
"markupSum": 2.34 //number, необязательный - наценка (сумма), в копейках
}
]
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя»:
{
"properties": [ //array of objects, необязательный - дополнительный реквизит пользователя
{
"key": "имя", //string, необязательный - наименование дополнительного реквизита пользователя
"value": "значение" //string, необязательный - значение дополнительного реквизита пользователя
}
]
}
Кассовый чек коррекции, бланк строгой отчетности коррекции¶
{
"receiptCorrection": { //для бланка строгой отчетности - bsoCorrection
"receiptCode": 31, //number, обязательный для кассового чека - код документа, всегда равен 31
"bsoCode": 41, //number, обязательный для БСО - код документа, всегда равен 41
"user": "ООО \"Золотой пятачок\"", //string, необязательный - наименование пользователя
"userInn": "6699009482", //string, необязательный - ИНН пользователя
"buyerInn": "6699000000", //string, необязательный - ИНН покупателя
"requestNumber": 45, //number, обязательный - номер чека за смену
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"shiftNumber": 8, //number, обязательный - номер смены
"operationType": 1, //number, обязательный - признак расчета
"taxationType": 1, //number, обязательный - применяемая система налогообложения
"operator": "Иван Петров", //string, обязательный - кассир
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"items": [{}], //array of objects, необязательный - предметы расчета
"nds18": 0, //number, необязательный - сумма НДС чека по ставке 18%
"nds20": 0, //number, необязательный - сумма НДС чека по ставке 20%
"nds10": 0, //number, необязательный - сумма НДС чека по ставке 10%
"nds0": 0, //number, необязательный - сумма расчета по чеку с НДС по ставке 0%
"ndsNo": 0, //number, необязательный - сумма расчета по чеку без НДС
"ndsCalculated18": 0, //number, необязательный - сумма НДС чека по расч. ставке 20/120
"ndsCalculated20": 0, //number, необязательный - сумма НДС чека по расч. ставке 18/118
"ndsCalculated10": 0, //number, необязательный - сумма НДС чека по расч. ставке 10/110
"totalSum": 1853, //number, обязательный - ИТОГ, в копейках
"cashTotalSum": 1853, //number, обязательный - сумма по чеку (БСО) наличными, в копейках
"ecashTotalSum": 0, //number, обязательный - сумма по чеку (БСО) безналичными, в копейках
"prePaymentTotalSum": 0, //number, необязательный - сумма по чеку (БСО) предоплатой (зачетом аванса и (или) предыдущих платежей)
"postPaymentTotalSum": 0, //number, необязательный - сумма по чеку (БСО) постоплатой (в кредит)
"considerationTotalSum": 0, //number, необязательный - сумма по чеку (БСО) встречным предоставлением
"fiscalDocumentNumber": 544, //number, обязательный - порядковый номер фискального документа
"fiscalSign": 3423453811, //number, обязательный - фискальный признак документа
"cashReceiptProperty": "доп свойство", //string, необязательный - дополнительный реквизит чека
"properties": [{}], //array of objects, необязательный - дополнительный реквизит пользователя
"paymentAgentType": 1, //number, необязательный - признак агента
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Описание «признак расчета», «систем налогообложения», «предмет расчета», «признак предмета расчета», «способ расчета», «скидки/наценки», «дополнительный реквизит пользователя», «признак агента» и «признак агента по предмету расчета» аналогичны чеку.
Отчет о закрытии фискального накопителя¶
{
"closeArchive": {
"code": 6, //number, обязательный - код документа, всегда равен 6
"userInn": "6699009482", //string, необязательный - ИНН пользователя
"retailPlaceAddress": "г. Екатеринбург. ул. Малопрудная 5", //string, обязательный - адрес расчетов
"operator": "Иван Петров", //string, обязательный - кассир
"dateTime": "2018-10-30T10:00:00", //string, обязательный - дата, время
"kktRegId": "0000000003065864 ", //string, обязательный - регистрационный номер ККТ
"fiscalDocumentNumber": 34, //number, обязательный - порядковый номер фискального документа
"fiscalDriveNumber": "99990788603", //string, обязательный - заводской номер фискального накопителя
"fiscalSign": 3423453811, //number, обязательный - фискальный признак документа
"properties":[{}], //array of objects, необязательный - дополнительный реквизит пользователя
"id": "00000000-0000-0000-0000-000000000000" //string, обязательный - идентификатор документа
}
}
Тип и формат реквизитов подструктуры «дополнительный реквизит пользователя» аналогичны отчету о регистрации.
Преобразование сертификатов¶
Для конвертации пользовательского сертификата в формат PEM:
- Откройте сертификат для просмотра (например, средствами Windows) – вкладка «Состав» – «Копировать в файл» – при сохранении выберите кодировку «Base-64»,
- либо воспользуйтесь утилитой
certutilиз набора «Certificate Services», указав имена файлов сертификата до и после конвертации:certutil.exe -encode input_certificate_file output_certificate_file
Сертификат в Base-64:
-----BEGIN CERTIFICATE-----
MIIJTzCCCP6gAwIBAgIKLUfNEQAAAAKeZjAIBgYqhQMCAg
.......
ig6Wya0ui9H9fTASUKfeJoOHE6u01whF06AZ3YrAMkluO1E=
-----END CERTIFICATE-----
Вопросы по работе API, а также пожелания по доработкам направляйте на ofd@kontur.ru.