Uzum Nasiya Partner API

openapi: 3.0.3
info:
  title: Uzum Nasiya Partner API
  version: 1.0.2
  description: >
    **Uzum Nasiya Partner API** — это REST API для интеграции партнеров с
    сервисом рассрочки Uzum Nasiya.


    #### ⚙️ Основные возможности


    - Регистрация клиента через WebView Uzum Nasiya

    - Проверка статуса клиента и его лимитов

    - Предварительный расчет договора по корзине товаров

    - Создание договора 

    - Подтверждение или отмена договора

    - Проверка статуса договора


    #### 🚀 Быстрый старт


    - [Авторизация](#section/Avtorizaciya) 

    - [Процесс оформления договора](#section/Process-oformleniya-dogovora)

    - [API методы](#tag/API-MFO)  


    ---

    ## Авторизация


    Авторизация выполняется через HTTP-заголовок Authorization. Все запросы к
    API должны содержать данный заголовок.


    ```

    Authorization: Bearer <ваш_токен>

    ```


    Токен является уникальным для каждого партнера и предоставляется менеджером
    со стороны Uzum Nasiya при подключении партнера к системе.


    При отсутствии или некорректном токене сервер вернет ошибку авторизации (401
    Unauthorized)


    ---

    ## Процесс оформления договора


    Процесс оформления договора состоит из четырех ключевых этапов:


    1. **Проверка пользователя** на возможность оформления договора


    2. **Расчет договора**


    3. **Создание договора**


    4. **Управление договором**: активация или отмена договора


    На диаграмме ниже представлен подробный процесс интеграции.


    <div style="text-align: center;">
      <a href="/img/nasiya-process.png" target="_blank">
        <img src="/img/nasiya-process.png" />
      </a>
    </div>


    1. Клиент вводит номер телефона в приложении партнера  


    2. Приложение партнера вызывает метод [POST
    /api/v1/buyers/check-status](#tag/API-MFO/operation/checkBuyerStatus)


    3. Uzum возвращает статус пользователя  


    4. Если статус = 0, 1, 2, 5, 10, 11, 12:  
      4.1 Приложение партнера предлагает завершить регистрацию  
      4.2 Открывается WebView регистрации  
      4.3 Клиент проходит регистрацию  
      4.4 Uzum выполняет проверку заявки  

    5. Если статус = 8, 9, 13, 14, 403:  
      5.1 Приложение партнера сообщает, что оформление невозможно  

    6. Если статус = 4:  
      6.1 Приложение партнера показывает возможность оформить рассрочку  

    7. Клиент нажимает «Оформить в рассрочку»  


    8. Приложение партнера вызывает метод [POST
    /api/v1/orders/calculate](#tag/API-MFO/operation/calculateOrder)


    9. Uzum возвращает список тарифов  


    10. Клиент выбирает тариф (например, 12 месяцев)  


    11. Приложение партнера вызывает метод [POST
    /api/v1/orders](#tag/API-MFO/operation/createOrder)


    12. Uzum возвращает `contract_id`  


    13. Если клиент отменяет оформление:  
        13.1 Приложение партнера вызывает метод [POST /api/v1/contracts/cancel](#tag/API-MFO/operation/cancelContract)  
        13.2 Uzum возвращает `response_code = 0`  
        13.3 Рассрочка отменяется  

    14. Если клиент подтверждает оформление:  
        14.1 Приложение партнера вызывает метод [POST /api/v1/contracts/confirm](#tag/API-MFO/operation/confirmContract)  
        14.2 Uzum возвращает `response_code = 0`  
        14.3 Договор считается активированным  

    15. Клиент выполняет оплату по графику  


    16. (Опционально) Приложение партнера может вызвать метод [POST
    /api/v1/contracts/check-status](#tag/API-MFO/operation/checkContractStatus)
    для получения информации по договору

        ---
    ## Статусы


    ### Статусы пользователя


    Статус пользователя определяет, может ли клиент оформить договор, или
    требуется дополнительное действие (регистрация, верификация и т.д.).


    | Код | Описание |

    |-----|----------|

    | 0 | Пользователь не найден в системе Uzum Nasiya |

    | 1 | Необходимо провести регистрацию и добавить карту |

    | 2 | Пользователь проходит проверку документов |

    | 4 | Пользователь верифицирован |

    | 5 | Отказано: Необходимо загрузить фото паспорта |

    | 8 | Отказано: Пользователь заблокирован или в черном списке (просрочка
    более 60 дней) |

    | 9 | Пользователь заблокирован |

    | 10 | Отказано: Необходимо загрузить селфи с паспортом |

    | 11 | Отказано: Необходимо загрузить страницу паспорта с пропиской |

    | 12 | Отказано: Необходимо добавить контактное лицо |

    | 13 | Клиент не может оформить договор. Необходимо обратиться в колл центр
    |

    | 14 | Клиент не может оформить договор у этого вендора. Необходимо
    обратиться в колл центр |

    | 403 | У клиента имеется задолженность |


    ---

    ### Статусы договора


    Статус договора отражает текущее состояние договора (активен, отменен,
    просрочен и т.д.).


    | Код | Описание |

    |-----|----------|

    | 0 | Не подтвержден |

    | 1 | Активный |

    | 2 | На модерации |

    | 3 | Просрочен (+60 дней) |

    | 4 | Просрочен (+30 дней) |

    | 5 | Отменен |

    | 9 | Закрытый |


    ---
servers:
  - url: https://merchants-api.uzumnasiya.uz
    description: Production
security: null
tags:
  - name: API MFO
paths:
  /api/v1/buyers/check-status:
    post:
      operationId: checkBuyerStatus
      tags:
        - API MFO
      summary: Проверка статуса пользователя
      description: Возвращает текущее состояние пользователя и доступные тарифные планы.
      security: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyerStatusRequest'
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStatusResponseMFO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/orders/calculate:
    post:
      operationId: calculateOrder
      tags:
        - API MFO
      summary: Калькуляция товаров
      description: >
        Выполняет предварительный расчет тарифных планов для корзины товаров
        перед созданием договора.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateRequest'
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/orders:
    post:
      operationId: createOrder
      tags:
        - API MFO
      summary: Создание договора
      description: |
        Создает договор рассрочки в системе Uzum Nasiya
        на основе выбранного тарифа и переданных товаров.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/contracts/check-status:
    post:
      operationId: checkContractStatus
      tags:
        - API MFO
      summary: Проверка статуса договора
      description: |
        Возвращает текущее состояние договора в системе Uzum Nasiya.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckContractStatusRequest'
      responses:
        '200':
          description: Информация о договоре
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckContractStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/contracts/confirm:
    post:
      operationId: confirmContract
      tags:
        - API MFO
      summary: Подтверждение договора
      description: |
        Подтверждает (активирует) договор в системе Uzum Nasiya
        после подписания пользователем.

        При успешном выполнении:
        - договор активируется
        - возвращается ссылка на подписанный акт

        Если договор уже активирован или имеет некорректный статус,
        возвращается соответствующий response_code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmContractRequest'
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmContractResponse'
        '400':
          description: Ошибка бизнес-логики подтверждения
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmContractErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/contracts/cancel:
    post:
      operationId: cancelContract
      tags:
        - API MFO
      summary: Полная отмена договора
      description: >
        Выполняет полную отмену договора в системе Uzum Nasiya.


        Метод используется партнером для аннулирования договора.

        Отмена возможна только при корректном статусе договора.


        При получении response_code = 1000 или 5XX рекомендуется повторить
        запрос.

        При других кодах необходимо проверить входные параметры.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelContractRequest'
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelContractResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/buyers/send-code-sms:
    post:
      operationId: sendContractSmsCode
      tags:
        - API MFO
      summary: Отправка SMS-кода для активации договора
      description: |
        Отправляет четырехзначный SMS-код на номер телефона клиента
        для активации договора.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsCodeRequest'
      responses:
        '200':
          description: SMS-код успешно отправлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSmsCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/buyers/check-code-sms:
    post:
      operationId: verifyContractSmsCode
      tags:
        - API MFO
      summary: Подтверждение SMS-кода активации договора
      description: |
        Подтверждает четырехзначный SMS-код,
        отправленный клиенту для активации договора.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifySmsCodeRequest'
      responses:
        '200':
          description: Результат подтверждения кода
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySmsCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    VerifySmsCodeRequest:
      type: object
      description: Запрос на подтверждение SMS-кода.
      required:
        - phone
        - contract_id
        - code
      properties:
        phone:
          type: string
          description: Номер телефона клиента.
          example: '998909531494'
        contract_id:
          type: integer
          description: Идентификатор договора.
          example: 12454
        code:
          type: string
          description: SMS-код.
          example: '975498'
    VerifySmsCodeResponse:
      type: object
      description: Ответ подтверждения SMS-кода.
      required:
        - status
        - error
        - data
      properties:
        status:
          type: string
          example: success
          description: Статус выполнения запроса.
        error:
          type: array
          description: Массив ошибок.
          items:
            type: object
          example: []
        data:
          type: object
          properties:
            contract_id:
              type: integer
              description: Идентификатор активированного договора.
              example: 12454
            message:
              type: string
              description: Сообщение о результате активации.
              example: Shartnoma muvaffaqiyatli tasdiqlandi!
    SendSmsCodeRequest:
      type: object
      description: Запрос на отправку SMS-кода.
      required:
        - phone
        - contract_id
      properties:
        phone:
          type: string
          description: Номер телефона клиента.
          example: '998909531494'
        contract_id:
          type: integer
          description: Идентификатор договора в системе Uzum Nasiya.
          example: 12454
    SendSmsCodeResponse:
      type: object
      description: Ответ метода отправки SMS-кода.
      required:
        - status
        - error
        - data
      properties:
        status:
          type: string
          example: success
          description: Статус выполнения запроса.
        error:
          type: array
          description: Массив ошибок.
          items:
            type: object
          example: []
        data:
          type: object
          properties:
            hashed:
              type: string
              description: Захешированный SMS-код.
              example: $2y$10$B.ajVLZMnJZIk8nr6QbeveMP4w4ULF9M6Rr4ZfuZn
            is_registered:
              type: boolean
              description: Признак регистрации пользователя в системе.
              example: true
    ContractStatusData:
      type: object
      description: Детальная информация о договоре.
      required:
        - id
        - contract_id
        - type
        - created_at
        - updated_at
        - contract_status
      properties:
        id:
          type: integer
          description: Внутренний порядковый идентификатор записи.
          example: 106
        contract_id:
          type: integerй
          description: Номер договора в системе Uzum Nasiya.
          example: 343
        type:
          type: string
          description: Тип договора (например mfo).
          example: mfo
        myid_attempts:
          type: integer
          description: Количество попыток прохождения регистрации через MyID.
          example: 0
        created_at:
          type: string
          format: date-time
          description: Дата и время создания договора.
          example: '2022-12-07T08:24:15.000000Z'
        updated_at:
          type: string
          format: date-time
          description: Дата и время последнего обновления договора.
          example: '2022-12-07T08:27:17.000000Z'
        contract_status:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 9
          description: |
            Статус договора
          example: 5
        status:
          type: integer
          description: >
            Статус страниц процесса активации договора (внутренний параметр
            системы).

            Не используется партнерами.
          example: 50
        qr_status:
          type: integer
          description: |
            Тип договора (внутренний параметр системы).
            Не используется партнерами.
          example: 0
        is_signed:
          type: boolean
          description: Наличие подписи договора в системе Uzum Nasiya.
          example: true
    CheckContractStatusResponse:
      type: object
      description: Ответ метода проверки статуса договора.
      required:
        - status
        - error
        - data
      properties:
        status:
          type: string
          description: Общий результат выполнения запроса.
          example: success
        error:
          type: array
          description: Массив ошибок.
          items:
            type: object
          example: []
        data:
          $ref: '#/components/schemas/ContractStatusData'
    CheckContractStatusRequest:
      type: object
      description: Запрос на получение информации о договоре.
      required:
        - contract_id
      properties:
        contract_id:
          type: integer
          description: Номер договора в системе Uzum Nasiya.
          example: 5511
    CancelContractResponse:
      type: object
      description: Ответ метода полной отмены договора.
      required:
        - status
        - error
        - data
        - response_code
      properties:
        status:
          type: string
          description: Общий результат выполнения запроса.
          example: success
        error:
          type: array
          description: Массив ошибок.
          items:
            type: object
          example: []
        data:
          type: array
          description: Массив даных. В этом ответе — пустой.
          items:
            type: object
          example: []
        response_code:
          type: integer
          description: |
            Код результата выполнения метода полной отмены договора:

            `0`    — RESPONSE_SUCCESS  
            `4004` — RESPONSE_CONTRACT_NOT_FOUND  
            `4009` — RESPONSE_CONTRACT_INCORRECT_STATUS  
            `4005` — RESPONSE_INVALID_CONTRACT_DATA  
            `1000` — RESPONSE_TECHNICAL_ERROR  
            `6001` — RESPONSE_MAX_REQUEST_LIMIT  

            При получении 1000 или 5XX — повторите запрос.
          enum:
            - 0
            - 4004
            - 4009
            - 4005
            - 1000
            - 6001
          example: 4004
    CancelContractRequest:
      type: object
      description: Запрос на полную отмену договора.
      required:
        - contract_id
      properties:
        contract_id:
          type: integer
          description: |
            Внутренний идентификатор договора (order),
            полученный из метода создания договора `/api/v1/orders`.
          example: 5511
    ConfirmContractErrorResponse:
      type: object
      description: Ошибка подтверждения договора.
      required:
        - status
        - error
        - data
        - response_code
      properties:
        status:
          type: string
          example: error
          description: Статус выполнения запроса.
        error:
          type: array
          description: Список ошибок.
          items:
            type: object
            properties:
              type:
                type: string
                description: Тип сообщения.
                example: danger
              text:
                type: string
                description: Человекочитаемое описание ошибки.
                example: Shartnoma allaqachon tasdiqlangan!
              sub_text:
                type: string
                nullable: true
                description: Дополнительное описание ошибки.
                example: null
        data:
          type: array
          description: При ошибке возвращается пустой массив.
          items: {}
          example: []
        response_code:
          type: integer
          description: |
            Код бизнес-ошибки подтверждения договора.
          example: 4010
    ConfirmContractRequest:
      type: object
      description: Запрос на подтверждение (активацию) договора.
      required:
        - contract_id
      properties:
        contract_id:
          type: integer
          description: |
            Идентификатор договора в системе Uzum Nasiya.
            Получается при создании договора.
          example: 5511
    ConfirmContractResponse:
      type: object
      description: Ответ при успешной активации договора.
      required:
        - status
        - error
        - data
        - response_code
      properties:
        status:
          type: string
          description: Статус выполнения запроса.
          example: success
        error:
          type: array
          description: Массив ошибок. При успешном ответе — пустой.
          items:
            type: object
          example: []
        data:
          type: object
          description: Данные по активированному договору.
          required:
            - client_act_pdf
          properties:
            client_act_pdf:
              type: string
              description: Ссылка на подписанный пользователем акт.
              example: https://ari.paymart.uz/storage/contract/968.pdf
        response_code:
          type: integer
          description: |
            Код результата выполнения метода:

            0    — RESPONSE_SUCCESS  
            4004 — RESPONSE_CONTRACT_NOT_FOUND  
            4009 — RESPONSE_CONTRACT_INCORRECT_STATUS  
            4010 — RESPONSE_CONTRACT_ALREADY_ACTIVATED  
            5003 — RESPONSE_PARTNER_ACCESS_DENIED  
            5005 — RESPONSE_INVALID_PARTNER_DATA  
            1000 — RESPONSE_TECHNICAL_ERROR  

            При получении 1000 или 5XX рекомендуется повторить запрос.
            При других кодах необходимо проверить входные параметры.
          enum:
            - 0
            - 4004
            - 4009
            - 4010
            - 5003
            - 5005
            - 1000
          example: 0
    CalculatedTariff:
      type: object
      required:
        - tariff
        - period_months
        - total
        - origin
        - month
        - is_available
        - status
        - is_promo
        - is_mini_loan
        - client_photo_upload
        - first_payment_date
        - deposit
        - balance
      properties:
        tariff:
          type: string
          description: Идентификатор тарифного плана.
          example: 6 Default
        tariff_name:
          type: string
          description: Название тарифного плана.
          example: Limit Max
        period_months:
          type: integer
          description: Количество месяцев рассрочки.
          example: 6
        title_ru:
          type: string
          description: Название тарифа на русском языке.
        title_uz:
          type: string
          description: Название тарифа на узбекском языке.
        is_promo:
          type: boolean
          description: Является ли тариф промо-акцией.
          example: false
        is_mini_loan:
          type: boolean
          description: Признак краткосрочного займа.
          example: false
        client_photo_upload:
          type: boolean
          description: Загружена ли фотография клиента.
          example: false
        first_payment_date:
          type: string
          format: date
          description: Дата первого платежа.
          example: '2024-08-01'
        total:
          type: number
          description: Общая сумма с наценкой Uzum Nasiya.
          example: 1260
        origin:
          type: number
          description: Сумма товаров без наценки.
          example: 1000
        total_without_promo:
          type: number
          description: Сумма без учета промо-скидки.
        origin_promo:
          type: number
          description: Сумма товара без наценки с учетом промо.
        deposit:
          type: number
          description: Депозитный взнос пользователя.
          example: 0
        month:
          type: number
          description: Ежемесячный платеж.
          example: 210
        balance:
          type: number
          description: Доступный лимит по тарифу.
          example: 0
        is_available:
          type: boolean
          description: Доступен ли тариф пользователю.
        status:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: |
            Доступность тарифа:
            0 — тариф доступен
            1 — тариф с периодом < 4 недоступен
            2 — тариф с периодом > 4 недоступен
          example: 2
        custom_discount:
          type: number
          description: Персональная скидка пользователя (%).
        error_message:
          type: string
          description: Сообщение об ошибке (если тариф недоступен).
        products:
          type: array
          description: Пересчитанные товары по данному тарифу.
          items:
            $ref: '#/components/schemas/CalculatedProduct'
    CalculatedProduct:
      type: object
      required:
        - product_id
        - price
        - amount
        - sum
        - origin
        - origin_promo
      properties:
        product_id:
          type: integer
          description: ID товара у партнера.
        price:
          type: number
          description: Стоимость товара с наценкой.
        amount:
          type: integer
          description: Количество товара.
        sum:
          type: number
          description: Стоимость с наценкой × количество.
        origin:
          type: number
          description: Стоимость без наценки.
        origin_promo:
          type: number
          description: �

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/uzum/refs/heads/main/openapi/uzum-nasiya-openapi.yaml