openapi: 3.0.0
info:
  title: Letter Sending Service API
  version: "0.1"
  description: API for sending letters, tracking, and managing related information.
servers:
  - url: 'https://api.pochta-sud.ru/'
    description: Main API server

paths:
  /letter:
    get:
      security:
        - bearerAuth: []
      summary: List all sent letters
      description: Get a list of all letters that have been sent.
      responses:
        '200':
          description: An array of letters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Letter'

    post:
      summary: Send a letter
      description: Send a letter with attachments.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - document
              properties:
                source:
                  $ref: '#/components/schemas/SourceParty'
                destination:
                  $ref: '#/components/schemas/DestinationParty'
                document:
                  type: string
                  format: binary
                  description: Main document to send
                document_name:
                  type: string
                  description: Name of main document file
                attachments:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Additional documents to send
                attachment_names:
                  type: array
                  items:
                    type: string
                  description: Name of each attachment file
      responses:
        '200':
          description: Letter sent successfully

  /letter/{id}:
    get:
      summary: Get a specific letter
      description: Get detailed information about a specific letter.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the letter to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: Detailed information about the letter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Letter'

  /letter/{id}/invoice:
    get:
      summary: Get invoice
      description: Download the invoice as a PDF file.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the letter to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: Invoice PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
                description: A PDF file of the invoice

  /letter/{id}/listing:
    get:
      summary: Get letter listing
      description: Download the listing as a PDF file.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the letter to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: Listing PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
                description: A PDF file of the listing

  /letter/{id}/tracking:
    get:
      summary: Track a letter
      description: Get tracking information for a specific letter.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the letter to track
          schema:
            type: integer
      responses:
        '200':
          description: Tracking information of the letter
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date-time
                    value:
                      type: string


  /balance:
    get:
      summary: Get current balance
      description: Get the current balance in rubles.
      responses:
        '200':
          description: Current balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    format: float
                    description: Current balance in rubles

  /notification:
    get:
      summary: Get notification message
      description: Get informational message.
      responses:
        '200':
          description: Informational message
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Informational message content

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    PartyType:
      type: string
      enum:
        - individual
        - organization

    DestinationParty:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/PartyType'
      discriminator:
        propertyName: type
        mapping:
          individual: '#/components/schemas/DestinationIndividual'
          organization: '#/components/schemas/DestinationOrganization'
    
    DestinationIndividual:
      allOf:
        - $ref: '#/components/schemas/DestinationParty'
        - type: object
          required:
            - name
            - address
          properties:
            name:
              type: string
              description: ФИО физического лица
            address:
              type: string

    DestinationOrganization:
      allOf:
        - $ref: '#/components/schemas/DestinationParty'
        - type: object
          required:
            - name
            - taxId
            - address
          properties:
            name:
              type: string
              description: Название организации
            taxId:
              type: string
              description: ИНН организации
            address:
              type: string

    SourceParty:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/PartyType'
      discriminator:
        propertyName: type
        mapping:
          individual: '#/components/schemas/SourceIndividual'
          organization: '#/components/schemas/SourceOrganization'
    
    SourceIndividual:
      allOf:
        - $ref: '#/components/schemas/SourceParty'
        - type: object
          required:
            - name
            - address
            - email
          properties:
            name:
              type: string
              description: ФИО физического лица
            address:
              type: string
            email:
                type: string
                format: email

    SourceOrganization:
      allOf:
        - $ref: '#/components/schemas/SourceParty'
        - type: object
          required:
            - name
            - taxId
            - address
            - email
          properties:
            name:
              type: string
              description: Название организации
            taxId:
              type: string
              description: ИНН организации
            address:
              type: string
            email:
                type: string
                format: email

    Letter:
      type: object
      properties:
        letterId:
          type: integer
        source:
          $ref: '#/components/schemas/SourceParty'
        destination:
          $ref: '#/components/schemas/DestinationParty'
        status:
          type: string
          description: Current status of the letter

security:
  - bearerAuth: []