openapi: 3.0.0
info:
  description: API for synchronizing and mapping data from and to Timezynk. Oauth2
    authentication, require permission level manager or api-client with scope write:company.
    Info about authentication [https://developer.timezynk.com](https://developer.timezynk.com/#section/Authentication)
  title: Timezynk integration bridge API
  version: 0.1.4
servers:
- url: /
tags:
- description: Synk data from a data source to a Timezynk registry.
  name: Data source
- description: Synk data from a Timezynk registry to a data sink.
  name: Data sink
paths:
  /data-sources:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
          description: Success.
        401:
          description: Unauthorized.
        500:
          description: Unexpected error.
      summary: List registered datasources
      tags:
      - Data source
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSource'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
          description: Success.
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        409:
          description: Conflict. A data source with the provided id is already existing.
        500:
          description: Unexpected error.
      summary: Register a data source
      tags:
      - Data source
  /data-sinks:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSink'
          description: Success.
        401:
          description: Unauthorized.
        500:
          description: Unexpected error.
      summary: List registered datasources
      tags:
      - Data sink
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSink'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSink'
          description: Success.
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        409:
          description: Conflict. A data source with the provided id is already existing.
        500:
          description: Unexpected error.
      summary: Register a data source
      tags:
      - Data sink
  /data-sources/{dataSourceId}/synchronization-state:
    get:
      parameters:
      - description: Id of the data source
        explode: false
        in: path
        name: dataSourceId
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SynchronizationState'
                type: array
          description: Success.
        401:
          description: Unauthorized.
        500:
          description: Unexpected error.
      summary: Lists synchronization status for your data sources
      tags:
      - Source
  /entities:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySettings'
          description: Success.
        401:
          description: Unauthorized.
        500:
          description: Unexpected error.
      summary: List entities
      tags:
      - Entity
  /entities/{entityId}:
    put:
      parameters:
      - description: Id of the entity
        explode: false
        in: path
        name: entityId
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySettings'
          description: Success.
        401:
          description: Unauthorized.
        500:
          description: Unexpected error.
      summary: Update entity
      tags:
      - Entity
  /entities/{entityId}/changes:
    get:
      parameters:
      - description: Id of the entity
        explode: false
        in: path
        name: entityId
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
          description: Success.
          headers:
            Link:
              description: Url of the next batch of items
              explode: false
              schema:
                type: string
              style: simple
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        500:
          description: unexpected error.
      summary: Sync changes from data source
      tags:
      - Entity
    post:
      parameters:
      - description: Id of the entity
        explode: false
        in: path
        name: entityId
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/DataSource'
              type: array
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
          description: Success.
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        500:
          description: unexpected error.
      summary: Sync changes from data source
      tags:
      - Entity
  /entities/{entityId}/next-sync:
    get:
      parameters:
      - description: Id of the entity
        explode: false
        in: path
        name: entityId
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityNextSync'
          description: Success.
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        500:
          description: unexpected error.
      summary: Next sync
      tags:
      - Entity
    put:
      description: This endpoint acts as a confirmation for a successful synchronization.
        When called, it will record the current timestamp, and use to calculate when
        next synchronization should occur.
      parameters:
      - description: Id of the entity
        explode: false
        in: path
        name: entityId
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              description: Field to store relevant meta for the next synchronization.
                E.g. for a data source you might want to store a timestamp, and for
                a data sink, you might want to store the Link header returned in the
                most recent GET /entities/{entityId}/changes response.
              type: string
      responses:
        200:
          description: Success.
        400:
          description: Bad Request. Data provided in request body is invalid.
        401:
          description: Unauthorized.
        500:
          description: unexpected error.
      summary: Next sync
      tags:
      - Entity
components:
  schemas:
    DataSource:
      example:
        company-id: company-id
        entities:
        - timestamp-key: timestamp-key
          name: name
          id: id
          field-key: field-key
          fields:
          - name: name
            format: format
            id: id
            type: string
            required: true
          - name: name
            format: format
            id: id
            type: string
            required: true
        - timestamp-key: timestamp-key
          name: name
          id: id
          field-key: field-key
          fields:
          - name: name
            format: format
            id: id
            type: string
            required: true
          - name: name
            format: format
            id: id
            type: string
            required: true
        vendor: vendor
        name: name
        id: id
      properties:
        id:
          description: id of the source
          format: ObjectId
          readOnly: true
          type: string
        name:
          description: name of the source
          type: string
        vendor:
          description: id of the system to integrate with Timezynk.
          type: string
        company-id:
          description: id of the company that owns this data
          readOnly: true
          type: string
        entities:
          description: list of available entities
          items:
            $ref: '#/components/schemas/Entity'
          type: array
      required:
      - company-id
      - entities
      - id
      - name
      - vendor
    DataSink:
      allOf:
      - $ref: '#/components/schemas/DataSource'
    Entity:
      example:
        timestamp-key: timestamp-key
        name: name
        id: id
        field-key: field-key
        fields:
        - name: name
          format: format
          id: id
          type: string
          required: true
        - name: name
          format: format
          id: id
          type: string
          required: true
      properties:
        id:
          description: id of the entity,
          format: ObjectId
          readOnly: true
          type: string
        name:
          description: title of the entity
          type: string
        fields:
          description: list of available entities
          items:
            $ref: '#/components/schemas/Field'
          type: array
        field-key:
          description: Identifies a unique field which will be used as key (id) for
            the entity rows.
          type: string
        timestamp-key:
          description: Identifies a timestamp field which will be used to calculate
            the most recent updated synced entry.
          type: string
      required:
      - field-key
      - fields
      - id
      - name
      - timestamp-key
    Field:
      example:
        name: name
        format: format
        id: id
        type: string
        required: true
      properties:
        id:
          description: id representing the field name from your dataset.
          type: string
        name:
          description: title of the field
          type: string
        type:
          description: the value json data type
          enum:
          - string
          - number
          - boolean
          type: string
        format:
          description: how to value should be formatted
          type: string
        required:
          default: true
          description: indicates if this field is required
          type: boolean
      required:
      - id
      - name
      - required
      - type
    EntitySettings:
      example:
        sync-interval: 0
        company-id: company-id
        collection-id: collection-id
        id: id
        source-id: source-id
        field-mapping:
        - entity-field-id: entity-field-id
          collection-field-id: collection-field-id
        - entity-field-id: entity-field-id
          collection-field-id: collection-field-id
      properties:
        id:
          description: Id of the entity.
          format: ObjectId
          readOnly: true
          type: string
        company-id:
          description: id of the company that owns this data.
          format: ObjectId
          readOnly: true
          type: string
        source-id:
          description: Id of the source which contains the entity.
          format: ObjectId
          readOnly: true
          type: string
        collection-id:
          description: Id of the Timezynk collection to map fields. E.g. a registry
            id or invoices
          format: ObjectId
          type: string
        sync-interval:
          description: Duration of the sync interval entered in ms.
          format: int64
          type: integer
        field-mapping:
          description: list of field mapping
          items:
            $ref: '#/components/schemas/FieldSettings'
          type: array
      required:
      - collection-id
      - company-id
      - field-mapping
      - id
      - source-id
      - sync-interval
    EntityNextSync:
      example:
        meta: meta
        next-sync: 0.8008281904610115
      properties:
        meta:
          description: Field to store relevant meta for the next synchronization.
            E.g. for a data source you might want to store a timestamp, and for a
            data sink, you might want to store the Link header returned in the most
            recent GET /entities/{entityId}/changes response.
          type: string
        next-sync:
          description: Timestamp of when next synchronization should occur.
          format: timestamp
          type: number
    FieldSettings:
      example:
        entity-field-id: entity-field-id
        collection-field-id: collection-field-id
      properties:
        entity-field-id:
          description: Id of the entity field to map.
          type: string
        collection-field-id:
          description: Id of the Timezynk collection field to map.
          type: string
      required:
      - collection-field-id
      - entity-field-id
    SynchronizationState:
      example:
        sync-interval: 6
        last-sync: 0
        entity-id: entity-id
        last-update: last-update
      properties:
        entity-id:
          description: Id of the entity.
          type: string
        last-sync:
          description: Timestamp in ms of the latest sync.
          format: int64
          type: integer
        last-update:
          description: Legacy field.
          type: string
        sync-interval:
          description: Duration of the sync interval entered in ms.
          format: int64
          type: integer
      required:
      - entity-id
      - last-sync
      - last-update
      - sync-interval