openapi: 3.1.0
info:
  title: Document API
  version: v2
servers:
  - url: https://api-ext-sboxmeta.partners.spotnana.com
    description: Sandbox URL
security:
  - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Document:
      type: object
      title: Document
      description: Document details.
      required:
        - url
        - documentId
        - documentMetadata
      properties:
        url:
          type: string
          description: S3 location of the document.
          example: https://s3.amazonaws.com/bucket-name/folder-name/file-name
        documentId:
          type: string
          format: uuid
          description: Unique identifier of the document.
          example: f49d00fe-1eda-4304-ba79-a980f565281d
        documentMetadata:
          $ref: '#/components/schemas/DocumentMetadata'
    DocumentMetadata:
      title: DocumentMetadata
      description: Metadata related to document.
      type: object
      required:
        - documentType
        - entityType
        - entityId
        - entityMetadata
        - name
      properties:
        documentType:
          $ref: '#/components/schemas/DocumentType'
        entityType:
          $ref: '#/components/schemas/EntityType'
        entityId:
          type: string
          description: Entity Id for the given entity type.
          example: '123124'
        entityMetadata:
          $ref: '#/components/schemas/EntityMetadata'
        name:
          type: string
          description: Document name.
          example: BoardingPass.pdf
    DocumentType:
      title: DocumentType
      description: Document type.
      type: string
      enum:
        - BOARDING_PASS
        - CONFIRMATION
        - INVOICE
        - VISA
        - MISCELLANEOUS
        - OTHERS
        - TASK_PROCESSOR
        - EVENT_COVER_IMAGE
        - LOGO_IMAGE
      example: VISA
      x-ignoreBreakingChanges:
        - DocumentType->LOGO_IMAGE
    EntityMetadata:
      title: EntityMetadata
      description: Metadata for associated entity of document.
      type: object
      oneOf:
        - $ref: '#/components/schemas/PnrMetadataWrapper'
        - $ref: '#/components/schemas/EventMetadataWrapper'
    EntityType:
      title: EntityType
      description: Entity type against which the document is to uploaded.
      type: string
      enum:
        - PNR
        - COMPANY
        - AIR_ITINERARY
        - EVENT
        - LOCATION_IMAGE
      example: PNR
      x-ignoreBreakingChanges:
        - EntityType->TRIP
        - EntityType->TICKETING_ERROR
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    ErrorResponse:
      type: object
      properties:
        debugIdentifier:
          type: string
          description: Link to debug the error internally.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: Error code to identify the specific errors.
              message:
                type: string
                description: Message containing details of error.
              errorParameters:
                type: array
                description: Error message parameters.
                items:
                  $ref: '#/components/schemas/ErrorParameter'
              errorDetail:
                type: string
                description: More details about the error.
    EventEntityMetadata:
      title: EventEntityMetadata
      description: Metadata when document is associated to an event.
      type: object
      properties:
        address:
          $ref: '#/components/schemas/PostalAddress'
    EventMetadataWrapper:
      type: object
      title: EventMetadataWrapper
      properties:
        eventMetadata:
          $ref: '#/components/schemas/EventEntityMetadata'
    FlightMetadata:
      title: FlightMetadata
      description: Flight metadata against which document is associated.
      type: object
      properties:
        flightId:
          type: string
          description: Unique identifier of the flight.
          example: CgNERU4SA1NGTxoKNTQ1NzI5ODcxMQ
    FlightMetadataWrapper:
      type: object
      title: FlightMetadataWrapper
      properties:
        flightMetadata:
          $ref: '#/components/schemas/FlightMetadata'
    GetDocumentResponse:
      type: object
      title: GetDocumentResponse
      description: Response containing a document.
      required:
        - document
      properties:
        document:
          $ref: '#/components/schemas/Document'
    GetDocumentsResponse:
      type: object
      title: GetDocumentsResponse
      description: Response containing a list of documents.
      required:
        - documents
      properties:
        documents:
          type: array
          description: List of documents.
          items:
            $ref: '#/components/schemas/Document'
    Latlng:
      title: Latlng
      description: Latitude and Longitude for a Location
      type: object
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          description: Latitude of the Location
          format: double
          example: 77.1025
        longitude:
          type: number
          description: Longitude of the Location
          format: double
          example: 28.7041
    LegMetadata:
      title: LegMetadata
      description: Leg metadata against which document is associated.
      type: object
      properties:
        legId:
          type: string
          description: Unique identifier of the leg.
          example: CgNTRk8SA0RFThoKNTQ1NzI5ODcxMQ==
    LegMetadataWrapper:
      type: object
      title: LegMetadataWrapper
      properties:
        legMetadata:
          $ref: '#/components/schemas/LegMetadata'
    PnrMetadata:
      title: PnrMetadata
      description: Metadata when document is associated to pnr entity.
      type: object
      oneOf:
        - $ref: '#/components/schemas/FlightMetadataWrapper'
        - $ref: '#/components/schemas/LegMetadataWrapper'
    PnrMetadataWrapper:
      type: object
      title: PnrMetadataWrapper
      required:
        - travelType
      properties:
        pnrMetadata:
          $ref: '#/components/schemas/PnrMetadata'
        invoiceMetadata:
          type: object
          title: InvoiceMetadata
          description: Metadata associated with an invoice document.
          required:
            - invoiceNumber
          properties:
            invoiceNumber:
              type: string
              example: SPOT-0001
            invoiceType:
              type: string
              example: FARE_INVOICE
              enum:
                - SERVICE_FEE_INVOICE
                - FARE_INVOICE
                - GENERIC_INVOICE
        travelType:
          $ref: '#/components/schemas/TravelType'
    PostalAddress:
      title: PostalAddress
      description: Postal Address Details
      type: object
      required:
        - addressLines
        - regionCode
      properties:
        addressLines:
          description: Address lines
          type: array
          items:
            type: string
            example: Golden Gate Bridge
        administrativeArea:
          type: string
          description: >
            Code of administrative area. For example: DL for Delhi, India.

            Highest administrative subdivision which is used for postal

            addresses of a country or region.

            For example, this can be a state, a province, an oblast, or a
            prefecture.

            Specifically, for Spain this is the province and not the autonomous

            community (e.g. "Barcelona" and not "Catalonia").

            Many countries don't use an administrative area in postal addresses.
            E.g.

            in Switzerland this should be left unpopulated.
          example: CA
        administrativeAreaName:
          type: string
          description: >
            Name of administrative area. This is full name corresponding to
            administrativeArea. 

            Like Delhi for DL area code. For some places, code and name maybe
            same as well like Tokyo.
          example: California
        description:
          description: Address description
          type: string
          example: San Francisco Home
        isDefault:
          description: >-
            Whether this address is default address in case multiple addresses
            are specified.
          type: boolean
          example: true
        languageCode:
          description: >
            BCP-47 language code of the contents of this address (if known).
            This is often the UI 

            language of the input form or is expected to match one of the
            languages used in the 

            address' country/region, or their transliterated equivalents.

            This can affect formatting in certain countries, but is not critical
            to the correctness 

            of the data and will never affect any validation or other
            non-formatting related operations.

            Examples: "zh-Hant", "ja", "ja-Latn", "en".
          type: string
          example: en
        locality:
          description: Generally refers to the city/town portion of the address.
          type: string
          example: San Francisco
        locationCode:
          description: >-
            IATA 3-letter location code. See
            https://www.iata.org/en/services/codes.
          type: string
          example: LAX
        organization:
          description: The name of the organization at the address.
          type: string
          example: Spotnana
        postalCode:
          description: >-
            Postal code of the address. This is a required field when setting
            for a user/legal entity/company etc.
          type: string
          example: '94130'
        continentCode:
          description: 2 letter continent code of the continent this address falls in.
          type: string
          example: AF
        recipients:
          description: The recipient at the address.
          type: array
          items:
            type: string
        regionCode:
          description: Region code of the country/region of the address.
          type: string
          example: US
        regionName:
          description: Region name of the country/region of the address.
          type: string
          example: America
        revision:
          type: integer
          format: int32
          example: 1
        sortingCode:
          description: >
            Additional, country-specific, sorting code. This is not used

            in most regions. Where it is used, the value is either a string like

            "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a
            number

            alone, representing the "sector code" (Jamaica), "delivery area
            indicator"

            (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).
          type: string
          example: Jamaica
        sublocality:
          description: >-
            Sublocality of the address. This can be neighborhoods, boroughs,
            districts.
          type: string
        timezone:
          description: Time zone of the address.
          type: string
          example: America/Los_Angeles
        coordinates:
          description: Map coordinates of the address.
          $ref: '#/components/schemas/Latlng'
    TravelType:
      type: string
      title: TravelType
      description: Travel Type
      enum:
        - AIR
        - HOTEL
        - CAR
        - RAIL
        - LIMO
        - MISC
        - ALL
      example: AIR
    UploadDocumentRequest:
      type: object
      title: UploadDocumentRequest
      description: Request body for upload document.
      required:
        - documentMetadata
        - file
      properties:
        documentMetadata:
          $ref: '#/components/schemas/DocumentMetadata'
        file:
          type: string
          format: binary
          description: Contents of the document to be uploaded.
    UploadDocumentResponse:
      type: object
      title: UploadDocumentResponse
      description: Response for upload document.
      required:
        - documentId
        - documentMetadata
      properties:
        documentId:
          type: string
          format: uuid
          description: Unique identifier of the document.
          example: f49d00fe-1eda-4304-ba79-a980f565281d
        documentMetadata:
          $ref: '#/components/schemas/DocumentMetadata'
tags:
  - name: Document
    description: >-
      APIs for managing and performing operations on documents related to trips
      and bookings.
paths:
  /v2/documents:
    post:
      tags:
        - Documents
      summary: Upload a document
      description: Upload a document for a specific entity type (e.g., a PNR).
      operationId: uploadDocument
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadDocumentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
        - Documents
      summary: List documents
      description: List all the uploaded documents for a specific entity ID and type.
      operationId: listDocuments
      parameters:
        - name: entityType
          in: query
          description: Entity type against which document is associated.
          required: true
          schema:
            $ref: '#/components/schemas/EntityType'
        - name: entityId
          in: query
          description: Entity Id for the given entity type.
          required: true
          schema:
            type: string
          example: '123124'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/documents/{documentId}:
    get:
      tags:
        - Documents
      summary: Get document
      description: Retrieve a document.
      operationId: getDocument
      parameters:
        - name: documentId
          in: path
          description: Document Id
          required: true
          schema:
            type: string
            format: uuid
          example: f49d00fe-1eda-4304-ba79-a980f565281d
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Documents
      summary: Delete document
      description: Delete a document.
      operationId: deleteDocument
      parameters:
        - name: documentId
          in: path
          description: Document Id
          required: true
          schema:
            type: string
            format: uuid
          example: f49d00fe-1eda-4304-ba79-a980f565281d
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
