openapi: 3.0.3
info:
  title: "DOCUMENT SERVICE API"
  description: "This RESTful API is designed to serve the Flemish Government Document Senders. It can be used to send Documents over different delivery channels (paper, email or ebox). The API adopts the Federated e-Box API. This version has operations that can be used to service both citizen and enterprises. Release date March 09 2021."
  contact:
    name: "Magda helpdesk"
    email: "helpdesk.magda@vlaanderen.be"
  license:
    name: "e-Box"
    url: "https://overheid.vlaanderen.be/magda"
  version: "1.0"
servers:
  - url: "/api/v1/messages"
tags:
  - name: "messages"
paths:
  /files/upload/EMAIL:
    post:
      tags:
        - "messages"
      summary: "Internal service. Upload a message to the printing partner, for it to be sent via email."
      operationId: "uploadMessageEMAIL"
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              properties:
                file:
                  type: string
                  description: "ZIP file containing a JSON-description of the message to Send + n PDF files."
                  format: binary
        required: true
      responses:
        201:
          $ref: '#/components/responses/Created'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /files/upload/PAPER:
    post:
      tags:
        - "messages"
      summary: "Internal service. Upload a message to the printing partner, for it to be sent via paper."
      operationId: "uploadMessagePAPER"
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              properties:
                file:
                  type: string
                  description: "ZIP file containing a JSON-description of the message to Send + n PDF files."
                  format: binary
        required: true
      responses:
        201:
          $ref: '#/components/responses/Created'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /messages:
    post:
      tags:
      - "messages"
      summary: "Send a message, using a channel (email, paper mail, ebox) and delivery method (registered or normal) of your choice."
      operationId: createMessage
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - messageToSend
              properties:
                messageToSend:
                  $ref: '#/components/schemas/MessageToSend'
                upfile1:
                  type: string
                  format: binary
                  nullable: true
                upfile2:
                  type: string
                  format: binary
                  nullable: true
                upfile3:
                  type: string
                  format: binary
                  nullable: true
                upfile4:
                  type: string
                  format: binary
                  nullable: true
                upfile5:
                  type: string
                  format: binary
                  nullable: true
                upfile6:
                  type: string
                  format: binary
                  nullable: true
        required: true
      responses:
        201:
          description: Created
          headers:
            X-Magda-Exceptions:
              description: "Only used in the context of EBOX delivery and if there was a problem with the consent of the receiver's ebox."
              schema:
                $ref: '#/components/schemas/MagdaExceptionList'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendStatusMessageList'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
    get:
      tags:
        - "messages"
      summary: "Allows to search for messages."
      operationId: findMessages
      parameters:
        - name: delivery
          in: query
          description: "Which delivery channel was used"
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DeliveryChannel'
        - name: sentAfter
          in: query
          description: "Message was sent after this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided."
          schema:
            type: string
            format: date-time
        - name: sentBefore
          in: query
          description: "Message was sent before this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided."
          schema:
            type: string
            format: date-time
        - name: subject
          in: query
          description: "What was the subject of the message. Case insensitive search. Seach for the value as a substring"
          schema:
            type: string
        - name: receiver
          in: query
          description: "Free search field that will be used to find the messages based on Receiver information: firstName, lastName, organisationName, citizenId, organisationId, emailAddress. Case insensitive search. Seach for the value as a substring"
          schema:
            type: string
        - name: firstName
          in: query
          description: "What was the first name of the message receiver. Case insensitive search. Seach for the value as a substring"
          schema:
            type: string
        - name: lastName
          in: query
          description: "What was the last name of the message receiver. Case insensitive search. Seach for the value as a substring"
          schema:
            type: string
        - name: organization
          in: query
          description: "What was the orgnization name of the message receiver. Case insensitive search. Seach for the value as a substring"
          schema:
            type: string
        - name: email
          in: query
          description: "What was the email address of the message receiver. Case insensitive search. Seach for the value as an exact string"
          schema:
            type: string
        - name: insz
          in: query
          description: "What was the INSZ number of the message receiver. Case insensitive search. Seach for the value as an exact string"
          schema:
            type: string
        - name: kbo
          in: query
          description: "What was the INSZ number of the message receiver. Case insensitive search. Seach for the value as an exact string"
          schema:
            type: string
        - name: postalCode
          in: query
          description: "What was the Postal Code of the message receiver. Case insensitive search. Seach for the value as an exact string"
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: status
          in: query
          description: "What is the actual status of the message. Case insensitive search. Seach for the value as an exact string"
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: key1
          in: query
          description: "The message must have at least one busines data element that this key. Case insensitive search. Seach for the value as an exact string"
          schema:
            type: string
        - name: value1
          in: query
          description: "Only usable in combination with key1 query parameter. The message must have at least one busines data element with key key1 query parameter that has value1 as it value. Case insensitive search. Seach for the value as an exact string"
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: key2
          in: query
          description: "The message must have at least one busines data element that this key. Case insensitive search. Seach for the value as an exact string"
          schema:
            type: string
        - name: value2
          in: query
          description: "Only usable in combination with key2 query parameter. The message must have at least one busines data element with key key2 query parameter that has value1 as it value. Case insensitive search. Seach for the value as an exact string"
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: retourReceivedAfter
          in: query
          description: "The message was returned to sender on the provided date or later. Only applicable for messages delivered by PAPER."
          schema:
            type: string
            format: date-time
        - name: eboxReadAfter
          in: query
          description: "The message was returned to sender on the provided date or later. Only applicable for messages delivered by EBOX."
          schema:
            type: string
            format: date-time
        - name: orderBy
          in: query
          description: "On which field to sort. In case DELIVERY is chosen, secondary sorting is done based on DATE_SENT - DESC."
          schema:
            type: string
            default: DATE_SENT
            enum:
            - DATE_SENT
            - DELIVERY
        - name: order
          in: query
          description: "Descending or ascending sorting"
          schema:
            type: string
            default: DESC
            enum:
            - ASC
            - DESC
        - name: take
          in: query
          description: "How many results need to be returned"
          schema:
            type: integer
        - name: skip
          in: query
          description: "How many results need to be skipped"
          schema:
            type: integer
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSearchResults'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /eboxPreferences/search:
    post:
      tags:
        - "messages"
      summary: "Consult the EboxPreferences by posting a list of eboxIds. Can be used in bulk but only for one ebox type at once."
      operationId: getEboxPreferencesByList
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        description: List of eboxIds
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EboxIdSameTypeList'
        required: false
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EboxInfoList'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        404:
          description: No mailbox found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /publishMessageBOSA:
    post:
      tags:
        - "messages"
      summary: "Internal service. Publish a new EBOX message to a citizen, using multipart request: one JSON as the message description and one or more attachments. The <originalMessageId> tag in the JSON-part indicates a reply in a bidirectional flow."
      operationId: postMessageBOSA
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - messageToPublish
              properties:
                messageToPublish:
                  type: string
                  description: "JSON-description of the message to Publish. See MessageToPublish definition."
                  example: "See MessageToPublish definition."
                upfile1:
                  type: string
                  format: binary
                upfile2:
                  type: string
                  format: binary
                upfile3:
                  type: string
                  format: binary
                upfile4:
                  type: string
                  format: binary
                upfile5:
                  type: string
                  format: binary
                upfile6:
                  type: string
                  format: binary
        required: true
      responses:
        201:
          $ref: '#/components/responses/Published'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /publishMessageCitizen:
    post:
      tags:
        - "messages"
      summary: "Internal service. Publish a new EBOX message to a citizen, using multipart request: one JSON as the message description and one or more attachments. The <originalMessageId> tag in the JSON-part indicates a reply in a bidirectional flow."
      operationId: postMessageCitizen
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - messageToPublish
              properties:
                messageToPublish:
                  type: string
                  description: "JSON-description of the message to Publish. See MessageToPublish definition."
                  example: "See MessageToPublish definition."
                upfile1:
                  type: string
                  format: binary
                upfile2:
                  type: string
                  format: binary
                upfile3:
                  type: string
                  format: binary
                upfile4:
                  type: string
                  format: binary
                upfile5:
                  type: string
                  format: binary
                upfile6:
                  type: string
                  format: binary
        required: true
      responses:
        201:
          $ref: '#/components/responses/Published'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /publishMessageSocialSecurity:
    post:
      tags:
        - "messages"
      summary: "Internal service. Publish a new EBOX message to an enterprise, using multipart request: one JSON as the message description and one or more attachments. The <originalMessageId> tag in the JSON-part indicates a reply in a bidirectional flow."
      operationId: postMessageSocialSecurity
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - messageToPublish
              properties:
                messageToPublish:
                  type: string
                  description: "JSON-description of the message to Publish. See MessageToPublish definition."
                  example: "See MessageToPublish definition."
                upfile1:
                  type: string
                  format: binary
                upfile2:
                  type: string
                  format: binary
                upfile3:
                  type: string
                  format: binary
                upfile4:
                  type: string
                  format: binary
                upfile5:
                  type: string
                  format: binary
                upfile6:
                  type: string
                  format: binary
        required: true
      responses:
        201:
          $ref: '#/components/responses/Published'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /searchMessageStatus:
    post:
      tags:
        - "messages"
      summary: "Internal service. Obtain a messageStatus for a list of eBox messages."
      operationId: getEBoxStatus
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        description: "The MessagesStatusRequest is a list of couples messageId/eboxId."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageIdEboxIdList'
        required: false
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EBoxMessagesStatusList'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        404:
          $ref: '#/components/responses/MessageNotFound'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /messages/{messageId}/attachments:
    get:
      tags:
        - "messages"
      summary: "Allows to download the attachments of a message. In case an attachment ID is provided, the service will try to provide the concerned attachment. In case no attachmentId is provided, the service will try to provide all attachments of the concerned message. In case multiple attachments are available, they        will be provided within a ZIP file."
      operationId: getMessageAttachments
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - name: attachmentFileName
          in: query
          description: "Which attachment to get: the file name including the extention"
          schema:
            type: string
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        200:
          description: OK
          headers:
            content-type:
              description: "The content type of the attachment: PDF or ZIP."
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        403:
          $ref: '#/components/responses/NoMessageAuthorization'
        404:
          description: Message or attachment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /messages/{messageId}/status:
    get:
      tags:
        - "messages"
      summary: "Allows to obtain the status of a message."
      operationId: getMessageStatus
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/EBoxMessageStatus'
                  - $ref: '#/components/schemas/PaperOrEmailMessageStatus'
                discriminator:
                  propertyName: objectType
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        403:
          $ref: '#/components/responses/NoMessageAuthorization'
        404:
          $ref: '#/components/responses/MessageNotFound'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /messages/{messageId}/metadata:
    get:
      tags:
        - "messages"
      summary: "Allows to download the meta-data of a message."
      operationId: getMessageMetadata
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageMetadata'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        403:
          $ref: '#/components/responses/NoMessageAuthorization'
        404:
          $ref: '#/components/responses/MessageNotFound'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
  /statusRequest:
    post:
      tags:
        - "messages"
      summary: "Operation to obtain the messageStatus for a list of messages that were sent via one and the same deliveryChannel."
      operationId: getMessageStatuses
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      requestBody:
        description: "The MessagesStatusRequest is a list of status requests of one and the same deliveryChannel."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageIdsOfSameChannel'
        required: false
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesStatusOfSameDeliveryChannel'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/InvalidAuthorization'
        404:
          $ref: '#/components/responses/MessageNotFound'
        500:
          $ref: '#/components/responses/UnexpectedServerError'
        502:
          $ref: '#/components/responses/BadGateway'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        504:
          $ref: '#/components/responses/GatewayTimeout'
components:
  parameters:
    CorrelationId:
      name: x-correlation-id
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/Correlation-Id'
    Idempotency-Key:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
    MessageId:
      name: messageId
      in: path
      description: "Globally unique identifier (GUID) for the message"
      required: true
      schema:
        type: string
  responses:
    Created:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadStatusMessage'
    Published:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicationStatusMessage'
    BadRequest:
      description: Invalid data supplied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    InvalidAuthorization:
      description: Invalid authorization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    NoMessageAuthorization:
      description: Not authorized to obtain this message
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    MessageNotFound:
      description: Message not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    UnexpectedServerError:
      description: Unexpected Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    BadGateway:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    GatewayTimeout:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  schemas:
    AttachmentToPublish:
      required:
        - httpPartName
        - mainContent
      type: object
      properties:
        attachmentTitle:
          $ref: '#/components/schemas/TranslatedString'
        httpPartName:
          type: string
          description: the name of the http part that contain the bytes, filename
            and mime type of the document.
        mainContent:
          type: boolean
          description: "Indicates the priority of this attachment: ''true'' means that this attachment is considered as main content of the message, ''false'' means this attachment is considered as an annex. Attention, the readStatus of a message will be true as soon as a ''mainContent'' is consulted."
        digest:
          $ref: '#/components/schemas/Digest'
        attachmentSigned:
          type: boolean
          description: "Boolean used to indicate if the attachment is signed or not."
          default: false
      description: "An attachment item contains the meta data of the attachment."
    BusinessDataToPublish:
      required:
        - key
        - values
      type: object
      properties:
        key:
          type: string
          description: "Significative key of the businessData element."
        name:
          $ref: '#/components/schemas/TranslatedString'
        description:
          $ref: '#/components/schemas/TranslatedString'
        values:
          type: array
          description: "Values represented by the businessData."
          items:
            $ref: '#/components/schemas/TranslatedString'
      description: "A businessData element contains businessData concerning the message linked to it, in the form of a name and an array of values. To publish a BusinessData element, at least a key and an array of values is needed."
    Digest:
      required:
        - digestMethod
        - digestValue
      type: object
      properties:
        digestValue:
          type: string
          description: "Digest value returned by the cryptographic hash function encoded in base64url as defined in RFC 4648  nr5 (https://tools.ietf.org/html/rfc4648#section-5)."
        digestMethod:
          type: string
          description: "Cryptographic hash function used to obtain the digest."
          enum:
            - sha_256
      description: "Object containing the digestValue and digestMethod describing the cryptographic hash function of an item."
    EboxId:
      required:
        - eboxIdValue
        - eboxType
      type: object
      properties:
        eboxType:
          type: string
          enum:
            - ENTERPRISE
            - CITIZEN
        eboxIdValue:
          type: string
          example: "0406798006"
    EboxIdSameTypeList:
      required:
        - eboxIdType
        - eboxIdValueList
        - eboxType
      type: object
      properties:
        eboxType:
          type: string
          example: ENTERPRISE
        eboxIdType:
          type: string
          example: EnterpriseNumber
        eboxIdValueList:
          type: array
          items:
            $ref: '#/components/schemas/PersonOrEnterpriseIdentifier'
    EboxInfo:
      required:
        - eboxId
        - exclusivelyEbox
      type: object
      properties:
        eboxId:
          $ref: '#/components/schemas/EboxId'
        exclusivelyEbox:
          type: boolean
          description: "Indication if the enterprise/citizen has chosen to use the ebox as the exclusive channel (Do not send a paper copy anymore)."
          example: true
        lastConnectionDate:
          type: string
          description: "Most recently date-time when a user has been connected to its ebox using official GUI. Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the ebox was last consulted."
          format: date-time
          example: 2019-04-19T20:00:00Z
        totalNumberOfMessages:
          type: integer
          description: "Sum of all messages for every document provider."
          example: 999
        totalNumberOfUnreadMessages:
          type: integer
          description: "Sum of all unread messages for every document provider."
          example: 3
    EboxInfoList:
      type: array
      items:
        $ref: '#/components/schemas/EboxInfo'
    MessageIdEboxId:
      type: object
      properties:
        messageId:
          type: string
          description: Identifier of a message
        eboxId:
          $ref: '#/components/schemas/EboxId'
    MessageToSend:
      required:
        - delivery
      type: object
      properties:
        delivery:
          $ref: '#/components/schemas/DeliveryChannel'
        eboxDeliveryData:
          $ref: '#/components/schemas/MessageToPublish'
        paperDeliveryData:
          $ref: '#/components/schemas/PaperDeliveryData'
        emailDeliveryData:
          $ref: '#/components/schemas/EmailDeliveryData'
        businessData:
          type: array
          description: "List of business data"
          items:
            $ref: '#/components/schemas/BusinessDataToPublish'
      description: "A messageToSend is composed of a delivery channel and optionally a messageToPublish (via ebox), an email data block and a physical address data block."
    MessageMetadata:
      type: object
      properties:
        messageSent:
          $ref: '#/components/schemas/MessageToSend'
        dateSent:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent. Zero offset format."
          format: date-time
        consent:
          type: boolean
          description: "The consent status at the time the message was sent. In case we did not obtain consent info at the time of sending, this property will not be included in the response."
        statusInfo:
          $ref: '#/components/schemas/DeliveryInformation'
        attachmentsMetaData:
          type: array
          description: "The URLs on which the attachments of this message can be downloaded."
          items:
            $ref: '#/components/schemas/AttachmentMetaData'
      description: "The meta-data of the message. Can be used to obtain some of the pramaters on how the message was delivered."
    MessageReceiver:
      type: "object"
      description: "The data of the message receiver."
      properties:
        firstName:
          type: "string"
          description: "Only applicable for EBOX, PAPER or AUTOMATIC delivery. In case of EBOX delivery, it is populated with the first name of the forTheAttentionOf block."
        lastName:
         type: "string"
         description: "In case of EBOX delivery, it is populated with the first name of the forTheAttentionOf block. In case of EMAIL delivery, it is populated with the value of the name fiels of the receiver block."
        organisationName:
          type: "string"
          description: "Only applicable for PAPER or AUTOMATIC delivery."
        citizenId:
          type: "string"
          description: "The national number of the receiver. Only applicable for EBOX or AUTOMATIC delivery."
        organisationId:
          type: "string"
          description: "The company number of the receiver. Only applicable for EBOX or AUTOMATIC delivery."
        emailAddress:
          type: "string"
          description: "Only applicable for EMAIL delivery."
    MessageSearchResults:
      required:
        - totalAmount
      type: object
      properties:
        totalAmount:
          type: integer
          description: "The total amount of messages in this collection"
        messages:
          type: array
          description: "The collection of the overview data of each message."
          items:
            $ref: '#/components/schemas/MessageOverview'
      description: "The consise information about a collection of messages."
    DeliveryChannel:
      type: string
      description: "The delivery method used to deliver the message"
      enum:
        - EBOX
        - PAPER
        - EMAIL
        - AUTOMATIC
        - PAPER_AND_EBOX
    MessageIdList:
      description: "When instantiated, makes sure to use the value 'MessageIdList' for the property objectType."
      type: object
      required:
        - content
      properties:
        objectType:
          type: string
        content:
          type: array
          items:
            type: string
    MessageOverview:
      required:
        - dateSent
        - delivery
        - messageMetadataURI
      type: object
      properties:
        delivery:
          $ref: '#/components/schemas/DeliveryChannel'
        dateSent:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent. Zero offset format."
          format: date-time
        subject:
          type: string
          description: "The subject of the message"
        receiver:
          $ref: '#/components/schemas/MessageReceiver'
        messageMetadataURIs:
          $ref: '#/components/schemas/DeliveryInformation'
      description: "The consise information about a message."
    AttachmentMetaData:
      required:
        - fileName
      type: object
      properties:
        fileName:
          type: string
        url:
          type: string
          description: "The URL where the attachment can be downloaded."
      description: "The metaData of the attachment."
    MessageToPublish:
      required:
        - bodyMainContent
        - recipient
        - replyAuthorized
        - subject
      type: object
      properties:
        recipient:
          $ref: '#/components/schemas/EboxId'
        forTheAttentionOf:
          $ref: '#/components/schemas/ForTheAttentionOf'
        originalMessageId:
          type: string
          description: "Id of the original message (bidirectional use case)."
        subject:
          $ref: '#/components/schemas/TranslatedString'
        messageTypeId:
          type: string
          description: "Identifier of a messageType."
        expirationDate:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
          format: date-time
        senderOrganizationId:
          pattern: '[0-1][0-9]{9}'
          type: string
          description: "Enterprise number (BCE - KBO number) of the sender organization."
          example: "0406798006"
        senderApplicationId:
          type: string
          description: "Identifier of the senderApplication."
        registeredMail:
          type: boolean
          description: "Indicates whether or not the message was published as a registered mail in the ebox."
          default: false
        attachments:
          type: array
          description: "A list of attachments."
          items:
            $ref: '#/components/schemas/AttachmentToPublish'
        bodyMainContent:
          type: boolean
          description: "This property must be present only if there is a body. Indicates the priority of the bodyContent: true means that the body is considered as main content of the message, false means it is considered as an annex. Attention, the readStatus of a message will be true as soon as  a mainContent is consulted."
          default: false
        bodyContent:
          $ref: '#/components/schemas/TranslatedString'
        businessDataList:
          type: array
          description: "List of business data"
          items:
            $ref: '#/components/schemas/BusinessDataToPublish'
        paymentData:
          $ref: '#/components/schemas/PaymentData'
        replyAuthorized:
          type: boolean
          description: "Indicate if the message allows replies."
          default: false
      description: "A messageToPublish is basically composed of a mandatory set of metadata (e.g. recipient, subject, messageTypeId, etc.); optional attachment(s) and/or body, with at least one main content."
    TypedMessageIdEboxIdList:
      description: "A typed version of the MessageIdEboxIdList. When instantiated, makes sure to use the value 'TypedMessageIdEboxIdList' for the property objectType."
      required:
        - content
      type: object
      properties:
        objectType:
          type: string
        content:
          $ref: '#/components/schemas/MessageIdEboxIdList'
    MessageIdEboxIdList:
      type: array
      items:
        $ref: '#/components/schemas/MessageIdEboxId'
    MessageIdsOfSameChannel:
      description: "When instantiated, makes sure to use the value 'MessageIdsOfSameChannel' for the property objectType."
      required:
        - deliveryChannel
      type: object
      properties:
        deliveryChannel:
          $ref: '#/components/schemas/DeliveryChannel'
        messages:
          type: object
          oneOf:
            - $ref: '#/components/schemas/MessageIdList'
            - $ref: '#/components/schemas/TypedMessageIdEboxIdList'
          discriminator:
            propertyName: objectType
    EBoxMessageStatus:
      description: "When instantiated, makes sure to use the value 'EBoxMessageStatus' for the property objectType."
      required:
        - eboxId
        - messageId
        - readStatus
      type: object
      properties:
        objectType:
          type: string
        messageId:
          type: string
          description: "Identifier of a message."
        eboxId:
          $ref: '#/components/schemas/EboxId'
        expirationDate:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox, including an offset)"
          format: date-time
        readStatus:
          type: boolean
          description: "Indicates whether or not the main content of the message has already been opened."
          default: false
        visible:
          type: boolean
          description: "Indication whether or not the message is visible or not."
          default: true
    PaperOrEmailMessageStatus:
      description: "When instantiated, makes sure to use the value 'PaperOrEmailMessageStatus' for the property objectType."
      required:
        - messageId
      type: object
      properties:
        objectType:
          type: string
        messageId:
          type: string
        shippingDate:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was injected in the bpost framework."
          format: date-time
        mailId:
          type: string
        trackAndTraceUri:
          type: string
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/MessageStatusEvent'
    MessageStatusEvent:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        updated:
          type: string
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when this status was updated.
          format: date-time
        comment:
          type: string
    EBoxMessagesStatusList:
      type: array
      items:
        $ref: '#/components/schemas/EBoxMessageStatus'
    MessagesStatusOfSameDeliveryChannel:
      required:
        - deliveryChannel
        - messageStatuses
      type: object
      properties:
        deliveryChannel:
          $ref: '#/components/schemas/DeliveryChannel'
        messageStatuses:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EBoxMessageStatus'
              - $ref: '#/components/schemas/PaperOrEmailMessageStatus'
            discriminator:
              propertyName: objectType
    PaymentData:
      required:
        - amount
        - currency
        - dueDate
        - iban
        - paymentDataId
        - vatAmount
      type: object
      properties:
        paymentDataId:
          type: string
          description: Identifier of the paymentData.
        amount:
          type: number
          description: Amount that needs to be paid, vat not included.
          format: double
        vatAmount:
          type: number
          description: Amount of the vat, to be added to the base amount when applicable.
          format: double
        currency:
          type: string
          description: Currency in which the amount must be paid, following ISO 4217.
        dueDate:
          type: string
          description: Date on which the payment needs to be fulfilled.
          format: date-time
        iban:
          type: string
          description: Bank account on which the amount must be paid, following ISO
            13616:2007.
        bic:
          type: string
          description: Bank Identifier Code.
        reference:
          type: string
          description: Reference added to the payment.
      description: Data concerning payments.
    SendStatusMessageList:
      type: array
      items:
        $ref: '#/components/schemas/SendStatusMessage'
    SendStatusMessage:
      required:
        - messageId
      type: object
      properties:
        messageId:
          type: string
          description: Identifier of a message
        expirationDate:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
          format: date-time
        deliveryChannel:
          $ref: '#/components/schemas/DeliveryChannel'
        code:
          type: string
          description: Business Code
        message:
          type: string
          description: Business Code Description
    PublicationStatusMessage:
      required:
        - expirationDate
        - messageId
      type: object
      properties:
        messageId:
          type: string
          description: Identifier of a message.
        expirationDate:
          type: string
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will
            expire in the ebox.
          format: date-time
        code:
          type: string
          description: Business Code.
        message:
          type: string
          description: Business Code Description.
    UploadStatusMessage:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of a message.
        host:
          type: string
        filename:
          type: string
    MagdaException:
      required:
        - code
        - date
        - diagnosis
        - origin
        - type
      type: object
      properties:
        code:
          type: integer
          description: "HTTP status code of the request from which this exception stemmed."
        origin:
          maxLength: 5
          type: string
          description: "Who originated this exception."
        type:
          type: string
          description: "Specifies the kind of Exception that occurred. ERROR: The main flow could not be executed successfully. WARNING: The main flow was executed successfully, but there was a non-blocking problem. INFO: The main flow was executed without any problem, but there is addition information that can be communicated."
          enum:
            - ERROR
            - WARNING
            - INFO
        date:
          type: string
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the error was found."
          format: date-time
        diagnosis:
          type: string
          description: "Short explation of the exception. The possible values are explained in the user guide."
        circumstance:
          type: string
          description: "More details of the cause of the exception."
        annotations:
          type: string
          description: "Not yet in use. To be worked out later."
        elementReferences:
          type: string
          description: "Contains a reference to the payload element on which this exception is applicable."
      description: "A representation of a MAGDA exception."
    MagdaExceptionList:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/MagdaException'
    ErrorMessage:
      required:
        - detail
        - title
      type: object
      properties:
        type:
          type: string
          description: "A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be about:blank."
        title:
          type: string
          description: "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation."
        status:
          type: string
          description: "The HTTP status code generated by the origin server for this occurrence of the problem."
        detail:
          type: string
          description: "A human-readable explanation specific to this occurrence of the problem."
        instance:
          type: string
          description: "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
      description: "A representation of a generic error message."
    TranslatedString:
      type: object
      properties:
        nl:
          type: string
        fr:
          type: string
        de:
          type: string
      description: Common type defined to provide a string value for each supported
        language among nl, fr, de.
    Address:
      type: object
      required:
        - country
        - line1
      properties:
        title:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        organisation:
          type: string
        line1:
          type: string
        line2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
          description: ISO2 country code
    PaperDeliveryData:
      type: object
      properties:
        registeredMail:
          type: boolean
          description: Indicates if the mail should be sent as a registered mail or
            not.
          default: false
        acknowledgmentOfReceipt:
          type: boolean
          description: Indicates if the receiever needs to sign a document in which
            the reception of the mail is conformed. Thei document is mailed back to
            the reourAddress. In case this is true, retourAddress is mandatory.
          default: false
        side:
          type: string
          enum:
            - RV
            - RS
        documentType:
          type: string
          description: Indicates the kind of document (F.i. 'invoice', 'Informative
            Letter'). Will be used by the printing partner for reporting purposes.
        priority:
          type: string
          description: 'Indicates how many days bpost has to deliver the paper mail: dlp1/dlp3/dlp4.'
        documentAvailableUntilDate:
          type: string
          description: Date (yyyy-MM-dd) until when the document should be available
            for download.
          format: date
        keyCommunicatedViaChannel:
          type: string
          description: Indicates if the key that is required to download a digital
            copy of the document must be sent separately from the original document.
          default: SEPARATE_PAGE
          enum:
            - SAME_PAGE
            - SEPARATE_PAGE
            - SEPARATE_LETTER
            - NO_DOWNLOAD_KEY
        address:
          $ref: '#/components/schemas/Address'
        retourAddress:
          $ref: '#/components/schemas/Address'
    EmailDeliveryData:
      type: object
      properties:
        registeredMail:
          type: boolean
          description: Indicates if the email should be sent as a registered email
            or not.
          default: false
        receiver:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        sender:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        subject:
          type: string
        body:
          type: object
          properties:
            file:
              type: string
            content:
              type: string
    ForTheAttentionOf:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
    DeliveryInformation:
      type: array
      description: "The URLs on which information can be retrieved for a message. Can be a collection in case multiple deliveries were done for this messages."
      items:
        type: object
        properties:
          delivery:
            $ref: '#/components/schemas/DeliveryChannel'
          messageId:
            type: string
          uri:
            type: string
    Correlation-Id:
      description: "ID of the transaction. Use this ID for log tracing and incident handling."
      type: string
      maxLength: 36
      minLength: 10
    IdempotencyKey:
      description: "When retrying a failed call, the retry call should have the same Idempotency Key."
      type: string
      maxLength: 36
      minLength: 10
    PersonOrEnterpriseIdentifier:
      type: string
      pattern: "[0-9]{10,11}"
      description: the unique identifier of a citizen
      example: "0406798006"