openapi: 3.0.3
info:
  title: MasCustomer API v3
  description: >
    I am the MasCustomer API version 3.0.
    <br><br>
    <b>NOTE:</b> The examples provided here are made up and should not be used for testing purposes. Make sure to change all parameters before attempting to make any request.
  version: 3.11.0
externalDocs:
  description: Find out more about Swagger
  url: https://developer-portal-master.private.dev-01.k8s.masmovil.com/en/docs/
servers:
  # Public Servers
  - url: https://customers.sta.masstack.com/v3/
    description: staging
  - url: https://customers.masstack.com/v3/
    description: production

tags:
  - name: Customers
    description: Access to customers
  - name: Memos
    description: Gate to access memos information.
  - name: Typifications
    description: Access to ms-typifications api
  - name: Invoices
    description: Access to invoices


paths:
  /orgs/{orgId}/memos:
    get:
      tags:
        - Memos
      summary: Get all the memos, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      description: Get all the memos, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      operationId: memos
      deprecated: false
      security:
        - permissions:
            - customers.memos.list
      x-content-type: application/json
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/createFrom'
        - $ref: '#/components/parameters/createTo'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemosPag'
        '400':
          description: Parameters values not allowed or incorrect
          $ref: '#/components/responses/400BadRequestGeneric'
        '401':
          $ref: '#/components/responses/401UnauthorizedGeneric'
        '404':
          description: Memo not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '500':
          $ref: '#/components/responses/500InternalServerErrorGeneric'

  /orgs/{orgId}/memos/hosttable/{hosttable}:
    get:
      tags:
        - Memos
      summary: Get the memos by hostTable, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      description: Get the memos by hostTable, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      operationId: memosHostTable
      deprecated: false
      security:
        - permissions:
            - customers.memos.list
      x-content-type: application/json
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/hostTable'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/createFrom'
        - $ref: '#/components/parameters/createTo'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemosPag'
        '400':
          description: Parameters values not allowed or incorrect
          $ref: '#/components/responses/400BadRequestGeneric'
        '401':
          $ref: '#/components/responses/401UnauthorizedGeneric'
        '404':
          description: Memo not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '500':
          $ref: '#/components/responses/500InternalServerErrorGeneric'

  /orgs/{orgId}/memos/customers/{customerId}:
    get:
      tags:
        - Memos
      x-content-type: application/json
      summary: Get the memos by customerId, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      description: Get the memos by customerId, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      operationId: memosCustomer
      deprecated: false
      security:
        - permissions:
            - customers.memos.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/createFrom'
        - $ref: '#/components/parameters/createTo'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemosPag'
        '400':
          description: Parameters values not allowed or incorrect
          $ref: '#/components/responses/400BadRequestGeneric'
        '401':
          $ref: '#/components/responses/401UnauthorizedGeneric'
        '404':
          description: Memo not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '500':
          $ref: '#/components/responses/500InternalServerErrorGeneric'

  /orgs/{orgId}/memos/hosttable/{hosttable}/customers/{customerId}:
    get:
      tags:
        - Memos
      x-content-type: application/json
      summary: Get the memos by hostTable and customerId, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      description: Get the memos by hostTable and customerId, filtered by createStamp column if necessary. The number of elements in the  response cam be limited by the user.
      operationId: memosHostTableCustomer
      deprecated: false
      security:
        - permissions:
            - customers.memos.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/hostTable'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/createFrom'
        - $ref: '#/components/parameters/createTo'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemosPag'
        '400':
          description: Parameters values not allowed or incorrect
          $ref: '#/components/responses/400BadRequestGeneric'
        '401':
          $ref: '#/components/responses/401UnauthorizedGeneric'
        '404':
          description: Memo not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '500':
          $ref: '#/components/responses/500InternalServerErrorGeneric'

  /orgs/{orgId}/customers/{customerId}/devices:
    get:
      tags:
        - Customers
      summary: get devices financing info for mobile subscription type
      description: Returns financing info for mobile subscription devices for the purpose of calculating credit limits.
      operationId: getDevicesInfoByCustomerId
      security:
        - permissions:
            - customers.customers.devices.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesInfoByCustomerId'
        '400':
          description: Invalid account ID supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        '404':
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '405':
          $ref: '#/components/responses/405MethodNotAllowedGeneric'

  /orgs/{orgId}/accounts/{accountId}/invoices:
    patch:
      tags:
        - Invoices
      summary: Update invoice attributes
      operationId: updateInvoiceConfiguration
      security:
        - permissions:
            - customers.accounts.invoices.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceConfigUpdate'
      responses:
        '204':
          description: Invoice configuration updated
        '400':
          description: Invalid invoice configuration supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        '404':
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'

  /orgs/{orgId}/customers/{customerId}/typifications:
    post:
      tags:
        - Typifications
      summary: Insert new typifications
      operationId: postTypifications
      security:
        - permissions:
            - customers.customers.typifications.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        description: typification parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTypificationRequest'
      responses:
        '201':
          description: Typification created successfully. No content to return.
        '400':
          description: Parameters values not allowed or incorrect
          $ref: '#/components/responses/400BadRequestGeneric'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        '403':
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        '500':
          $ref: '#/components/responses/500InternalServerErrorGeneric'
    get:
      tags:
        - Typifications
      summary: Get customer typifications
      operationId: getTypifications
      security:
        - permissions:
            - customers.customers.typifications.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTypificationsResponse'
        '400':
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        '404':
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        '405':
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        '500':
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'

components:
  securitySchemes:
    permissions:
      type: apiKey
      in: header
      name: x-auth-roles
      description: Permissions are retrieved from roles, which come in a header

  parameters:
    # path parameters
    orgId:
      name: orgId
      in: path
      required: true
      description: organization name
      example: telco
      schema:
        type: string
    customerId:
      name: customerId
      in: path
      required: true
      description: customer identifier
      example: 214748364
      schema:
        type: integer
        format: int64
    accountId:
      name: accountId
      in: path
      required: true
      description: account identifier
      example: 214748364
      schema:
        type: integer
        format: int64
    hostTable:
      name: hosttable
      in: path
      required: true
      description: Name of table where this memo record is assignedSee HostTable.
      schema:
        type: string

    # query parameters
    limit:
      name: limit
      in: query
      example: 100
      required: false
      deprecated: false
      description: Limit the elements numbers in response
      schema:
        type: integer
        format: int64
    offset:
      name: offset
      in: query
      example: 100
      required: false
      deprecated: false
      description: Move the pointer to the first element in response
      schema:
        type: integer
        format: int64
    createFrom:
      name: create-from
      in: query
      example: '2020-01-01'
      description: start date query against createStamp column, with format yyyy-mm-dd, for example 2020-01-01
      required: false
      schema:
        type: string
        format: date
    createTo:
      name: create-to
      in: query
      example: '2020-12-31'
      description: end date query against createStamp column with format yyyy-mm-dd, for example 2020-01-01
      required: false
      schema:
        type: string
        format: date

  responses:
    400BadRequestGeneric:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    401UnauthorizedGeneric:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            code: 0003
            status: UNAUTHORIZED
            message: Unauthorized
            DetailMsg: Tenant XXX could not be validated
    403ForbiddenGeneric:
      description: Forbidden resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            code: 10
            status: FORBIDDEN
            message: Forbidden
            DetailMsg: The state does not allow login
    404NotFoundGeneric:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    405MethodNotAllowedGeneric:
      description: Method not allowed
      content: { }
    500InternalServerErrorGeneric:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            code: 0002
            status: UNEXPECTED
            message: Unexpected error
            DetailMsg: "com.masorange.mcus.core.application.errors.UnexpectedException: Unexpected error"

  schemas:
    GetTypificationsResponse:
      type: object
      properties:
        typifications:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - created_at
              - channel
              - user_id
              - msisdn
              - campaign
              - reason
            properties:
              id:
                type: string
              created_at:
                type: string
                format: date-time
                description: Typification creation date
                example: "2022-01-01T01:01:01Z"
              channel:
                type: string
                description: Channel where the typification was performed
                example: "agents"
              tenant:
                type: string
                description: Tenant where the typification was performed
                example: "masmovil"
              area:
                type: string
                description: User area where the typification was performed
                example: "RETENCION"
              user_id:
                type: string
                description: User performing the typification.
              msisdn:
                type: string
                description: Phone number related to the typification
                example: "612789456"
              campaign:
                type: string
                description: Campaign related to the typification
              reason:
                type: string
                description: Typification reason
              subreason1:
                type: string
                description: Typification subreason1
              subreason2:
                type: string
                description: Typification subreason2
              result:
                type: string
                description: Typification result
              subresult:
                type: string
                description: Typification subresult
              conversation_id:
                type: string
                description: Conversation identifier related to the typification
              operator:
                type: string
                description: Operator related to the typification
              description:
                type: string
                description: Typification description
              initial_fee:
                type: number
                format: float

    CreateTypificationRequest:
      type: object
      additionalProperties: false
      required:
        - channel
        - user_id
        - msisdn
        - campaign
        - reason
      properties:
        channel:
          type: string
          description: Channel where the typification was performed
          example: agents
        user_id:
          type: string
          description: User performing the typification. It takes an email format
        msisdn:
          type: string
          description: Phone number related to the typification
          pattern: "^[6-9][0-9]{8}$"
        conversation_id:
          type: string
          description: Conversation identifier related to the typification
        operator:
          type: string
          description: Operator related to the typification
        campaign:
          type: string
          description: Campaign related to the typification
        reason:
          type: string
          description: Typification reason
        subreason1:
          type: string
          description: Typification subreason1
        subreason2:
          type: string
          description: Typification subreason2
        result:
          type: string
          description: Typification result
        subresult:
          type: string
          description: Typification subresult
        description:
          type: string
          description: Typification description
        initial_fee:
          type: number
          format: float

    DevicesInfoByCustomerId:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/DeviceResponseByCustomerId'

    Memo:
      type: object
      required:
        - host_table
      properties:
        id:
          type: string
          description: primary key
          example: "e18f3337-433a-45a2-95e4-0ebece657743"
        host_table:
          type: string
          description: HostTable in  cassandra database
          example: "ModSub"
        key_value:
          type: string
          description: KeyValue in  cassandra database
          example: CoRuleID
        memo_seq:
          type: integer
          format: int64
          description: MemoSeq in  cassandra database
          example: 214748364
        customer_num:
          type: integer
          format: int64
          description: CustNum in  cassandra database
          example: 214748364
        customer_external_id:
          type: integer
          format: int64
          description: Customer external Id
          example: 214748364
        subscription_id:
          type: integer
          format: int64
          description: Customer external Id
          example: 214748364
        memo_title:
          type: string
          description: MemoTitle in  cassandra database
          example: "FixedLine Barring"
        memo_text:
          type: string
          description: MemoText in cassandra database
          example: "En un lugar de la Mancha, de cuyo nombre no quiero acordarme, no ha mucho tiempo que vivía un hidalgo de los de lanza en astillero, adarga antigua, rocín flaco y galgo corredor. Una olla de algo más vaca que carnero, salpicón las más noches, duelos y quebrantos los sábados, lantejas los viernes, algún palomino de añadidura los domingos, consumían las tres partes de su hacienda. El resto della concluían sayo de velarte, calzas de velludo para las fiestas, con sus pantuflos de lo mesmo, y los días de entresemana se honraba con su vellorí de lo más fino. Tenía en su casa una ama que pasaba de los cuarenta y una sobrina que no llegaba a los veinte, y un mozo de campo y plaza que así ensillaba el rocín como tomaba la podadera. Frisaba la edad de nuestro hidalgo con los cincuenta años. Era de complexión recia, seco de carnes, enjuto de rostro, gran madrugador y amigo de la caza."
        memo_type:
          type: string
          description: MemoType in cassandra database
          example: "Service"
        source:
          type: string
          format: int64
          description: Source in cassandra database
          example: 214748364
        create_stamp:
          type: string
          format: date
          description: CreStamp in cassandra database
          example: "2020-01-31"
        create_user:
          type: string
          description: CreUser in  cassandra database
          example: "123654"
        change_stamp:
          type: string
          format: date
          description: ChgStamp in cassandra database
          example: "2020-01-31"
        change_user:
          type: string
          format: int64
          description: ChgUser in  cassandra database
          example: 214748364

    Memos:
      type: object
      properties:
        memos:
          type: array
          items:
            $ref: '#/components/schemas/Memo'

    MemosPag:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Memos'
        next_request:
          type: string
          description: Url next set of data
          example: http://localhost:8081/memos/?limit=40&offset=0

    DeviceResponseByCustomerId:
      type: object
      properties:
        start_date:
          type: string
          format: date-time
          example: "2020-01-31T00:00:00Z"
        subscription_id:
          type: integer
          format: int64
          description: identification subscription
          example: 123654
        subscription_terminal_id:
          type: integer
          format: int64
          description: subscription terminal id
          example: 214748364
        status:
          $ref: '#/components/schemas/StatusDevices'
        fees:
          $ref: '#/components/schemas/Fees'
        permanence:
          $ref: '#/components/schemas/Permanence'
        is_mandatory:
          type: boolean
          example: true
        expedition_info:
          $ref: '#/components/schemas/ExpeditionInfo'

    StatusDevices:
      type: object
      description: status device
      required:
        - id
        - value
      properties:
        id:
          type: integer
          format: int32
          description: identification device status
          example: 214748364
        value:
          type: string
          description: Device status value
          example: ACTIVO

    Permanence:
      type: object
      description: permanence info
      properties:
        campaign_id:
          type: number
          format: int32
          description: id campaig
          example: 214748364
        description:
          type: string
          description: permanence description
          example: "Permanencia 24M"
        duration_months:
          type: integer
          format: int32
          description: duration months
          example: 24
        start_date:
          type: string
          format: date-time
          example: "2020-01-31T00:00:00Z"
          description: binding start date
        end_date:
          type: string
          format: date-time
          example: "2022-01-31T00:00:00Z"
          description: binding end date
        category_type:
          type: integer
          format: int32
          description: category type
          example: 1

    Fees:
      type: object
      description: device info
      properties:
        upfront_fee:
          type: number
          format: double
          description: upfront fee (initial payment)
          example: 0
        installment_plan:
          $ref: '#/components/schemas/InstallmentPlan'
        final_installment_plan:
          $ref: '#/components/schemas/InstallmentPlan'

    InstallmentPlan:
      type: object
      description: request detail
      properties:
        last_installment_fee:
          type: number
          format: double
          description: final payment
          example: 0.0
        monthly_fee:
          type: number
          format: double
          description: monthly fee
          example: 6.00
        duration:
          type: integer
          format: int32
          description: duration (total permanence)
          example: 0
        unpaid_installments:
          type: integer
          format: int32
          description: pending fees
          example: 10
        financed_by:
          type: string
          example: "MASMOVIL"

    ExpeditionInfo:
      type: object
      description: expedition info
      properties:
        item_number:
          type: number
          format: int64
          description: item number
          example: 214748364
        request_date:
          type: string
          format: date-time
          example: "2020-01-31T00:00:00Z"
          description: request date
        expedition_date:
          type: string
          format: date-time
          example: "2020-01-31T00:00:00Z"
          description: expedition date
        status:
          $ref: '#/components/schemas/Status'

    Status:
      type: object
      description: status
      required:
        - id
        - value
      properties:
        id:
          type: integer
          format: int32
          description: identification status
          example: 214748364
        value:
          type: string
          description: status value
          example: ACTIVO

    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: Custom error code
        status:
          type: string
          description: Status
        message:
          type: string
          description: Status message
        detailMsg:
          type: string
          description: Detailed description of the error

    InvoiceConfigUpdate:
      type: object
      description: New invoice configuration
      required:
        - delivery_mode
      properties:
        delivery_mode:
          type: string
          description: New delivery mode
          enum:
            - EMAIL
            - PAPER
            - APPLICATION

  x-releaseInfo:
    description: >

      ### Release Notes
      * **3.11.0**: Deprecate and remove energy endpoint (MCUS-3999)
       - DELETE POST /orgs/{orgId}/event (entire endpoint removed).
       - Removed V3 events: sellProductsV3, activateSubscriptionsV3, terminatedSubscriptionsV3, cancelledSubscriptionsV3
       - Reason: Lucera energy integration no longer in use
       - DELETE GET /orgs/{orgId}/customers/{customerId}/credentials (entire endpoint removed).

      * **3.10.2**: Permission unification.
      
      * **3.10.1**: Deprecate endpoints.
       - PATCH /orgs/{orgId}/accounts/{accountId}/payment-method (DELETE).
      
      * **3.10.0**: Add field financed_by new in get devices response inside InstallmentPlan object
        - financed_by
        
      * **3.9.1**: Add fields new in get devices response
        - category_type
        - start_date
        
      * **3.9.0**: Add endpoint to update invoice delivery mode. updateInvoiceConfiguration
        - PATCH /orgs/{orgId}/accounts/{accountId}/invoices
      
      * **3.8.0**: Add endpoint to fetch customer typifications. getTypifications
        - GET /orgs/{orgId}/customers/{customerId}/typifications
    
      * **3.7.0**: Add endpoint to create typifications. postTypifications
        - POST /orgs/{orgId}/customers/{customerId}/typifications
      
      * **3.6.0**: Delete endpoint to get customer
       - Deleted GET /orgs/{orgId}/customers/{customerId}
      
      * **3.5.0**: Add endpoint to update account payment method
        - New endpoint
          - /orgs/{orgId}/accounts/{accountId}/payment-method
      * **3.4.0**: Add endpoint to get customer details by customerId
        - New endpoint
          - /orgs/{orgId}/customers/{customerId}
      * **3.3.0**: Change GET devices response
        - Adds new field to
          - /orgs/{orgId}/customers/{customerId}/devices
      
      * **3.2.0**: Add endpoint to get customer credentials
        - New endpoint
          - /orgs/{orgId}/customers/{customerId}/credentials
      
      * **3.0.4**: Bug fix documentation to  Memos Api . 
        - Make query field optional
        - Examples with real data
      
      * **3.0.3**: Fix devices field name. 
        - Changed <code>terminals</code> field to <code>devices</code>
      
      * **3.0.2**: Add documentation to  Memos Api . 
        - /orgs/{orgId}/memos
        - /orgs/{orgId}/memos/hosttable/{hosttable}
        - /orgs/{orgId}/memos/customers/{customerId}
        - /orgs/{orgId}/memos/hosttable/{hosttable}/customers/{customerId}

      * **3.0.1**: Add Memos Api endPoints to access memorandum backend. 
        - New endpoints
          - /orgs/{orgId}/memos
          - /orgs/{orgId}/memos/hosttable/{hosttable}
          - /orgs/{orgId}/memos/customers/{customerId}
          - /orgs/{orgId}/memos/hosttable/{hosttable}/customers/{customerId}
      
      * **3.0.0**: First version to v3
        - New endpoint
          - /orgs/{orgId}/customers/{customerId}/devices

  x-othersOverviewInfo:
    description: >

      ### More info
