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. Last updated 23-06-2023."
  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'
      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'
      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. More than 6 upfiles only supported for PAPER delivery."
      operationId: createMessage
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      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
                upfile7:
                  type: string
                  format: binary
                  nullable: true
                upfile8:
                  type: string
                  format: binary
                  nullable: true
                upfile9:
                  type: string
                  format: binary
                  nullable: true
                upfile10:
                  type: string
                  format: binary
                  nullable: true
                upfile11:
                  type: string
                  format: binary
                  nullable: true
                upfile12:
                  type: string
                  format: binary
                  nullable: true
                upfile13:
                  type: string
                  format: binary
                  nullable: true
                upfile14:
                  type: string
                  format: binary
                  nullable: true
                upfile15:
                  type: string
                  format: binary
                  nullable: true
                upfile16:
                  type: string
                  format: binary
                  nullable: true
                upfile17:
                  type: string
                  format: binary
                  nullable: true
                upfile18:
                  type: string
                  format: binary
                  nullable: true
                upfile19:
                  type: string
                  format: binary
                  nullable: true
                upfile20:
                  type: string
                  format: binary
                  nullable: true
                qrfile:
                  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. Search 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. 
           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. Search 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. Search for the value as a substring"
          schema:
            type: string
        - name: organization
          in: query
          description: "What was the organization name of the message receiver. Case insensitive search. Search 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. Search 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. Search 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. Search 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. Search 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. Search 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. Search 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. Search 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. Search 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. Search 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: receiverPartition
          in: query
          description: "The ebox partition where the messages are sent to."
          schema:
            type: string
        - name: requiredAction
          in: query
          description: "Filter on messages for which an action from the receiver is required. It also takes messages that the receiver has confirmed the action execution. A message with a required action is a message where in the messageActionsStatus array, there is one action of type requiredActionToConfirm."
          schema:
            type: boolean
        - name: requiredActionNotExecuted
          in: query
          description: "Filter on messages for which an action from the receiver is required, but the action has not yet been confirmed."
          schema:
            type: boolean
        - name: requiredActionDueDateBefore
          in: query
          description: "Filter on messages for which an action from the receiver is required before the given date."
          schema:
            type: string
            format: date
        - name: requiredActionDueDateAfter
          in: query
          description: "Filter on messages for which an action from the receiver is required before the given date."
          schema:
            type: string
            format: date
        - 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'
      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'
  /messages/fednot:
    post:
      tags:
        - "messages/fednot"
      summary: "Send a message for FEDNOT"
      operationId: createFednotMessage
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/Idempotency-Key'
      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
                qrfile:
                  type: string
                  format: binary
                  nullable: true
        required: true
      responses:
        201:
          description: Created
          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/fednot"
      summary: "Allows to search for FEDNOT messages."
      operationId: findFednotMessages
      parameters:
        - 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: limit
          in: query
          description: "How many results need to be returned"
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: "The first position to return from the results of the query. The default is 0, which starts the page at the first result."
          schema:
            type: integer
            default: 0
            minimum: 0
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EboxMessageSearchResults'
        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/fednot/{messageId}/attachments/{attachmentId}/content:
    get:
      tags:
        - "messages/fednot"
      summary: "Allows to download the attachments of a FEDNOT message."
      operationId: getFednotMessageAttachment
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - $ref: '#/components/parameters/AttachmentId'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        200:
          description: OK
          headers:
            content-type:
              description: "The content type of the attachment: PDF."
              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}/attachments:
    get:
      tags:
        - "messages"
      summary: "Allows to download the attachment of a FEDNOT 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'
      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'
      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}/IPEXdata:
    patch:
      tags:
        - "messages"
      summary: "INTERNAL SERVICE - Allows to update the ipex data of a message."
      operationId: updateIpexData
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        description: "The Status Update Request"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIpexDataRequest'
        required: true
      responses:
        204:
          description: No Content
        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}/preview:
    get:
      tags:
        - "messages"
      summary: "Allows to obtain a preview of the PDF of a paper message (including front pages)."
      operationId: GetPaperPDFPreview
      parameters:
        - $ref: '#/components/parameters/MessageId'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        200:
          description: OK
          headers:
            content-type:
              description: "The content type of the binary: PDF."
              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 PDF 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}/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'
      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'
  /ebox/{eboxId}/partitions:
    get:
      tags:
        - "messages"
      summary: "Allows to get the partitions of an Ebox."
      operationId: getEboxPartitions
      parameters:
        - $ref: '#/components/parameters/EboxId'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partitions'
        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'
  /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'
      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'
  /searchMessageStatus:
    post:
      tags:
        - "messages"
      summary: "INTERNAL SERVICE - Obtain a messageStatus for a list of eBox messages."
      operationId: getEBoxStatus
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
      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'
  /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'
      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
    AttachmentId:
      name: attachmentId
      in: path
      description: "Globally unique identifier (GUID) for the attachment"
      required: true
      schema:
        type: string
    EboxId:
      name: eboxId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/PersonOrEnterpriseIdentifier'
  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 contains 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
        ssin:
          description: Social Security Identification Number issued by the National Register or CBSS
          type: string
          pattern: '^\d{11}$'
          example: "44022722580"
        enterpriseNumber:
          description: Identifier issued by CBE for a registered organization
          type: string
          pattern: '^[0|1]\d{9}$'
          example: "0406798006"
        partition:
          type: string
          description: An ebox partition.
          example: secretariat
        eboxIdValue:
          description: 'DEPRICATED property which is replaced by the ssin or enterprise number above. FEDNOT consumers should NOT use this field.'
          $ref: '#/components/schemas/PersonOrEnterpriseIdentifier'
    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."
    EboxMessage:
      description: A message is basically composed of a set of metadata (e.g. subject, receipt date, read status, etc.), one or more attachments and optionnaly a body or payment data.
      type: object
      required:
        - messageId
        - subject
        - sender
        - senderApplicationId
        - recipient
        - messageTypeId
        - receiptDate
        - expirationDate
        - isRead
      properties:
        messageId:
          type: string
          description: Unique identifier of the message in the ebox. We suggest to make it unique to all ebox to avoid problems for the sent-box.
        subject:
          $ref: "#/components/schemas/TranslatedString"
        sender:
          $ref: "#/components/schemas/EboxId"
        senderApplicationId:
          type: "string"
          description: Identifier of the senderApplication
        recipient:
          $ref: "#/components/schemas/EboxId"
        messageTypeId:
          type: "string"
          description: Identifier of a messageType
        receiptDate:
          type: string
          format: date-time
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was received in the ebox.
          example: "2022-12-19T00:00:00+01:00"
        expirationDate:
          type: string
          format: date-time
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox.
          example: "2025-12-19T00:00:00+01:00"
        isRead:
          type: boolean
          description: Indicates whether or not the message has already been read. A message is marked as read if the main content is consulted. If the main content is an attachment, then it is considered consulted if the content is downloaded.
          default: false
        firstReadDate:
          type: string
          format: date-time
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message is read.
          example: "2024-12-19T00:00:00+01:00"
        isVisible:
          type: boolean
          description: Indication whether or not the message is visible or not.
          default: true
        isRegisteredMail:
          type: boolean
          description: "Indicates whether or not the message was published as a registered mail in the ebox. Pay attention that a juridical law is written about electronical registered mail and contains criterias to follow in order to publish a message with the same juridical value than a postal registered mail. DO NOT put this boolean at true if the message does not follow the criterias."
          default: false
        forTheAttentionOf:
          $ref: "#/components/schemas/ForTheAttentionOf"
        isReplyAuthorized:
          type: boolean
          description: "Indicate if the message allows replies. If there is a message action of type replyWithTemplate for the message then the reply must follow the template of one of the message action. If there is not, then a reply can be sent without following any template."
          default: false
        parentMessageId:
          type: string
          description: In case of a reply, the parentMessageId is the identifier of the replied message.
        originalMessageId:
          type: string
          description: External id of the published message. Can be used as a correlation id defined by the sender.
        replyDueDate:
          type: string
          format: date-time
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) until when the reply is possible. This property can not be set if the isReplyAuthorized is false. The reply due date must be before the expiration date."
          example: "2025-01-01:00:00+01:00"
        isReplied:
          type: boolean
          description: Indication whether or not the message has a reply.
          default: false
        lastReplyDate:
          type: string
          format: date-time
          description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was replied in the ebox. Only present when reply=true
          example: "2023-09-01:00:00+01:00"
        attachments:
          description: Documents attached to the messages.
          type: array
          items:
            $ref: "#/components/schemas/Attachment"
        hasBody:
          type: boolean
          description: Indication whether or not the message has a bodyContent. The body content can be consulted by doing the request GET ``/ebox/messages/{messageId}/body``.
          default: false
        isBodyMainContent:
          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
        hasStructuredData:
          type: boolean
          description: "Indication whether or not the message has message data. The MessageData structure exists to convey information that should not be displayed to the endUser. It can be used for machine to machine processing. The messageData can be consulted by doing the request GET ``/ebox/messages/{messageId}/structuredData``."
          default: false
        hasMessageActions:
          type: boolean
          description: "Indication whether or not the message has one or several message actions. The message actions with their status can be consulted by doing the request GET ``/ebox/messages/{messageId}/messageActions``. Then the message action can be consulted by doing the request GET ``/messageActions/{messageActionId}`` with the IDs retrieved from previous request."
          default: false
        hasPaymentData:
          type: boolean
          description: "Indication whether or not the message has paymentData. The payment data can be consulted by doit the request GET ``/ebox/messages/{messageId}/paymentData``."
          default: false
        businessDataList:
          type: array
          description: A businessData element is a meta data linked to the message content that can be displayed to the recipient and its value is also taken into account for the message search feature.
          items:
            $ref: "#/components/schemas/BusinessDataToPublish"
    Attachment:
      description: An attachment item contains all the metadata of an attachment and the link to the attachtment content itself
      type: object
      required:
        - attachmentId
        - fileName
        - isMainContent
        - mediaType
        - size
      properties:
        attachmentId:
          type: string
          description: Unique identifier of the attachment
        attachmentTitle:
          $ref: "#/components/schemas/TranslatedString"
        fileName:
          type: string
          description: The file name provided by the sender, with its extension
          example: yourDocument.pdf
        isMainContent:
          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."
        mediaType:
          type: string
          description: Standardized identifier for file formats following RFC2046
          enum:
            - "application/pdf"
            - "application/zip"
            - "application/xml"
            - "text/csv"
            - "text/html"
            - "text/plain"
            - "text/xml"
            - "application/vnd.oasis.opendocument.text"
            - "application/vnd.oasis.opendocument.spreadsheet"
            - "application/vnd.oasis.opendocument.presentation"
            - "application/vnd.oasis.opendocument.graphics"
            - "application/vnd.ms-excel"
            - "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
            - "application/vnd.ms-powerpoint"
            - "application/msword"
            - "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
            - "image/png"
            - "image/jpeg"
        size:
          type: number
          format: double
          example: 1800.0
          description: Size of the attachment, expressed in kB
        digest:
          $ref: "#/components/schemas/Digest"
        isAttachmentSigned:
          type: boolean
          description: Boolean used to indicate if the attachment is signed or not.
          default: false
        contentHref:
          type: string
          format: uri
          description: URL to the content of the attachment
    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."
        erratumMessageId:
          type: string
          description: In case this ebox message is erroneous, Id of the erratum ebox message.
        erroneousMessageId:
          type: string
          description: In case this ebox message is a correction of an erroneous ebox message, Id of the erroneous ebox message.
        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 fields 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."
    EboxMessageSearchResults:
      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/EboxMessage'
      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, make 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'
        messageData:
          type: string
          description: "The MessageData structure exists to convey information that SHOULD NOT be displayed to the endUser. This is in contrast with BusinessData structure which SHOULD be displayed as is to the endUser."
        paymentData:
          $ref: '#/components/schemas/PaymentData'
        replyAuthorized:
          type: boolean
          description: "Indicate if the message allows replies."
          default: false
        replyDueDate:
          type: string
          format: "date-time"
          description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) until when the reply is possible."
        messageActions:
          type: array
          description: "Array of actions available for the recipient. Only one of type requiredActionToConfirm can be in this array."
          items:
            $ref: "#/components/schemas/MessageActionToPublish"
        erroneousMessageId:
          type: string
          description: "Id of the erroneous message. It Cannot be the Id of a message that has already an erratum. It cannot be the Id of a message published by another organization."
      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."
    MessageActionToPublish:
      type: object
      description: "Object to add a possible action to a message for the recipient and its due date"
      required:
        - "messageActionId"
      properties:
        messageActionId:
          type: "string"
          description: "the identifier of the MessageAction"
        executionDueDate:
          type: "string"
          format: "date-time"
          description: "Add a due date for the action."
    MessageActions:
      type: object
      description: "Object to show info about that status of message actions."
      required:
        - "messageActionId"
      properties:
        messageActionId:
          type: "string"
          description: "the identifier of the MessageAction"
        executionDueDate:
          type: "string"
          format: "date-time"
          description: "The due date of the action."
        executed:
          type: "boolean"
          default: false
          description: "Indicator of message action being executed or not."
        executionDate:
          type: "string"
          format: "date-time"
          description: "The execution date of the action."
    TypedMessageIdEboxIdList:
      description: "A typed version of the MessageIdEboxIdList. When instantiated, make 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, make 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, make 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
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/MessageStatusEvent'
        messageActions:
          type: array
          items:
            $ref: '#/components/schemas/MessageActions'
    PaperOrEmailMessageStatus:
      description: "When instantiated, make 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
    RemittanceInformationStructured:
      description: "Remittance Information Structured. Only one remittance should be provided between unstructured and structured. The sum of reference, type and issuer length shall be less of 280 characters."
      type: object
      required:
        - reference
      properties:
        reference:
          type: "string"
          description: "Remittance Information Structured Reference"
          maxLength: 320
        type:
          type: "string"
          description: "Remittance Information Structured Type"
          maxLength: 320
        issuer:
          type: "string"
          description: "Remittance Information Structured Issuer"
          maxLength: 320
    QrCodeToPublish:
      type: object
      required:
        - type
        - data
        - httpPartName
      properties:
        data:
          type: "string"
          description: "QR Code data deeplink"
          maxLength: 320
        type:
          type: "string"
          description: "QR Code type"
          maxLength: 320
        httpPartName:
          type: "string"
          description: "QR Image as HttpPart (mediaType infered)"
    Beneficiary:
      type: object
      description: "Only address fields that are actually used in this context: line1, city, postalCode, country. Other address fields are irrelevant within the context of a Benificiary."
      required:
        - name
      properties:
        name:
          type: "string"
          description: "Beneficiary Name"
        address:
          $ref: '#/components/schemas/Address'
    PaymentData:
      required:
        - amount
        - currency
        - dueDate
        - iban
        - paymentDataId
        - vatAmount
      type: object
      properties:
        paymentDataId:
          type: string
          description: Identifier of the paymentData.
        totalAmount:
          type: number
          description: Amount that needs to be paid, vat included.
          format: double
          pattern: '^\d*(.\d){0,1}\d{0,1}$'
        amount:
          type: number
          description: Amount that needs to be paid, vat not included.
          format: double
          pattern: '^\d*(.\d){0,1}\d{0,1}$'
        vatAmount:
          type: number
          description: Amount of the vat, to be added to the base amount when applicable.
          format: double
          pattern: '^\d*(.\d){0,1}\d{0,1}$'
        currency:
          type: string
          description: Currency in which the amount must be paid, following ISO 4217.
          maxLength: 3
        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.
          maxLength: 23
        bic:
          type: string
          description: Bank Identifier Code.
          maxLength: 8
        reference:
          type: string
          description: "Reference added to the payment. Deprecated, please use remittanceInformationStructured or remittanceInformationUnstructured."
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        remittanceInformationUnstructured:
          type: "string"
          maxLength: 140
          description: "Remittance Information Unstructured. Only one remittance should be provided between unstructured and structured."
        remittanceInformationStructured:
          $ref: '#/components/schemas/RemittanceInformationStructured'
        qrCode:
          $ref: '#/components/schemas/QrCodeToPublish'
      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
          maxLength: 320
        lastName:
          type: string
          maxLength: 320
        organisation:
          type: string
        line1:
          type: string
          maxLength: 320
        line2:
          type: string
        postalCode:
          type: string
          maxLength: 20
        city:
          type: string
          maxLength: 120
        region:
          type: string
        country:
          type: string
          description: ISO2 country code
          maxLength: 8
    PaperDeliveryData:
      type: object
      properties:
        objectType:
          type: string
        registeredMail:
          type: boolean
          default: false
          description: Indicates if the mail should be sent as a registered mail or
            not.
        acknowledgmentOfReceipt:
          type: boolean
          default: false
          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.
        side:
          type: string
          default: RV
          enum:
            - RV
            - RS
        offset:
          type: integer
          description: Indicates the page on which the printing of the first file should start (offset = 0 => start printing on front side of first page. Detail explanation to be found in the user guide. Behaviour to be considered in combination with side and keycommunicatedViaChannel parameters).
          nullable: true
          default: null
          minimum: 0
          maximum: 3
        documentType:
          type: string
          description: Indicates the kind of document (F.i. 'invoice', 'Informative
            Letter'). Will be used by the printing partner for reporting purposes.
          maxLength: 120
        priority:
          type: string
          default: dlp3
          description: 'Indicates how many days bpost has to deliver the paper mail: dlp1/dlp3'
        documentAvailableUntilDate:
          type: string
          format: date
          description: 'Date (yyyy-MM-dd) until when the document should be available for download.'
        keyCommunicatedViaChannel:
          type: string
          default: SEPARATE_PAGE
          enum:
            - SAME_PAGE
            - SEPARATE_PAGE
            - SEPARATE_LETTER
            - NO_DOWNLOAD_KEY
          description: Indicates if the key that is required to download a digital
            copy of the document must be sent separately from the original document.
        address:
          $ref: '#/components/schemas/Address'
        retourAddress:
          $ref: '#/components/schemas/Address'
        sendPaperIfNotReadByDate:
          type: string
          format: date-time
          description: 'Earliest date-time when a delayed paper delivery should be started in case the ebox message remains unread. Only applicable for AUTOMATIC delivery channel and consent given.'
        receiverSsin:
          $ref: '#/components/schemas/NationalNumber'
        receiverEnterpriseNumber:
          $ref: '#/components/schemas/EnterpriseNumber'
    NationalNumber:
      type: string
      pattern: "[0-9]{11}"
      example: "70012533955"
      description: "The national number of the concerned person."
    EnterpriseNumber:
      type: string
      pattern: "[0-9]{10}"
      example: "0406798006"
      description: "The enterprise number of the concerned enterprise."
    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
              maxLength: 320
        sender:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
              maxLength: 320
        subject:
          type: string
          maxLength: 320
        body:
          type: object
          properties:
            file:
              type: string
            content:
              type: string
    Partitions:
      type: object
      properties:
        items:
          type: array
          description: "The collection of partitions for an e-Box."
          items:
            $ref: '#/components/schemas/Partition'
      description: "The consise information about a collection of messages."
    Partition:
      type: "object"
      required:
        - "id"
      properties:
        id:
          description: "The partition business identifier. It will not be displayed to the end user but can be used as identifier in REST request."
          type: "string"
          format: "[A-Za-z0-9\\-_.]{1,256}"
          example: "HRdepartment"
        name:
          $ref: "#/components/schemas/TranslatedString"
    ForTheAttentionOf:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
    UpdateIpexDataRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - Created
            - Error
            - Failed
            - Printed
            - Processing
            - Sent
            - Pending
            - Cancelled
        ipexError:
          type: string
        ipexProcessDate:
          type: string
          format: date-time
          description: "Message was processed by IPEX at this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided."
        ipexMailId:
          type: string
        ipexRetourDate:
          type: string
          format: date-time
          description: "Message was returned to sender and found by IPEX at this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided."
    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
      nullable: false
      maxLength: 36
      minLength: 10
    IdempotencyKey:
      description: "When retrying a failed call, the retry call should have the same Idempotency Key."
      type: string
      nullable: false
      maxLength: 36
      minLength: 10
    PersonOrEnterpriseIdentifier:
      type: string
      pattern: "[0-9]{10,11}"
      description: the unique identifier of a citizen or enterprise
      example: "0406798006"