Uzum Fiscalization API

openapi: 3.2.0
info:
  title: Uzum Fiscalization API
  version: 0.0.2
  description: '**Uzum Fiscalization** is a service for fiscalizing receipts and submitting them to the Uzbekistan tax authority via API.'
tags:
- name: Fiscalization
  description: In this section, the API provides methods for working with fiscal receipts.
paths:
  /v2/receipt:
    post:
      tags:
      - Fiscalization
      summary: /v2/receipt
      description: The direct receipt fiscalization method is intended for registering sales transactions in the GNK system.
      parameters:
      - in: header
        name: X-API-Key
        required: true
        schema:
          type: string
        description: Unique API key. We assign and provide this key to each partner.
      operationId: fiscal_receipt_generation_fiscal_receipt_generation_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiptData'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptGenerationResponse'
        '202':
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '403':
          description: Auth error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /v2/refund_receipt:
    post:
      tags:
      - Fiscalization
      summary: /v2/refund_receipt
      description: 'The refund receipt fiscalization method is intended for registering returns in the GNK system.


        For fiscalization of a refund receipt, the following conditions must be met:

        - The `paymentId` of the refund receipt must equal the `paymentId` of the sales receipt.

        - The sales receipt must have been previously fiscalized.'
      parameters:
      - in: header
        name: X-API-Key
        required: true
        schema:
          type: string
        description: Unique API key. We assign and provide this key to each partner.
      operationId: fiscal_receipt_refund_fiscal_receipt_refund_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundData'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptRefundResponse'
        '202':
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRefundRequestResponse'
        '403':
          description: Auth error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '404':
          description: Reciept not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundByPaymentIdResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /v2/receipt/{operation_id}/receipt_url:
    get:
      summary: /v2/receipt/{operation_id}/receipt_url
      description: The method for obtaining a link to the fiscal receipt after its fiscalization.
      parameters:
      - in: path
        name: operation_id
        required: true
        schema:
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
        description: Unique operation identifier.
      - in: header
        name: X-API-Key
        required: true
        schema:
          type: string
        description: Unique API key. We assign and provide this key to each partner.
      operationId: get_receipt_url
      tags:
      - Fiscalization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReceiptURLResponse'
        '202':
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingForReceiptURLResponse'
        '400':
          description: There is no URL for prepaid/credit receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoURLForPrepaidCreditReceipt'
        '403':
          description: Auth error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '404':
          description: Reciept not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundByPAOResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
components:
  schemas:
    InternalServerErrorResponse:
      title: Internal Server Error
      required:
      - message
      type: object
      properties:
        message:
          type: string
          example: Server encountered an unexpected condition that prevented it from fulfilling the request. Please, contact support
    AuthErrorResponse:
      title: AuthErrorResponse
      type: object
      properties:
        message:
          title: Operation Id
          type: string
          format: string
          description: "Available Values:\n * Multiple auth headers are defined\n * Auth header is not defined\n * User is not found\n"
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
    RequestAccepted:
      title: Request Accepted
      required:
      - message
      - code
      type: object
      properties:
        payment_id:
          title: Payment Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique payment identifier in the electronic payment system. Returned if the `payment_id` is not provided in the fiscalization request.
        code:
          title: Code
          type: integer
          description: "Possible values\n * 0 - Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * 1 - Error occurred in communications with ofd.soliq.uz. We will retry it later. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * 2 - Didn't fiscalized receipt yet. We're in process of retrying it. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n"
        message:
          title: Message
          type: string
          description: "Possible values\n * Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * Error occurred in communications with ofd.soliq.uz. We will retry it later. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * Didn't fiscalized receipt yet. We're in process of retrying it. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n"
          example: Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks
    RefundData:
      title: RefundData
      required:
      - payment_id
      - operation_id
      - cash_amount
      - card_amount
      - date_time
      - items
      type: object
      properties:
        payment_id:
          title: Payment Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique payment identifier.
        operation_id:
          title: Operation Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique operation identifier.
        cash_amount:
          title: Cash Amount
          type: integer
          minimum: 0
          description: Amount of cash refund in tiyns before discount. Tiyn is the fractional monetary unit equal to 1/100 of the Uzbek som. Accordingly, if the cash refund amount is 1,000 som, you need to pass the value of 100,000 tiyns (1,000 * 100).
        card_amount:
          title: Card Amount
          type: integer
          minimum: 0
          description: Amount of card refund in tiyns before discount. Tiyn is the fractional monetary unit equal to 1/100 of the Uzbek som. Accordingly, if the card refund amount is 1,000 som, you need to pass the value of 100,000 tiyns (1,000 * 100).
        date_time:
          title: Date Time
          type: string
          description: 'Date and time should be specified in ISO 8601 format. If the time zone is not specified, the service will interpret them according to the time of Tashkent city. Specify the date and time within 24 hours after receiving confirmation of the successful payment.

            '
          format: date-time
        ppt_id:
          title: PPT ID
          type: string
          description: Unique transaction identifier assigned by the payment processing center.
        card_type:
          title: Card Type
          description: "Type of card used for the transaction:\n* `1` – Corporate card  \n* `2` – Personal card\n"
          type: integer
          enum:
          - 1
          - 2
        items:
          title: Items
          type: array
          items:
            $ref: '#/components/schemas/ReceiptDataItem'
          description: List of items to be returned.
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    NotFoundByPAOResponse:
      title: Reciept not found by PAO
      required:
      - message
      type: object
      properties:
        message:
          title: message
          type: string
          example: Receipt with {payment id} payment id and {operation id} operation id was not found
    ReceiptRefundResponse:
      title: RefundReceiptGenerationResponse
      type: object
      required:
      - receipt_url
      - receipt_id
      properties:
        receipt_id:
          title: Receipt Id
          type: integer
          example: 209726
          description: Receipt number in the tax committee (GNC).
        receipt_url:
          title: Receipt URL
          type: string
          example: https://ofd.soliq.uz/epi?t=EZ000000000296&r=51&c=20230807182725&s=176112857133
          description: Link to the receipt; not provided in the case of advance or credit receipts.
    ReceiptGenerationResponse:
      title: ReceiptGenerationResponse
      type: object
      required:
      - payment_id
      - receipt_id
      properties:
        receipt_id:
          title: Receipt Id
          type: integer
          example: 209726
          description: Receipt number in the tax committee (GNC).
        payment_id:
          title: Payment Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique payment identifier in the electronic payment system. It is generated on our side if `payment_id` is not specified in the fiscalization request.
        receipt_url:
          title: Receipt URL
          type: string
          example: https://ofd.soliq.uz/epi?t=EZ000000000296&r=51&c=20230807182725&s=176112857133
          description: Link to the receipt; not provided in the case of advance or credit receipts.
    NotFoundByPaymentIdResponse:
      title: Reciept not found by PaymentId
      required:
      - message
      type: object
      properties:
        message:
          title: message
          type: string
          example: Receipt with {payment id} payment id was not found
    BadRequestResponse:
      title: Bad Request
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          enum:
          - 1
          - 2
          description: "Sort order:\n * 1 - Invalid spic/package code. Please check values and resend request\n * 2 - Receipt with the same payment_id and receipt_type was already send. Please check values and resend request\n"
        message:
          type: string
          example: Invalid spic/package code. Please check values and resend request
    ReceiptDataItem:
      title: ReceiptDataItem
      required:
      - product_name
      - price
      - count
      - spic
      - package_code
      - vat_percent
      type: object
      properties:
        product_name:
          title: Product Name
          type: string
          description: Name of the product or service.
          maxLength: 63
        price:
          title: Price
          type: integer
          minimum: 0
          description: The cost of the product in tyiyn. Tyiyn is the subunit of the Uzbek sum, equal to 1/100 of a sum. Accordingly, if the cost of the product is 1,000 sum, you should send the value of 100,000 tyiyn (1,000 * 100).
        discount:
          title: Discount
          type: integer
          minimum: 0
          description: The total discount amount for all units of this product in the cart, expressed in tyiyn. Tyiyn is the subunit of the Uzbek sum, equal to 1/100 of a sum. Accordingly, if the discount amount is 1,000 sum, you should send the value of 100,000 tyiyn (1,000 * 100).
        voucher:
          title: Voucher
          type: integer
          minimum: 0
          description: The total marketplace discount amount, calculated based on the number of products and expressed in tyiyn. This discount does not reduce the total check amount, but it is not charged to the customer during the checkout payment. Tyiyn is the subunit of the Uzbek sum, equal to 1/100 of a sum. Accordingly, if the discount amount is 1,000 sum, you should send the value of 100,000 tyiyn (1,000 * 100).
        count:
          title: Count
          type: number
          mininum: 0
          format: double
          example: 1.998
          description: The quantity of the product in the order.
        spic:
          title: Spic
          type: string
          description: IKPU code.
        package_code:
          title: Package Code
          type: string
          description: Packaging code.
          minLength: 0
          maxLength: 20
        vat_percent:
          title: Vat Percent
          type: integer
          minimum: 0
          description: VAT rate in % for this item.
        commission_info:
          title: Commission Info
          allOf:
          - $ref: '#/components/schemas/ReceiptDataCommissionInfo'
          description: Payer data.
        owner_type:
          title: Owner Type
          type: integer
          description: 'Product/Service owner type: * 0 - Resale * 1 - In-house production * 2 - Service

            '
          enum:
          - 0
          - 1
          - 2
    GetReceiptURLResponse:
      required:
      - receipt_url
      title: GetReceiptURLResponse
      type: object
      properties:
        receipt_url:
          title: Receipt Url
          type: string
    ReceiptDataCommissionInfo:
      title: ReceiptDataCommissionInfo
      type: object
      properties:
        TIN:
          title: Tin
          type: string
          description: Taxpayer Identification Number (TIN) of the principal. It is mandatory if PINF is not provided. Simultaneous filling of both TIN and PINF is not allowed.
        PINFL:
          title: Pinfl
          maxLength: 14
          minLength: 14
          type: string
          description: PINF of the principal. It is mandatory if TIN is not provided. Simultaneous filling of both PINF and TIN is not allowed.
    ReceiptData:
      title: ReceiptData
      required:
      - operation_id
      - date_time
      - cash_amount
      - card_amount
      - items
      type: object
      properties:
        payment_id:
          title: Payment Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique payment identifier. When using the Uzum checkout, this identifier corresponds to the `order_id`. In the case of cash payments, the transfer of the identifier is not required; the `payment_id` will be automatically assigned by our system.
        operation_id:
          title: Operation Id
          type: string
          format: uuid
          example: 61e057d9-b737-42fa-ae33-614a284a5a92
          description: Unique transaction identifier that you must generate in your system.
        date_time:
          title: Date Time
          type: string
          description: 'The date and time should be provided in ISO 8601 format. If the time zone is not specified, the service will interpret them according to Tashkent time. The date and time should be within 24 hours after receiving confirmation of successful payment.


            Time zone of Tashkent: "2023-11-01T14:00:00+05:00".

            Without specifying the time zone: "2023-11-01T14:00:00".

            Coordinated Universal Time: "2023-11-01T09:00:00Z".

            '
          format: date-time
          example: '2023-08-07T20:00:35+05:00'
        cash_amount:
          title: Cash Amount
          type: integer
          minimum: 0
          description: The cash payment amount in tyiins before any discounts are applied. A tyiin is the fractional monetary unit, equal to 1/100 of an Uzbek sum. Therefore, if the cash payment amount is 1,000 sums, the value to be transmitted should be 100,000 tyiins (1,000 * 100).
        card_amount:
          title: Card Amount
          type: integer
          minimum: 0
          description: The card payment amount in tyiins before any discounts are applied. A tyiin is the fractional monetary unit, equal to 1/100 of an Uzbek sum. Therefore, if the card payment amount is 1,000 sums, the value to be transmitted should be 100,000 tyiins (1,000 * 100).
        phone_number:
          title: Phone Number
          type: string
          maxLength: 12
          example: 998991234567
          description: 'The customer''s phone number in international format, for example, `''998940202903''`.


            It is allowed to use numbers from Russia and Kazakhstan, such as `''79991116921''`. If there is no phone number or if a number from Russia or Kazakhstan is used, cashback will not be credited.

            '
        ppt_id:
          title: PPT ID
          type: string
          description: Unique transaction identifier assigned by the payment processing center.
        card_type:
          title: Card Type
          description: "Type of card used for the transaction:\n* `1` – Corporate card  \n* `2` – Personal card\n"
          type: integer
          enum:
          - 1
          - 2
        receipt_type:
          title: Receipt Type
          default: 0
          description: "Receipt type:\n  * 0 - Sale\n  * 1 - Advance\n  * 2 - Credit\n"
          type: integer
          enum:
          - 0
          - 1
          - 2
        items:
          title: Items
          type: array
          items:
            $ref: '#/components/schemas/ReceiptDataItem'
          description: Detailed list of products or services included in the customer's cart.
    WaitingForReceiptURLResponse:
      title: Waiting For Receipt URL Response
      required:
      - message
      type: object
      properties:
        message:
          title: message
          type: string
          example: Your request was accepted, but receipt still not has been fiscalized. Retry later, please
    BadRefundRequestResponse:
      title: Bad Refund Request
      required:
      - message
      type: object
      properties:
        message:
          type: string
          example: Refund is unavailable due to expiration
    RefundAccepted:
      title: Refund Request Accepted
      required:
      - message
      - code
      type: object
      properties:
        code:
          title: Code
          type: integer
          description: "Possible values\n * 0 - Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * 1 - Error occurred in communications with ofd.soliq.uz. We will retry it later. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * 2 - Didn't fiscalized receipt yet. We're in process of retrying it. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n"
        message:
          title: Message
          type: string
          description: "Possible values\n * Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * Error occurred in communications with ofd.soliq.uz. We will retry it later. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n * Didn't fiscalized receipt yet. We're in process of retrying it. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks\n"
          example: Didn't receive a timely response from an ofd.soliq.uz server. Your request was accepted and receipt receipt will be fiscalized as soon as ofd.soliq.uz is available. You can either retry request later, call /v2/receipt_url/{operation_id} method or subscribe to callbacks
    NoURLForPrepaidCreditReceipt:
      title: No URL For Prepaid/Credit Receipt
      required:
      - message
      type: object
      properties:
        message:
          title: message
          type: string
          example: URL for prepaid/credit receipt does not exists
x-tagGroups:
- name: API
  description: hi
  tags:
  - Check Service Status
  - Fiscalization
  - Submit QR Code Payment Receipt to Tax Authorities
- name: Testing
  tags:
  - Testing
- name: Additional information
  tags:
  - Updates