openapi: 3.0.0
info:
  version: 2.2.0
  title: Ticketing Api
  description: 'Rest API that can be invoked from third party services in order to manage tickets. The underlying ticketing tools are corporate Atlassian Jira instances and Oceane.
                This API allows work with multiple ticketing providers as <b>TGJira, Jira Next, Jira Amarillo, Jira Nodus and Oceane</b>.
                It allows to perform basic operations involving tickets, like create, update, search, link and transition, also adding comment and attachments to existing tickets.'
servers:
  - url: 'https://ticketing.sta.masstack.com/v2'
    description: Staging
  - url: 'https://ticketing.masstack.com/v2'
    description: Production
tags:
  - name: Ticket
    description: Ticket operations
  - name: Comment
    description: Comments operations
  - name: Attachment
    description: Attachments operations
  - name: IssueLink
    description: Issue links operations
  - name: Remotelink
    description: Remote links operations
  - name: IssueLinkTypes
    description: Issue link types operations
  - name: Grid
    description: Grid operations
  - name: IaSummary
    description: IA Summary operations
  - name: IaDuration
    description: IA duration prediction operations
  - name: Insight
    description: Jira Insight operations
  - name: Customfield
    description: Custom fields operations
paths:
  '/orgs/{org}/ticket':
    post:
      security:
        - bearerAuth: []
      tags:
        - Ticket
      summary: Create ticket
      description: Creates a ticket from a JSON representation.
      operationId: CreateTicket
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      requestBody:
        required: true
        description: Json with ticket creation fields. See request ticket/metadata/create/properties.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ticket'
      responses:
        '201':
          $ref: '#/components/responses/201_Created_Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/orgs/{org}/ticket/{ticketId}':
    patch:
      security:
        - bearerAuth: []
      tags:
        - Ticket
      summary: Update ticket
      description: Edits a ticket from a JSON representation.
      operationId: updateTicket
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      requestBody:
        required: true
        description: Json with fields to update. See request /ticket/{ticketId}/metadata/update/properties.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ticket'
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      security:
        - bearerAuth: []
      tags:
        - Ticket
      summary: Get ticket
      description: Returns a full representation of the ticket for the given key.
      operationId: getTicketById
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/expand'
        - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Full representation of the ticket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/orgs/{org}/search/ticket':
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Search ticket
      description: '
        This method allows you to search tickets filtering and ordering as you need.<br\>
        Special opeators are allowed
        $like: value<br\>
        $in: [array]<br\>
        $notIn: [array]<br\>
        $isEmpty: ""<br\>
        $greaterThanEquals: value<br\>
        $greaterThan: value<br\>
        $lessThanEquals: value<br\>
        $lessThan: value<br\>

        Field names used in filters can be both Jira field name or MAS-Ticketing-API name, i.e. you can use \"customerDocument\" or \"Documento Cliente\".'
      operationId: searchTickets
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      requestBody:
        description: Filters to apply to search query
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Ticket response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      security:
        - bearerAuth: []
      tags:
        - Ticket
      summary: Search ticket by JQL
      description: This method allows you search ticket by JQL (Jira Query Language)
      operationId: searchTicketsByJql
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/jql'
      responses:
        '200':
          description: Ticket Search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketSearchGetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/orgs/{org}/searchByTerritoryOwner':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Search tickets by territory owner
      description: 'Performs a search returning tickets corresponding to the territory-owner in path'
      operationId: searchTicketsByTerritoryOwner
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Search by territory owner response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketSearchGetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/orgs/{org}/searchByIDParams':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Search tickets by ID parameters
      description: 'Performs a search returning tickets based on ID parameters. At least one of the following parameters must be provided: customer_id, work_order_id, line, or document_id.'
      operationId: searchTicketsByIDParams
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/work_order_id'
        - $ref: '#/components/parameters/line'
        - $ref: '#/components/parameters/document_id'
      responses:
        '200':
          description: Search by ID parameters response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketSearchGetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/orgs/{org}/ticket/{ticketId}/transitions':
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Transition ticket
      description: This method allows you to execute a transition, i.e. change ticket status.
      operationId: doTransition
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transition'
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Get ticket available transitions
      description: Get information about allowed transitions for a ticket, depending on current status.
      operationId: getAllowedTransitions
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
        - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Transitions response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransitionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  '/ticket/{ticketId}/ia/summary':
    get:
      security:
        - bearerAuth: []
      tags:
        - IaSummary
      summary: Get IA summary for a ticket
      description: >
        Returns the AI-generated summary for a given ticket without updating the ticket in the ticketing provider.
        The response includes the operative summary and the message for the client, as generated by the IA service.


        **Security:** requires a valid Bearer JWT token. The token must carry the `ticketing-mas.ticketing.access.allowed`
        API access role and the `ticketing.ticket.iaSummary` operation permission.
        mTLS requests (without Authorization header) are also accepted.
      operationId: getTicketIaSummary
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: IA summary response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IaSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/ia/duration':
    get:
      security:
        - bearerAuth: []
      tags:
        - IaDuration
      summary: Get IA duration prediction for a ticket
      description: >
        Returns the AI-predicted estimated resolution date for a given ticket.
        The prediction is calculated by adding the predicted minutes to the ticket creation date.
        The response includes the formatted estimated resolution date and the raw estimated minutes.
        Additionally, the endpoint updates the ticket's `estimated_resolution_date` custom field asynchronously.


        **Security:** requires a valid Bearer JWT token. The token must carry the `ticketing-mas.ticketing.access.allowed`
        API access role and the `ticketing.ticket.iaSummary` operation permission.
        mTLS requests (without Authorization header) are also accepted.
      operationId: getTicketIaDuration
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: IA duration prediction response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IaDurationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/insights':
    get:
      security:
        - bearerAuth: []
      tags:
        - Insight
      summary: Get Jira Insights map
      description: >
        Returns the Jira Insights object map for the specified ticketing provider.
        The map contains insight objects indexed by their identifier.


        **Security:** requires a valid Bearer JWT token. The token must carry the `ticketing-mas.ticketing.access.allowed`
        API access role.
        mTLS requests (without Authorization header) are also accepted.
      operationId: getInsightsMap
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: Insights map response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsMapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/insights/types':
    get:
      security:
        - bearerAuth: []
      tags:
        - Insight
      summary: Get Jira Insights map with types
      description: >
        Returns the Jira Insights object map with type information for the specified ticketing provider.
        The map contains insight objects with their associated types indexed by identifier.


        **Security:** requires a valid Bearer JWT token. The token must carry the `ticketing-mas.ticketing.access.allowed`
        API access role.
        mTLS requests (without Authorization header) are also accepted.
      operationId: getInsightsMapWithTypes
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: Insights map with types response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsMapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/customfields':
    get:
      security:
        - bearerAuth: []
      tags:
        - Customfield
      summary: Get custom fields map
      description: >
        Returns the custom fields mapping for a specific ticketing provider or for all providers if no provider header is specified.
        The response includes the count of custom fields and detailed metadata objects for each custom field.


        **Behavior:**
        - If `ticketing-provider` header is provided: returns custom fields for that specific provider
        - If `ticketing-provider` header is omitted: returns custom fields for all providers that support custom fields


        **Security:** requires a valid Bearer JWT token. The token must carry the `ticketing-mas.ticketing.access.allowed`
        API access role.
        mTLS requests (without Authorization header) are also accepted.
      operationId: getCustomFieldsMap
      parameters:
        - in: header
          name: ticketing-provider
          description: >
            Optional. Acronym identifying the ticketing provider.
            If provided, returns custom fields only for the specified provider.
            If omitted, returns custom fields for all providers.
            JAM (Jira Amarillo), TGJ (TGJira), JNEXT (JiraNext), JNODUS (Jira Nodus), OCEANE (Oceane)
          schema:
            type: string
            enum:
              - JAM
              - TGJ
              - JNEXT
              - JNODUS
              - OCEANE
          required: false
      responses:
        '200':
          description: Custom fields map response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CustomFieldsSingleProviderResponse'
                  - $ref: '#/components/schemas/CustomFieldsAllProvidersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/comment':
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - Comment
      summary: Create ticket comment
      description: This method allows you to add a comment in a ticket
      operationId: addComment
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      requestBody:
        description: Properties ticketId and body are mandatory.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/assignee':
    put:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Assign a ticket
      description: Assign a ticket to some user
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assignee'
            example:
              assignee: admin.micro
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
  '/ticket/{ticketId}/attachment':
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - Attachment
      summary: Create ticket attachment
      description: Attach a file in a specific ticket
      operationId: addAttachment
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      requestBody:
        description: The properties ticketId, name and data are required.
          Data must be base64 encoded.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attachment'
        required: true
      responses:
        '201':
          description: Attachment Created synchronous response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/attachment/{attachmentId}':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Attachment
      summary: Get ticket attachment
      description: Get an attachment from specific ticket
      operationId: getAttachmentById
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/attachmentId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: Attachment GET response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentGETResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/attachment/{attachmentId}':
    delete:
      security:
        - bearerAuth: [ ]
      tags:
        - Attachment
      summary: Delete an attachment
      description: Delete an attachment
      operationId: deleteAttachmentById
      parameters:
        - $ref: '#/components/parameters/attachmentId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  '/ticket/metadata/create/properties':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Get ticket creation fields
      description: Get information about fields needed to create a given type of ticket
      operationId: getFieldsForTicketType
      parameters:
        - $ref: '#/components/parameters/projectKey'
        - $ref: '#/components/parameters/ticketType'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          $ref: '#/components/responses/CreationDataInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/metadata/update/properties':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Get ticket editable fields
      description: Get information about editable fields.
      operationId: getEditableFields
      parameters:
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          $ref: '#/components/responses/EditableFields'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/metadata/types':
    get:
      security:
        - bearerAuth: []
      tags:
        - Ticket
      summary: Get ticket types
      description: Get information about ticket types per project
      operationId: getTicketTypes
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: Get ticket types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TicketTypes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/field/info':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - Ticket
      summary: Get ticket field information
      description: Get information about api names with api_name, customfield_id or jira_label params (Only one)
      operationId: getTicketFieldInfo
      parameters:
        - $ref: '#/components/parameters/api_name'
        - $ref: '#/components/parameters/customfield_id'
        - $ref: '#/components/parameters/jira_label'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: Get field info successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  jira_label:
                    type: string
                    example: Huella
                  api_name:
                    type: string
                    example: track
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ticket/{ticketId}/grid':
    put:
      security:
        - bearerAuth: [ ]
      tags:
        - Grid
      summary: Update grid line
      description: Update a line from the grid for a given ticket
      parameters:
        - $ref: '#/components/parameters/customfield_name'
        - $ref: '#/components/parameters/ticketId'
        - $ref: '#/components/parameters/ticketingProvider'
      requestBody:
        description: Data structure that modifies the specified columns from a given line of the grid (as per its row identificator)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGridRow'
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
  '/issueLink':
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - IssueLink
      summary: Create IssueLink
      description: Create IssueLink for specific ticket
      operationId: createIssueLink
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueLink'
      responses:
        '201':
          description: issue link created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: issue link created successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/issueLink/{issueLinkId}':
    get:
      security:
        - bearerAuth: []
      tags:
        - IssueLink
      summary: Get IssueLink
      description: Get IssueLink by id
      operationId: getIssueLinkById
      parameters:
        - $ref: '#/components/parameters/issueLinkId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          $ref: '#/components/responses/IssueLinkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      security:
        - bearerAuth: [ ]
      tags:
        - IssueLink
      summary: Delete IssueLink
      description: Delete IssueLink by id
      operationId: deleteIssueLink
      parameters:
        - $ref: '#/components/parameters/issueLinkId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '204':
          $ref: '#/components/responses/No_Content_204'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/remotelink':
    post:
      security:
        - bearerAuth: []
      tags:
        - Remotelink
      summary: Create a remote link
      description: 'Create a remote link'
      operationId: createRemoteLink
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '201':
          description: create a remote link
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: remote issue link created successfully.
  '/issueLinkType':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - IssueLinkTypes
      summary: Get all IssueLinkTypes
      description: 'Available issue links types'
      operationId: getAllIssueLinkTypes
      parameters:
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: get all IssueLinkTypes for specific issue
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/responses/IssueLinkType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/issueLinkType/{issueLinkId}':
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - IssueLinkTypes
      summary: Get IssueLinkType
      description: 'Get the issue links types for specific issue link'
      operationId: getIssueLinkTypeForATicket
      parameters:
        - $ref: '#/components/parameters/issueLinkId'
        - $ref: '#/components/parameters/ticketingProvider'
      responses:
        '200':
          description: all IssueLinkTypes for specific issue
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/responses/IssueLinkType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    api_name:
      in: query
      name: api_name
      description: Search a field information with api name
      required: false
      schema:
        type: string
        example: track
    customfield_name:
      in: query
      name: customFieldName
      description: Custom field name as per mapped from customfield_id's
      required: false
      schema:
        type: string
        example: workorder_index
    customfield_id:
      in: query
      name: customfield_id
      description: Search a field information with customfield_id
      required: false
      schema:
        type: string
        example: customfield_12800
    jira_label:
      in: query
      name: jira_label
      description: Search a field information with the TGJira field name
      required: false
      schema:
        type: string
        example: Huella
    jql:
      in: query
      name: jql
      description: jql query
      required: true
      schema:
        type: string
    issueLinkId:
      in: path
      name: issueLinkId
      description: issue link id
      required: true
      schema:
        type: string
    attachmentId:
      in: path
      name: attachmentId
      description: Attachment Id
      required: true
      schema:
        type: string
    fieldName:
      in: path
      name: fieldName
      description: The field name in MasMovil ticketing API.
      required: true
      schema:
        type: string
    projectKey:
      in: query
      name: projectKey
      description: The project key in MasMovil ticketing tool
      required: true
      schema:
        type: string
    ticketId:
      in: path
      name: ticketId
      description: >-
        Ticket **key** in the MasMovil ticketing tool (e.g. `ATC-20923`, `INST-7902`).

        **Important — key vs. id:** every ticket has two different identifiers that must not
        be confused:

        - **key** — alphanumeric reference in `PROJECT-NUMBER` format (e.g. `ATC-20923`).
          This is the value you must pass in this parameter.

        - **id** — internal numeric identifier (e.g. `937328`). This is a different field
          returned in the response body and must NOT be used as a path parameter.

        Always use the key. Using the numeric id will result in a 404 or an unexpected result.
      required: true
      schema:
        type: string
        example: ATC-20923
    ticketingProvider:
      in: header
      name: ticketing-provider
      description: Acronym identifying the underlying ticketing tool where the tickets are. JAM (Jira Amarillo), TGJ (TGJira), JNEXT (JiraNext), JNODUS (Jira Nodus), OCEANE (Oceane)
      schema:
        type: string
        enum:
          - JAM
          - TGJ
          - JNEXT
          - JNODUS
          - OCEANE
      required: true
    org:
      in: path
      name: org
      description: Organization name as it is registered in Mas-Stack
      required: true
      schema:
        type: string
      example: yoigo
    expand:
      in: query
      name: expand
      description: Filter for ticket response body. (You must add 'attachment' query param to get ticket attachments in response body)
      schema:
        type: string
        items:
          type: string
          enum:
            - history
            - attachment
    ticketType:
      in: query
      name: ticketType
      description: The ticket type in MasMovil ticketing tool
      required: true
      schema:
        type: string
    customer_id:
      in: query
      name: customer_id
      description: Customer ID to search for tickets
      required: false
      schema:
        type: string
        example: "12345"
    work_order_id:
      in: query
      name: work_order_id
      description: Work Order ID to search for tickets
      required: false
      schema:
        type: string
        example: "WO123456"
    line:
      in: query
      name: line
      description: Line number to search for tickets
      required: false
      schema:
        type: string
        example: "678900000"
    document_id:
      in: query
      name: document_id
      description: Document ID to search for tickets
      required: false
      schema:
        type: string
        example: "12345678X"
  responses:
    No_Content_204:
      description: No content
    IssueLinkResponse:
      description: Issue Link
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IssueLink'
    IssueLinkType:
      description: Issue Link response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IssueLinkType'
    EditableFields:
      description: Editable Fields for ticket
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EditableFields'
    201_Created_Ticket:
      description: Entity has been created succesfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TicketCreateResponse'
    CreationDataInfo:
      description: Fields for ticket type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreationDataInfo'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_404'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_400'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_401'
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_500'
  schemas:
    Ticket:
      type: object
      properties:
        key:
          type: string
          description: Ticket key reference.
        project:
          type: string
          description: Project key. RED, PROV, INST, etc. See Field Information request to query available values and field information.
        ticketType:
          type: string
          description: Ticket type. You can query available values using Get Ticket Types request.
        summary:
          type: string
          description: A simple summary for the ticket.
        description:
          type: string
          description: A detail description for the ticket.
        components:
          type: array
          items:
            type: string
          description: Components list. See Field Information request to query available values and field information.
        customFields:
          type: object
          description: Object containing extra custom fields depending on ticket typology
      example:
        key: INST-7902
        project: INST
        ticketType: Incidencia
        description: Cita - Cliente solicita contacto en fecha concreta - Y28257924
        summary: Cita - Y28257924
        customFields:
          segment: Residencial
          brand: Yoigo
          category: Cita
          subcategory: Cliente solicita contacto en fecha concreta
          work_order_id: Y28257924
    TicketSearchGetResponse:
      type: object
      properties:
        startAt:
          type: integer
          example: 0
        maxResults:
          type: integer
          example: 50
        total:
          type: integer
          example: 3
        tickets:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
    TicketCreateResponse:
      type: object
      properties:
        id:
          type: integer
          description: Ticket ID
          example: 3645
        key:
          type: string
          description: Ticket Key. You could reference the ticket by its key or by ID
          example: INST-1341
    TicketTypes:
      type: object
      properties:
        projectKey:
          type: string
          description: Project key reference
        name:
          type: string
          description: Project name
        issuetypes:
          description: Issue types list with all types available
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: issue type name
              description:
                type: string
                description: issue type description
      example:
        - projectKey: EKT
          name: Euskaltel
          issuetypes:
            - name: Aviso de llamada perdida
              description: Incidencia-Servicios
            - name: Contestador
              description: Incidencia-Servicios
            - name: No salta el aviso de saldo
              description: Incidencia-Servicios
        - projectKey: MM
          name: MásMóvil Customer Care
          issuetypes:
            - name: Problemas TV
              description: Incidencia
            - name: Desacuerdo con la cuota de TV
              description: Incidencia
            - name: Bloqueo por IMEI-Tarea
              description: Tarea-Móvil
    Comment:
      type: object
      properties:
        ticketId:
          type: string
          description: >-
            Ticket key in `PROJECT-NUMBER` format (e.g. `ATC-20923`).
            Use the key, not the numeric id (e.g. `937328`) — they are different identifiers.
          example: ATC-20923
        author:
          type: string
          description: Comment author, must match with ticketing provider user.
        body:
          type: string
          description: The text you want to add as a comment to the ticket
      example:
        ticketId: "INST-3241"
        body: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
      required:
        - body
    Attachment:
      type: object
      properties:
        name:
          type: string
          description: File name
        data:
          type: string
          description: File content in base64 format
        mimeType:
          type: string
          description: The file mime type. See https://docs.w3cub.com/http/basics_of_http/mime_types/complete_list_of_mime_types
      example:
        name: MYSIM_3847484.pdf
        data: /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxITEhUSEhMVFhUXGBcVFxUVFRUVF...
        mimeType: "image/jpeg"
      required:
        - name
        - data
    AttachmentResponse:
      type: object
      properties:
        self:
          type: string
          description: The URL of the attachment metadata details.
        content:
          type: string
          description: The URL of the attachment.
        filename:
          type: string
          description: The name of the attachment file. there is not much more to say
        created:
          type: string
          description: The datetime the attachment was created.
        size:
          type: integer
          description: The size of the attachment.
      example:
        self: https://mas-ticketing-sta.dev-01.k8s.masmovil.com/mas-ticketing-api/ticket/73232/attachment/24819
        content: https://mas-ticketing-sta.dev-01.k8s.masmovil.com/mas-ticketing-api/ticket/73232/attachment/24819/MYSIM_398171_53e82c60-075c-42ab-af94-868ef8b80071.pdf
        filename: MYSIM_398171_53e82c60-075c-42ab-af94-868ef8b80071.pdf
        created: 2022-01-13T09:20:22.556+0000
        mimeType: multipart/form-data; charset=UTF-8
        size: 5576
    AttachmentGETResponse:
      type: object
      properties:
        ticketId:
          type: string
          description: >-
            Ticket key in `PROJECT-NUMBER` format (e.g. `ATC-20923`).
            Use the key, not the numeric id (e.g. `937328`) — they are different identifiers.
          example: ATC-20923
        name:
          type: string
          description: Attachment file name
        attachmentId:
          type: integer
          description: Attachment Id
        base64:
          type: string
          description: Attachment content in base64 format
      example:
        ticketId: "ATC-20923"
        name: "MYSIM_398171_53e82c60-075c-42ab-af94-868ef8b80071.pdf"
        attachmentId: "24819"
        base64: "/9j/4AAQSkZJRgABAQAAAQABAAD/..."
    Transition:
      type: object
      properties:
        transitionId:
          type: integer
          description: Transition Id reference to operate with.
        status:
          type: string
          description: Status name reference to operate with. It´s optional, you can reference by transitionId or status
        customFields:
          type: object
          description: Custom fields to update during the transition. Use actual Jira custom field names as properties (e.g., external_system_name, external_system_info, solution_detail, etc.). Only fields allowed by the specific transition will be processed.
      example:
        transitionId: 111
        customFields:
          external_system_name: Orange
          external_system_info: Prueba de escalado externo via API de robot
          external_system_category: Instalación
      required:
        - transitionId
    SendCommsTransitionExample:
      type: object
      properties:
        transitionId:
          type: integer
          description: Transition Id to be executed
        communication_channel:
          type: string
          description: Communication channel to be used
        communication_type:
          type: string
          description: Type of the communication to be sent
        ticket:
          type: string
          description: Ticket key reference
        recipient:
          type: string
          description: Recipient's contact information
        url:
          type: string
          description: URL to be sent
        text:
          type: object
          description: Text for the communication
        preview:
          type: object
          description: Specifies whether a preview is needed
      example:
        transitionId: 351
        communication_channel: SMS
        communication_type: Informar Cierre Avería
        ticket: ATC-222117
        recipient: "677777777"
        url: ""
        text: test
        preview: No
    TransitionsResponse:
      type: object
      properties:
        id:
          type: integer
          description: Transition Id
        name:
          type: string
          description: Transitions name
        status:
          type: string
          description: Status destination
      example:
        - id: 41
          name: Reasignar
          status: Asignado
        - id: 21
          name: Resolver
          status: RESUELTO
    IssueLinkType:
      type: object
      properties:
        id:
          type: string
          description: IssueLinkType Id
        name:
          type: string
          description: IssueLinkType name
        inward:
          type: string
          description: Issue origin action
        outward:
          type: string
          description: Issue destination action
    IssueLink:
      type: object
      properties:
        id:
          type: string
          description: IssueLink Id
        type:
          type: object
          description:  IssueLink type
          properties:
            name:
              type: string
              description: IssueLink type name
        inwardIssue:
          type: object
          description: Issue origin reference
          properties:
            key:
              type: string
              description: Issue origin reference key
        outwardIssue:
          type: object
          description: Issue destination reference
          properties:
            key:
              type: string
              description: Issue destination reference key
    SearchRequest:
      type: object
      properties:
        filters:
          description: Object array with fields you want filter by and its conditions
          type: array
          items:
            type: object
            properties:
              ApiFieldName:
                type: string
                description: Api field name
              value:
                type: object
                description: Field Name value must be equals to direct value or macth the condition here requested
                properties:
                  operator:
                    type: string
                    description: condition operator. See operator enum
                    enum: [ $like, $in,$notIn,$isEmpty, $greaterThanEquals,$greaterThan, $lessThanEquals,$lessThan ]
                  value:
                    type: string
                    description: condition must match
        orderby:
          description: fields to order by plus asc or desc orientation Exmpl. key desc
          type: object
          properties:
            fields:
              type: array
              description: fields separated by coma and with desc o asc orientation
              items:
                type: object
                properties:
                  field:
                    type: string
        fields:
          type: array
          description: This property allows you filter the fields you want in the response body
          items:
            type: string
        startAt:
          type: integer
          description: Start position in the complete result, you want as firt item in the response body
        maxResults:
          type: integer
          description: Numbers of items you want back
      example:
        filters:
          project: "MAS"
          issuetype:
            $in: [ "Avería (FTTH)", "Avería (xDSL)" ]
          status:
            $notIn: [ "Resolved", "Descartado", "CLOSE" ]
          massiveFaults:
            $isNotEmpty: ""
        orderby:
          fields: [ "status desc" ]
        startAt: 0
        maxResults: 100
    UpdateGridRow:
      type: array
      items:
        type: object
        description: Rows from the grid
        properties:
          rowId:
            description: Row identificator of the row to be modified
            type: string
            example: row_94ba7042-c49b-4f53-971b-44549b9c08a0
          columns:
            description: Object containing the names (key value pairs) of the columns to be modified
            type: object
            additionalProperties:
              type: string
              example: test
    Assignee:
      type: object
      properties:
        assignee:
          type: string
          description: user id, username o email.
          example: javier.fernandezh
    EditableFields:
      type: object
      properties:
        description:
          type: object
          description: Field example
          properties:
            name:
              type: string
              description: Field name
              example: Descripción
        customerPostalCode:
          type: object
          description: Field example
          properties:
            name:
              type: string
              description: Field name
              example: Código Postal
        customerSegment:
          type: object
          description: Field example
          properties:
            name:
              type: string
              description: Field name
              example: Segmento Cliente
            allowedValues:
              type: array
              description: list of allowed values
              items:
                type: object
                properties:
                  value:
                    type: string
                    description: Field allowed values
              example:
                - value: EMPRESA
                - value: RESIDENCIAL
                - value: HORECA
                - value: AUTONOMO
    CreationDataInfo:
      type: object
      properties:
        subscriptionNumber:
          type: object
          description: Field example
          properties:
            required:
              type: boolean
              description: Field is required
              example: true
            name:
              type: string
              description: Field name
              example: Suscripción
        icc:
          type: object
          description: Field example
          properties:
            required:
              type: boolean
              description: Field is required
              example: false
            name:
              type: string
              description: Field name
              example: ICC
        contactEmail:
          type: object
          description: Field example
          properties:
            required:
              type: boolean
              description: Field is required
              example: false
            name:
              type: string
              description: Field name
              example: Email del Cliente
    IaSummaryResponse:
      type: object
      properties:
        operative_summary:
          type: string
          description: AI-generated operative summary of the ticket, describing the current situation and actions taken.
          example: "El cliente reporta fallo total de servicio FTTH desde el 12/02. Se ha realizado diagnóstico remoto sin resultado. Técnico desplazado el 14/02, detectó avería en la ONU. Pendiente reposición de equipo."
        message_for_client:
          type: string
          description: AI-generated message intended to be communicated to the client summarising the ticket status.
          example: "Estamos trabajando en la resolución de su incidencia. Un técnico ha visitado su domicilio y hemos identificado el problema. Procederemos a la sustitución del equipo en los próximos días."
      example:
        operative_summary: "El cliente reporta fallo total de servicio FTTH desde el 12/02. Se ha realizado diagnóstico remoto sin resultado. Técnico desplazado el 14/02, detectó avería en la ONU. Pendiente reposición de equipo."
        message_for_client: "Estamos trabajando en la resolución de su incidencia. Un técnico ha visitado su domicilio y hemos identificado el problema. Procederemos a la sustitución del equipo en los próximos días."
    IaDurationResponse:
      type: object
      properties:
        estimated_resolution_date:
          type: string
          description: AI-predicted estimated resolution date formatted as dd/MM/yyyy HH:mm
          example: "15/04/2026 14:30"
        estimated_minutes:
          type: number
          format: double
          description: Raw estimated minutes from ticket creation to resolution as predicted by the IA service.
          example: 301766.34
      example:
        estimated_resolution_date: "15/04/2026 14:30"
        estimated_minutes: 301766.34
    Error_400:
      type: object
      properties:
        code:
          type: string
          example: '0015'
          description: Error code number
        status:
          type: string
          description: Status error
          example: BAD_REQUEST
        message:
          type: string
          description: Error message
          example: Bad Request
        detailMsg:
          type: string
          description: Message detail
          example: detail message about the error
    Error_401:
      type: object
      properties:
        code:
          type: string
          example: '0003'
          description: Error code number
        status:
          type: string
          description: Status error
          example: UNAUTHORIZED
        message:
          type: string
          description: Error message
          example: Unauthorized
        detailMsg:
          type: string
          description: Message detail
          example: null
    Error_404:
      type: object
      properties:
        code:
          type: string
          example: '0004'
          description: Error code number
        status:
          type: string
          description: Status error
          example: NOT_FOUND
        message:
          type: string
          description: Error message
          example: Not found
        detailMsg:
          type: string
          description: Message detail
          example: Resource not found
    Error_500:
      type: object
      properties:
        code:
          type: string
          description: Error code number
          example: '0002'
        status:
          type: string
          description: Status error
          example: UNEXPECTED
        message:
          type: string
          description: Error message
          example: Unexpected Error
        detailMsg:
          type: string
          description: Message detail
          example: null
    InsightsMapResponse:
      type: object
      properties:
        size:
          type: integer
          description: Number of insight objects in the map
          example: 42
        response:
          type: object
          description: Map of insight objects indexed by their identifier
          additionalProperties:
            type: object
            description: Insight object details
          example:
            "1":
              id: "1"
              name: "Customer Assets"
              objectType: "Customer"
            "2":
              id: "2"
              name: "Network Devices"
              objectType: "Infrastructure"
    CustomFieldsSingleProviderResponse:
      type: object
      properties:
        ticketingProvider:
          type: string
          description: The ticketing provider acronym
          example: TGJ
        customFieldsCount:
          type: integer
          description: Total number of custom fields for this provider
          example: 45
        customFieldsObjects:
          type: object
          description: Detailed metadata for each custom field
          additionalProperties:
            type: object
            properties:
              id:
                type: string
                description: Jira custom field ID
              name:
                type: string
                description: Jira field label
              apiName:
                type: string
                description: API field name used in requests
              fieldType:
                type: string
                description: Field data type
          example:
            customer_document:
              id: customfield_10100
              name: Documento Cliente
              apiName: customer_document
              fieldType: string
            work_order_id:
              id: customfield_10101
              name: ID Orden de Trabajo
              apiName: work_order_id
              fieldType: string
    CustomFieldsAllProvidersResponse:
      type: object
      properties:
        providers:
          type: array
          description: List of custom fields data for each ticketing provider
          items:
            type: object
            properties:
              ticketingProvider:
                type: string
                description: The ticketing provider acronym
              customFieldsCount:
                type: integer
                description: Total number of custom fields for this provider
              customFieldsObjects:
                type: object
                description: Detailed metadata for each custom field
                additionalProperties:
                  type: object
        totalProviders:
          type: integer
          description: Total number of providers with custom fields
          example: 3

  x-othersOverviewInfo:
      description: |+

        ### Examples

        Examples can be found within the "Schemas" section, named using PascalCasing and with the word "Example" appended at the end.
        ```ThisIsAnExampleExample```
