openapi: 3.0.0
servers:
info:
  description: Proposed API for receipt generation
  version: "1"
  title: General fiscalisation api used by Rentel app
  contact:
    email: nfc@rentel.me
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  /receipt:
    post:
      summary: creates a receipt
      operationId: createReceipt
      description: A request for new receipt
      responses:
        '200':
          description: Чек успешно передан в систему
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseSuccess'
        '400':
          description: Ошибка при передаче чека
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody400'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                Request:
                  $ref: '#/components/schemas/Request'
        description: Receipt to add
components:
  schemas:
    Request:
      type: object
      required:
        - Inn
        - Type
      properties:
        Inn:
          type: string
          format: integer
          example: "0123456789"
          description: ИНН компании (Тег 1018)
        Type:
          type: string
          enum: [Income, IncomeReturn, IncomePrepayment, IncomeReturnPrepayment, IncomeCorrection, BuyCorrection, IncomeReturnCorrection, ExpenseReturnCorrection, Expense, ExpenseReturn]
          example: Income
          description: 'Тип формируемого фискального документа (чек). (Тег 1054) Тип может принимать следующие значения:
          – «Income» — получение денежных средств от покупателя;
          – «IncomeReturn» — возврат денежных средств, полученных от покупателя;
          – «IncomePrepayment» — авансовый платеж от покупателя;
          – «IncomeReturnPrepayment» — возврат аванса;
          – «IncomeCorrection» — чек коррекции/приход;
          – «BuyCorrection» — чек коррекции/расход;
          – «IncomeReturnCorrection» - чек коррекции/Возврат прихода;
          – «ExpenseReturnCorrection» - чек коррекции/Возврат расхода;
          – «Expense» — выдача денежных средств покупателю;
          – «ExpenseReturn» — возврат денежных средств, выданных покупателю.'
        InvoiceId:
          type: string
          format: uuid
          example: 6f000fee-bbac-4444-bda1-e9ce9999fcc7
          description: 'Идентификатор, присвоенный вашей информационной системой в запросе на формирование кассового чека.
            Использование идентификатора предотвращает формирование дублей чеков
            Важно! Изменяйте идентификатор для перепробития неуспешных чеков («StatusCode»: 3)'
        CallbackUrl:
          type: string
          format: url
          example: 'http://testcallbackurl:12345'
          description: 'URL-адрес. В параметре указывается значение URL-адреса. Если поле заполнено корректно, то после обработки документа (успешной или неуспешной фискализации в ККТ: статус «CONFIRMED» или «KKT_ERROR»), ответ будет отправлен POST запросом по URL указанному в данном поле.'
        CustomerReceipt:
          $ref: '#/components/schemas/CustomerReceipt'
        Items:
          description: Товарные позиции, приобретаемые клиентом (Тег 1059)
          type: array
          items:
            $ref: '#/components/schemas/Item'
        PaymentItems:
          description: Суммы по типам оплат. Если null, то вся оплата наличными.
          type: array
          items:
            $ref: '#/components/schemas/PaymentItem'
    Item:
      description: Тег 1059
      type: object
      required:
        - Amount
      properties:
        Label:
          description: 'Описание товара или услуги. Если параметр «PaymentMethod» имеет значение равное 3 – аванс, тогда параметр Label может быть не включен в состав запроса. (Тег 1030)'
          type: string
          example: Оплата услуг по страхованию.
        Price:
          description: Цена товарной позиции в рублях (Тег 1079).
          type: number
          example: 5555.55
        Quantity:
          description: Количество товара в товарной позиции (Тег 1023). Возможно дробное число.
          type: number
          example: 1.0
        Amount:
          description: Общая стоимость товарной позиции. Равно «Price» * «Quantity» (Тег 1043).
          type: number
          example: 5555.55
        Vat:
          description: 'Ставка налога. Вид вычисляемого НДС (Тег 1199). Параметр может принимать следующие значения:
            - «Vat10» — налог на добавленную стоимость (НДС) 10%;
            - «Vat18» — НДС 18%;
            - «Vat20» — НДС 20% 24);
            - «Vat0» — НДС 0%;
            - «VatNo» — НДС не облагается;
            - «CalculatedVat10110» — вычисленный НДС 10% от 110% суммы;
            - «CalculatedVat18118» — вычисленный НДС 18% от 118% суммы;
            - «CalculatedVat20120» — вычисленный НДС 20% от 120% суммы25).'
          type: string
          enum: [Vat10, Vat18, Vat20, Vat0, VatNo CalculatedVat10110, CalculatedVat18118, CalculatedVat20120]
          example: Vat20
        MarkingCodeData:
          $ref: '#/components/schemas/MarkingCodeData'
        Measure:
          description: 'Единицы измерения количества предмета (Тег 2108)'
          type: string
          enum: [PIECE, GRAM, KILOGRAM, TON, CENTIMETER, DECIMETER, METER, SQUARE_CENTIMETER, SQUARE_DECIMETER, SQUARE_METER, MILLILITER, LITER, CUBIC_METER, KILOWATT_HOUR, GIGACALORIE, DAY, HOUR, MINUTE, SECOND, KILOBYTE, MEGABYTE, GIGABYTE, TERABYTE, OTHER]
          example: PIECE
        PaymentMethod:
          description: 'Признак способа расчета (Тег 1214) 
          - 1 — предоплата 100%;
          - 2 — предоплата;
          - 3 — аванс;
          - 4 — полный расчет;
          - 5 — частичный расчет;
          - 6 — передача в кредит;
          - 7 — оплата в кредит.'
          type: integer
          enum: [1,2,3,4,5,6,7]
          example: 1
        PaymentType: 
          description: 'Признак предмета расчета для конкретной позиции в чеке. (тег 1212) Если значение отсутствует, берется значение для всего чека. '
          type: integer
          enum: [1, 2, 3, 4]
          nullable: true
          example: 1

    CustomerReceipt:
      type: object
      required:
        - TaxationSystem
        - PaymentType
        - BillAddress
      properties:
        CheckMcMode:
          description: Параметр проверки кода маркировки
          type: string
          nullable: true
          example: null
          enum: [IGNORE_ANY_ERRORS, REQUIRE_NO_M_MINUS]
        TaxationSystem:
          description: 'Система налогообложения.(Тег 1055)'
          type: string
          enum: [Common, SimpleIn, SimpleInOut, Unified, UnifiedAgricultural, Patent]
          example: Common
        Email:
          type: string
          example: 'example@ya.ru'
          description: Адрес электронной почты клиента
        Phone:
          type: string
          example: '+79000000001'
          description: Контактный телефон клиента
        AutomaticDeviceNumber:
          description: Номер автоматического устройства  (Тег 1036)
          type: string
          nullable: true
          example: '46204'
        BillAddress:
          description: Место осуществления расчетов  (Тег 1187)
          type: string
          nullable: true
        PaymentType: 
          type: integer
          enum: [1, 2, 3, 4]
          example: 1
          description: 'Признак предмета расчета для всего чека. Важно! Если в данном поле значение клиентом не указано, то используется значение по умолчанию, которое устанавливается по умолчанию при заведении учетной записи в информационной системе. 1 - «ТОВАР»  2 — «ПОДАКЦИЗНЫЙ ТОВАР» 3 —  «РАБОТА», 4 – «УСЛУГА»'
        CustomUserProperty:
          $ref: '#/components/schemas/CustomUserProperty'
        PaymentAgentInfo:
          $ref: '#/components/schemas/PaymentAgentInfo'
        CorrectionInfo:
          $ref: '#/components/schemas/CorrectionInfo'
    CustomUserProperty:
      type: object
      nullable: true
      properties:
        Name:
          type: string
          description: Наименование дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты (Тег 1085)
          example: CustomUserPropertyName
        Value:
          type: string
          description: Значение дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты (Тег 1086)
          example: CustomUserPropertyValue
    MarkingCodeData:
      description: Код маркировки товарной позиции (Тег 1163).
      type: object
      nullable: true
      properties:
        Type:
          description: Формат КМ
          type: string
          enum: [UNKNOWN_PRODUCT_CODE, EAN8, EAN13, ITF14, GS1, GS1M, SHORT_MC, FUR, EGAIS20, EGAIS30, KTF1, KTF2, KTF3, KTF4, KTF5, KTF6]
          example: UNKNOWN_PRODUCT_CODE
        Code:
          description: Код маркировки.Передается значение, полученное сканером штрих-кода
          type: string
          example: "0003574EA75F63675258464D5939504837435A5057"
        PlannedStatus:
          description: 'Планируемый статус товара с КМ (Тег 2003).Может принимать следующие значения:
            - PIECE_PRODUCT_INCOME — Штучный товар, подлежащий обязательной маркировке средством идентификации, реализован;
            - MEASURED_PRODUCT_INCOME — Мерный товар, подлежащий обязательной маркировке средством идентификации, в стадии реализации;
            - PIECE_PRODUCT_RETURN — Штучный товар, подлежащий обязательной маркировке средством идентификации, возвращен;
            - MEASURED_PRODUCT_RETURN — Часть товара, подлежащего обязательной маркировке средством идентификации, возвращена;
            - PRODUCT_STATUS_NOT_CHANGED — Статус товара, подлежащего обязательной маркировке средством идентификации, не изменился.'
          type: string
          enum: [PIECE_PRODUCT_INCOME, MEASURED_PRODUCT_INCOME, PIECE_PRODUCT_RETURN, MEASURED_PRODUCT_RETURN, PRODUCT_STATUS_NOT_CHANGED]
          example: PIECE_PRODUCT_INCOME
        Fractional:
          $ref: '#/components/schemas/Fractional'
    Fractional:
      description: Дробное количество маркированного товара  (Тег 1291)
      type: object
      required:
        - Numerator
        - Denominator
      properties:
        Numerator:
          description: Числитель (Тег 1293). Значение должно быть строго меньше знаменателя (Denominator).
          type: number
          example: 1
        Denominator:
          description: Знаменатель (Тег 1294).
          type: number
          example: 1
    PaymentItem:
      description: Сумма по типам оплат
      properties:
        PaymentType:
          description: 'Тип оплаты:
          0 – наличными (Тег 1031);
          1 – безналичными (Тег 1081);
          2 – предварительная оплата (аванс) (Тег 1215);
          3 – предварительная оплата (кредит) (Тег 1216);
          4 – иная форма оплаты (Тег 1217).'
          type: integer
          enum: [0, 1, 2, 3, 4]
          example: 1
        Sum:
          description: Сумма по типу (Тег 1020)
          type: number
          example: 5555.55
    PaymentAgentInfo:
      description: Данные платежного агента (Тег 1223)
      nullable: true
      properties:
        AgentType:
          description: Тип (признак) платежного агента (Тег 1057) BANK_PAYMENT_AGENT — банковский платежный агент;
            BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
            PAYMENT_AGENT — платежный агент;
            PAYMENT_SUBAGENT — платежный субагент;
            CONFIDANT — поверенный;
            COMMISSIONER — комиссионер;
            AGENT — агент.'
          type: string
          enum: [BANK_PAYMENT_AGENT, BANK_PAYMENT_SUBAGENT, PAYMENT_AGENT, PAYMENT_SUBAGENT, CONFIDANT, COMMISSIONER, AGENT]
          example: 'AGENT'
        TransferAgentPhone:
          description: Телефон оператора по переводу денежных средств (Тег 1057)
          type: string
          example: '+79091234567'
        TransferAgentName:
          description: Имя агента (Тег 1026)
          type: string
          example: 'ПАО Сбербанк'
        TransferAgentAddress:
          description: Адрес агента  (Тег 1005)
          type: string
          example: 'г. Москва, проспект Мира 7'        
        TransferAgentINN: 
          description: ИНН агента  (Тег 1016)
          type: string
          example: '5047063977'
        PaymentAgentOperation:
          description: Операция платежного агента (Тег 1044)
          type: string
          example: 'Оплата по лицевому счету'
        PaymentAgentPhone:
          description: Телефон платежного агента  (Тег 1073)
          type: string
          example: '+79000000008'
        ReceiverPhone:
          description: Телефон потребителя (Тег 1074)
          type: string
          example: '+79000000009'
        SupplierInn: 
          description: ИНН поставщика (Тег 1226)
          type: string
          example: '1739815479'
        SupplierName:
          description: Наименование поставщика (Тег 1225)
          type: string
          example: 'ООО «Фототехника»'
        SupplierPhone:
          description: Телефон поставщика (Тег 1171)
          type: string
          example: '+74959613422'
    CorrectionInfo:
      description: 'Структура, описывает информацию по чеку коррекции.
        Внимание! Структура присутствует в данных только в случае генерации чека коррекции. Для генерации обычного чека данная структура не нужна.  (Тег 1174)'
      nullable: true
      example: null
      required:
        - Type
        - Description
      properties:
        Type:
          description: 'Тип коррекции:
            SELF — коррекция производится самостоятельно;
            INSTRUCTION — коррекция производится по предписанию  (Тег 1173)'
          type: string
          enum: [SELF, INSTRUCTION]
          example: SELF            
        Description:
          description: Описание коррекции и причин коррекции
          type: string
          example: 'Ошибочный чек'
        ReceiptDate:
          description: 'Дата пробития чека, к которому применяется чек коррекции. В формате «ДД.ММ.ГГ»'
          type: string
          example: '19.01.22'
        ReceiptId:
          description: 'Номер предписания налогового органа или номер корректируемого чека (Тег 1179)'
          type: string
          example: '5644062179'
    ResponseSuccess:
      properties:
        Status:
          description: Состояние обработки запроса
          type: string
          enum: [Success]
          example: Success
        Data:
          description: Сопутствующие данные
          type: object
    ResponseBody400:
      properties:
        Status:
          type: string
          enum: [Failed]
          example: Failed
          description: Состояние обработки запроса
        Data:
          description: Сопутствующие данные
          properties:
            Error:
              type: object
              properties:
                Code:
                  description: код ошибки всегда отличен от 0
                  type: integer
                  example: 1
                Message:
                  type: string
                  example: Неизвестная ошибка при передаче чека в систему