openapi: 3.0.3
info:
  title: MasCustomers API
  description: >
    I am <b><i>MasCustomers API</i></b>. My intention is provide the necessary functionality to be able to give E2E coverage to the entire life-cycle of a client.
    <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: 4.66.4
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/v4
    description: staging
  - url: https://customers.masstack.com/v4
    description: production
tags:
  - name: Accounts
    description: Access to accounts
    externalDocs:
      description: Real examples, happy paths and error scenarios for account operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-accounts-api-features
  - name: External accounts
    description: Access to external accounts
    externalDocs:
      description: Real examples, happy paths and error scenarios for external accounts operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-accounts-api-features
  - name: Customers
    description: Access to customers
    externalDocs:
      description: Real examples, happy paths and error scenarios for customer operations
      url:  https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-customers-api-features
  - name: External customers
    description: Access to external customers
    externalDocs:
      description: Real examples, happy paths and error scenarios for external customers operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-customers-api-features
  - name: Categories
    description: Access to customer categories
    externalDocs:
      description: Real examples, happy paths and error scenarios for category operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-accounts-api-features
  - name: Customers Categories
    description: Access to customer categories
    externalDocs:
      description: Real examples, happy paths and error scenarios for customer categories operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-categories-api-features
  - name: Special Treatment
    description: Access to special treatment
    externalDocs:
      description: real examples, happy paths and error scenarios for special treatment operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-special-treatment-api-features
  - name: Customer Special Treatment
    description: Access to customers special treatment
    externalDocs:
      description: real examples, happy paths and error scenarios for customer special treatment operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-special-treatment-api-features
  - name: Credit Card Tokenization
    description: Credit card tokenization request operations
  - name: Customer credentials
    description: Access to customer credentials
    externalDocs:
      description: Real examples, happy paths and error scenarios for customer credentials operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-credentials-api-features
  - name: Customer identification processes
    description: Access to customer identification processes
    externalDocs:
      description: Real examples, happy paths and error scenarios for customer identification processes operations
      url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-documents-api-features

paths:
  /orgs/{org_id}/customers:
    post:
      tags:
        - Customers
      summary: Post customer information
      description: |
        Create a single customer.  
        During customer registration, the contact email is used to register the customer's contact email and credentials. Therefore, it is validated that this email address does not already exist as another customer's credentials.  
        However, when modifying this data from the PATCH Customer endpoint, only the contact email can be modified, without making any changes to the credentials, and therefore no validation is performed, since different customers can have the same contact email.
      operationId: postCustomer
      security:
        - permissions:
            - customers.customers.create
      parameters:
        - $ref: '#/components/parameters/orgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              discriminator:
                propertyName: type
                mapping:
                  'PRIVATE_CUSTOMER': '#/components/schemas/NewPrivateCustomer'
                  'CORPORATE_CUSTOMER': '#/components/schemas/NewCorporateCustomer'
                  'DIGITAL_CUSTOMER': '#/components/schemas/NewDigitalCustomer'
              oneOf:
                - $ref: '#/components/schemas/NewPrivateCustomer'
                - $ref: '#/components/schemas/NewCorporateCustomer'
                - $ref: '#/components/schemas/NewDigitalCustomer'
            examples:
              post_private_customer:
                $ref: '#/components/examples/post_private_customer'
              post_corporate_customer:
                $ref: '#/components/examples/post_corporate_customer'
              post_digital_customer:
                $ref: '#/components/examples/post_digital_customer'
      responses:
        "201":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCreated'
        "400":
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "409":
          description: Customer with same externalId exists
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/search:
    get:
      tags:
        - Customers
      summary: Get customer ids associated to a given identity document or email. When searching by identity document, the type of document must be provided.
      description: Returns customer ids
      operationId: searchCustomer
      security:
        - permissions:
            - customers.customers.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/identityDocument'
        - $ref: '#/components/parameters/identityDocumentType'
        - $ref: '#/components/parameters/email'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchResponse'
        "400":
          description: Invalid parameter supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}:
    get:
      tags:
        - Customers
      summary: Get customer information
      description: Returns all the info about a single customer given by customer id.
      operationId: getCustomer
      security:
        - permissions:
            - customers.customers.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              examples:
                get_digital_customer:
                  $ref: '#/components/examples/get_digital_customer'
                get_private_customer:
                  $ref: '#/components/examples/get_private_customer'
                get_corporate_customer:
                  $ref: '#/components/examples/get_corporate_customer'
        "400":
          description: Invalid customer id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    delete:
      tags:
        - Customers
      summary: Delete customer information
      description: Delete customer by its id.
      operationId: deleteCustomer
      security:
        - permissions:
            - customers.customers.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid customer id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    patch:
      tags:
        - Customers
      summary: Update customer information
      description: |
        Update customer information.   
        When modifying the contact email, only this data can be modified, without making any changes to the credentials, and therefore no validation is performed, since different customers can have the same contact email.
      operationId: patchCustomer
      security:
        - permissions:
            - customers.customers.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCustomerRequest'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
      externalDocs:
        description: Real examples, happy paths and error scenarios for customer patch operation
        url: https://github.com/masmovil/mm-monorepo/tree/master/pkg/mas-stack/bss/mas-customers/customers/customers-api/src/acceptance/resources/mas-customers-customers-api-features/customer_patch.feature

  /orgs/{org_id}/accounts/{account_id}:
    get:
      tags:
        - Accounts
      summary: Get account information
      description: Returns all the info about a single account given by account id.
      operationId: getAccount
      security:
        - permissions:
            - customers.accounts.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccount'
              examples:
                get_telco_postpaid_account_with_direct_debit:
                  $ref: '#/components/examples/get_telco_postpaid_account_with_direct_debit'
                get_telco_postpaid_account_with_bank_transfer:
                  $ref: '#/components/examples/get_telco_postpaid_account_with_bank_transfer'
                get_telco_postpaid_account_with_teci:
                  $ref: '#/components/examples/get_telco_postpaid_account_with_teci'
                get_digital_recurring_prepaid_account:
                  $ref: '#/components/examples/get_digital_recurring_prepaid_account'

        "400":
          description: Invalid account id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/payment-method:
    patch:
      tags:
        - Accounts
      summary: Update account payment method
      description: Update account payment method for a given account id
      operationId: patchAccountPaymentMethod
      security:
          - permissions:
              - customers.accounts.paymentmethod.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAccountPaymentMethod'
            examples:
              patch_account_payment_method_credit_card:
                $ref: '#/components/examples/patch_account_payment_method_credit_card'
              patch_account_payment_method_direct_debit:
                $ref: '#/components/examples/patch_account_payment_method_direct_debit'
              patch_account_payment_method_bank_transfer:
                $ref: '#/components/examples/patch_account_payment_method_bank_transfer'

      responses:
        "202":
          description: Asynchronous payment method update accepted (credit card with reference_id for pending tokenization)
        "204":
          description: Synchronous payment method update completed successfully (bank transfer, direct debit, or credit card with token_id)
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/payment-methods/historical:
    get:
      tags:
        - Accounts
      summary: Get account payment methods history
      description: |-
        Returns the history of payment methods for a single account given by account id.
        The result includes all historical payment methods with their details.
      operationId: getAccountPaymentMethodsHistory
      security:
        - permissions:
            - customers.accounts.paymentmethod.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodHistoryResponse'
        "400":
          description: Invalid account id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/billing-address:
    get:
      tags:
        - Accounts
      summary: Get account billing address history
      description: |-
        Returns the history of billing address changed about a single account given by account id.  
        You can filter the time period you want to query. To do this, you must enter the **'from'** and **'to'* query parameters. Neither field is required for the query. If you do not enter these fields, the entire billing address change history for the account will be displayed. If you enter these fields, they must be entered in the **yyyy-MM-dd** format.
      operationId: getAccountBillingAddressHistory
      security:
        - permissions:
            - customers.accounts.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAddressHistoryResponse'
        "400":
          description: Invalid account id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/invoice-recipient:
    get:
      tags:
        - Accounts
      summary: Get account invoice address information
      description: |-
        Returns the invoice address information about a single account given by account id.
      operationId: getAccountInvoiceAddress
      security:
        - permissions:
            - customers.accounts.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceAddressResponse'
        "400":
          description: Invalid account id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/promotions:
    post:
      tags:
        - Accounts
      summary: Add promotion to account
      description: Add promotion for a given account id
      operationId: postAccountPromotion
      security:
        - permissions:
            - customers.accounts.promotions.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPromotions'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    get:
      tags:
        - Accounts
      summary: get account promotions
      description: >
        list account promotions by account<br>
        ACTIVATED: Returns the list of active promotions for the account. Those with a past activated_date and future expiration_date, which must be applied to the customer's invoice. This is the default value if not sent.<br>
        SCHEDULED: Returns the list of scheduled promotions: those with a future activation date.<br>
        ALL: includes all those mentioned in the previous two.
      operationId: getAccountPromotions
      security:
        - permissions:
            - customers.accounts.promotions.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/accountPromotionType'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPromotions'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/promotions_hist:
    get:
      tags:
        - Accounts
      summary: get promotion history to accounts
      description: get all operation to promotions to account by date
      operationId: getAccountPromotionHistories
      security:
        - permissions:
            - customers.accounts.promotions.history.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/startDate'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPromotionHistories'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/tokenization-requests:
    get:
      tags:
        - Credit Card Tokenization
      summary: Get credit card tokenization requests
      description: Returns all tokenization requests for an account, ordered by creation date (most recent first)
      operationId: getAccountCreditCardTokenizationRequests
      security:
        - permissions:
            - customers.accounts.paymentmethod.tokenization.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCardTokenizationRequestListDTO'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/accounts/{account_id}/promotions/{account_promotion_id}:
    patch:
      tags:
        - Accounts
      summary: Update promotion account
      description: Update cancellation date to account promotion
      operationId: patchAccountPromotion
      security:
        - permissions:
            - customers.accounts.promotions.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/accountPromotionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAccountPromotion'
            examples:
              post_account_promotion:
                $ref: '#/components/examples/request_account_promotion_update'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/associated_users:
    put:
      tags:
        - Customers
      summary: Set customer authorized representative
      description: >
        Creates or updates the authorized representative of a business customer.

        The `associated_users` array must contain exactly one element.

        Currently, only the `AUTHORIZED_REPRESENTATIVE` role is supported.
        If `role` is not provided, it defaults to `AUTHORIZED_REPRESENTATIVE`.
      operationId: putCustomerRepresentative
      security:
        - permissions:
            - customers.customersRepresentative.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutAssociatedUsersRequest'
            example:
              associated_users:
                - identity_document:
                    number: "12345678Z"
                    type: "NIF"
                  role: "AUTHORIZED_REPRESENTATIVE"
                  name: "John"
                  first_surname: "Doe"
                  second_surname: "Smith"
                  nationality: "ES"
      responses:
        "204":
          description: Authorized representative set successfully
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/available-credit-cards:
    get:
      tags:
        - Customers
      summary: Get customer tokenized credit cards
      description: Returns all tokenized credit cards for the specified customer id
      operationId: getCustomerTokenizedCreditCards
      security:
        - permissions:
            - customers.customers.creditcard.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Credit cards returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTokenizedCreditCards'

  /orgs/{org_id}/customers/{customer_id}/categories/historical:
    get:
      tags:
        - Customers Categories
      summary: Get customer category history values
      description: For a given customer id, returns the history for category updates
      operationId: getCustomerCategoryHistory
      security:
        - permissions:
            - customers.customers.categories.history.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Customer Category History returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCategoryHistory'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/categories:
    post:
      tags:
        - Customers Categories
      summary: Post new customer category
      description: Associates a new category id for a specified customer id
      operationId: postCustomerCategoryById
      security:
        - permissions:
            - customers.customers.categories.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCustomerCategory'
      responses:
        "201":
          description: Categories added successfully
          content: {}
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id or category id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Customer category already exists
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

    get:
      tags:
        - Customers Categories
      summary: Get customer categories
      description: Returns all categories for the specified customer id
      operationId: getCustomerCategories
      security:
        - permissions:
            - customers.customers.categories.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Categories returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCategories'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/categories/{category_id}:
    get:
      tags:
        - Customers Categories
      summary: Get customer category by id
      description: Returns one category for the specified customer id and category id
      operationId: getCustomerCategoryById
      security:
        - permissions:
            - customers.customers.categories.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/categoryId'
      responses:
        "200":
          description: Category returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCategory'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id or category id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    delete:
      tags:
        - Customers Categories
      summary: Delete customer category by id
      description: Delete one category for the specified customer id and category id
      operationId: deleteCustomerCategoryById
      security:
        - permissions:
            - customers.customes.categories.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/categoryId'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id or category id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    patch:
      tags:
        - Customers Categories
      summary: Update customer category information by customer and category id
      description: Update customer category information by customer and category id
      operationId: patchCustomerCategoryById
      security:
        - permissions:
            - customers.customers.categories.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/categoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCustomerCategory'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer id or category id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/external-customers/{customer_external_id}:
    get:
      tags:
        - External customers
      summary: Get customer id by external id
      description: Returns customer id given by customer external id
      operationId: getCustomerIdByCustomerExternalId
      security:
        - permissions:
            - customers.customers.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerExternalId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerId'
        "400":
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/external-accounts/{account_external_id}:
    get:
      tags:
        - External accounts
      summary: Get account id by external id
      description: Returns account id given by account external id
      operationId: getAccountIdByAccountExternalId
      security:
        - permissions:
            - customers.accounts.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountExternalId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountId'
        "400":
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/external-accounts/{account_external_id}/contracts:
    get:
      tags:
        - External accounts
      summary: Get all contracts by account external id
      description: Returns all contracts by account external id
      operationId: getContractsByAccountExternalId
      security:
        - permissions:
            - customers.accounts.contracts.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountExternalId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contracts'
        "400":
          description: Invalid account external id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account external id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/external-accounts/{account_external_id}/contracts/active:
    get:
      tags:
        - External accounts
      summary: Get active contract by account external id
      description: Returns active contract by account external id
      operationId: getActiveContractsByAccountExternalId
      security:
        - permissions:
            - customers.accounts.contracts.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/accountExternalId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        "400":
          description: Invalid account external id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Account external id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/categories:
    get:
      tags:
        - Categories
      summary: Get categories
      description: Returns all categories for the specified tenant
      operationId: getCategories
      security:
        - permissions:
            - customers.categories.list
      parameters:
        - $ref: '#/components/parameters/orgId'
      responses:
        "200":
          description: All categories returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Categories'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    post:
      tags:
        - Categories
      summary: Post categories
      description: Inserts new categories for the specified tenant
      operationId: postCategories
      security:
        - permissions:
            - customers.categories.create
      parameters:
        - $ref: '#/components/parameters/orgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCategories'
      responses:
        "201":
          description: Categories created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Categories'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/categories/{category_id}:
    get:
      tags:
        - Categories
      summary: Get category
      description: Returns specified category
      operationId: getCategory
      security:
        - permissions:
            - customers.categories.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/categoryId'
      responses:
        "200":
          description: Category returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Category not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    patch:
      tags:
        - Categories
      summary: Update category information
      description: Update category information
      operationId: patchCategory
      security:
        - permissions:
            - customers.categories.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/categoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCategory'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid category_id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Category not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    delete:
      tags:
        - Categories
      summary: Delete category by id
      description: Delete the category by its id
      operationId: deleteCategoryById
      security:
        - permissions:
            - customers.categories.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/categoryId'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Category id not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/credentials:
    post:
      tags:
        - Customer credentials
      summary: post customer credential
      description: Create customer credential
      operationId: postCredentialByCustomerId
      security:
        - permissions:
            - customers.customers.credentials.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
      responses:
        "201":
          description: Credential added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialCreated'
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: There is a credential conflict because it already exists
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    get:
      tags:
        - Customer credentials
      summary: get customer credentials
      description: Return customer credentials
      operationId: getCredentialsByCustomerId
      security:
        - permissions:
            - customers.customers.credentials.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Customer credentials returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credentials'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Credential not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'
    patch:
      tags:
        - Customer credentials
      summary: update customer credential expiration date
      description: Update expiration date of a customer credential
      operationId: patchCustomerCredentialById
      security:
        - permissions:
            - customers.customersCredentials.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCustomerCredentialRequest'
      responses:
        "204":
          description: Credential expiration date updated successfully
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or credential not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/credentials/change:
    post:
      tags:
        - Customer credentials
      summary: change customer credential username
      description: |
        Changes the username of a customer credential. Handles both RESERVED and ACTIVE credentials.
        For ACTIVE credentials: updates +CRED system and sends notification.
        For RESERVED credentials: updates database only.
      operationId: changeCustomerCredentials
      security:
        - permissions:
            - customers.customersCredentials.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeCredentialRequest'
      responses:
        "204":
          description: Credential username changed successfully (no content)
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or credential not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: New username already exists for another customer
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/credentials/migration:
    post:
      tags:
        - Customer credentials
      summary: post customer credential for migrations
      description: Create customer credential for migrations
      operationId: postCredentialMigrationByCustomerId
      security:
        - permissions:
            - customers.customersCredentialsMigration.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
      responses:
        "201":
          description: Credential added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialCreated'
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: There is a credential conflict because it already exists
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/special-treatment:
    get:
      tags:
        - Special Treatment
      summary: Get special treatment
      description: Returns all special treatments for the specific tenant
      operationId: listSpecialTreatments
      security:
        - permissions:
            - customers.categories.specialtreatment.list
      parameters:
        - $ref: '#/components/parameters/orgId'
      responses:
        "200":
          description: List of special treatment values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecialTreatmentValues'
        "400":
          description: Invalid supplied tenant
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Resource not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

    patch:
      tags:
        - Special Treatment
      summary: Update special treatment
      description: Update the list of valid special treatment values for this tenant
      operationId: updateSpecialTreatments
      parameters:
        - $ref: '#/components/parameters/orgId'
      security:
        - permissions:
            - customers.categories.specialtreatment.update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecialTreatmentValues'
      responses:
        "204":
          description: Special treatment values updated successfully
        "400":
          description: Invalid special treatment values
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/special-treatment:
    get:
      tags:
        - Customer Special Treatment
      summary: Get customer special treatment
      description: >
        Returns the special treatment assigned to the customer.
        Currently, only one value is allowed.
      operationId: getCustomerSpecialTreatment
      security:
        - permissions:
            - customers.customers.categories.specialtreatment.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Special treatment assigned to the customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSpecialTreatment'
        "400":
          description: Invalid special treatment values
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Resource not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

    put:
      tags:
        - Customer Special Treatment
      summary: Set customer special treatment
      description: >
        Creates or updates the special treatment assigned to a customer.
        The special treatment is associated with a single customer.
        Only one special treatment for customer is handled at the moment
      operationId: putCustomerSpecialTreatment
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      security:
        - permissions:
            - customers.customers.categories.specialtreatment.update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSpecialTreatment'
      responses:
        "204":
          description: Customer special treatment set successfully
        "400":
          description: Invalid request body
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Resource not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'

    delete:
      tags:
        - Customer Special Treatment
      summary: Delete customer special treatment
      description: Deletes the special treatment assigned to the customer
      operationId: deleteCustomerSpecialTreatment
      security:
        - permissions:
            - customers.customers.categories.specialtreatment.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "204":
          description: Successful operation
        "400":
          description: Invalid request
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer special treatment not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/credentials/{credential_id}:
    delete:
      tags:
        - Customer credentials
      summary: delete customer credential
      description: Delete customer credential given its id
      operationId: deleteCredentialById
      security:
        - permissions:
            - customers.customers.credentials.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/credentialId'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid customer id or credential id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or credential not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Validation exception
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/credentials/activate:
    post:
      tags:
        - Customer credentials
      summary: activate customer credential
      description: Activate customer credential
      operationId: activateCredentialByCustomerId
      security:
        - permissions:
            - customers.customersCredentials.update
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "202":
          description: Credential activation accepted
        "400":
          description: Invalid request
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or credential not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/accounts:
    get:
      tags:
        - Accounts
      summary: Get the account ID list
      description: Get the account ID list for a single customer
      operationId: getAccountsByCustomerId
      security:
        - permissions:
            - customers.accounts.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: Customer accounts returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountIds'
        "400":
          description: Invalid customer supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

    post:
      tags:
        - Accounts
      summary: Post account information
      description: Create account information about a single account and a single customer
      operationId: postAccountByCustomerId
      security:
        - permissions:
            - customers.accounts.create
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAccount'
            examples:
              post_postpaid_account_iban:
                $ref: '#/components/examples/post_postpaid_account_iban'
              post_postpaid_account_bank_transfer:
                $ref: '#/components/examples/post_postpaid_account_bank_transfer'
              post_postpaid_account_credit_card:
                $ref: '#/components/examples/post_postpaid_account_credit_card'
      responses:
        "200":
          description: Synchronous workflow completed successfully (bank transfer, direct debit, or credit card with token_id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCreated'
        "202":
          description: Asynchronous workflow accepted (credit card with reference_id for pending tokenization)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCreated'
        "400":
          description: Invalid supplied request
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/accounts/{account_id}:
    delete:
      tags:
        - Accounts
      summary: Delete account information
      description: Delete account information about a single account and a single customer given by the ids.
      operationId: deleteAccountByCustomerIdAndAccountId
      security:
        - permissions:
            - customers.accounts.delete
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "204":
          description: successful operation
        "400":
          description: Invalid customer id or account id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/accounts/{account_id}/available-payment-methods:
    get:
      tags:
        - Accounts
      summary: Get available payment methods for an account
      description: Returns all available payment methods for an account
      operationId: getAvailablePaymentMethodsByAccountId
      security:
        - permissions:
            - customers.accounts.paymentmethod.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/accountId'
      responses:
        "200":
          description: Payment methods returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailablePaymentMethods'
        "400":
          description: Invalid parameter supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or account not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/identification-processes/{identification_process_id}:
    get:
      tags:
        - Customer identification processes
      summary: Get document for a customer identification process
      description: >
        Returns the document for a customer identification process
        A customer can have multiple identification processes, each one with a different external id
        Each identification process has a document associated
      operationId: getIdentificationProcessById
      security:
        - permissions:
          - customers.customers.identificationprocess.read
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/identificationProcessId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIdentificationProcessResponse'
              examples:
                get_nif_identification_process:
                  $ref: '#/components/examples/request_nif_identification_process'
                get_nie_identification_process:
                  $ref: '#/components/examples/request_nie_identification_process'
                get_passport_identification_process:
                  $ref: '#/components/examples/request_passport_identification_process'
        "400":
          description: Invalid customer id or identification process id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer or not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Method not allowed ex
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/identification-processes:
    get:
      tags:
        - Customer identification processes
      summary: Get all identification processes for a customer sorted by creation date
      description: >
        Returns all identification processes for a customer sorted by creation date
        A customer can have multiple identification processes
      operationId: listIdentificationProcessesByCustomerId
      security:
        - permissions:
            - customers.customers.identificationprocess.list
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIdentificationProcessesResponse'
              examples:
                list_identification_processes:
                  $ref: '#/components/examples/response_list_identification_processes'
        "400":
          description: Invalid customer id supplied
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "405":
          description: Method not allowed
          $ref: '#/components/responses/405MethodNotAllowedGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

  /orgs/{org_id}/customers/{customer_id}/convert-nie-to-nif:
    patch:
      tags:
        - Customers
      summary: Convert NIE to NIF
      description: Updates a customer’s document from the specified NIE to the specified NIF
      operationId: convertNieToNif
      parameters:
        - $ref: '#/components/parameters/orgId'
        - $ref: '#/components/parameters/customerId'
      security:
        - permissions:
          - customers.customers.document.update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertNieToNifRequest'
      responses:
        "204":
          description: NIE converted successfully
        "400":
          description: Invalid NIE/NIF format
          $ref: '#/components/responses/400BadRequestGeneric'
        "401":
          description: Unauthorized
          $ref: '#/components/responses/401UnauthorizedGeneric'
        "403":
          description: Forbidden
          $ref: '#/components/responses/403ForbiddenGeneric'
        "404":
          description: Customer not found
          $ref: '#/components/responses/404NotFoundGeneric'
        "409":
          description: Validation exception
          $ref: '#/components/responses/409ConflictGeneric'
        "500":
          description: Internal Server Error
          $ref: '#/components/responses/500InternalServerErrorGeneric'
        "503":
          description: Service Unavailable
          $ref: '#/components/responses/503ServiceUnavailableGeneric'
        "504":
          description: Repository timeout
          $ref: '#/components/responses/504RepositoryTimeoutGeneric'

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: org_id
      in: path
      required: true
      description: organization name
      example: telco
      schema:
        type: string
    customerId:
      name: customer_id
      in: path
      required: true
      description: Customer identifier
      example: "123e4567-e89b-12d3-a456-556642440000"
      schema:
        type: string
        format: uuid
    credentialId:
      name: credential_id
      in: path
      required: true
      description: Credential identifier
      example: "028076fa-c264-42bb-9983-8872a576be28"
      schema:
        type: string
        format: uuid
    categoryId:
      name: category_id
      in: path
      required: true
      description: Category id to be returned
      example: 214748364
      schema:
        type: integer
        format: int32
    accountExternalId:
      name: account_external_id
      in: path
      required: true
      description: External id of account to return
      example: 214748364
      schema:
        type: string
    customerExternalId:
      name: customer_external_id
      in: path
      required: true
      description: Customer external id
      example: 214748364
      schema:
        type: string
    accountId:
      name: account_id
      in: path
      required: true
      description: Account identifier
      example: "123e4567-e89b-12d3-a456-556642440000"
      schema:
        type: string
        format: uuid
    username:
      name: username
      in: path
      required: true
      description: Email used by customer to authenticate
      example: username@masmovil.com
      schema:
        type: string
        maxLength: 82
    identityDocument:
      name: identity_document
      in: query
      description: Document with numbers and letters
      example: "12345678A"
      schema:
        type: string
    identityDocumentType:
      name: identity_document_type
      in: query
      description: Document type
      example: "NIF"
      schema:
        type: string
        enum: [NIF, NIE, PASSPORT, CIF]
    email:
      name: email
      in: query
      description: Email used by customer to authenticate
      example: "email@example.com"
      schema:
        type: string
    identificationProcessId:
      name: identification_process_id
      in: path
      required: true
      description: Id of the customer identification process
      example: 4189285b-08f8-4628-adda-4767d81362e7
      schema:
        type: string
        format: uuid
    from:
      name: 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
    to:
      name: 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
    accountPromotionId:
      name: account_promotion_id
      in: path
      required: true
      description: Account promotion relation identifier
      example: "123e4567-e89b-12d3-a456-556642440000"
      schema:
        type: string
        format: uuid
    accountPromotionType:
      name: account_promotion_type
      in: query
      description: Account Promotion Type
      example: "ACTIVE"
      schema:
        type: string
        enum: [ ACTIVE, SCHEDULED, ALL ]
    startDate:
      name: start_date
      in: query
      description: Reference date to list account promotion operation history
      required: false
      schema:
        type: string
        format: date
      example: "2025-09-01"

  responses:
    400BadRequestGeneric:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.998
                  title: Bad request
                  ref: http://
                  message: Bad request

    401UnauthorizedGeneric:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.996
                  title: Unauthorized
                  ref: http://
                  message: Unauthorized

    403ForbiddenGeneric:
      description: Forbidden resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.995
                  title: Forbidden
                  ref: http://
                  message: Forbidden

    404NotFoundGeneric:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.997
                  title: Resource not found
                  ref: http://
                  message: Resource not found

    405MethodNotAllowedGeneric:
      description: Method not allowed

    409ConflictGeneric:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.994
                  title: Conflict
                  ref: http://
                  message: The resource already exists

    500InternalServerErrorGeneric:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.999.999
                  title: Unexpected error
                  ref: http://
                  message: Unexpected error

    503ServiceUnavailableGeneric:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.001.005
                  title: Database error
                  ref: http://
                  message: Connection los

    504RepositoryTimeoutGeneric:
      description: Repository timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - error:
                  code: MCUS.001.009
                  title: Database error
                  ref: http://
                  message: Statement timeout

  schemas:
    ListIdentificationProcessesResponse:
      type: object
      additionalProperties: false
      required:
        - processes
      properties:
        processes:
          type: array
          items:
            $ref: '#/components/schemas/IdentificationProcessSummaryResponse'


    GetIdentificationProcessResponse:
      type: object
      additionalProperties: false
      required:
        - document
      allOf:
        - $ref: '#/components/schemas/IdentificationProcessSummaryResponse'
        - properties:
            document:
              $ref: '#/components/schemas/DocumentResponse'

    IdentificationProcessSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - process_id
        - process_date
      properties:
        process_id:
          type: string
          format: uuid
          description: Identification process id
          example: 4189285b-08f8-4628-adda-4767d81362e7
        process_date:
          type: string
          description: Date of the identification process. Format according to ISO 8601
          format: date-time
          example: '2023-01-27T03:44:52.000Z'

    DocumentResponse:
      type: object
      additionalProperties: false
      required:
        - url_expiration_date
        - public_url
        - media_type
        - name
        - type
        - size_bytes
      properties:
        url_expiration_date:
          type: string
          description: Expiration date for the supplied link. Format according to ISO 8601
          format: date-time
          example: '2023-01-27T03:44:52.000Z'
        public_url:
          type: string
          description: Link to download the contract
          example: https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
        media_type:
          type: string
          description: >
            Format of the document to be stored. It must match the format of the binary document
            Allowed values: pdf, jpeg, jpg, png
          example: application/pdf
        name:
          type: string
          description: Name of the document (without spaces)
          readOnly: true
          example: my_id_document.pdf
        type:
          type: string
          description: Type of contract
          x-extensible-enum:
            - "NIF"
            - "NIE"
            - "PASSPORT"
          example: "NIF"
        size_bytes:
          type: integer
          description: Size of the document in bytes
          example: 123456

    AccountCreated:
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Account id
          nullable: false
          example: "123e4567-e89b-12d3-a456-556642440000"
        external_id:
          type: string
          nullable: true
          description: Account external id
          example: "214748364"

    BillingAddress:
      type: object
      additionalProperties: false
      required:
        - address_lines
        - postal_code
        - locality
        - administrative_area
        - region_code
      properties:
        address_lines:
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
            minLength: 3
            maxLength: 100
            example: "Avenida de Bruselas, 38"
        postal_code:
          type: string
          example: "28108"
          maxLength: 5
          pattern: "^([0-4]\\d{4})|(5[0-2]\\d{3})$"
        state_id:
          type: string
          example: "28"
          maxLength: 2
          pattern: "^([0-4]\\d|5[0-2])$"
        locality:
          type: string
          minLength: 2
          maxLength: 255
          example: "Alcobendas"
        administrative_area:
          type: string
          minLength: 4
          maxLength: 50
          example: "Madrid"
        region_code:
          type: string
          example: "ES"

    BillingAddressHistory:
      type: object
      additionalProperties: false
      required:
        - billing_address
        - init_date
      properties:
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        init_date:
          type: string
          format: date-time
          description: Account address init date
          example: "2022-01-01T01:01:01Z"
        end_date:
          type: string
          format: date-time
          description: Account address end date
          example: "2022-01-01T01:01:01Z"

    BillingAddressHistoryResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          nullable: false
          format: uuid
          description: Account id
          example: "123e4567-e89b-12d3-a456-556642440000"
        external_id:
          type: string
          description: Account external id
          example: "214748364"
          nullable: true
        from:
          type: string
          format: date
          example: '2020-01-01'
          nullable: true
        to:
          type: string
          format: date
          example: '2020-01-01'
          nullable: true
        history:
          type: array
          nullable: false
          minItems: 1
          items:
            $ref: '#/components/schemas/BillingAddressHistory'

    InvoiceAddressResponse:
      type: object
      additionalProperties: false
      required:
        - name
        - address_lines
        - postal_code
        - locality
        - administrative_area
        - region_code
      properties:
        name:
          type: string
          description: Destiny name
          example: "Antonio Benavente Blanco"
          maxLength: 300
        address_lines:
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
            minLength: 3
            maxLength: 255
            example: "Avenida de Bruselas, 38"
        postal_code:
          type: string
          example: "28108"
          maxLength: 5
          pattern: "^([0-4]\\d{4})|(5[0-2]\\d{3})$"
        locality:
          type: string
          minLength: 2
          maxLength: 255
          example: "Alcobendas"
        administrative_area:
          type: string
          minLength: 4
          maxLength: 50
          example: "Madrid"
        region_code:
          type: string
          example: "ES"

    GetAccount:
      type: object
      additionalProperties: false
      required: [id, customer_id, modality, created_at, updated_at]
      properties:
        id:
          type: string
          nullable: false
          format: uuid
          description: Account id
          example: "123e4567-e89b-12d3-a456-556642440000"
        external_id:
          type: string
          description: Account external id
          example: "214748364"
          nullable: true
        customer_id:
          type: string
          nullable: false
          format: uuid
          description: Customer id
          example: "1efd6af5-dc6b-438e-b523-44f91322beac"
        customer_external_id:
          type: string
          nullable: true
          description: Customer external id (legacy Oracle CUSTOMERID)
          example: "23768603"
        contract_reference:
          type: string
          nullable: true
          description: Contract reference
          example: "MMC1708177227910"
        modality:
          type: string
          nullable: false
          enum:
            - PREPAID
            - RECURRING_PREPAID
            - POSTPAID
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        payment_method:
          $ref: '#/components/schemas/GetPaymentMethod'
        invoice:
          $ref: '#/components/schemas/AccountInvoice'
        created_at:
          type: string
          format: date-time
          description: Account creation date
          example: "2022-01-01T01:01:01Z"
        ended_at:
          type: string
          nullable: true
          format: date-time
          description: Account end date
          example: "2022-01-01T01:01:01Z"
        updated_at:
          type: string
          format: date-time
          description: Account end date
          example: "2022-01-01T01:01:01Z"

    AccountInvoice:
      type: object
      nullable: true
      required: [cycle, due_date_id, due_days_id]
      description: Account invoice info
      additionalProperties: false
      properties:
        cycle:
          $ref: '#/components/schemas/InvoiceCycle'
        due_date_id:
          type: integer
          description: Due date identifier
          example: 5
        due_days_id:
          type: integer
          description: Due days identifier
          example: 1
        delivery_mode:
          type: string
          description: Delivery mode
          enum:
            - EMAIL
            - PAPER
            - APPLICATION

    InvoiceCycle:
      type: object
      description: Invoice cycle info
      properties:
        name:
          type: string
          description: Invoice cycle name
          example: "DIA 1 - MENSUAL"
        day:
            type: integer
            format: int32
            description: Invoice cycle start day
            example: 1
        type:
            type: string
            description: Invoice cycle type, valid values 'M' for monthly and 'D' for daily
            example: "M"
        frequency:
            type: integer
            format: int32
            description: This is the number of times the time period (indicated by the type, which can be months or days) is repeated for each individual invoice period.
            example: 1

    PaymentType:
      type: string
      nullable: false
      enum: [ 'BANK_TRANSFER', 'DIRECT_DEBIT', 'CREDIT_CARD' ]

    GetPaymentType:
      type: string
      nullable: false
      enum: [ 'BANK_TRANSFER', 'DIRECT_DEBIT', 'CREDIT_CARD', "TECI" ]

    PatchPaymentType:
      type: string
      nullable: false
      enum: [ 'BANK_TRANSFER', 'DIRECT_DEBIT',  'CREDIT_CARD' ]

    AvailablePaymentMethods:
      type: object
      additionalProperties: false
      properties:
        payment_methods:
          type: array
          nullable: false
          minItems: 1
          items:
            $ref: '#/components/schemas/AvailablePaymentMethod'

    AvailablePaymentMethod:
      type: string
      nullable: false
      enum:
        - 'BANK_TRANSFER'
        - 'DIRECT_DEBIT'
        - 'CREDIT_CARD'
        - 'TECI'

    PaymentMethod:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/PaymentType'
        details:
          $ref: '#/components/schemas/PaymentMethodDetails'

    PaymentMethodDetails:
      type: object
      nullable: true
      description: iban is mandatory when type is DIRECT_DEBIT, token_id OR reference_id is mandatory when type is CREDIT_CARD
      oneOf:
        - properties:
            iban:
              type: string
              description: Only for direct debit payment method
              pattern: '^([a-zA-Z]{2})(\d{2})(\d{4})(\d{4})(\d{2})(\d{10})$'
              example: "ES7921000813610123456789"
          required:
            - iban
          additionalProperties: false
        - properties:
            token_id:
              type: string
              format: uuid
              description: Only for credit card payment method (synchronous tokenization), this value is the token id of the tokenized credit card
              example: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
          required:
            - token_id
          additionalProperties: false
        - properties:
            reference_id:
              type: string
              description: Only for credit card payment method (asynchronous tokenization), this value is the reference id for the pending tokenization request
              example: "ref-123e4567-e89b-12d3-a456-556642440000"
          required:
            - reference_id
          additionalProperties: false

    PatchAccountPaymentMethod:
        type: object
        additionalProperties: false
        required:
            - type
        properties:
            type:
              $ref: '#/components/schemas/PatchPaymentType'
            details:
              $ref: '#/components/schemas/PatchAccountPaymentMethodDetails'

    PatchAccountPaymentMethodDetails:
      type: object
      nullable: true
      description: iban is mandatory when type is DIRECT_DEBIT, token_id OR reference_id is mandatory when type is CREDIT_CARD
      oneOf:
        - properties:
            iban:
              type: string
              description: Only for direct debit payment method
              pattern: '^([a-zA-Z]{2})(\d{2})(\d{4})(\d{4})(\d{2})(\d{10})$'
              example: "ES7921000813610123456789"
          required:
            - iban
          additionalProperties: false
        - properties:
            token_id:
              type: string
              format: uuid
              description: Only for credit card payment method (synchronous tokenization), this value is the token id of the tokenized credit card
              example: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
          required:
            - token_id
          additionalProperties: false
        - properties:
            reference_id:
              type: string
              description: Only for credit card payment method (asynchronous tokenization), this value is the reference id for the pending tokenization request
              example: "ref-123e4567-e89b-12d3-a456-556642440000"
          required:
            - reference_id
          additionalProperties: false

    GetPaymentMethod:
      type: object
      additionalProperties: false
      description: >
        Payment method is required for RECURRING_PREPAID and POSTPAID modalities.
        PREPAID modality has no payment method associated.
      required:
        - type
      example:
        direct_debit:
          type: "DIRECT_DEBIT"
          details:
              iban: "ES7921000813610123456789"
        credit_card:
          type: "CREDIT_CARD"
          details:
              token_id: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
        bank_transfer:
          type: "BANK_TRANSFER"
          details: {}
        teci:
          type: "TECI"
          details:
            token_teci: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
      properties:
        type:
          $ref: '#/components/schemas/GetPaymentType'
        details:
          type: object
          nullable: true
          description: iban is mandatory when type is DIRECT_DEBIT, credit_card is mandatory when type is CREDIT_CARD, token-teci is mandatory when type is TECI
          oneOf:
            - $ref: '#/components/schemas/GetDirectDebitPaymentMethodDetails'
            - $ref: '#/components/schemas/GetCreditCardPaymentMethodDetails'
            - $ref: '#/components/schemas/GetTeciPaymentMethodDetails'

    GetDirectDebitPaymentMethodDetails:
      type: object
      additionalProperties: false
      required:
        - iban
      properties:
        iban:
          type: string
          description: Only for direct debit payment method
          pattern: '^([a-zA-Z]{2})(\d{2})(\d{4})(\d{4})(\d{2})(\d{10})$'
          example: "ES7921000813610123456789"
        mandato_id:
            type: string
            description: Mandate id. Only for direct debit payment method
            example: "F001MMC2505202249176101"
        mandato_created_date:
          type: string
          nullable: true
          format: date-time
          description: Mandate creation date. Only for direct debit payment method
          example: "2022-01-01T01:01:01Z"

    GetCreditCardPaymentMethodDetails:
      type: object
      additionalProperties: false
      required:
          - id
          - summary
          - expiration_date
      properties:
          id:
            type: string
            format: uuid
            description: Credit card id. Only for credit card payment method
            example: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
          summary:
            type: string
            description: Masked credit card number. Only for credit card payment method
            example: "5100"
          expiration_date:
            type: string
            description: Credit card expiration date (MM/yyyy format). Only for credit card payment method
            example: "05/2029"

    GetTeciPaymentMethodDetails:
      type: object
      additionalProperties: false
      required:
        - token-teci
      properties:
        token-teci:
          type: string
          description: Only for TECI payment method
          example: "Ob1dI04xvw-k25HBs3a4SHqTkkRWxKAnbFVcX1QzAfk"

    CustomerTokenizedCreditCards:
      type: object
      additionalProperties: false
      properties:
        available_credit_cards:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/CustomerTokenizedCreditCard'

    CustomerTokenizedCreditCard:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Credit card id
          example: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
        created_at:
          type: string
          format: date-time
          description: Credit card creation date
          example: "2022-01-01T01:01:01Z"
        summary:
          type: string
          description: Masked credit card number
          example: "5100"
        expiration_date:
          type: string
          description: Credit card expiration date (MM/yyyy format)
          example: "05/2029"

    PaymentMethodHistoryResponse:
      type: object
      additionalProperties: false
      properties:
        payment_methods:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/PaymentMethodHistoryRecord'

    PaymentMethodHistoryRecord:
      type: object
      additionalProperties: false
      required:
        - payment_method_type
        - created_at
      properties:
        payment_method_type:
          type: string
          description: Type of payment method
          enum:
            - BANK_TRANSFER
            - DIRECT_DEBIT
            - CREDIT_CARD
          example: "DIRECT_DEBIT"
        details:
          type: string
          description: Payment method details (IBAN for direct debit, card number for credit card)
          nullable: true
          example: "ES7921000813610123456789"
        created_at:
          type: string
          format: date-time
          description: Date when this payment method was set/historified
          example: "2022-01-01T01:01:01Z"

    PostAccount:
      type: object
      additionalProperties: false
      required:
        - modality
        - payment_method
      properties:
        modality:
          type: string
          nullable: false
          enum:
            #- PREPAID
            - RECURRING_PREPAID
            - POSTPAID
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        payment_method:
          $ref: '#/components/schemas/PaymentMethod'

    AccountIds:
      type: object
      additionalProperties: false
      properties:
        accounts:
          type: array
          nullable: false
          minItems: 0
          items:
            $ref: '#/components/schemas/AccountId'

    AccountId:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Account id
          example: "123e4567-e89b-12d3-a456-556642440000"

    CustomerSearchResponse:
      type: object
      additionalProperties: false
      properties:
        customer:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
              format: uuid
              description: Customer's identifier
              example: "123e4567-e89b-12d3-a456-556642440000"
            external_id:
              type: string
              description: Customer's external identifier
              example: "214748364"
              nullable: true

    CustomerResponseCommonProperties:
      type: object
      required: [id, created_at, updated_at, 'type', 'preferred_language', 'segment', 'contact_info']
      properties:
        id:
          type: string
          format: uuid
          description: Customer's identifier
          example: "123e4567-e89b-12d3-a456-556642440000"
        external_id:
          type: string
          description: Customer's external identifier
          example: "214748364"
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Customer's creation date
          example: "2022-01-01T01:01:01Z"
        ended_at:
          type: string
          format: date-time
          description: Customer's deactivation date
          example: "2022-01-01T01:01:01Z"
          nullable: true
        updated_at:
          type: string
          format: date-time
          description: Customer's last modification date
          example: "2022-01-01T01:01:01Z"
        type:
          $ref: '#/components/schemas/CustomerType'
        preferred_language:
          $ref: '#/components/schemas/LanguageCode'
        secondary_language:
          $ref: '#/components/schemas/LanguageCode'
        segment:
          $ref: '#/components/schemas/Segment'
        contact_info:
          $ref: '#/components/schemas/ContactInfoResponse'

    CustomerResponse:
      type: object
      oneOf:
        - $ref: '#/components/schemas/PrivateCustomerResponse'
        - $ref: '#/components/schemas/CorporateCustomerResponse'
        - $ref: '#/components/schemas/DigitalCustomerResponse'

    DigitalCustomerResponse:
      type: object
      required: [id, type, preferred_language, digital_personal_info, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
          description: Customer's identifier
          example: "123e4567-e89b-12d3-a456-556642440000"
        created_at:
          type: string
          format: date-time
          description: Customer's creation date
          example: "2022-01-01T01:01:01Z"
        ended_at:
          type: string
          format: date-time
          description: Customer's deactivation date
          example: "2022-01-01T01:01:01Z"
          nullable: true
        updated_at:
          type: string
          format: date-time
          description: Customer's last modification date
          example: "2022-01-01T01:01:01Z"
        type:
          $ref: '#/components/schemas/CustomerType'
        preferred_language:
          $ref: '#/components/schemas/LanguageCode'
        secondary_language:
          $ref: '#/components/schemas/LanguageCode'
        digital_personal_info:
          $ref: '#/components/schemas/DigitalPersonalInfoResponse'

    PrivateCustomerResponse:
      type: object
      required: [personal_info]
      allOf:
        - $ref: '#/components/schemas/CustomerResponseCommonProperties'
        - type: object
          properties:
            personal_info:
              $ref: '#/components/schemas/PersonalInfoResponse'

    CorporateCustomerResponse:
      type: object
      required: [company_info]
      allOf:
        - $ref: '#/components/schemas/CustomerResponseCommonProperties'
        - type: object
          properties:
            company_info:
              $ref: '#/components/schemas/CompanyInfoResponse'

    PersonalInfoName:
      type: string
      description: Customer's first name (including middle name if applicable)
      example: "Antonio"
      minLength: 1
      maxLength: 50

    PersonalInfoFirstSurname:
      type: string
      description: Customer's first surname
      example: "Benavente"
      minLength: 2
      maxLength: 50

    PersonalInfoSecondSurname:
      type: string
      description: Consumer's rest of surnames
      example: "Blanco"
      nullable: true
      minLength: 2
      maxLength: 50

    PersonalInfoBirthdate:
      type: string
      format: date
      description: Customer's date of birth
      example: "2022-01-01"

    PersonalInfoNationality:
      type: string
      description: Customer's nationality code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) uppercase format. 'ZZ' is used for unknown countries.
      example: "ES"
      pattern: '^[A-Z]{2}$'

    PersonalInfo:
      type: object
      additionalProperties: false
      required: ['identity_document', 'name', 'first_surname', 'nationality', 'birthdate']
      description: Private customer personal information
      properties:
        identity_document:
          $ref: '#/components/schemas/PersonalIdentityDocument'
        name:
          $ref: '#/components/schemas/PersonalInfoName'
        first_surname:
          $ref: '#/components/schemas/PersonalInfoFirstSurname'
        second_surname:
          $ref: '#/components/schemas/PersonalInfoSecondSurname'
        gender:
          type: string
          description: Customer's gender
          enum:
            - MALE
            - FEMALE
            - UNSPECIFIED
        nationality:
          description: Customer's nationality code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) uppercase format. 'ZZ' is used for unknown countries.
          example: "ES"
          type: string
        birthdate:
          $ref: '#/components/schemas/PersonalInfoBirthdate'

    PatchPersonalInfo:
      type: object
      description: Private customer personal information
      properties:
        name:
          $ref: '#/components/schemas/PersonalInfoName'
        first_surname:
          $ref: '#/components/schemas/PersonalInfoFirstSurname'
        second_surname:
          $ref: '#/components/schemas/PersonalInfoSecondSurname'
        birthdate:
          $ref: '#/components/schemas/PersonalInfoBirthdate'
        nationality:
          $ref: '#/components/schemas/PersonalInfoNationality'

    CompanyInfoLegalName:
      type: string
      description: Company's legal name
      example: "IBM Inc"
      minLength: 2
      maxLength: 300

    CompanyInfoFoundingDate:
      type: string
      format: date
      description: Company's foundation date
      example: "2022-01-01"

    PatchDigitalPersonalInfo:
      type: object
      description: Update Digital Personal Info
      properties:
        name:
          $ref: '#/components/schemas/DigitalPersonalInfoName'
        first_surname:
          $ref: '#/components/schemas/DigitalPersonalInfoFirstSurname'
        second_surname:
          $ref: '#/components/schemas/DigitalPersonalInfoSecondSurname'
        mobile_phone_number:
          $ref: '#/components/schemas/MobilePhoneNumber'

    DigitalPersonalInfoResponse:
          type: object
          additionalProperties: false
          description: Digital customer personal information
          properties:
            name:
              $ref: '#/components/schemas/DigitalPersonalInfoName'
            first_surname:
              $ref: '#/components/schemas/DigitalPersonalInfoFirstSurname'
            second_surname:
              $ref: '#/components/schemas/DigitalPersonalInfoSecondSurname'
            email:
              $ref: '#/components/schemas/DigitalEmail'
            mobile_phone_number:
              $ref: '#/components/schemas/MobilePhoneNumber'

    PersonalInfoResponse:
      type: object
      additionalProperties: false
      description: Private customer personal information
      properties:
        identity_document:
          $ref: '#/components/schemas/PersonalIdentityDocument'
        name:
          type: string
          description: Customer's first name (including middle name if applicable)
          example: "Antonio"
          minLength: 1
          maxLength: 50
        first_surname:
          type: string
          nullable: true
          description: Customer's first surname
          example: "Benavente"
          minLength: 2
          maxLength: 50
        second_surname:
          type: string
          nullable: true
          description: Consumer's rest of surnames
          example: "Blanco"
          minLength: 2
          maxLength: 50
        gender:
          type: string
          nullable: true
          description: Customer's gender
          enum:
            - MALE
            - FEMALE
            - UNSPECIFIED
        nationality:
          type: string
          nullable: true
          description: Customer's nationality code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) uppercase format. 'ZZ' is used for unknown countries.
          example: "ES"
        birthdate:
          type: string
          format: date
          nullable: true
          description: Customer's date of birth
          example: "2022-01-01"

    CompanyInfo:
      type: object
      additionalProperties: false
      required: ['identity_document', 'associated_users', 'legal_name', 'founding_date']
      properties:
        identity_document:
          $ref: '#/components/schemas/CorporateIdentityDocument'
        legal_name:
          $ref: '#/components/schemas/CompanyInfoLegalName'
        founding_date:
          $ref: '#/components/schemas/CompanyInfoFoundingDate'
        associated_users:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/AssociatedUser'

    CompanyInfoResponse:
      type: object
      additionalProperties: false
      properties:
        identity_document:
          $ref: '#/components/schemas/CorporateIdentityDocument'
        legal_name:
          type: string
          description: Company's legal name
          example: "IBM Inc"
          minLength: 3
          maxLength: 300
        founding_date:
          type: string
          format: date
          nullable: true
          description: Company's foundation date
          example: "2022-01-01"
        associated_users:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/AssociatedUser'

    PatchCompanyInfo:
      type: object
      description: |
        Update Company Info for a corporate customer. Only `legal_name` and `founding_date` are patchable.

        > **Note:** The `associated_users` field has been removed from this schema as of v4.57.0.
        > If sent alongside valid fields (`legal_name` or `founding_date`), it will be silently ignored
        > and the request will succeed with `204 No Content`.
        > If sent as the **only** field in `company_info`, the request will return `400 Bad Request`
        > with `"At least one field must be present"`.

        **Valid usage:**
        ```json
        { "company_info": { "legal_name": "IBM", "founding_date": "1990-01-01" } }
        ```

        **Invalid usage (deprecated, do not use):**
        ```json
        { "company_info": { "associated_users": [{ "identity_document": { "number": "12345678Z", "type": "NIF" } }] } }
        ```
      properties:
        legal_name:
          $ref: '#/components/schemas/CompanyInfoLegalName'
        founding_date:
          $ref: '#/components/schemas/CompanyInfoFoundingDate'

    AssociatedUser:
      type: object
      description: Business Customer associated user
      required:
        - identity_document
        - name
        - first_surname
        - nationality
      properties:
        identity_document:
          $ref: '#/components/schemas/PersonalIdentityDocument'
        role:
          type: string
          description: The role of the user in the relationship between their company and us
          enum: ['AUTHORIZED_REPRESENTATIVE']
          default: 'AUTHORIZED_REPRESENTATIVE'
        name:
          type: string
          description: Associated user's first name (including middle name if applicable)
          example: "Antonio"
          maxLength: 100
        first_surname:
          type: string
          description: Associated user's first surname
          example: "Benavente"
          maxLength: 100
        second_surname:
          type: string
          description: Associated user's rest of surnames
          example: "Blanco"
          nullable: true
          maxLength: 100
        nationality:
          description: Associated user's nationality code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) uppercase format. 'ZZ' is used for unknown countries.
          example: "ES"
          type: string

    PutAssociatedUsersRequest:
      type: object
      additionalProperties: false
      required:
        - associated_users
      properties:
        associated_users:
          type: array
          minItems: 1
          maxItems: 1
          description: List of associated users to set. Currently only one representative per customer is supported.
          items:
            $ref: '#/components/schemas/AssociatedUser'

    LanguageCode:
      type: string
      description: Customer's preferred language code in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) lowercase format
      example: es
      nullable: false
      enum:
        - es
        - ca
        - gl
        - eu
        - en
        - pt

    Segment:
      type: string
      description: >
        Customer's segment, whether it is an individual, a self-employed customer, or a company (although so far we just support SME - Small Medium Enterprise).
        
        For PrivateCustomer:
        * CONSUMER
        
        For CorporateCustomer:
        * SELF_EMPLOYEE
        * SME

      nullable: false
      enum:
        - CONSUMER
        - SELF_EMPLOYEE
        - SME

    PatchPhoneNumberArray:
      type: array
      description: List of phone numbers that the customer can be contacted with. At least one phone number is required
      items:
        $ref: '#/components/schemas/PatchPhoneNumber'
      minItems: 1
      maxItems: 1

    ContactInfoPhoneNumbers:
      type: array
      description: List of phone numbers that the customer can be contacted with. At least one default phone number is required
      items:
        $ref: '#/components/schemas/PhoneNumber'
      minItems: 1
      maxItems: 1

    PatchEmailArray:
      type: array
      description: List of emails that the customer can be contacted with. At least one email is required
      items:
        $ref: '#/components/schemas/PatchEmail'
      minItems: 1
      maxItems: 1

    ContactInfoEmails:
      type: array
      description: List of emails that the customer can be contacted with. At least one default email is required
      items:
        $ref: '#/components/schemas/Email'
      minItems: 1
      maxItems: 1

    PatchContactInfo:
      type: object
      additionalProperties: false
      properties:
        phone_numbers:
          $ref: '#/components/schemas/PatchPhoneNumberArray'
        emails:
          $ref: '#/components/schemas/PatchEmailArray'

    ContactInfo:
      type: object
      additionalProperties: false
      required: ['phone_numbers', 'emails', 'postal_address']
      properties:
        phone_numbers:
          $ref : '#/components/schemas/ContactInfoPhoneNumbers'
        emails:
          $ref : '#/components/schemas/ContactInfoEmails'
        postal_address:
          $ref: '#/components/schemas/Address'

    ContactInfoResponse:
      type: object
      additionalProperties: false
      required: ['phone_numbers', 'emails', 'addresses']
      properties:
        phone_numbers:
          description: List of 0 to 1 phone numbers that the customer can be contacted with.
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/PhoneNumberResponse'
        emails:
          description: List of 0 to 1 emails that the customer can be contacted with.
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/EmailResponse'
        addresses:
          description: List of 0 or more postal addresses that the customer can be contacted with.
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/Address'

    PatchEmail:
      type: object
      additionalProperties: false
      required: [ 'email' ]
      properties:
        email:
          type: string
          example: "email@example.com"
          description: Case insensitive customer's email, no accent marks allowed
          maxLength: 82

    Email:
      type: object
      additionalProperties: false
      required: ['email']
      properties:
        email:
          type: string
          example: "email@example.com"
          description: Case insensitive customer's email, no accent marks allowed
          maxLength: 82
        is_default:
          type: boolean
          description: >
            If the payload contains ony one email, this boolean value is ignored, and this email is set as the default one. <br>
            If the payload contains more than one email, only one of them can be set as the default one.
          example: true

    EmailResponse:
      type: object
      additionalProperties: false
      properties:
        email:
          type: string
          example: "email@example.com"
          description: Case insensitive customer's email, no accent marks allowed
          maxLength: 82

    Address:
      type: object
      additionalProperties: false
      description: Postal address of the customer or user
      required: [ 'address_lines', 'postal_code', 'locality', 'administrative_area', 'region_code' ]
      properties:
        address_lines:
          type: array
          description: The full address, including the floor, door, and other supplements.
          items:
            type: string
            minLength: 3
            maxLength: 100
          minItems: 1
          maxItems: 1
          example: [ "Calle Mayor 2, 3º A" ]
        postal_code:
          type: string
          description: Address postal code, which identifies the subdivision within a locality where the address is located.
          example: "28039"
          maxLength: 5
          pattern: "^([0-4]\\d{4})|(5[0-2]\\d{3})$"
        locality:
          type: string
          description: Name of the city, town, or similar where the address is located.
          example: "Fuenlabrada"
          minLength: 2
          maxLength: 255
        administrative_area:
          type: string
          description: Name of the state, province, or similar where the address is located.
          example: "Madrid"
          nullable: true
          minLength: 4
          maxLength: 50
        region_code:
          type: string
          description: Region or country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) uppercase format. 'ZZ' is used for unknown countries.
          example: "ES"

    PhoneNumberType:
      type: string
      description: Phone number type, which determines if it can receive SMS or not
      enum:
        - MOBILE

    PatchPhoneNumber:
      type: object
      additionalProperties: false
      required: [ 'country_code', 'number', 'type' ]
      properties:
        country_code:
          type: string
          description: "[Phone number country code according to the ITU](https://countrycode.org/) (optionally preceded with a '+')"
          example: "+34"
          pattern: "^\\+34$"
        number:
          type: string
          description: Phone number value
          example: "615667898"
          pattern: "^[67]\\d{8}$"
        type:
          $ref: '#/components/schemas/PhoneNumberType'

    PhoneNumber:
      type: object
      additionalProperties: false
      required: ['country_code', 'number', 'type']
      properties:
        country_code:
          type: string
          description: "[Phone number country code according to the ITU](https://countrycode.org/) (optionally preceded with a '+')"
          example: "+34"
          pattern: "^\\+34$"
        number:
          type: string
          description: Phone number value
          example: "615667898"
          pattern: "^[67]\\d{8}$"
        type:
          $ref: '#/components/schemas/PhoneNumberType'
        is_default:
          type: boolean
          description: >
            If the payload contains ony one phone number, this boolean value is ignored, and this phone number is set as the default one. <br>
            If the payload contains more than one phone number, only one of them can be set as the default one.
          example: true

    PhoneNumberResponse:
      type: object
      additionalProperties: false
      properties:
        country_code:
          type: string
          description: "[Phone number country code according to the ITU](https://countrycode.org/) (optionally preceded with a '+')"
          example: "+34"
          pattern: "^\\+34$"
        number:
          type: string
          description: Phone number value
          example: "615667898"
          pattern: "^[6789]\\d{8}$"
        type:
          type: string
          description: Phone number type, which determines if it can receive SMS or not
          enum:
            - MOBILE
            - LANDLINE

    PersonalIdentityDocument:
      type: object
      additionalProperties: false
      description: Private customer identification document
      required: ['number', 'type']
      properties:
        number:
          type: string
          description: Alphanumeric part of the Identification Document
          example: "14861628V"
          maxLength: 30
        type:
          type: string
          description: Identification Document type
          enum:
            - NIF
            - NIE
            - PASSPORT

    CorporateIdentityDocument:
      type: object
      additionalProperties: false
      description: Corporate customer identification document
      required: ['number', 'type']
      properties:
        number:
          type: string
          description: Alphanumeric part of the Identification Document
          example: "B14507610"
          maxLength: 30
        type:
          type: string
          description: Identification Document type
          default: 'CIF'
          enum: ['CIF']

    CustomerType:
      type: string
      enum: ['PRIVATE_CUSTOMER', 'CORPORATE_CUSTOMER', 'DIGITAL_CUSTOMER']

    NewPrivateCustomer:
      type: object
      additionalProperties: false
      description: Information required to create a new private/particular customer with no association to any business
      required: ['type', 'preferred_language', 'segment', 'contact_info', 'personal_info']
      properties:
        type:
          $ref: '#/components/schemas/CustomerType'
        preferred_language:
          $ref: '#/components/schemas/LanguageCode'
        segment:
          $ref: '#/components/schemas/Segment'
        contact_info:
          $ref: '#/components/schemas/ContactInfo'
        personal_info:
          $ref: '#/components/schemas/PersonalInfo'

    NewDigitalCustomer:
      type: object
      additionalProperties: false
      description: Information required to create a new digital customer
      required: ['type', 'preferred_language', 'digital_personal_info']
      properties:
        type:
          $ref: '#/components/schemas/CustomerType'
        preferred_language:
          $ref: '#/components/schemas/LanguageCode'
        digital_personal_info:
          $ref: '#/components/schemas/DigitalPersonalInfo'

    DigitalPersonalInfo:
      type: object
      additionalProperties: false
      required: ['email']
      description: Digital customer personal information
      properties:
        name:
          $ref: '#/components/schemas/DigitalPersonalInfoName'
        first_surname:
          $ref: '#/components/schemas/DigitalPersonalInfoFirstSurname'
        second_surname:
          $ref: '#/components/schemas/DigitalPersonalInfoSecondSurname'
        email:
          $ref: '#/components/schemas/DigitalEmail'
        mobile_phone_number:
          $ref: '#/components/schemas/MobilePhoneNumber'

    DigitalPersonalInfoName:
      type: string
      description: Customer's first name
      example: "Jose"
      minLength: 1
      maxLength: 255

    DigitalPersonalInfoFirstSurname:
      type: string
      description: Customer's first surname
      example: "Carrero"
      minLength: 2
      maxLength: 255

    DigitalPersonalInfoSecondSurname:
      type: string
      description: Consumer's rest of surnames
      example: "Diaz"
      nullable: true
      minLength: 2
      maxLength: 255

    DigitalEmail:
      type: string
      example: "email@example.com"
      description: Case insensitive customer's email, no accent marks allowed
      maxLength: 82

    MobilePhoneNumber:
      type: object
      additionalProperties: false
      required: ['country_code', 'number']
      properties:
        country_code:
          type: string
          description: "[Phone number country code according to the ITU](https://countrycode.org/) (optionally preceded with a '+')"
          example: "+34"
          pattern: "^\\+34$"
        number:
          type: string
          description: Mobile Phone number value
          example: "615667898"
          pattern: "^[67]\\d{8}$"

    PatchCustomerRequest:
      allOf:
        - type: object
          description: Information required to update a customer
          properties:
            preferred_language:
              $ref: '#/components/schemas/LanguageCode'
            contact_info:
              $ref: '#/components/schemas/PatchContactInfo'
        - anyOf:
            - type: object
              properties:
                personal_info:
                  $ref: '#/components/schemas/PatchPersonalInfo'
            - type: object
              properties:
                company_info:
                  $ref: '#/components/schemas/PatchCompanyInfo'
            - type: object
              properties:
                digital_personal_info:
                  $ref: '#/components/schemas/PatchDigitalPersonalInfo'

    NewCorporateCustomer:
      type: object
      additionalProperties: false
      description: Information required to create a new corporate customer
      required: ['type', 'preferred_language', 'segment', 'contact_info', 'company_info']
      properties:
        type:
          $ref: '#/components/schemas/CustomerType'
        preferred_language:
          $ref: '#/components/schemas/LanguageCode'
        segment:
          $ref: '#/components/schemas/Segment'
        contact_info:
          $ref: '#/components/schemas/ContactInfo'
        company_info:
          $ref: '#/components/schemas/CompanyInfo'

    CredentialCreated:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Credential id
          example: "123e4567-e89b-12d3-a456-556642440000"
          nullable: false

    CustomerCreated:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Customer id
          example: "123e4567-e89b-12d3-a456-556642440000"
          nullable: false
        external_id:
          type: string
          description: Customer external id. Only returned when inserted by ourselves.
          example: "1111"
          nullable: true

    CustomerId:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Customer id
          example: "123e4567-e89b-12d3-a456-556642440000"

    Categories:
      type: object
      required:
        - categories
      additionalProperties: false
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'

    Credentials:
      type: object
      required:
        - credentials
      properties:
        username:
          type: string
          description: Username
          example: username@masmovil.com
          deprecated: true
        customer_id:
          type: string
          format: uuid
          description: Customer id
          example: "123e4567-e89b-12d3-a456-556642440000"
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/CredentialResponse'

    Credential:
      type: object
      description: Credential of customer
      required:
        - username
      properties:
        username:
          type: string
          description: Username
          example: username@masmovil.com
          maxLength: 82

    CredentialResponse:
      type: object
      description: Credential of customer
      required:
        - id
        - username
      properties:
        id:
          type: string
          nullable: false
          format: uuid
          description: Credential id
          example: "0c3c8412-2ac2-4c93-8122-c8afb9141457"
        username:
          type: string
          description: Username
          example: username@masmovil.com
          maxLength: 82

    PatchCustomerCredentialRequest:
      type: object
      additionalProperties: false
      required:
        - expiration_date
      properties:
        expiration_date:
          type: string
          format: date
          nullable: true
          description: Expiration date of the credential. Use null to remove the expiration date.
          example: "2025-12-31"

    ChangeCredentialRequest:
      type: object
      description: Request to change customer credential username
      required:
        - username
      additionalProperties: false
      properties:
        username:
          type: string
          description: New username (email format)
          example: nuevo@masmovil.com
          maxLength: 150

    Category:
      type: object
      required:
        - id
        - name
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int32
          description: Category id
          example: 214748364
        name:
          type: string
          description: Category name. Only accepts alphanumeric characters and underscore special character. Will not accept spaces
          pattern: "^[A-Za-z0-9_]{1,50}$"
          example: "risk"
        description:
          type: string
          description: Category description
          example: "Risk category"
        valid_values:
          type: array
          description: >
            Optional field to restrict the possible values that the category can have when it's associated with the customer.
            If this field is empty or not present, the category can have any value when associated with the customer.
          uniqueItems: true
          items:
            type: string
            pattern: "^[a-z0-9_]{1,50}$"
            minLength: 1
            maxLength: 50
            example: "high"

    PostCategories:
      type: object
      required:
        - categories
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/PostCategory'

    PostCategory:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Category name. Only accepts alphanumeric characters and underscore special character. Will not accept spaces
          pattern: "^[a-z0-9_]{1,50}$"
          example: "risk"
        description:
          type: string
          description: Category description
          example: "Risk category"
        valid_values:
          type: array
          description: >
            Optional field to restrict the possible values that the category can have when it's associated with the customer.
            If this field is empty or not present, the category can have any value when associated with the customer.
          uniqueItems: true
          items:
            type: string
            pattern: "^[a-z0-9_]{1,50}$"
            minLength: 1
            maxLength: 50

    PatchCategory:
      type: object
      properties:
        description:
          type: string
          description: Category description
          example: "Risk category"
        valid_values:
          type: array
          description: Must include all values already present and new values to be added, or less values to be removed.
          uniqueItems: true
          items:
            type: string
            pattern: "^[a-z0-9_]{1,50}$"
            minLength: 1
            maxLength: 50

    PostCustomerCategory:
      type: object
      required:
        - id
        - value
      properties:
        id:
          type: integer
          format: int32
          description: Category id
          example: 214748364
        value:
          type: string
          pattern: "^[a-z0-9_]{1,50}$"
          description: Category value.
          example: "influencer"
          nullable: true
        description:
          type: string
          minLength: 1
          maxLength: 200
          description: Description of the category value.
          example: "Bill discount"
        reason:
          type: string
          minLength: 1
          maxLength: 200
          description: Reason for the set of value.
          example: "Masmovil sponsors their videos"

    CustomerCategories:
      type: object
      required:
        - customer_id
        - categories
      additionalProperties: false
      properties:
        customer_id:
          type: string
          format: uuid
          description: Customer id
          example: "123e4567-e89b-12d3-a456-556642440000"
        categories:
          type: array
          description: Customer categories
          items:
            $ref: '#/components/schemas/CustomerCategory'

    CustomerCategory:
      type: object
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: integer
          description: Category ID
          format: int32
          example: 214748364
        name:
          type: string
          description: Category name
          example: "risk"
        value:
          type: string
          description: Category value. If null, category won't be shown
          example: "a"
          nullable: true
        description:
          type: string
          minLength: 1
          maxLength: 50
          description: Description of the category value
          example: "This is an a of category 1"
        reason:
          type: string
          minLength: 1
          maxLength: 50
          description: Reason for the set of value
          example: "Change because this is a test"
        create_date_time:
          type: string
          format: date-time
          description: Category creation date and time
          example: "2022-01-01T01:01:01Z"
        last_modified_date_time:
          type: string
          format: date-time
          description: Category last modified date and time
          example: "2022-01-01T01:01:01Z"

    CustomerCategoryHistory:
      type: object
      required:
        - customer_id
        - categories
      additionalProperties: false
      properties:
        customer_id:
          type: string
          format: uuid
          description: Customer id
          example: "123e4567-e89b-12d3-a456-556642440000"
        categories:
          type: array
          description: Customer categories with history
          items:
            $ref: '#/components/schemas/CategoryHistory'

    CategoryHistory:
      type: object
      required:
        - id
        - name
        - historical_values
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int32
          description: Customer category id
          example: 214748364
        name:
          type: string
          description: Category name
          example: risk
        historical_values:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                description: Category value
                example: "a"
              description:
                type: string
                minLength: 1
                maxLength: 50
                description: Description of the category value
                example: "This is an a of category 1"
              reason:
                type: string
                minLength: 1
                maxLength: 50
                description: Reason for the set of value
                example: "Change because this is a test"
              create_date:
                type: string
                format: date-time
                description: Category creation date time
                example: "2022-01-01T01:01:01Z"
              end_date:
                type: string
                format: date-time
                description: Category end date time
                example: "2022-01-01T01:01:01Z"
                nullable: true
              last_modified_date:
                type: string
                format: date-time
                description: Category last modified date time
                example: "2022-01-01T01:01:01Z"
              modified_by:
                type: string
                example: "user"

    PatchCustomerCategory:
      type: object
      minProperties: 1
      properties:
        value:
          type: string
          pattern: "^[a-z0-9_]{1,50}$"
          description: Category value.
          example: "influencer"
          nullable: true
        description:
          type: string
          minLength: 1
          maxLength: 200
          description: Description of the category value.
          example: "This is an a of category 1"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 200
          description: Reason for the set of value.
          example: "Riesgo por campañas de fidelizacion: Fidelizacion CP Outbound MM"
          nullable: true

    SpecialTreatmentValues:
      type: object
      properties:
        values:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 50
          uniqueItems: true
      required:
        - values
      example:
        values: ["silver", "gold", "platinum", "vip"]

    CustomerSpecialTreatment:
      allOf:
        - $ref: '#/components/schemas/SpecialTreatmentValues'
        - type: object
          properties:
            values:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 50
              minItems: 0
              maxItems: 1
      example:
        values: ["vip"]

    Contracts:
      type: object
      required:
        - contracts
      additionalProperties: false
      properties:
        contracts:
          type: array
          description: Contracts
          items:
            $ref: '#/components/schemas/Contract'

    Contract:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-556642440000"
        account_external_id:
          type: string
          description: Account external id
          example: "214748364"
        start_date:
          type: string
          format: date-time
          description: Contract start date
          example: "2022-01-01T01:01:01Z"
        end_date:
          type: string
          format: date-time
          description: Contract end date
          example: "2022-01-01T01:01:01Z"
        requests:
          type: array
          description: Contract requests
          items:
            $ref: '#/components/schemas/ContractRequest'

    ContractRequest:
      type: object
      properties:
        request_external_id:
          type: string
          description: Request id
          example: "214748364"
        create_date:
          type: string
          format: date-time
          description: Category creation date
          example: "2022-01-01T01:01:01Z"
        contract_reference_id:
          type: string
          description: Contract reference id
          example: "MMC2105077108808"
        type:
          type: string
          description: Contract request type
          example: "SALE_MOBILE_ONLY"
        origin_user:
          type: string
          description: Origin user
          example: "john.doe"

    ErrorResponse:
      type: object
      additionalProperties: false
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
                description: Customer error code
              title:
                type: string
                description: Customer error title
              ref:
                type: string
              details:
                type: string
                description: Detailed description of the error

    ConvertNieToNifRequest:
      type: object
      required:
        - nif
      properties:
        nif:
          type: string
          minLength: 1
          description: NIF
          example: "07687697Q"

    PostAccountPromotion:
      type: object
      required:
        - promotion_id
      properties:
        promotion_id:
          type: integer
          description: Promotion identifier
          minLength: 1
          maxLength: 4
          example: 2064
        reference_date:
          type: string
          format: date
          description: Reference date to calculate activation date and expiration date
          example: "2025-09-01"

    PatchAccountPromotion:
      type: object
      required:
        - cancellation_date
      properties:
        cancellation_date:
          type: string
          format: date
          description: Cancellation Date to promotion in account
          example: "2025-09-01"

    AccountPromotion:
      type: object
      properties:
        id:
          type: string
          description: Promotion Account identifier
          format: uuid
          example: "123e4567-e89b-12d3-a456-556642440000"
        account_id:
          type: string
          description: Account identifier
          format: uuid
          example: "123e4567-e89b-12d3-a456-556642440000"
        promotion_id:
          type: integer
          description: Promotion identifier
          minLength: 1
          maxLength: 4
          example: 2064
        start_date:
          type: string
          format: date
          description: Star Date to promotion in account
          example: "2025-09-01"
        end_date:
          type: string
          format: date
          description: End Date to promotion in account
          example: "2026-03-01"
        status:
          type: string
          description: Status to promotion in account
          x-extensible-enum:
            - "PENDING"
            - "ACTIVATED"
            - "EXPIRED"
          example: "PENDING"

    AccountPromotions:
      type: array
      nullable: false
      minItems: 0
      items:
        $ref: '#/components/schemas/AccountPromotion'

    AccountPromotionHistory:
      type: object
      properties:
        account_id:
          type: string
          description: Account identifier
          format: uuid
          example: "123e4567-e89b-12d3-a456-556642440000"
        promotion_id:
          type: integer
          description: Promotion identifier
          minLength: 1
          maxLength: 4
          example: 2064
        start_date:
          type: string
          format: date
          description: Star Date to promotion in account
          example: "2025-09-01"
        end_date:
          type: string
          format: date
          description: End Date to promotion in account
          example: "2026-03-01"
        status:
          type: string
          description: Status to promotion in account
          x-extensible-enum:
            - "PENDING"
            - "ACTIVATED"
            - "EXPIRED"
          example: "PENDING"
        operation:
          type: string
          description: Operation
          x-extensible-enum:
            - "INSERT"
            - "UPDATE"
            - "DELETE"
          example: "INSERT"

    AccountPromotionHistories:
      type: array
      nullable: false
      minItems: 0
      items:
        $ref: '#/components/schemas/AccountPromotionHistory'

    CreditCardTokenizationRequestDTO:
      type: object
      required:
        - reference_id
        - account_id
        - status
        - created_at
        - updated_at
      properties:
        reference_id:
          type: string
          format: uuid
          description: Unique reference ID for the tokenization request
          example: "550e8400-e29b-41d4-a716-446655440000"
        account_id:
          type: string
          format: uuid
          description: Account identifier
          example: "123e4567-e89b-12d3-a456-556642440000"
        status:
          type: string
          description: Tokenization request status
          enum:
            - PENDING
            - COMPLETED
            - REJECTED
            - TOKEN_ALREADY_EXISTS
            - OUTDATED
          example: "COMPLETED"
        token_id:
          type: string
          nullable: true
          description: Credit card token (present when status=COMPLETED)
          example: "8E1C82FDC10E4FE78F10BAF9C4DEB93C"
        error_message:
          type: string
          nullable: true
          description: Error details (present when status=REJECTED)
          example: "The credit card tokenization process failed due to invalid card details"
        created_at:
          type: string
          format: date-time
          description: Timestamp when the request was created
          example: "2025-10-28T07:13:27Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the request was last updated
          example: "2025-10-28T07:13:27Z"

    CreditCardTokenizationRequestListDTO:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreditCardTokenizationRequestDTO'

    InvoicePersonalInfoName:
      type: string
      description: Customer's first name
      example: "Jose"
      minLength: 1
      maxLength: 255

    InvoicePersonalInfoFirstSurname:
      type: string
      description: Customer's first surname
      example: "Carrero"
      nullable: true
      minLength: 2
      maxLength: 255

    InvoicePersonalInfoSecondSurname:
      type: string
      description: Consumer's rest of surnames
      example: "Diaz"
      nullable: true
      minLength: 2
      maxLength: 255

  examples:
    get_telco_postpaid_account_with_direct_debit:
      summary: Example of a telco postpaid account with direct debit
      value:
        id: 4b155f4a-a0e4-41f2-a0d3-987d1f4bc363
        external_id: 789345
        customer_id: e3483c02-d25b-4317-80fd-2b77c93ce59c
        customer_external_id: "23768603"
        contract_reference: MMC1708177227910
        modality: POSTPAID
        billing_address:
          address_lines: ["Avenida de Bruselas, 38"]
          postal_code: "28108"
          state_id: "28"
          locality: "Alcobendas"
          administrative_area: "Madrid"
          region_code: "ES"
        payment_method:
          type: "DIRECT_DEBIT"
          details:
            iban: "ES7921000813610123456789"
        created_at: "2021-01-01T00:00:00Z"
        updated_at: "2021-01-01T00:00:00Z"
    get_telco_postpaid_account_with_bank_transfer:
      summary: Example of a telco postpaid account with bank transfer
      value:
        id: 4b155f4a-a0e4-41f2-a0d3-987d1f4bc363
        external_id: 789345
        customer_id: e3483c02-d25b-4317-80fd-2b77c93ce59c
        customer_external_id: "23768603"
        contract_reference: MMC1708177227910
        modality: POSTPAID
        billing_address:
          address_lines: ["Avenida de Bruselas, 38"]
          postal_code: "28108"
          state_id: "28"
          locality: "Alcobendas"
          administrative_area: "Madrid"
          region_code: "ES"
        payment_method:
          type: "BANK_TRANSFER"
        created_at: "2021-01-01T00:00:00Z"
        updated_at: "2021-01-01T00:00:00Z"
    get_telco_postpaid_account_with_teci:
      summary: Example of a telco postpaid account with teci
      value:
        id: 4b155f4a-a0e4-41f2-a0d3-987d1f4bc363
        external_id: 789345
        customer_id: e3483c02-d25b-4317-80fd-2b77c93ce59c
        customer_external_id: "23768603"
        contract_reference: MMC1708177227910
        modality: POSTPAID
        billing_address:
          address_lines: ["Avenida de Bruselas, 38"]
          postal_code: "28108"
          state_id: "28"
          locality: "Alcobendas"
          administrative_area: "Madrid"
          region_code: "ES"
        payment_method:
          type: "TECI"
          details:
            token-teci: "Ob1dI04xvw-k25HBs3a4SHqTkkRWxKAnbFVcX1QzAfk"
        created_at: "2021-01-01T00:00:00Z"
        updated_at: "2021-01-01T00:00:00Z"
    get_digital_recurring_prepaid_account:
      summary: Example of a digital account
      value:
        id: 4b155f4a-a0e4-41f2-a0d3-987d1f4bc363
        customer_id: e3483c02-d25b-4317-80fd-2b77c93ce59c
        contract_reference: ORC1708177227910
        modality: RECURRING_PREPAID
        payment_method:
          type: "CREDIT_CARD"
          details:
            token_id: 5e85be4a-6903-4ea6-8ab4-4b972339747d
        created_at: "2021-01-01T00:00:00Z"
        updated_at: "2021-01-01T00:00:00Z"
    post_postpaid_account_iban:
      summary: New postpaid account with DIRECT_DEBIT
      value:
        modality: "POSTPAID"
        billing_address:
          address_lines: ["Avenida de Euclides"]
          postal_code: "28108"
          locality: "Alcobendas"
          administrative_area: "Madrid"
          region_code: "ES"
        payment_method:
          type: "DIRECT_DEBIT"
          details:
            iban: "ES7921000813610123459999"
    post_postpaid_account_bank_transfer:
      summary: New postpaid account with BANK_TRANSFER
      value:
        modality: "POSTPAID"
        billing_address:
          address_lines: ["Avenida de Euclides"]
          postal_code: "28108"
          locality: "Alcobendas"
          administrative_area: "Madrid"
          region_code: "ES"
        payment_mtehod:
          type: "BANK_TRANSFER"
    post_postpaid_account_credit_card:
      summary: New digital account with CREDIT_CARD
      value:
        modality: "RECURRING_PREPAID"
        payment_method:
          type: "CREDIT_CARD"
          details:
            token_id: "123e4567-e89b-12d3-a456-5566424443242"
    post_private_customer:
      summary: New private customer
      value:
        type: "PRIVATE_CUSTOMER"
        preferred_language: "es"
        segment: "CONSUMER"
        contact_info:
          phone_numbers:
            - country_code: "+34"
              type: "MOBILE"
              number: "666777888"
          emails:
            - email: "john.doe@example.com"
          postal_address:
            - address_lines: [ "Avenida de Euclides" ]
              postal_code: "28108"
              locality: "Alcobendas"
              administrative_area: "Madrid"
              region_code: "ES"
        personal_info:
          name: "John"
          first_surname: "Doe"
          second_surname: "Smith"
          nationality: "ES"
          birthdate: 1975-03-26
          identity_document:
            type: "NIF"
            number: "14861628V"
    post_corporate_customer:
      summary: New corporate customer
      value:
        type: "CORPORATE_CUSTOMER"
        preferred_language: "es"
        segment: "SME"
        contact_info:
          phone_numbers:
            - country_code: "+34"
              type: "MOBILE"
              number: "666777888"
          emails:
            - email: john.doe@example.com
          postal_address:
            - address_lines: [ "Avenida de Euclides" ]
              postal_code: "28108"
              locality: "Alcobendas"
              administrative_area: "Madrid"
              region_code: "ES"
        company_info:
          legal_name: "Acme inc"
          founding_date: 1975-03-26
          identity_document:
            type: "CIF"
            number: "U24142952"
    post_digital_customer:
      summary: New digital customer
      value:
        type: "DIGITAL_CUSTOMER"
        preferred_language: "es"
        digital_personal_info:
          name: "John"
          first_surname: "Doe"
          second_surname: "Smith"
          email: "john.doe@example.com"
          mobile_phone_number:
            country_code: "+34"
            number: "666777888"
    patch_account_payment_method_credit_card:
      summary: Update account payment method to CREDIT_CARD
      value:
        type: "CREDIT_CARD"
        details:
          token_id: "e58ed763-928c-4155-bee9-fdbaaadc15f3"
    patch_account_payment_method_direct_debit:
      summary: Update account payment method to DIRECT_DEBIT
      value:
        type: "DIRECT_DEBIT"
        details:
          iban: "ES7921000813610123459999"
    patch_account_payment_method_bank_transfer:
      summary: Update account payment method to BANK_TRANSFER
      value:
        type: "BANK_TRANSFER"
    response_list_identification_processes:
      summary: Provides a list of customer identification processes
      value:
        process_id: "4189285b-08f8-4628-adda-4767d81362e7"
        process_date: "2023-01-27T03:44:52.000Z"
    request_nif_identification_process:
      summary: Provides an customer identification process with a downloadable NIF document
      value:
        process_id: "123e4567-e89b-12d3-a456-556642440000"
        process_date: "2023-01-27T03:44:52.000Z"
        document:
          url_expiration_date: "2023-01-27T03:44:52.000Z"
          public_url: "https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d"
          media_type: "application/pdf"
          name: "my_nif"
          type: "NIF"
          size_bytes: 789561
    request_nie_identification_process:
      summary: Provides an customer identification process with a downloadable NIE document
      value:
        process_id: "123e4567-e89b-12d3-a456-556642440000"
        process_date: "2023-01-27T03:44:52.000Z"
        document:
          url_expiration_date: "2026-01-27T03:44:52.000Z"
          public_url: "https://storage.googleapis.com/mas-documents-prod/a7b2e693-d71a-4cee-8313-1972acc0394d"
          media_type: "application/pdf"
          name: "my_nie"
          type: "NIE"
          size_bytes: 896123
    request_passport_identification_process:
      summary: Provides an customer identification process with a downloadable Passport document
      value:
        process_id: "123e4567-e89b-12d3-a456-556642440000"
        process_date: "2023-01-27T03:44:52.000Z"
        document:
          url_expiration_date: "2025-01-27T03:44:52.000Z"
          public_url: "https://storage.googleapis.com/mas-documents-prod/9cb2e693-d71a-4cee-8313-1972acc0394d"
          media_type: "application/pdf"
          name: "my_passport"
          type: "PASSPORT"
          size_bytes: 512345
    request_account_promotion_create:
      summary: Post standard to add promotion to account
      value:
        promotion_id: "2064"
        reference_date: "2025-09-01"
    request_account_promotion_update:
      summary: Patch standard to add promotion to account
      value:
        cancellation_date: "2025-09-01"
    get_digital_customer:
      summary: Digital Customer Example
      value:
        id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        type: "DIGITAL_CUSTOMER"
        preferred_language: "es"
        created_at: "2024-01-15T10:30:00Z"
        updated_at: "2024-06-20T14:45:00Z"
        digital_personal_info:
          name: "Jose"
          first_surname: "Carrero"
          second_surname: "Diaz"
          email: "jose.carrero@example.com"
          mobile_phone_number:
            country_code: "+34"
            number: "612345678"
    get_private_customer:
      summary: Private Customer Example
      value:
        id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        external_id: "214748364"
        type: "PRIVATE_CUSTOMER"
        preferred_language: "es"
        segment: "INDIVIDUAL"
        created_at: "2023-03-10T09:15:00Z"
        updated_at: "2024-05-25T16:20:00Z"
        personal_info:
          identity_document:
            number: "12345678Z"
            type: "NIF"
          name: "Antonio"
          first_surname: "Benavente"
          second_surname: "Blanco"
          gender: "MALE"
          nationality: "ES"
          birthdate: "1985-07-15"
        contact_info:
          phone_numbers:
            - country_code: "+34"
              number: "698765432"
              type: "MOBILE"
          emails:
            - "antonio.benavente@example.com"
          addresses:
            - street_name: "Calle Gran Via"
              street_number: "28"
              postal_code: "28013"
              city: "Madrid"
              province: "Madrid"
              country: "ES"
    get_corporate_customer:
      summary: Corporate Customer Example
      value:
        id: "c3d4e5f6-a7b8-9012-cdef-123456789012"
        external_id: "987654321"
        type: "CORPORATE_CUSTOMER"
        preferred_language: "es"
        segment: "SME"
        created_at: "2022-11-05T11:00:00Z"
        updated_at: "2024-04-12T13:30:00Z"
        company_info:
          identity_document:
            number: "B12345678"
            type: "CIF"
          legal_name: "Tecnologías Avanzadas SL"
          founding_date: "2015-03-20"
          associated_users:
            - identity_document:
                number: "87654321X"
                type: "NIF"
              name: "Maria"
              first_surname: "Garcia"
              second_surname: "Lopez"
              nationality: "ES"
        contact_info:
          phone_numbers:
            - country_code: "+34"
              number: "917654321"
              type: "LANDLINE"
            - country_code: "+34"
              number: "655443322"
              type: "MOBILE"
          emails:
            - "contacto@example.com"
          addresses:
            - street_name: "Paseo de la Castellana"
              street_number: "95"
              postal_code: "28046"
              city: "Madrid"
              province: "Madrid"
              country: "ES"

  x-releaseInfo:
    description: >
      ### Release Notes
      * **4.66.4** : Add secondary language to customer responses.
        - Added `secondary_language` field to `CustomerResponseCommonProperties` schema.
        - Added `secondary_language` field to `DigitalCustomerResponse` schema.

      * **4.66.3** : Modify permission for endpoint.
        - Modify permission of PATCH /orgs/{org_id}/customers/{customer_id}/credentials
        - Modify permission of POST /orgs/{org_id}/customers/{customer_id}/credentials/change
        - Modify permission of POST /orgs/{org_id}/customers/{customer_id}/credentials/activate

      * **4.66.2** : Modify permission for endpoint.
        - Modify permission of PUT /orgs/{org_id}/customers/{customer_id}/associated_users
      
      * **4.66.1** : Document the credential generation process when a customer is registered.
        - Modify description of POST /orgs/{org_id}/customers 
        - Modify description of PATCH /orgs/{org_id}/customers/{customer_id}

      * **4.66.0** : Add POST /credentials/change endpoint to update customer credential username
        - Added new endpoint POST /orgs/{org_id}/customers/{customer_id}/credentials/change

      * **4.65.0** : Align email/username maxLength with domain validation.
        - `DigitalEmail`: maxLength 255 → 82.
        - `Credential.username` and `CredentialResponse.username`: maxLength 150 → 82.

      * **4.64.1** : Add external_id to CustomerSearchResponse:
        - Added `external_id` field to `CustomerSearchResponse` schema

      * **4.64.0** : Update credentials endpoints:
        - PATCH /orgs/{org_id}/customers/{customer_id}/credentials: removed credential_id path parameter
        - Added new endpoint POST /orgs/{org_id}/customers/{customer_id}/credentials/activate (no body, 202 Accepted)

      * **4.63.0** : Add new endpoints
        - Added new endpoint POST /orgs/{org_id}/customers/{customer_id}/credentials/migration

      * **4.62.2** : Delete type for GET /orgs/{org_id}/accounts/{account_id}/invoice-recipient
        - Delete user type
        - Add field name for different customers
      
      * **4.62.1** : Add nationality field to PatchPersonalInfo
        - Added `nationality` field to `PatchPersonalInfo` schema
        - Added `PersonalInfoNationality` schema with ISO 3166-1 alpha-2 pattern validation (`^[A-Z]{2}$`)
      
      * **4.62.0** : Add address_lines validation for undefined string and max length 100
        - Reject `address_lines` values containing the literal string `"undefined"` in POST /customers and POST /customers/{id}/accounts
        - Enforce max length of 100 characters on `address_lines` items, aligned with Oracle column limits
        - Updated `maxLength` from 255 to 100 in `Address` and `BillingAddress` schemas

      * **4.61.0** : Add new endpoints
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}/invoice-recipient

      * **4.60.0** : Add PUT /customers/{customer_id}/associated_users:
        - Added new endpoint PUT /orgs/{org_id}/customers/{customer_id}/associated_users
        - Added schema `PutAssociatedUsersRequest` for the request body (reuses `AssociatedUser` for items)

      * **4.59.0** : Add description in PatchCompanyInfo object
        - Added description in PatchCompanyInfo object to show some examples of valid and invalid uses

      * **4.57.0** : Remove associated_users from customers PATCH:
        - Removed `associated_users` property from `PatchCompanyInfo` schema
        - Removed `PatchAssociatedUser` schema (no longer referenced)
        - GET operations retain full `associated_users` support in `CompanyInfo` and `CompanyInfoResponse`

      * **4.56.1** : Add customer_external_id to GET Account response
        - Added optional nullable field customer_external_id to GET /orgs/{org_id}/accounts/{account_id} response
        - Field contains the legacy Oracle CUSTOMERID for Telco customers, null for Digital customers

      * **4.56.0** : Add PATCH customers credentials:
        - Added new endpoint PATCH /orgs/{org_id}/customers/{customer_id}/credentials/{credential_id}
      
      * **4.55.0** : Add credit card tokenization support
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}/tokenization-requests
        - Added reference_id option in POST /orgs/{org_id}/customers/{customer_id}/accounts payment method details
        - Added reference_id option in PATCH /orgs/{org_id}/accounts/{account_id}/payment-method details
         
      * **4.54.2** : Add examples for customer types in GET /orgs/{org_id}/customers/{customer_id}
        - Added examples for Digital Customer, Private Customer, and Corporate Customer response types
        - Examples demonstrate the different response schemas based on customer type discriminator

      * **4.54.1** : change permissions read for list in the endpoints
        - GET /orgs/{org_id}/accounts/{account_id}/promotions
        - GET /orgs/{org_id}/accounts/{account_id}/promotions_hist

      * **4.54.0** : Add new endpoints
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}/promotions
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}/promotions_hist

      * **4.53.1** : modify respond to post account promotion endpoint
        - Add response body in  endpoint POST /orgs/{org_id}/accounts/{account_id}/promotions

      * **4.53.0**: Add new endpoint
        - Added new endpoint PATCH and POST /orgs/{org_id}/accounts/{account_id}/promotions

      * **4.52.0**: Add new endpoint
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}/billing-address

      * **4.51.2**: Remove special treatment pattern restriction
        - Removed pattern restriction for special treatment values in POST and PUT endpoints.

      * **4.51.1**: Update life cycle object documentation

      * **4.51.0**: Add new endpoint
        - Added new endpoint DELETE /orgs/{org_id}/customers/{customer_id}/special-treatment
      
      * **4.50.0**: Add new endpoints
        - Added new endpoint GET /orgs/{org_id}/special-treatment
        - Added new endpoint PATCH /orgs/{org_id}/special-treatment
        - Added new endpoint GET /orgs/{org_id}/customers/{customer_id}/special-treatment
        - Added new endpoint PUT /orgs/{org_id}/customers/{customer_id}/special-treatment
      
      * **4.49.1**: Permission unification.

      * **4.49.0** : Changes in returned fields for GET /orgs/{org_id}/accounts/{account_id}
       - New: Added new delivery_mode to AccountInvoice schema.

      * **4.48.0** : Changes in returned fields for GET /orgs/{org_id}/accounts/{account_id}
       - New: Added new not nullable field due_date_id to AccountInvoice schema.
       - New: Added new not nullable field due_days_id to AccountInvoice schema.
      
      * **4.47.0** : Add new endpoint
        - Added new endpoint PATCH /orgs/{org_id}/customers/{customer_id}/convert-nie-to-nif

      * **4.46.0** : Make payment_method optional field for GET /orgs/{org_id}/accounts/{account_id}
       - Prepaid accounts will not have payment_method field in the response.
      
      * **4.45.0** : Allow TECI payment method
       - Adds examples for get account with TECI payment method.
       - Change enum for available payment methods.
     
      * **4.44.0** : Added new field to GET /orgs/{org_id}/accounts/{account_id}
       - Added new schema AccountInvoice to GetAccount with field <code>cycle</code>.
       - Added fields <code>name</code>,  <code>day</code>, <code>type</code> and <code>frequency</code> to InvoiceCycle schema.
      
      * **4.43.0** : Add Customer Identification Process endpoints
        - Add new endpoint: GET /orgs/{org_id}/customers/{customer_id}/identification-processes/{identification_process_id}
        - Add new endpoint: GET /orgs/{org_id}/customers/{customer_id}/identification-processes

      * **4.42.0** : Added properly formed examples
       - Adds examples to several endpoints with correct requests/responses, as some autogenerated examples where semantically incorrect.
       - Moves some examples to the components section.
      
      * **4.41.0** : Removed status from GetAccount schema. Changed 
        - Removed `status` field from GetAccount schema. Won't be used
        - Changed PaymentMethod required field from `reference_id` to `token_id`
      
      * **4.40.0** : Removed status from GetAccount schema. Changed 
        - Removed `status` field from GetAccount schema. Won't be used
        - Changed PaymentMethod required field from `reference_id` to `token_id`
      
      * **4.39.0** : Add new field to GetAccount schema and refactor GetPaymentMethod. Removed uuid from `reference_id` field
        - Added new field `status` with enum values ACTIVE and PAYMENT_METHOD_PENDING to GetAccount schema
        - Added oneOf to identify if payment method is DirectDebit or CreditCard more easily
        - Removed uuid format from `reference_id` field in GetPaymentMethod schema
      
      * **4.38.0** : Add new field to BillingAddress schema
        - Added new field `state_id` to BillingAddress schema
      
      * **4.37.0** : Fix schema name NewDigitalCustomer
        - Fix schema name DigitalCustomer to NewDigitalCustomer for consistency in schema names
      
      * **4.36.0** : Modify POST /accounts and GET /account
        - Delete required to billing_address object in POST /accounts
        - New enum RECURRING_PREPAID modality in POST /accounts
        - New enum RECURRING_PREPAID in GET /accounts/{account_id}
        - New enum CREDIT_CARD in PaymentType schema
        - New property reference_id in PaymentMethod schema to POST /accounts
        - (fix) Delete external_id in DigitalCustomerResponse schema
      
      * **4.35.0** : Modify response of GET /accounts/{account_id}
        - Modified response endpoint GET /orgs/{org_id}/accounts/{account_id}
      
      * **4.34.0** : Update format for credit card expiration date
        - Updated endpoint GET /orgs/{org_id}/customers/{customer_id}/available-credit-cards
      
      * **4.33.0** : Add new schema DigitalCustomer to post customer, get customer and patch customer
        - Added new schema DigitalCustomer #/components/schemas/DigitalCustomer
        - Added new schema DigitalPersonalInfoResponse #/components/schemas/DigitalPersonalInfoResponse
        - Added new schema PatchDigitalPersonalInfo #/components/schemas/PatchDigitalPersonalInfo
        - Added new schema MobilePhoneNumber #/components/schemas/MobilePhoneNumber
      
      * **4.32.0** : Add new endpoint
        - Added new endpoint PATCH /orgs/{org_id}/accounts/{account_id}/payment-method
      
      * **4.31.0** : Add new endpoint
        - Added new endpoint GET /orgs/{org_id}/customers/{customer_id}/available-credit-cards
      
      * **4.30.0** : Delete customer credentials by id
        - Added credential id to the response of GET /orgs/{org_id}/customers/{customer_id}/credentials
        - Refactor endpoint DELETE /orgs/{org_id}/customers/{customer_id}/credentials/{credential_id} to delete using the credential id instead of the username
      
      * **4.29.0** : Add new POST type endpoint to associate categories to customer
        - Added new endpoint POST /orgs/{org_id}/customers/{customer_id}/categories/{category_id}

      * **4.28.0** : Add new endpoint
        - Added new endpoint DELETE /orgs/{org_id}/categories/{category_id}
      
      * **4.27.0** : Add new endpoint
        - Added new endpoint PATCH /orgs/{org_id}/categories/{category_id}
      
      * **4.26.0** : Add new endpoint
        - Added new endpoint DELETE /orgs/{org_id}/customers/{customer_id}/categories/{category_id}
      
      * **4.25.0** : Add new endpoint
        - Added new endpoint GET /orgs/{org_id}/customers/{customer_id}/categories/{category_id}
      
      * **4.24.0** : Add new endpoint
        - Added new endpoint GET /orgs/{org_id}/customers/search
      
      * **4.23.0** : Added category valid_values
        - add field valid_values to Category and PostCategories
      
      * **4.22.2** : Unify Segment
        - remove PrivateSegment and replace it with Segment
        - remove CorporateSegment and replace it with Segment
      
      * **4.22.1** : Add missing HTTP status code
        - added to all endpoints the missing HTTP status codes that could be returned.
      
      * **4.22.0** : Adds new endpoint
        - added url GET /orgs/{org_id}/customers/{customers_id}/accounts
      
      * **4.21.0** : Added new endpoint
        - added new endpoint PATCH /orgs/{org_id}/customers

      * **4.20.3** : Merged segment field on GET /orgs/{org_id}/customers/{customer_id}
        - PrivateSegment and CorporateSegment schemas have been merged into Segment for the getCustomer operation.
      
      * **4.20.2** : Rework of field in GET /orgs/{org_id}/accounts/{account_id}
        - Rework of <code>payment_method</code> field.
      
      * **4.20.1** : Fixed field format GET /orgs/{org_id}/accounts/{account_id}
        - Added UUID format to <code>customer_id</code> field.
      
      * **4.20.0** : Added new endpoint GET /orgs/{org_id}/accounts/{account_id}
        - Added new endpoint GET /orgs/{org_id}/accounts/{account_id}
      
      * **4.19.0** : Updated getCustomer endpoint response with all the missing fields.
        - getCustomer now returns either a PrivateCustomer or a CorporateCustomer plus the generated fields.
        - Generated fields have been renamed to created_at, ended_at and updated_at.
        - `external_id` has been removed from the response. It can be added in the future if needed.
      
      * **4.18.0** : Segment enum is split into two separate enums, one for private customer, another for corporate customer. 
      
      * **4.17.0** : Changes in response code set for getCustomerIdByCustomerExternalId endpoint
              - added 500 error code
              - removed 400 error code
      
      * **4.16.0** : Changes in response code set for getAccountIdByAccountExternalId endpoint
        - added 500 error code
        - removed 400 error code
      
      * **4.15.0** : Adding required field in AssociatedUser
        - Added <code>nationality></code> fields in AssociatedUser
      
      * **4.14.0** : LanguageCode schema type changed from string to enum
        - LanguageCode schema type changed from string to enum
      
      * **4.13.0** : Adds new endpoint
        - added url GET /orgs/{org_id}/external-accounts/{external_account_id}
      
      * **4.12.0** : Adds new endpoint
        - added url POST /orgs/{org_id}/customers/{customer_id}/accounts
      
      * **4.11.2** : Removed non-required fields in AssociatedUser and added new field to POST /orgs/{org_id}/customers response
        - Removed <code>contact_info></code> and <code>nationality></code> fields in AssociatedUser
        - Added <code>external_id></code> to POST /orgs/{org_id}/customers response
      
      * **4.11.1** : Validation in ContactInfo Schema
        - Added required properties and pattern/format validation in ContactInfo Schema  
      
      * **4.11.0** : Adds new endpoint
        - added url DELETE /orgs/{org_id}/customers/{customer_id}
      
      * **4.10.0** : Adds new endpoint
        - added url DELETE /orgs/{org_id}/customers/{customer_id}/credentials/{username}

      * **4.9.0** : Adds new endpoint
        - added url DELETE /orgs/{org_id}/customers/{customer_id}/accounts/{account_id}
      
      * **4.8.0** : Adds new endpoint
        - added url POST /orgs/{org_id}/customers/{customer_id}/credentials
      
      * **4.7.1** : Changed return code in PATCH and returning new dates renamed with time
        - Changed return code from 200 to 201 PATCH /orgs/{org_id}/customers/{customer_id}/categories
        - Changed return code from 200 to 201 PATCH /orgs/{org_id}/external-customers/{customer_external_id}/categories
        - New fields <code>create_date_time></code>, <code>end_date_time></code>, <code>last_modified_date_time></code> 
            in GET /orgs/{org_id}/customers/{customer_id}/categories
      
      * **4.7.0** : Added customer schema
        - added customer schema
      
      * **4.6.1** : Changes POST /orgs/{org_id}/customers
        - change request to avoid auto generated fields
      
      * **4.6.0** : Adds new endpoint
        - add url POST /orgs/{org_id}/customers/credentials
      
      * **4.5.0** : Adds new endpoint
        - add url POST /orgs/{org_id}/customers

      * **4.3.6** : Field <code>value></code> in customer categories now is nullable
        - Field <code>value></code> in customer categories now is nullable. Customer categories with null value won't be shown
      
      * **4.3.5** : Delete traceability system.
        - erase url /orgs/{org_id}/traces/customers
        - erase url /orgs/{org_id}/traces/trees
      * **4.3.4** : Adds ErrorResponse schema and adds disable additional properties on responses.
      
      * **4.3.3** : Remove max-length from <code>reason></code> in customer category. Will be checked in code 
        - Removed maxLength from <code>reason></code> field

      * **4.3.2** : Creation this change logs and rename enums to TraceParams
        - Creation this release notes
        - Rename Enums to TraceParams