# Test and edit this file at https://editor.swagger.io/

openapi: 3.0.0

info:
  version: 1.0.0
  title: TableCheck API - Sync V1
  description: |-
    The Sync API provides a mechanism for receiving notifications when objects
    are created, updated, or deleted within TableCheck's systems.
    Webhooks are also available for this API.
    In addition to this page, please read the Implementation Guide carefully.
  termsOfService: https://tablecheck.atlassian.net/wiki/spaces/API/pages/61571353/TableCheck+API+Terms+of+Service

externalDocs:
  description: Implementation Guide
  url: https://tablecheck.atlassian.net/wiki/spaces/API/pages/44631150/Sync+v1

servers:



  - url: https://api.tablecheck.com/api/sync/v1/
    description: Production (uses live data)

paths:
  /webhooks:
    get:
      summary: List all Webhooks
      description: Lists all Webhooks which are used to deliver SyncEvents.
      operationId: listWebhooks
      tags:
        - webhooks
      responses:
        '200':
          description: The list of webhooks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhooksListResponse"
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a new Webhook settings
      description: Updates the webhook settings which are used to deliver SyncEvents.
      operationId: createWebhook
      tags:
        - webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              '$ref': "#/components/schemas/Webhook"
      responses:
        '200':
          description: The Webhook which was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhooksListResponse"
        '400': &BadRequestError
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestError"
        '403': &ForbiddenError
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        '422': &UnprocessableEntityError
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/UnprocessableEntityError"
        '500': &ServerError
          description: Server Error
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/ServerError"

  /webhooks/{webhook_id}:
    get:
      summary: Show Webhook
      description: Returns a specific Webhook object.
      operationId: showWebhook
      tags:
        - webhooks
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: The ID of the Webhook to show
          schema:
            type: string
      responses:
        '200':
          description: The webhooks settings object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookShowResponse"
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/Error"
    put:
      summary: Update Webhook
      description: Updates a Webhook settings object.
      operationId: updateWebhook
      tags:
        - webhooks
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: The ID of the Webhook to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              '$ref': "#/components/schemas/Webhook"
      responses:
        '200':
          description: The Webhook which was updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookShowResponse"
        '400': *BadRequestError
        '403': *ForbiddenError
        '422': *UnprocessableEntityError
        '500': *ServerError
    delete:
      summary: Delete a specific Webhook
      operationId: deleteWebhook
      tags:
        - webhooks
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: The ID of the Webhook to delete
          schema:
            type: string
      responses:
        '200':
          description: Webhook deleted
        '400': *BadRequestError
        '403': *ForbiddenError
        '422': *UnprocessableEntityError
        '500': *ServerError

  /account:
    get:
      summary: Get Account settings
      description: Returns the Account settings.
      operationId: getAccount
      tags:
        - account
      responses:
        '200':
          description: The Account settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountResponse"
        '400': *BadRequestError
        '403': *ForbiddenError
        '422': *UnprocessableEntityError
        '500': *ServerError

    put:
      summary: Update Account settings
      description: Updates the Account settings.
      operationId: updateAccount
      tags:
        - account
      requestBody:
        content:
          application/json:
            schema:
              '$ref': "#/components/schemas/Account"
      responses:
        '200':
          description: The updated Account settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountResponse"
        '400': *BadRequestError
        '403': *ForbiddenError
        '422': *UnprocessableEntityError
        '500': *ServerError

  /sync_events:
    get:
      summary: Fetch SyncEvents (and optionally mark as "delivered")
      description: |
        Fetches SyncEvents. By default returns only undelivered SyncRequest
        (unless delivered_at_min/delivered_at_max params are specified.)
        Returns up to 1000 items per response.
      operationId: listSyncEvents
      tags:
        - sync_events
      parameters:
        - name: deliver
          in: query
          description: |
            If true, marks all queried SyncEvents as "delivered".
            Used when polling the API for new (undelivered) SyncEvents.
          schema:
            type: boolean
            default: false
        - name: syncable_types
          in: query
          description: Limits the types of the underlying objects to include in the response. Comma-separated.
          schema:
            type: string
            format: comma-separated
            example: reservation,customer
            enum: ["blockage","customer","franchise","membership","membership_program","menu_category","menu_item","reservation","reservation_flag","section","shop","table"]
        - name: shop_ids
          in: query
          description: Queries for SyncEvents for specific Shops. Comma-separated.
          schema:
            type: string
            format: comma-separated
            example: 93e2Zaed5d6ca1fd8e5355337,5ca1f35541293e2Zaed5d6d8e
        - name: created_at_min
          in: query
          description: |
            Queries historical SyncEvents by the time they were created.
          schema:
            type: string
            format: date-time
        - name: created_at_max
          in: query
          description: |
            Queries historical SyncEvents by the time they were created.
            If set, created_at_min is also required.
          schema:
            type: string
            format: date-time
        - name: delivered_at_min
          in: query
          description: |
            Queries historical SyncEvents by the time they were delivered.
            If set, only delivered SyncEvents will be included in the response.
          schema:
            type: string
            format: date-time
        - name: delivered_at_max
          in: query
          description: |
            Queries historical SyncEvents by the time they were delivered.
            If set, delivered_at_min is also required.
            If set, only delivered SyncEvents will be included in the response.
          schema:
            type: string
            format: date-time
        - name: include_delivered
          in: query
          description: |
            Indicates that delivered SyncEvents should be included in the response.
            Ignored if delivered_at_min and delivered_at_max are set.
          schema:
            type: boolean
            default: false

      responses:
        '200':
          description: SyncEvent found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncEventsListResponse"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/Error"

  /sync_events/{sync_event_id}:
    get:
      summary: Fetch a specific SyncEvent
      operationId: showSyncEvent
      tags:
        - sync_events
      parameters:
        - name: sync_event_id
          in: path
          required: true
          description: The ID of the SyncEvent to retrieve
          schema:
            type: string
      responses:
        '200':
          description: SyncEvent found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncEventShowResponse"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/Error"
    delete:
      summary: Mark a specific SyncEvent as delivered
      operationId: deleteSyncEvent
      tags:
        - sync_events
      parameters:
        - name: sync_event_id
          in: path
          required: true
          description: The ID of the SyncEvent to mark as delivered
          schema:
            type: string
      responses:
        '200':
          description: SyncEvent marked as delivered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncEventShowResponse"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                '$ref': "#/components/schemas/Error"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: AUTHORIZATION

  schemas:
    WebhooksListResponse:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/Webhook"

    WebhookShowResponse:
      type: object
      properties:
        webhook:
          $ref: "#/components/schemas/Webhook"

    Webhook:
      type: object
      required:
        - callback_url
      properties:
        callback_method:
          description: Specifies whether to deliver SyncEvent callbacks by HTTP POST or PUT.
          type: string
          default: "post"
          enum: ["post","put"]
        callback_url:
          description: |
            The callback URL which to automatically deliver SyncEvents.
            Even if not specified, it is still possible to query SyncEvents via the API.
          type: string
          format: url
        callback_auth_method:
          description: Adds optional authentication to the webhook callbacks.
          type: string
          default: "none"
          enum: ["none","basic","http","oauth2"]
        callback_oauth_url:
          description: OAuth URL endpoint for authentication, used when callback_auth_method is "oauth2".
          type: string
          format: url
        callback_username:
          description: Username used when callback_auth_method is "basic" or "oauth2" (OAuth Client ID).
          type: string
        callback_password:
          description: Username used when callback_auth_method is "basic", "http", or "oauth2" (OAuth Secret Key).
          type: string
        franchise_ids:
          description: |
            Constrains the Franchises for which the callback will be delivered.
            An empty array means "all Franchises" (no restriction).
          type: array
          default: []
          items:
            type: string
            format: bson-id
            example: 7ed5d6893ae5355ca1fd33e2
        shop_ids:
          description: |
            Constrains the Shops for which the callback will be delivered.
            An empty array means "all Shops" (no restriction).
          type: array
          default: []
          items:
            type: string
            format: bson-id
            example: ae5355ca1fd337ed5d6893e2

    AccountResponse:
      type: object
      properties:
        account:
          $ref: "#/components/schemas/Account"

    Account:
      type: object
      properties:
        locale:
          description: Sets locale for API notifications.
          type: string
          enum: ["en","ja","ko","zh-CN","zh-TW","de","es","fr","nl","it","pt","tr","ru","id","ms","tl","th","lo","km","vi","ar","he","hi"]
        notify_emails:
          description: List of emails to notify upon webhook delivery failure.
          type: array
          default: []
          items:
            type: string
            format: email
            example: notify@me.com

    SyncEventsListResponse:
      type: object
      properties:
        sync_events:
          type: array
          items:
            $ref: "#/components/schemas/SyncEvent"

    SyncEventShowResponse:
      type: object
      properties:
        sync_event:
          $ref: "#/components/schemas/SyncEvent"

    SyncEvent:
      type: object
      properties:
        id:
          description: The database ID of the SyncEvent.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        event_type:
          description: |
            The manner in which object was modified.
          type: string
          enum:
            - created
            - updated
            - deleted
        syncable_id:
          description: The database ID of the modified object.
          type: string
          format: bson-id
          example: ca1fd893e2Zae5355337ed5d6
        syncable_ref:
          description: The ID set by you (the counterparty) on the modified object, if applicable.
          type: string
        syncable_type:
          description: The object type of the modified object.
          type: string
          enum: ["blockage","customer","franchise","membership","membership_program","menu_category","menu_item","reservation","reservation_flag","section","shop","table"]
        franchise_id:
          description: The database ID of the modified object's Franchise.
          type: string
          format: bson-id
          example: 37ed5d5ca1fd3Z6893e2ae535
        shop_id:
          description: The database ID of the modified object's Shop, if applicable.
          type: string
          format: bson-id
          example: e2Z5ca1fd337edae5355d6893
        created_at:
          description: The timestamp of when the SyncEvent was generated.
          type: string
          format: date-time
        updated_at:
          description: The timestamp of when the SyncEvent was last updated. This field is not present on webhook callbacks.
          type: string
          format: date-time
        delivered_at:
          description: The timestamp at which the SyncEvent was first successfully delivered. This field is not present on webhook callbacks.
          type: string
          format: date-time
        delivery_method:
          description: The method by which the SyncEvent was first successfully delivered, either "webhook" or "api". Will be null if undelivered.
          type: string
          enum: ['webhook', 'api']
        response_code:
          description: The HTTP response code received when attempting to deliver the SyncEvent to the webhook URL. 200 means success, all others indicate failure. This field is not present on webhook callbacks.
          type: number
          format: http-status
          example: 200

    BadRequestError:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: parameter_missing
              message:
                type: string
                example: Required parameter is missing.

    ForbiddenError:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: api_key_invalid
              message:
                type: string
                example: Your API key is invalid.

    ServerError:
      description: Occurs when the server is busy or a bug exists. You should retry the same request after some time.
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: not_created
              message:
                type: string
                example: Could not create resource due to missing parameter.

    UnprocessableEntityError:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: not_created
              message:
                type: string
                example: Could not create resource due to missing parameter.

    Error:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: not_found
              message:
                type: string
                example: Item not found

security:
  - ApiKeyAuth: []
