openapi: 3.1.0
info:
  title: SAP Commerce Cloud Assisted Service Module API
  description: >-
    REST API for assisted service capabilities in SAP Commerce Cloud,
    enabling customer service representatives (CSRs) to assist customers
    with their shopping experience. Provides operations for customer
    lookup, cart emulation, session management, and customer 360 view.
  version: '1.0'
  contact:
    name: SAP Support
    url: https://support.sap.com/
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
externalDocs:
  description: Assisted Service Module Documentation
  url: https://help.sap.com/docs/SAP_COMMERCE/9d346683b0084da2938be8a285c0c27a/8b571515866910148fc18b9e59d3e084.html
servers:
  - url: https://{tenant}.{region}.commercecloud.sap/assistedservicewebservices
    description: SAP Commerce Cloud Production
    variables:
      tenant:
        description: Tenant identifier
        default: my-tenant
      region:
        description: Deployment region
        default: us
tags:
  - name: Agents
    description: Customer service agent operations
  - name: Carts
    description: Cart emulation and management on behalf of customers
  - name: Customers
    description: Customer lookup and 360 view
  - name: Sessions
    description: Assisted service session management
security:
  - oauth2: []
paths:
  /customers/search:
    get:
      operationId: searchCustomers
      summary: SAP Commerce Cloud Search customers
      description: >-
        Search for customers by name, email, or customer ID. Used by
        customer service agents to find customer accounts.
      tags:
        - Customers
      parameters:
        - name: query
          in: query
          required: true
          description: Search query (name, email, or customer ID)
          schema:
            type: string
        - name: baseSite
          in: query
          required: true
          description: Base site identifier
          schema:
            type: string
        - $ref: '#/components/parameters/currentPage'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Customer search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchPage'
        '401':
          description: Unauthorized
        '403':
          description: Agent does not have required permissions
  /customers/{customerId}:
    get:
      operationId: getCustomer360
      summary: SAP Commerce Cloud Get customer 360 view
      description: >-
        Retrieve a comprehensive 360-degree view of a customer including
        profile information, recent orders, active carts, and support tickets.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerId'
        - name: baseSite
          in: query
          required: true
          description: Base site identifier
          schema:
            type: string
      responses:
        '200':
          description: Customer 360 data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer360Data'
        '404':
          description: Customer not found
  /customers/{customerId}/carts:
    get:
      operationId: getCustomerCarts
      summary: SAP Commerce Cloud List customer carts
      description: >-
        Retrieve all carts belonging to a customer, used by agents
        to view and assist with shopping.
      tags:
        - Carts
      parameters:
        - $ref: '#/components/parameters/customerId'
        - name: baseSite
          in: query
          required: true
          description: Base site identifier
          schema:
            type: string
      responses:
        '200':
          description: Customer carts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartList'
        '404':
          description: Customer not found
  /sessions:
    post:
      operationId: createAssistedSession
      summary: SAP Commerce Cloud Start assisted service session
      description: >-
        Start a new assisted service session, binding the agent to a
        customer for cart emulation and support activities.
      tags:
        - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistedSessionRequest'
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistedSession'
        '400':
          description: Invalid session request
        '401':
          description: Unauthorized
  /sessions/{sessionId}:
    get:
      operationId: getAssistedSession
      summary: SAP Commerce Cloud Get session details
      description: >-
        Retrieve details of an active assisted service session.
      tags:
        - Sessions
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Assisted service session identifier
          schema:
            type: string
      responses:
        '200':
          description: Session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistedSession'
        '404':
          description: Session not found
    delete:
      operationId: endAssistedSession
      summary: SAP Commerce Cloud End assisted service session
      description: >-
        End an active assisted service session.
      tags:
        - Sessions
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Assisted service session identifier
          schema:
            type: string
      responses:
        '200':
          description: Session ended
        '404':
          description: Session not found
  /agents/{agentId}:
    get:
      operationId: getAgent
      summary: SAP Commerce Cloud Get agent details
      description: >-
        Retrieve details of a customer service agent.
      tags:
        - Agents
      parameters:
        - name: agentId
          in: path
          required: true
          description: Agent identifier
          schema:
            type: string
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          description: Agent not found
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Commerce Cloud
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            basic: Basic access
            assistedservicegroup: Assisted service agent access
  parameters:
    customerId:
      name: customerId
      in: path
      required: true
      description: Customer unique identifier
      schema:
        type: string
    currentPage:
      name: currentPage
      in: query
      description: Current page number (zero-based)
      schema:
        type: integer
        default: 0
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page
      schema:
        type: integer
        default: 20
  schemas:
    CustomerSearchPage:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSearchEntry'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CustomerSearchEntry:
      type: object
      properties:
        uid:
          type: string
          description: Customer email or UID
        name:
          type: string
          description: Customer full name
        customerId:
          type: string
          description: Customer ID
        lastCartId:
          type: string
          description: ID of the customer's most recent cart
        hasOrder:
          type: boolean
          description: Whether the customer has placed orders
    Customer360Data:
      type: object
      properties:
        overview:
          type: object
          properties:
            name:
              type: string
              description: Customer name
            email:
              type: string
              description: Customer email
            signedUpDate:
              type: string
              format: date-time
              description: Registration date
            address:
              type: object
              properties:
                town:
                  type: string
                country:
                  type: string
        latestActivity:
          type: object
          properties:
            type:
              type: string
              description: Activity type
            description:
              type: string
              description: Activity description
            date:
              type: string
              format: date-time
        recentOrders:
          type: array
          items:
            $ref: '#/components/schemas/OrderSummary'
        activeCarts:
          type: array
          items:
            $ref: '#/components/schemas/CartSummary'
        supportTickets:
          type: array
          items:
            $ref: '#/components/schemas/TicketSummary'
    OrderSummary:
      type: object
      properties:
        code:
          type: string
          description: Order code
        status:
          type: string
          description: Order status
        total:
          type: string
          description: Formatted order total
        placed:
          type: string
          format: date-time
          description: Order placement date
    CartSummary:
      type: object
      properties:
        code:
          type: string
          description: Cart code
        totalItems:
          type: integer
          description: Number of items
        total:
          type: string
          description: Formatted cart total
        modified:
          type: string
          format: date-time
          description: Last modification time
    TicketSummary:
      type: object
      properties:
        id:
          type: string
          description: Ticket identifier
        subject:
          type: string
          description: Ticket subject
        status:
          type: string
          description: Ticket status
        created:
          type: string
          format: date-time
          description: Ticket creation date
    CartList:
      type: object
      properties:
        carts:
          type: array
          items:
            $ref: '#/components/schemas/CartSummary'
    AssistedSessionRequest:
      type: object
      required:
        - customerId
        - baseSite
      properties:
        customerId:
          type: string
          description: Customer ID to assist
        baseSite:
          type: string
          description: Base site identifier
        cartId:
          type: string
          description: Optional specific cart to work with
    AssistedSession:
      type: object
      properties:
        sessionId:
          type: string
          description: Unique session identifier
        agentId:
          type: string
          description: Agent identifier
        customerId:
          type: string
          description: Customer being assisted
        baseSite:
          type: string
          description: Base site context
        cartId:
          type: string
          description: Active cart in the session
        createdAt:
          type: string
          format: date-time
          description: Session start time
        status:
          type: string
          enum:
            - ACTIVE
            - ENDED
          description: Session status
    Agent:
      type: object
      properties:
        uid:
          type: string
          description: Agent unique identifier
        name:
          type: string
          description: Agent full name
        email:
          type: string
          description: Agent email
        groups:
          type: array
          items:
            type: string
          description: Agent permission groups
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of results per page
        totalPages:
          type: integer
          description: Total number of pages
        totalResults:
          type: integer
          description: Total number of results