openapi: 3.0.3
info:
  description: This is an API to interact with the events platform of the Belgian federal government
  version: 3.0.0
  title: API for event submission and retrieval
  # put the contact info for your development or API team
 
tags:
- name: EboxEnterprise

paths:
  /enterprise/document/events:
    get:
      tags:
      - EboxEnterprise
      summary: returns events related to ebox documents
      operationId: getEboxEnterpriseDocumentEvents
      description: Returns events related to ebox documents.
      parameters:
        - $ref: '#/components/parameters/sequenceNumber'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/startTime'
      responses:
        200:
          description: search results matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EboxEnterpriseDocumentEventPage'
        204:
          $ref: '#/components/responses/NoContent'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'    
    post:
      tags:
      - EboxEnterprise
      summary: submit events related to ebox documents
      operationId: submitEboxEnterpriseDocumentEvents
      description: Submit events related to ebox documents.
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EboxEnterpriseDocumentEvent'      
      responses:
        201:
          description: events created
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    startTime:
      name: startTime
      in: query
      description: the start-time from when events should be returned
      required: false
      schema:
        type: string
        format: date-time    
    idempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: Idempotency-Key
    sequenceNumber:
      name: sequenceNumber
      in: query
      description: the event sequence number 
      required: true
      schema:
        type: integer
        format: int64
    pageSize:
      name: pageSize
      in: query
      description: the maximum number of events to return
      required: true
      schema:
        type: integer
        format: int32  
  schemas:
    EboxEnterpriseDocumentEvent:
      type: object
      properties:
        eventType:
          type: string
          enum:
            - "newDocument"
            - "newDocumentReminder"
            - "readDocument"
            - "documentExpirationAlert"
        eventCorrelationId:
          type: string
          description: the correlation identifier of the client / application for this event
        enterpriseId:
          type: string
          description: the kbo/cbe number of the enterprise
          pattern: "[0-9]{10}"
        messageId:
          type: string
        receiptDate:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time
        registeredMail:
          type: boolean
        messageTypeId:
          type: string
        senderOrganizationId:
          type: string
        senderApplicationId:
          type: string
        subject:
          $ref: '#/components/schemas/TranslatedString'
      required:
        - eventType
        - enterpriseId
        - messageId
        - receiptDate
        - expirationDate
        - registeredMail
    EboxEnterpriseDocumentEventPageItem:
      type: object
      properties:
        sequenceNumber:
          type: integer
          format: int64
        eventTime:
          type: string
          format: date-time
        providerId:
          type: string
          description: the identifier of the one that provided the event
        eventData:
          $ref: '#/components/schemas/EboxEnterpriseDocumentEvent'        
      required:
        - sequenceNumber
        - eventTime
        - providerId 
        - eventData      
    EboxEnterpriseDocumentEventPage:
      type: object
      properties:
        pageInfo:
          $ref: '#/components/schemas/EventPageInfo'
        EboxEnterpriseDocumentEvents:
          type: array
          items:
            $ref: '#/components/schemas/EboxEnterpriseDocumentEventPageItem'      
    EventPageInfo:
      type: object
      properties:
        sequenceNumber:
          type: integer
          format: int64
        hasNext:
          type: boolean
      required:
        - sequenceNumber
        - hasNext
    TranslatedString:
      type: object
      properties:
        nl:
          type: string
        fr:
          type: string
        de:
          type: string
        en:
          type: string
    Problem:
      description: A Problem Details object (RFC 7807)
      type: object
      properties:
        type:
          type: string
          format: uri
          description: An absolute URI that identifies the problem type
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML).
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 400
          maximum: 600
          exclusiveMaximum: true # "If you have an error here, you are probably using the wrong JSON Schema specification or the unstable version editor-next.swagger.io . See https://github.com/belgif/openapi-problem/issues/11"
          example: 503
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          format: uri
          description: An absolute URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          
  responses:
    BadRequest:
      description: "The input message is incorrect."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: "The consumer must pass a valid access token in the Authorization HTTP header for each request to a secure resource."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: "The consumer access token doesn’t have the required scope to invoke the operation."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: "The requested resource cannot be found."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NoContent:
      description: "The requested data not found."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalServerError:
      description: "The server has encountered a situation it doesn’t know how to handle."
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'