swagger: "2.0"
info:
  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 June 8th 2020."
  version: "1.0"
  title: "DOCUMENT SERVICE API"
  contact:
    name: "Magda helpdesk"
    email: "helpdesk.magda@vlaanderen.be"
  license:
    name: "e-Box"
    url: "https://overheid.vlaanderen.be/magda"
basePath: "/api/v1/messages"
tags:
- name: "messages"
schemes:
- "https"
paths:
  /files/upload:
    post:
      tags:
      - "messages"
      summary: "Upload a message to the printing partner, for it to be sent via email or paper."
      operationId: "uploadMessage"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
      - in: "formData"
        name: "file"
        type: "file"
        required: true
        description: "ZIP file containing a JSON-description of the message to Send + n PDF files."
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/UploadStatusMessage"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /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: "messages"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
        x-example: "b89519e6-aecd-4a5c-9665-a2d48615a268"
      - in: "formData"
        name: "messageToSend"
        type: "string"
        required: true
        description: "JSON-description of the message to Send. See MessageToSend definition."
        x-example: "See MessageToSend definition."
      - in: "formData"
        name: "upfile1"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile2"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile3"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile4"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile5"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile6"
        type: "file"
        required: false
      responses:
        201:
          description: "Created"
          headers:
            X-Magda-Exceptions:
              type: "string"
              description: "Only used in the context of EBOX delivery and if there was a problem with the consent of the receiver's ebox."
              x-example: "See Exception definition"
          schema:
            $ref: "#/definitions/SendStatusMessageList"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /eboxPreferences/search:
    post:
      tags:
      - "messages"
      summary: "Consult the EboxPreferences by posting a list of eboxIds."
      operationId: "getEboxPreferencesByList"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
      - in: "body"
        name: "eboxIdSameTypeList"
        description: "List of eboxIds"
        schema:
          $ref: "#/definitions/EboxIdSameTypeList"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/EboxInfoList"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "No mailbox found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /publishMessage:
    post:
      tags:
      - "messages"
      summary: "Publish a new message, 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."
      description: ""
      operationId: "postMessage"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
      - in: "formData"
        name: "messageToPublish"
        type: "string"
        required: true
        description: "JSON-description of the message to Publish. See MessageToPublish definition."
        x-example: "See MessageToPublish definition."
      - in: "formData"
        name: "upfile1"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile2"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile3"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile4"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile5"
        type: "file"
        required: false
      - in: "formData"
        name: "upfile6"
        type: "file"
        required: false
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/PublicationStatusMessage"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /searchMessageStatus:
    post:
      tags:
      - "messages"
      summary: "Get a messageStatus for a list of eBox messages."
      operationId: "getStatus"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
      - in: "body"
        name: "messagesStatusRequest"
        description: "The MessagesStatusRequest is a list of couples 'messageId/eboxId'."
        schema:
          $ref: "#/definitions/MessageIdEboxIdList"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/EBoxMessagesStatusList"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "Messages not found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /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"
      produces:
      - "application/octet-stream"
      - "application/json"
      parameters:
        - name: "messageId"
          in: "path"
          description: "Globally unique identifier (GUID) for the message"
          type: "string"
          required: true
        - name: "attachmentFileName"
          in: "query"
          description: "Which attachment to get: the file name including the extention"
          type: "string"
          required: false
        - name: "x-correlation-id"
          in: "header"
          description: "ID of the transaction. Use this ID for log tracing and incident handling."
          type: "string"
          minLength: 3
          maxLength: 20
          required: true
      responses:
        200:
          description: "OK"
          schema:
            type: file
            format: binary
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        403:
          description: "Not authorized to obtain this message"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "Message or attachment not found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /messages/{messageId}/metadata:
    get:
      tags:
      - "messages"
      summary: "Allows to download the meta-data of a message."
      operationId: "getMessageMetadata"
      produces:
      - "application/json"
      parameters:
        - name: "messageId"
          in: "path"
          description: "Globally unique identifier (GUID) for the message"
          type: "string"
          required: true
        - name: "x-correlation-id"
          in: "header"
          description: "ID of the transaction. Use this ID for log tracing and incident handling."
          type: "string"
          minLength: 3
          maxLength: 20
          required: true
      responses:
        200:
          description: "OK"
          schema:
            $ref: "#/definitions/MessageMetadata"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        403:
          description: "Not authorized to obtain this message"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "Messages not found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /messages/:
    get:
      tags:
      - "messages"
      summary: "Allows to search for messages."
      operationId: "findMessages"
      produces:
      - "application/json"
      parameters:
        - name: "delivery"
          in: "query"
          description: "Which delivery channel was used"
          type: "string"
          enum:
          - "EBOX"
          - "PAPER"
          - "EMAIL"
          - "AUTOMATIC"
        - name: "dateFrom"
          in: "query"
          description: "Message was sent after this date-time (yyyy-MM-dd'T'HH:mm:ssXXX)."
          type: "string"
          format: "date-time"
        - name: "dateUntil"
          in: "query"
          description: "Message was sent before this date-time (yyyy-MM-dd'T'HH:mm:ssXXX)."
          type: "string"
          format: "date-time"
        - name: "subject"
          in: "query"
          description: "What was the subject of the mesage"
          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."
          type: "string"
        - name: "orderBy"
          in: "query"
          description: "On which field to sort"
          type: "string"
          enum:
          - "DATE_SENT"
          - "DELIVERY"
          default: "DATE_SENT"
        - name: "order"
          in: "query"
          description: "Descending or ascending sorting"
          type: "string"
          enum:
          - "ASC"
          - "DESC"
          default: "DESC"
        - name: "take"
          in: "query"
          description: "How many results need to be returned"
          type: "string"
        - name: "skip"
          in: "query"
          description: "How many results need to be skipped"
          type: "string"
        - name: "x-correlation-id"
          in: "header"
          description: "ID of the transaction. Use this ID for log tracing and incident handling."
          type: "string"
          minLength: 3
          maxLength: 20
          required: true
      responses:
        200:
          description: "OK"
          schema:
            $ref: "#/definitions/MessageSearchResults"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        403:
          description: "Not authorized to obtain this message"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "Messages not found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
  /statuses:
    get:
      tags:
      - "messages"
      summary: "Operation to obtain the messageStatus for a list of messages that were sent via one and the same deliveryChannel."
      operationId: "getMessageStatus"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "x-correlation-id"
        type: "string"
        minLength: 3
        maxLength: 20
        required: true
        description: "ID of the transaction. Use this ID for log tracing and incident handling."
      - in: "body"
        name: "messagesStatusRequest"
        description: "The MessagesStatusRequest is a list of status requests of one and the same deliveryChannel."
        schema:
          $ref: "#/definitions/MessageIdsOfSameChannel"
      responses:
        200:
          description: "OK"
          schema:
            $ref: "#/definitions/MessagesStatusOfSameDeliveryChannel"
        400:
          description: "Invalid data supplied"
          schema:
            $ref: "#/definitions/ErrorMessage"
        401:
          description: "Invalid authorization"
          schema:
            $ref: "#/definitions/ErrorMessage"
        404:
          description: "Messages not found"
          schema:
            $ref: "#/definitions/ErrorMessage"
        500:
          description: "Unexpected Server Error"
          schema:
            $ref: "#/definitions/ErrorMessage"
        502:
          description: "Bad Gateway"
          schema:
            $ref: "#/definitions/ErrorMessage"
        503:
          description: "Service unavailable"
          schema:
            $ref: "#/definitions/ErrorMessage"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorMessage"
definitions:
  AttachmentToPublish:
    type: "object"
    required:
      - "mainContent"
      - "httpPartName"
    properties:
      attachmentTitle:
        description: "Common type defined to provide a string value for each supported language among nl, fr, de, en."
        $ref: "#/definitions/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:
        description: "Object containing the digestValue and digestMethod describing the cryptographic hash function of an item."
        $ref: "#/definitions/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:
    type: "object"
    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."
    properties:
      key:
        type: "string"
        description: "Significative key of the businessData element."
      name:
        $ref: "#/definitions/TranslatedString"
      description:
        $ref: "#/definitions/TranslatedString"
      values:
        description: "Values represented by the businessData."
        type: "array"
        items:
          $ref: "#/definitions/TranslatedString"
    required:
      - "key"
      - "values"
  Digest:
    type: "object"
    required:
    - "digestMethod"
    - "digestValue"
    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:
    type: "object"
    required:
    - "eboxType"
    - "eboxIdValue"
    properties:
      eboxType:
        type: "string"
        enum:
        - "ENTERPRISE"
        - "CITIZEN"
      eboxIdValue:
        type: "string"
        example: "0406798006"
  EboxIdList:
      type: "array"
      items:
        $ref: "#/definitions/EboxId"
  EboxIdSameTypeList:
    type: "object"
    required:
    - "eboxType"
    - "eboxIdType"
    - "eboxIdValueList"
    properties:
      eboxType:
        type: "string"
        example: "ENTERPRISE"
      eboxIdType:
        type: "string"
        example: "EnterpriseNumber"
      eboxIdValueList:
        type: "array"
        items:
          type: "string"
          example: "0406798006"
  EboxInfo:
     type: "object"
     required:
     - "eboxId"
     - "exclusivelyEbox"
     properties:
      eboxId:
        $ref: "#/definitions/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:
        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."
        type: "string"
        format: "date-time"
        example: "2019-04-19T20:00:00Z"
      totalNumberOfMessages:
        description: "Sum of all messages for every document provider."
        type: "integer"
        example: "999"
      totalNumberOfUnreadMessages:
        description: "Sum of all unread messages for every document provider."
        type: "integer"
        example: "3"
  EboxInfoList:
     type: "array"
     items:
      $ref: "#/definitions/EboxInfo" 
  MessageIdEboxId:
    type: "object"
    properties:
      messageId:
        type: "string"
        description: "Identifier of a message"
      eboxId:
        $ref: "#/definitions/EboxId"
  MessageToSend:
    type: "object"
    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."
    properties:
      delivery:
        description: "Should the message be delivered on paper mail, registered mail, via ebox, via email, or automatic (always ebox, in case no ebox consent was given by the receiver, also send paper mail)."
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
        - "AUTOMATIC"
        default: "AUTOMATIC"
      eboxDeliveryData:
        $ref: "#/definitions/MessageToPublish" 
      paperDeliveryData:
        $ref: "#/definitions/PaperDeliveryData"
      emailDeliveryData: 
        $ref: "#/definitions/EmailDeliveryData"
  MessageMetadata:
    type: "object"
    description: "The meta-data of the message. Can be used to obtain some of the pramaters on how the message was delivered."
    required:
     - "delivery"
     - "dateSent"
     - "expirationDate"
     - "registeredMail"
     - "sender"
     - "receiver"
     - "statusInfoURLs"
    properties:
      delivery:
        description: "The delivery method used to deliver the message"
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
        - "AUTOMATIC"
      dateSent:
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent."
        type: "string"
        format: "date-time"
      expirationDate:
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) until when the message is available for the receiver."
        type: "string"
        format: "date-time"
      registeredMail:   
        type: "boolean"
        description: "Indicates if the mail was sent as a registered mail or not."
      acknowledgmentOfReceipt:         
        type: "boolean"
        description: "Indicates if an acknowledge receipt was requested. Only applicable for PAPER or AUTOMATIC delivery."
      side:
        type: "string"
        enum:
          - "RV"
          - "RS"
        description: "Indicates if the document had to be printed Recto verso (RV) or single page (SV). Only applicable for PAPER or AUTOMATIC delivery."
      documentType:
        type: "string"
        description: "Indicates the kind of document (F.i. 'invoice', 'Informative Letter'). Only applicable for PAPER or AUTOMATIC delivery."
      priority:
        type: "string"
        description: "Indicates the priority that was used pl1/dlp3/dlp4. Only applicable for PAPER or AUTOMATIC delivery."
      keyCommunicatedViaChannel:
        type: "string"
        description: "Indicates if the key that is required to download a digital copy of the document was sent separately from the original document. Only applicable for PAPER or AUTOMATIC delivery."
        enum:
         - "SAME_PAGE"
         - "SEPARATE_PAGE"
         - "SEPARATE_LETTER"
      subject:
        type: "string"
        description: "The subject of the message. Only applicable for EMAIL, EBOX or AUTOMATIC delivery."
      sender:
        $ref: "#/definitions/MessageSender"
      receiver:
        $ref: "#/definitions/MessageReceiver"
      statusInfoURLs:
        type: "array"
        description: "The URLs on which status information can be retrieved for this message. Can be a collection in case of an AUTOMATIC delivery for which the receiver did not grant an ebox consent."
        items:
          type: "string"
      attachmentsMetaData:
        type: "array"
        description: "The URLs on which the attachments of this message can be downloaded."
        items:
          $ref: "#/definitions/AttachmentMetaData"
  MessageSearchResults:
    type: "object"
    description: "The consise information about a collection of messages."
    required:
     - "totalAmount"
    properties:
      totalAmount:
        description: "The total amount of messages in this collection"
        type: "integer"
      messages:
        description: "The collection of the overview data of each message."
        type: "array"
        items:
          $ref: "#/definitions/MessageOverview"
  MessageOverview:
    type: "object"
    description: "The consise information about a message."
    required:
     - "delivery"
     - "dateSent"
     - "receiverInfo"
     - "messageMetadataURI"
    properties:
      delivery:
        description: "The delivery method used to deliver the message"
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
        - "AUTOMATIC"
      dateSent:
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent."
        type: "string"
        format: "date-time"
      receiverInfo:
        description: "A concise string that identifies the key properties of the receiver."
        type: "string"
      messageMetadataURI:
        description: "The URI on which the message metadata can be found."
        type: "string"
  AttachmentMetaData:
    type: "object"
    description: "The metaData of the attachment."
    required:
     - "fileName"
    properties:
      fileName:
        type: "string"
      url:
        type: "string"
        description: "The URL where the attachment can be downloaded."
  MessageSender:
    type: "object"
    description: "The data of the message sender."
    properties:
      id:
        type: "string"
        description: "The URI of the MAGDA sender."
      qualityCode:
        type: "string"
        description: "The quality code of the MAGDA sender ."
      ornagisationalUnit:
        type: "string"
        description: "The Organisational Unit Cod eof the MAGDA sender. Can for instance contain OVO key."
      emailAddress:
        type: "string"
        description: "Only applicable for EMAIL delivery."
  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."
  MessageToPublish:
    type: "object"
    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."
    required:
    - "recipient"
    - "subject"
    - "bodyMainContent"
    - "replyAuthorized"
    properties:
      recipient:
        $ref: "#/definitions/EboxId"
      forTheAttentionOf:
        description: "Indication when the message is for the attention of a specific person, identified by the National registry number of this person."
        $ref: "#/definitions/ForTheAttentionOf"
      originalMessageId:
        type: "string"
        description: "Id of the original message (bidirectional use case)."
      subject:
        description: "Subject is the title of the message in each language."
        $ref: "#/definitions/TranslatedString"
      messageTypeId:
        type: "string"
        description: "Identifier of a messageType."
      expirationDate:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
      senderOrganizationId:
        type: "string"
        example: "0406798006"
        description: "Enterprise number (BCE - KBO number) of the sender organization."
        pattern: "[0-1][0-9]{9}"
      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: "#/definitions/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: "#/definitions/TranslatedString"
      businessDataList:
        type: "array"
        description: "List of business data"
        items:
          $ref: "#/definitions/BusinessDataToPublish"
      paymentData:
        type: "object"
        description: "The paymentData linked to the message being published."
        $ref: "#/definitions/PaymentData"
      replyAuthorized:
        type: "boolean"
        description: "Indicate if the message allows replies."
        default: false
  MessageIdEboxIdList:
    type: "array"
    items:
      $ref: "#/definitions/MessageIdEboxId"
  MessageIdsOfSameChannel:
    type: "object"
    required:
    - "deliveryChannel"
    - "messages"
    properties:
      deliveryChannel:
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
        description: "Identifier of a deliveryChannel (PAPER, EBOX, EMAIL)."
      eBoxMessages:
          $ref: "#/definitions/MessageIdEboxIdList"
      paperMessages:
        type: "array"
        items:
          type: "string"
          description: "Message ID. Identifier of a message."
          example: "02708728-5fe3-443f-933c-19c626838c40"
      emailMessages:
        type: "array"
        items:
          type: "string"
          description: "Message ID. Identifier of a message."
          example: "02708728-5fe3-443f-933c-19c626838c40"
  EBoxMessageStatus:
    type: "object"
    required:
    - "messageId"
    - "eboxId"
    - "readStatus"
    properties:
      messageId:
        type: "string"
        description: "Identifier of a message."
      eboxId:
        $ref: "#/definitions/EboxId"
      expirationDate:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
      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
  PaperOrEmailMessageStatusList:
    type: "array"
    items:
      $ref: "#/definitions/PaperOrEmailMessageStatus"
  PaperOrEmailMessageStatus:
    type: "object"
    required:
    - "messageId"
    properties:
      messageId:
        type: "string"
      shippingDate:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was injected in the bpost framework."
      trackAndTraceUri:
        type: "string"
      statuses:
        type: "array"
        items:
          $ref: "#/definitions/MessageStatusEvent"
  MessageStatusEvent:
    type: "object"
    properties:
      id:
        type: "string"
      status: 
        type: "string"
      updated:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when this status was updated."
      comment:
        type: "string"
  MessageStatusList:
    type: "object"
    properties:
      eBoxMessageStatuses:
        $ref: "#/definitions/EBoxMessagesStatusList"
      paperMessageStatuses:
        $ref: "#/definitions/PaperOrEmailMessageStatusList"
      emailMessageStatuses:
        $ref: "#/definitions/PaperOrEmailMessageStatusList"
  EBoxMessagesStatusList:
    type: "array"
    items:
      $ref: "#/definitions/EBoxMessageStatus"
  MessagesStatusOfSameDeliveryChannel:
    type: "object"
    required:
    - "deliveryChannel"
    - "messageStatuses"
    properties:
      deliveryChannel:
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
      messageStatuses:
          $ref: "#/definitions/MessageStatusList"
  PaymentData:
    type: "object"
    required:
    - "amount"
    - "currency"
    - "iban"
    - "paymentDataId"
    - "vatAmount"
    - "dueDate"
    properties:
      paymentDataId:
        type: "string"
        description: "Identifier of the paymentData."
      amount:
        type: "number"
        format: "double"
        description: "Amount that needs to be paid, vat not included."
      vatAmount:
        type: "number"
        format: "double"
        description: "Amount of the vat, to be added to the base amount when applicable."
      currency:
        type: "string"
        description: "Currency in which the amount must be paid, following ISO 4217."
      dueDate:
        type: "string"
        format: "date-time"
        description: "Date on which the payment needs to be fulfilled."
      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: "#/definitions/SendStatusMessage"
  SendStatusMessage:
    type: "object"
    required:
      - "messageId"
    properties:
      messageId:
        type: "string"
        description: "Identifier of a message"
      expirationDate:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
      deliveryChannel:
        description: "The way the message be delivered."
        type: "string"
        enum:
        - "EBOX"
        - "PAPER"
        - "EMAIL"
      code:
        type: "string"
        description: "Business Code"
      message:
        type: "string"
        description: "Business Code Description"
  PublicationStatusMessage:
    type: "object"
    required:
      - "messageId"
      - "expirationDate"
    properties:
      messageId:
        type: "string"
        description: "Identifier of a message."
      expirationDate:
        type: "string"
        format: "date-time"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox."
      code:
        type: "string"
        description: "Business Code."
      message:
        type: "string"
        description: "Business Code Description."
  UploadStatusMessage:
    type: "object"
    required:
      - "uuid"
    properties:
      uuid:
        type: "string"
        description: "Identifier of a message."
      host:
        type: "string"
      filename:
        type: "string"
  MagdaException:
    type: "object"
    required:
    - "code"
    - "origin"
    - "type"
    - "date"
    - "diagnosis"
    properties:
      code:
        type: "integer"
        maxLength: 10
        description: "HTTP status code of the request from which this exception stemmed."
      origin:
        type: "string"
        maxLength: 5
        description: "Who originated this exception."
      type:
        type: "string"
        enum:
        - "ERROR"
        - "WARNING"
        - "INFO"
        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."
      date:
        type: "string"
        description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the error was found."
      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."  
  ErrorMessage:
    type: "object"
    required:
    - "title"
    - "detail"
    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"
    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: dpl1/dlp3/dlp4."
      documentAvailableUntilDate:
        type: "string"
        format: "date"
        description: "Date (yyyy-MM-dd) until when the document should be available for download."
      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."
        enum:
         - "SAME_PAGE"
         - "SEPARATE_PAGE"
         - "SEPARATE_LETTER"
        default: "SEPARATE_PAGE"
      address:
        $ref: "#/definitions/Address"
      retourAddress:
        $ref: "#/definitions/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"