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>