openapi: "3.0.3"
info:
  description: "RESTful API designed to allows users to consult the partitions of an e-Box Enterprise and the users rights on them."
  version: "1.3"
  title: "Ebox Partition"
  contact:
    name: "eBoxIntegration"
    email: "eboxintegration@smals.be"
  license:
    name: "e-Box"
    url: "http://www.digitalbelgium.be"
tags:
  - name: "Monitoring"
  - name: "Enterprise checks"
  - name: "Mandate checks"
  - name: "Routing rules"
servers:
  - url: /REST/ebox/enterprise/partition/v1
security:
  - Oauth:
      [ 'scope:document:management:consult:ws-eboxrestentreprise:documentconsumer',
        'scope:document:management:consult:ws-eboxrestentreprise:publicationmandate',
        'scope:document:management:consult:ws-eboxrestentreprise:publicationsender',
        'scope:document:management:consult:ws-eboxrestentreprise:documentprovider',
        'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin',
        'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin',
        'scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible',
        'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser',
        'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser',
        'scope:document:management:consult:ws-eboxrestentreprise:publicationweb',
        'scope:document:management:consult:ws-eboxrestentreprise:monitoring',
        'scope:ksz-bcss:registered:epost-rest:proofofdispatch',
        'scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication',
        'scope:document:management:ws-eboxrestentreprise:eboxrepresentativeconsultation'
      ]

paths:
  /health:
    get:
      tags:
        - Monitoring
      summary: Check health of the service
      description: This resource is only available to supervision users
      operationId: checkHealth
      externalDocs:
        url: "https://www.belgif.be/specification/rest/api-guide/#health"
      responses:
        200:
          description: The service is UP, DEGRADED, DOWN
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
        503:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            [ 'scope:document:management:consult:ws-eboxrestentreprise:monitoring' ]

  /ebox/{enterpriseNumber}/routingRules:
    get:
      summary: "Retrieve partition routing rules for an ebox ordered from the highest priority to the lowest priority."
      description: "Retrieve partition routing rules conditions for an ebox. The list is ordered from the rule with the highest priority to the lowest priority. That is to say, the first rule in the list with conditions matching the properties of a message must be applied to change the message recipient partition to the target partition of the rule. If a condition is not given or has a null value, it means that it can be any value like a wildcard."
      operationId: getRoutingRules
      tags:
        - Routing rules
      parameters:
        - name: "enterpriseNumber"
          in: "path"
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
          required: true
        - name: "messageTypeId"
          in: "query"
          schema:
            type: string
        - name: "senderApplicationId"
          in: "query"
          schema:
            type: string
        - name: "senderOrganizationId"
          in: "query"
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderedRoutingRules"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            ['scope:ksz-bcss:registered:epost-rest:proofofdispatch',
             'scope:document:management:consult:ws-eboxrestentreprise:documentprovider']
      x-oauth2-required-scopes: any

  /ebox/{enterpriseNumber}/hasMandate:
    summary: "Verify the Mandatary has a mandate for the the requested operation on the ebox"
    description: "This endpoint is called when a mandatary tries perform an operation on the targeted ebox. The service will return true if a mandate exists"
    get:
      operationId: hasMandate
      tags:
        - "Mandate checks"
      parameters:
        - name: "enterpriseNumber"
          in: "path"
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
          required: true
        - name: "mandataryEnterpriseNumber"
          in: "query"
          required: true
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
        - name: "operation"
          required: true
          in: "query"
          schema:
            type: string
            enum:
              - publish
              - consult
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HasMandateResponse"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            [ 'scope:ksz-bcss:registered:epost-rest:proofofdispatch',
              'scope:document:management:consult:ws-eboxrestentreprise:documentprovider'
            ]
      x-oauth2-required-scopes: any

  /ebox/{enterpriseNumber}/partitions:
    get:
      tags:
        - "Enterprise checks"
      summary: "Get all existing partitions in the e-Box"
      description: ""
      operationId: "getPartitions"
      parameters:
        - name: "enterpriseNumber"
          in: "path"
          description: "The enterprise number assigned by CBE identifying the ebox."
          required: true
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Partitions"
        404:
          description: "Ebox not found"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            [ 'scope:document:management:consult:ws-eboxrestentreprise:documentconsumer',
              'scope:document:management:consult:ws-eboxrestentreprise:publicationmandate',
              'scope:document:management:consult:ws-eboxrestentreprise:publicationsender',
              'scope:document:management:consult:ws-eboxrestentreprise:documentprovider',
              'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin',
              'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin',
              'scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible',
              'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser',
              'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser',
              'scope:document:management:consult:ws-eboxrestentreprise:publicationweb',
              'scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication',
              'scope:document:management:ws-eboxrestentreprise:eboxrepresentativeconsultation']
      x-oauth2-required-scopes: any

  /ebox/{enterpriseNumber}/partitions/{partitionId}:
    get:
      tags:
        - "Enterprise checks"
      summary: "Get a partition in the e-Box."
      description: ""
      operationId: "getPartition"
      parameters:
        - name: "enterpriseNumber"
          in: "path"
          description: "The enterprise number assigned by CBE identifying the ebox."
          required: true
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
        - name: "partitionId"
          in: "path"
          description: "The partition identifier"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Partition"
        404:
          description: "Partition not found"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            ['scope:document:management:consult:ws-eboxrestentreprise:documentconsumer',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationmandate',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationsender',
             'scope:document:management:consult:ws-eboxrestentreprise:documentprovider',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationweb',
             'scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication',
             'scope:document:management:ws-eboxrestentreprise:eboxrepresentativeconsultation']
      x-oauth2-required-scopes: any

  /ebox/{enterpriseNumber}/userPartitionRights:
    get:
      tags:
        - "Enterprise checks"
      summary: "Consult the list of user partition rights."
      description: "An user can see only its own rights on partitions. A partition admin can see the user rights on the partition A Document Provider can see the rights of any user"
      operationId: "getUserPartitionRights"
      parameters:
        - name: "enterpriseNumber"
          in: "path"
          description: "The enterprise number assigned by CBE identifying the ebox."
          required: true
          schema:
            $ref: "#/components/schemas/EnterpriseNumber"
        - name: "partitionId"
          in: "query"
          description: "The partition identifier to see the user rights on a specific partition."
          required: false
          schema:
            type: "string"
        - name: "userId"
          in: "query"
          description: "The user identifer to see all the partitions where the user has an access on it. If the client is not a Document Provider, only the client's identifier can by set as value for this parameter."
          required: false
          schema:
            type: "string"
        - name: "userType"
          in: "query"
          description: "Mandatory if the userId param is specified. It allows to not make confusion with human users and application users."
          required: false
          schema:
            type: "string"
            enum:
              - "human"
              - "application"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserPartitionRightsList"
        404:
          description: "Ebox not found"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: "error payload"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - Oauth:
            ['scope:document:management:consult:ws-eboxrestentreprise:documentconsumer',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationmandate',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationsender',
             'scope:document:management:consult:ws-eboxrestentreprise:documentprovider',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser',
             'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser',
             'scope:document:management:consult:ws-eboxrestentreprise:publicationweb',
             'scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication',
             'scope:document:management:ws-eboxrestentreprise:eboxrepresentativeconsultation']
      x-oauth2-required-scopes: any


components:
  securitySchemes:
    Oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://services-int.socialsecurity.be/REST/oauth/v5/authorize'
          tokenUrl: 'https://privateservices-int.socialsecurity.be/REST/oauth/v5/token'
          scopes:
            'scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible': "This scope allows the RAE/co-RAE to consult their list of partitions and userPartitionRights."
            'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin': "This scope allows the GL/co-GL under the qualities QUAL_COMPANY, QUAL_EMP_NOSS, QUAL_EMP_NOSSPLA to consult their list of partitions and userPartitionRights."
            'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin': "This scope allows the GL/co-GL under the qualities  QUAL_SSC, QUAL_FSC, QUAL_SP_LEG to consult their list of partitions and userPartitionRights."
            'scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser': "This scope allows the user under the qualities QUAL_COMPANY, QUAL_EMP_NOSS, QUAL_EMP_NOSSPLA to consult their list of partitions."
            'scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser': "This scope allows the user under the qualities QUAL_SSC, QUAL_FSC, QUAL_SP_LEG to consult their list of partitions."
            'scope:document:management:consult:ws-eboxrestentreprise:publicationweb': "This scope allows institutions to consult the list of partitions of e-Box Enterprise."

        clientCredentials:
          tokenUrl: 'https://privateservices-int.socialsecurity.be/REST/oauth/v5/token'
          scopes:
            'scope:document:management:consult:ws-eboxrestentreprise:documentconsumer': "This scope allows the Document Consumers to consult the list of partitions of their e-Box Enterprise"
            'scope:document:management:consult:ws-eboxrestentreprise:publicationmandate': "This scope allows the Document Senders consult the list of partitions of e-Box Enterprise."
            'scope:document:management:consult:ws-eboxrestentreprise:publicationsender': "This scope allows the Document Senders to consult the list of partitions of e-Box Enterprise."
            'scope:document:management:consult:ws-eboxrestentreprise:documentprovider': "This scope allows the Document Providers to consult the list of partitions and userPartitionRights of e-Box Enterprise."
            'scope:ksz-bcss:registered:epost-rest:proofofdispatch': "This scope is an alternative to the Document Provider scope "
            'scope:document:management:consult:ws-eboxrestentreprise:monitoring': "This scope allows retrieving the monitoring status"
            'scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication': "This scope allows intermediate users with publication rights to check partition details"
            'scope:document:management:ws-eboxrestentreprise:eboxrepresentativeconsultation': "This scope allows intermediate users with consultation rights to check partition details"

  schemas:
    EnterpriseNumber:
      description: Identifier issued by CBE for a registered organization
      type: string
      pattern: '^[0-1]?\d{9}$'
      example: "0406798006"
    HealthStatus:
      description: Response message for the API health
      type: object
      properties:
        status:
          description: "Level indicating the health status of the service: UP (functioning as expected), DOWN (suffering unexpected failures), DEGRADED (partly unavailable but service can be continued with reduced functionality), or a custom status value"
          type: string
      required:
        - status

    HasMandateResponse:
      type: "object"
      required:
        - "hasMandate"
      properties:
        hasMandate:
          type: "boolean"
          description: "Indicates if the mandatary has indeed a mandate for the target enterprise number and the given operation"
    Rights:
      description: "Rights that an user can have on a partition"
      type: "object"
      required:
        - "consult"
        - "publish"
        - "partitionAdmin"
      properties:
        consult:
          type: "boolean"
          description: "Indicates whether the user can consult the messages received in the partition and reply them. This right authorize also the consultation of messages sent from the partition."
        publish:
          type: "boolean"
          description: "Indicates whether the user can publish messages from the partition."
        partitionAdmin:
          type: "boolean"
          description: "Indicates whether the user is an admin of the partition. This right allows the user to add and modify rights of other users on the partition."
    User:
      description: ""
      type: "object"
      required:
        - "id"
        - "type"
      properties:
        id:
          type: "string"
          description: "An user identifier understandable by the admin and external applications. It identifies a human user with a SSIN or an application user with and URN. The SSIN format is ^[0-9]{11}$"
          example: "90010122233"
        type:
          type: "string"
          description: "Indicates if the user is an human or an application"
          enum:
            - "human"
            - "application"
    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"
          example: "HRdepartment"
        name:
          $ref: "#/components/schemas/LocalizedString"
    Partitions:
      type: object
      properties:
        items:
          type: "array"
          items:
            $ref: "#/components/schemas/Partition"
      required:
        - "items"
    OrderedRoutingRules:
      type: object
      required:
        - "items"
      properties:
        items:
          type: "array"
          items:
            $ref: "#/components/schemas/RoutingRule"

    RoutingRule:
      description: Partition rule to ease the receipt of this kind of messages
      type: object
      required:
        - routingRuleId
        - priority
        - conditions
        - targetPartitionId
      properties:
        routingRuleId:
          type: integer
          description: Routing rule technical identifier
        priority:
          type: integer
          minimum: 0
          description: "The position in the list of routing rules if the list is ordered by priority. The higher is this number, the less priority has the routing rule. For example, if the priority number is 5, this rule must be applied to messages matching the condition instead of the rules that have a higher priority number and with matching condition. There should ne be routing rules with the same priority number. If a routing rule is created, the routing rule having the same priority number and all other routing rules having a higher priority number should have their priority number incremented by 1."
        conditions:
          type: array
          items:
            type: object
            description: "Criteria to follow to map a message to a partition. If a property is not given or has a null value, it means that the property can have any value like a wildcard. For example, if condition:{senderApplicationId:myApplication, senderOrganizationId:0123456789} then it means that every new messages from the organization 0123456789 and the sender application myApplication should be moved to the target partition."
            properties:
              messageTypeId:
                type: string
                description: identification of the message type
              senderApplicationId:
                type: string
                description: identification of the sender application
              senderOrganizationId:
                $ref: "#/components/schemas/EnterpriseNumber"
        targetPartitionId:
          type: string
          description: the partition where the messages matching the condition must be moved to.
        creationDate:
          type: string
          description: Date when the user created the routing rule
          format: date-time

    UserPartitionRights:
      description: "The rights linked to an user on a partition"
      type: "object"
      required:
        - "id"
        - "user"
        - "partitionId"
        - "rights"
      properties:
        id:
          type: "string"
          description: "userPartitionRights Identifier used to perform access management operations."
        user:
          $ref: "#/components/schemas/User"
        partitionId:
          type: "string"
          description: "The partition identifier."
          example: "HRdepartment"
        rights:
          $ref: "#/components/schemas/Rights"
    UserPartitionRightsList:
      description: "A list of links between users and partitions and their rights on these partitions."
      type: object
      properties:
        items:
          type: "array"
          items:
            $ref: "#/components/schemas/UserPartitionRights"
      required:
        - "items"

    LocalizedString:
      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"

    Problem:
      description: A Problem Details object (RFC 7807)
      type: object
      properties:
        type:
          type: string
          format: uri
          description: An absolute URI that identifies the problem type
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML).
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 400
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          format: uri
          description: An absolute URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
      example:
        {
          "type": "urn:problem-type:belgif:resourceNotFound",
          "href": "https://www.gcloud.belgium.be/rest/problems/resourceNotFound.html",
          "title": "Ebox not found",
          "status": 404,
          "detail": "The ebox specified as path parameter is not found.",
          "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
          "environment": "acceptation" # additional properties specific to the problem type are allowed
        }

