Magic Moment

Magic Moment Playbook Salesforce Integration API

Swagger 2.0 contract for the Playbook Salesforce integration service: OAuth 2.0 connection to Salesforce, sync settings, field and ID mappings, engagement sync settings, Salesforce lead statuses / opportunity stages / users lookups, Marketo credential settings, and read-sync triggering. Authenticated with an x-access-token (tenant/user) or x-api-key header.

GitHub OpenAPI

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/magic-moment/refs/heads/main/openapi/magic-moment-salesforce-integration-openapi.yml

Other Resources

🔗
Swagger
https://raw.githubusercontent.com/api-evangelist/magic-moment/refs/heads/main/openapi/_original/magic-moment-salesforce-integration-swagger.json
🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/magic-moment/refs/heads/main/overlays/magic-moment-salesforce-integration-overlay.yaml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/magic-moment/refs/heads/main/apis.yml

OpenAPI Specification

magic-moment-salesforce-integration-openapi.yml Raw ↑ 
consumes:
- application/json
produces:
- application/json
swagger: '2.0'
info:
  description: Salesforce連携アプリケーションAPI仕様
  title: Salesforce連携アプリケーション
  version: 1.0.0
paths:
  /crm/lead_statuses:
    get:
      security:
      - accessToken: []
      tags:
      - fetch_sfdc
      summary: Get value from Salesforce LeadStatus Object
      operationId: getLeadStatusOfSfdc
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/sfdc_api_name'
  /crm/opportunity_stages:
    get:
      security:
      - accessToken: []
      tags:
      - fetch_sfdc
      summary: Get value from Salesforce OpportunityStage Object
      operationId: getOpportunityStageOfSfdc
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/sfdc_api_name'
  /crm/users:
    get:
      security:
      - accessToken: []
      tags:
      - fetch_sfdc
      summary: Show list salesforce users API
      operationId: getSalesforceUsers
      parameters:
      - type: string
        name: keyword
        in: query
      - type: array
        items:
          type: string
        name: sfdcIds
        in: query
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/salesforceUser'
  /engagement_sync_settings:
    get:
      security:
      - accessToken: []
      tags:
      - engagement_sync_settings
      summary: Get EngagementSyncSetting data beetwen Playbook <-> Salesforce
      operationId: getEngagementSyncSettingOfSfdc
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/engagement_sync_setting'
    put:
      security:
      - accessToken: []
      tags:
      - engagement_sync_settings
      summary: Create/update EngagementSyncSetting data beetwen Playbook <-> Salesforce
      operationId: saveEngagementSyncSettingOfSfdc
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/engagement_sync_setting'
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/engagement_sync_setting'
  /engagement_sync_settings/{engagement_sync_setting_id}/:
    delete:
      security:
      - accessToken: []
      tags:
      - engagement_sync_settings
      summary: Delete Engagement sync setting
      operationId: deleteEngagementSyncSettingOfSfdc
      responses:
        '200':
          description: OK
    parameters:
    - $ref: '#/parameters/engagement_sync_setting_id'
  /healthcheck:
    get:
      tags:
      - utils
      summary: ヘルスチェック
      operationId: healthCheck
      responses:
        '200':
          description: OK
  /mappings:
    get:
      security:
      - accessToken: []
      tags:
      - mappings
      summary: Playbook <-> Salesforce の ID の対応関係を取得する
      operationId: getSyncIDMapOfSfdc
      parameters:
      - type: string
        format: uuid
        name: sync_setting_id
        in: query
      - type: string
        format: uuid
        name: mmp_id
        in: query
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/sync_id_maps'
    put:
      security:
      - accessToken: []
      tags:
      - mappings
      summary: Playbook <-> Salesforce の ID の対応関係を設定する
      operationId: saveSyncIDMapOfSfdc
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            id_maps:
              type: array
              items:
                type: object
                properties:
                  mmp_id:
                    $ref: '#/definitions/mmp_id'
                  sfdc_id:
                    $ref: '#/definitions/sfdc_id'
            sync_setting_id:
              $ref: '#/definitions/sync_setting_id'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/sync_id_maps'
  /mappings/{mapping_id}/:
    delete:
      security:
      - accessToken: []
      tags:
      - mappings
      summary: Delete mapping
      operationId: deleteSyncIDMapOfSfdc
      responses:
        '200':
          description: OK
    parameters:
    - $ref: '#/parameters/mapping_id'
  /oauth2/access-tokens:
    put:
      security:
      - apiKey: []
      tags:
      - oauth2
      summary: Update access tokens for all tenants
      operationId: updateAccessTokens
      responses:
        '204':
          description: OK
  /oauth2/authorize/:
    get:
      security:
      - accessToken: []
      tags:
      - oauth2
      summary: Salesforce認証・認可
      operationId: startSfdcAuth
      parameters:
      - type: boolean
        default: false
        name: is_sandbox
        in: query
      - type: string
        format: uri
        description: リダイレクトURI
        name: redirect_uri
        in: query
        required: true
      responses:
        '200':
          description: JSONリクエストの場合のみ、リダイレクトせずにリダイレクト先URLを返す
          schema:
            $ref: '#/definitions/redirect_url'
        '302':
          description: Found
          headers:
            Location:
              type: string
    delete:
      security:
      - accessToken: []
      tags:
      - oauth2
      summary: Unlink service
      operationId: deleteSfdcAuth
      responses:
        '200':
          description: OK
  /oauth2/callback/:
    get:
      description: 認可コールバックのエンドポイント
      tags:
      - oauth2
      summary: Salesforce認可コールバック
      operationId: callbackSfdcAuth
      parameters:
      - type: string
        name: code
        in: query
      - type: string
        name: state
        in: query
      responses:
        '201':
          description: OK
        '302':
          description: Found
          headers:
            Location:
              type: string
  /oauth2/results:
    get:
      security:
      - accessToken: []
      tags:
      - oauth2
      summary: 認証結果一覧
      operationId: listOauthResults
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/oauthResult'
  /settings:
    get:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Salesforce読み込み設定の取得
      operationId: getSyncSettingOfSfdc
      parameters:
      - type: string
        name: mmpObject
        in: query
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/sync_settings'
    post:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Playbook <-> Salesforce の対応関係設定追加
      operationId: createSyncSettingOfSfdc
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            auto_sync:
              type: boolean
            mmp_table_name:
              $ref: '#/definitions/mmp_table_name'
            sfdc_object_name:
              $ref: '#/definitions/sfdc_object_name'
            sync_field_map:
              $ref: '#/definitions/sync_field_map'
            sync_order:
              type: integer
      responses:
        '201':
          description: OK
  /settings/marketo:
    get:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Marketo認証設定の取得
      operationId: getCredentialSettingOfMarketo
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/marketo_credential_setting'
    post:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Marketo認証設定の登録
      operationId: createCredentialSettingsOfMarketo
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            clientId:
              type: string
            clientSecret:
              type: string
            consoleURL:
              type: string
            endpointURL:
              type: string
            identityURL:
              type: string
      responses:
        '201':
          description: OK
    patch:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Marketo認証設定の更新
      operationId: updateCredentialSettingsOfMarketo
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            clientId:
              type: string
            clientSecret:
              type: string
            consoleURL:
              type: string
            endpointURL:
              type: string
            identityURL:
              type: string
      responses:
        '200':
          description: OK
  /settings/{sync_setting_id}:
    patch:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Playbook <-> Salesforce の対応関係設定更新
      operationId: updateSyncFieldMapOfSfdc
      parameters:
      - name: body
        in: body
        schema:
          type: object
          properties:
            mmp_table_name:
              $ref: '#/definitions/mmp_table_name'
            sfdc_object_name:
              $ref: '#/definitions/sfdc_object_name'
            sync_field_map:
              $ref: '#/definitions/sync_field_map'
            write_sync_patterns:
              type: array
              items:
                $ref: '#/definitions/write_sync_pattern'
      responses:
        '201':
          description: OK
    parameters:
    - $ref: '#/parameters/sync_setting_id'
  /settings/{sync_setting_id}/engagement:
    post:
      security:
      - accessToken: []
      tags:
      - settings
      summary: Engagement の対応関係設定追加
      operationId: createEngagementSyncSettingOfSfdc
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            phase_sync_id_map_id:
              type: string
              format: uuid
            playbook_id:
              $ref: '#/definitions/mmp_id'
            progress:
              type: integer
      responses:
        '201':
          description: OK
    parameters:
    - $ref: '#/parameters/sync_setting_id'
  /sync/read:
    post:
      security:
      - accessToken: []
      - apiKey: []
      tags:
      - sync_sfdc
      summary: Salesforce からデータを読み込み Playbook にデータを反映する
      operationId: readSyncWithSfdc
      parameters:
      - name: body
        in: body
        schema:
          type: object
          properties:
            mode:
              type: string
            target:
              type: string
            team_id:
              type: string
      responses:
        '201':
          description: OK
  /sync/syncable:
    get:
      security:
      - accessToken: []
      - apiKey: []
      tags:
      - sync_sfdc
      summary: 同期状態
      operationId: getSyncable
      parameters:
      - type: string
        name: team_id
        in: query
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/syncable'
    put:
      security:
      - apiKey: []
      - accessToken: []
      tags:
      - sync_sfdc
      summary: 同期開始・ストップ
      operationId: toggleSyncable
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            syncable:
              type: boolean
            team_id:
              type: string
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                $ref: '#/definitions/syncable'
definitions:
  createdAt:
    description: 作成日
    type: string
    format: date-time
    example: '2017-07-21T17:32:28Z'
  engagement_sync_setting:
    type: object
    properties:
      id:
        type: string
        format: uuid
      phase_sync_id_map:
        type: object
        properties:
          id:
            type: string
            format: uuid
          mmp_id:
            type: string
            enum:
            - nurturing
            - qualification
            - closing
            - onboarding
            - adoption
            - expansion
            - recycling
            - end
          sfdc_id:
            type: string
          sync_setting:
            type: object
            properties:
              id:
                type: string
                format: uuid
              mmp_table_name:
                type: string
                enum:
                - playbook_phases
                - engagement_statuses
              sfdc_object_name:
                type: string
                enum:
                - LeadStatus
                - OpportunityStage
                - ContactStatus
      progress:
        type: number
        maximum: 100
      sync_setting:
        type: object
        properties:
          id:
            type: string
            format: uuid
          mmp_table_name:
            type: string
            enum:
            - engagements
          sfdc_object_name:
            type: string
            enum:
            - Lead
            - Opportunity
            - Contact
          sync_field_map:
            type: object
            properties:
              playbook_phase_id:
                type: string
  error:
    type: object
    required:
    - message
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string
  marketo_credential_setting:
    type: object
    required:
    - clientId
    - clientSecret
    - identityURL
    - endpointURL
    - consoleURL
    properties:
      clientId:
        type: string
      clientSecret:
        type: string
      consoleURL:
        type: string
      endpointURL:
        type: string
      identityURL:
        type: string
  mmp_id:
    type: string
    format: uuid
  mmp_table_name:
    type: string
  oauthResult:
    type: object
    properties:
      createdAt:
        $ref: '#/definitions/createdAt'
      isSandbox:
        description: Environment is sandbox or not
        type: boolean
        x-omitempty: false
      serviceType:
        description: 認証サービス
        type: string
        enum:
        - SALESFORCE
  principal:
    type: object
    properties:
      is_administrator:
        type: boolean
      team_id:
        type: string
      token:
        type: string
      user_id:
        type: string
  redirect_url:
    type: string
  salesforceUser:
    type: object
    properties:
      email:
        type: string
      first_name:
        type: string
      id:
        type: string
      last_name:
        type: string
      mmp_user_id:
        type: string
      name:
        type: string
      sync_map_id:
        type: string
  services:
    type: string
    enum:
    - SALESFORCE
  sfdc_api_name:
    type: object
    properties:
      api_name:
        type: string
      description:
        type: string
  sfdc_id:
    type: string
  sfdc_object_name:
    type: string
  sync_field_map:
    type: string
  sync_id_map:
    type: object
    properties:
      id:
        type: string
        format: uuid
      mmp_id:
        $ref: '#/definitions/mmp_id'
      sfdc_id:
        $ref: '#/definitions/sfdc_id'
      sync_setting_id:
        $ref: '#/definitions/sync_setting_id'
  sync_id_maps:
    type: array
    items:
      $ref: '#/definitions/sync_id_map'
  sync_setting:
    type: object
    properties:
      auto_sync:
        type: boolean
      id:
        type: string
        format: uuid
      mmp_table_name:
        $ref: '#/definitions/mmp_table_name'
      sfdc_object_name:
        $ref: '#/definitions/sfdc_object_name'
      sync_field_map:
        $ref: '#/definitions/sync_field_map'
      sync_order:
        type: integer
      team_id:
        type: string
        format: uuid
      write_sync_patterns:
        type: array
        items:
          $ref: '#/definitions/write_sync_pattern'
  sync_setting_id:
    type: string
    format: uuid
  sync_settings:
    type: array
    items:
      $ref: '#/definitions/sync_setting'
  syncable:
    type: object
    properties:
      syncable:
        type: boolean
        x-omitempty: false
      teamId:
        type: string
        format: uuid
  write_sync_pattern:
    type: string
    enum:
    - SIMPLE_WRITE
    - ARCHIVE
parameters:
  engagement_sync_setting_id:
    type: string
    format: uuid
    name: engagement_sync_setting_id
    in: path
    required: true
  mapping_id:
    type: string
    format: uuid
    name: mapping_id
    in: path
    required: true
  sync_setting_id:
    type: string
    format: uuid
    name: sync_setting_id
    in: path
    required: true
responses:
  bad_request:
    description: 入力が不正な場合に発生します。
    schema:
      $ref: '#/definitions/error'
  conflict:
    description: 対象がすでに存在している場合に発生します。
    schema:
      $ref: '#/definitions/error'
  default_error:
    description: error
    schema:
      $ref: '#/definitions/error'
  forbidden:
    description: 権限が不足している場合に発生します。
    schema:
      $ref: '#/definitions/error'
  not_found:
    description: 対象が存在しない場合に発生します。
    schema:
      $ref: '#/definitions/error'
  unauthorized:
    description: 認証に失敗した場合に発生します。
    schema:
      $ref: '#/definitions/error'
securityDefinitions:
  accessToken:
    type: apiKey
    name: x-access-token
    in: header
  apiKey:
    type: apiKey
    name: x-api-key
    in: header