Dojo Areas API

openapi: 3.2.0
info:
  title: EPOS Data API (REST) Areas API
  version: '1.0'
  description: 'REST contract that an external POS/EPOS system implements so Dojo products can

    fetch and update commerce entities (Orders, Tables, Areas, Parties, Reservations)

    and record payments. Use this when the EPOS exposes its own publicly reachable

    HTTP endpoints; for on-premise EPOSes that cannot accept inbound HTTP, use the

    [WebSocket variant](/epos-data-asyncapi/bundled.yaml) of the same contract.


    Core modules:

    - Tables

    - Areas

    - Orders

    - Parties

    - Reservations


    API modules can generally be

    implemented independently, with a small number of interdependent fields affected

    by other modules (for example, if Parties are implemented & the information is

    known, a `partyId` should be attached to an Order''s `dineInDetails`).


    All requests also contain special headers within the REST headers,

    containing details about the requestor that can be used for logging purposes or EPOS business logic

    (such as waiter id based access to entities).


    Before any of these endpoints will be invoked by Dojo, register the capabilities you implement with `PUT /epos/integrations/rest`. See the EPOS Data API guide for the full registration flow.'
servers:
- url: https://your-epos.example.com
  description: 'The EPOS Data REST API has no shared base URL: each EPOS provider hosts the

    endpoints on their own domain and registers them against that base via

    `PUT /epos/integrations/rest`. The placeholder `https://your-epos.example.com`

    is illustrative — replace with your own publicly reachable HTTPS URL.'
tags:
- name: Areas
paths:
  /v1/areas:
    get:
      tags:
      - Areas
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Area'
          description: Successfully returns all areas
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-list-areas
      summary: List areas
      description: 'Retrieves all areas that are being served. Capability: `ListAreas`

        '
      parameters:
      - $ref: '#/components/parameters/WaiterId'
      - $ref: '#/components/parameters/DojoRequestingProduct'
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/DeviceType'
components:
  schemas:
    EPOSError:
      title: EPOSError
      type: object
      required:
      - errorType
      properties:
        debugMessage:
          type: string
        traceId:
          type: string
        errorType:
          $ref: '#/components/schemas/EPOSErrorType'
    EPOSErrorType:
      type: string
      enum:
      - NotFound
      - UnexpectedError
      - InvalidRequest
      - Conflict
    Area:
      description: A representation of a physical area in a merchant's location.
      required:
      - id
      - name
      type: object
      properties:
        id:
          description: Unique ID of the area
          type: string
        name:
          description: User friendly name of the area
          type: string
          example: ''
        waiterIds:
          description: ''
          type: array
          items:
            type: string
      example:
        id: area_1234
        name: downstairs
  parameters:
    DeviceType:
      in: header
      name: device-type
      required: false
      schema:
        type: string
      example: Dojo Terminal
      description: The device making the request, if known
    DeviceId:
      name: device-id
      in: header
      required: false
      schema:
        type: string
      example: tm_sandbox_65c5fe8a104a1222b2d8b968
      description: The ID of the device making the request, if known
    WaiterId:
      in: header
      name: waiter-id
      required: false
      schema:
        type: string
      example: '42'
      description: The ID of the waiter making the request, if known
    DojoRequestingProduct:
      name: dojo-requesting-product
      in: header
      required: false
      schema:
        type: string
      example: Order&Pay
      description: The dojo product making the request, if known.