swagger: "2.0"
info:
  title: "Hermes SMP migration key API"
  description: "
    <article>
      <h1>Business Context</h1>
      <ul>
        <li>To boost generalization of e-invoicing in Belgium, the Government decided to set up Hermes (hrms), an xml to pdf gateway that brings Belgian enterprises not yet equipped with inbound e-invoicing tools within the reach of Peppol BIS invoice senders.</li>
        <li>A key component of hrms is HermeSMP (hsmp): this smp is dedicated to store only hrms receivers, ie all Belgian enterprises as long as they have not found a suitable Peppol Access Provider.</li>
        <li>This API provides a 'machine friendly exit' for participant by providing Peppol access point to get the necessary migration key to start the standard SMP migration process, as defined in Peppol specifications.</li>
        <li>Note that beside this API, there is also the possibility for an enterprise representative manually collects the migration key using a webform exposed by the Government. TODO : @Arnaud could you provide the url of the IWF</li>
      </ul>

      <h1>API Documentation</h1>
      <div>
      This documentation describes the REST interface for the exchanges between the HSMP and a client wishing to retrieve a migration key in order to take over a Peppol participant.<br/>
      This process is part of the <a href='https://github.com/OpenPEPPOL/documentation/blob/master/TransportInfrastructure/ICT-Transport-SML_Service_Specification-101.pdf'>Peppol SML specification</a>. But the actual exchange of the migration key part is left to specific implementation, as described in this extract of the SML specification:<br/><br/>
      <i>Another set of steps relating to SMPs and the SML relates to the migration of the metadata about a participant from one SMP to another SMP (for example, the participant decides to change suppliers for this function). There are interfaces to the SML to support migrations of this kind, which imply following a sequence of steps along the lines shown in figure 4.
         In this sequence, the original SMP receives a request from a participant to migrate its metadata to a new SMP (a step that is done out-of-band: there are no interfaces defined in these specifications for this).
          The SMP generates a Migration Key which is a unique string containing characters and numbers only, with a maximum length of 24 characters.
          The original SMP invokes the PrepareToMigrate operation of the SML and then passes the migration key to the new SMP (the key passing is an out-of-band step not defined in these specifications).
          When the new SMP has created the relevant metadata for the participant, it signals that it is taking over by invoking the Migrate operation of the SML, which then causes the DNS record(s) for that participant ID to be updated to point at the new SMP.
          Once this switch is complete, the original SMP can remove the metadata which it holds for the participant.</i>

      <br/><br/>
      </div>

      <h2>Mutual TLS authentication</h2>
      In order to call the API, the access point must use a valid Peppol certificate to perform a mutula TLS authentication:
      <ul>
      <li>Production Access point certificate can be used for PROD and TEST Participants (SML and SMK)</li>
      <li>Test Access Point Certificate can only be used for TEST Participants (SMK)</li>
      </ul>
      Swagger is not able to specify security based on mutual TLS authentication, therefore the security part is left empty in the endpoint documentation.

      <h2>User blacklisting</h2>
      HSMP allows a maximum of XX queries per day coming from a single certificate. If the limit is reached, the certificate is permanently baned. Access point may send a email request to BOSA support in order to to unblock the certificate.


      <h3>API DNS and IP's</h3>
      The DNS entries are done for the following domains:

      TEST SMK : smp.acc-hermes-belgium.be
      <ul>
      <li> 91.198.243.18 </li>
      <li> 91.198.243.19 </li>
      </ul>

      PROD SML : smp.hermes-belgium.be
      <ul>
        <li> 91.198.243.20 </li>
        <li> 91.198.243.21 </li>
      </ul>

      <h1>Changes</h1>
      <h2>1.0.0</h2>
      The first release was done as parto f the initial development of the HSMP. Its purpose was to enable the BOSA intelligent web form to gather and distribute the migration key.
      <h2>2.0.0beta</h2>
      Following up on Access Points feedback, BOSA decided to provide a public API for Access Point to automate Participant migration.<br/>
      Here is the list of changes:
      <ul>
        <li>The name of the API was changed to a more 'REST' friendly resource like name</li>
        <li>The xml elements names were adapted to be closer to the one used in the SML documentation</li>
        <li>The xml structure of the API request and response have been adapted in order to be fit in the capabilities of the swagger definition file.</li>
        <li>Authentication was change to leverage the Peppol PKI</li>
        <li>Error code were added. Note that due to swagger documentation, the error code are documented as x-000-HSMP-000. The API will respond a standard response code corresponding to the first 3 digits. The body of the response will contain the error code and message.</li>
      </ul>

    </article>
      "
  version: 2.0.0 Beta
host: smp.hermes-belgium.be
schemes:
  - https
paths:
  /MigrationRecords:
    get:
      summary: "Returns the migration keys for a list of participants; requires mutual TLS authentication."
      operationId: "MigrationRecords"
      consumes:
        - "application/xml"
      produces:
        - "application/xml"
      parameters:
        - in: "body"
          name: "body"
          description: "A list of up to 10 participants"
          required: true
          schema:
            $ref: "#/definitions/Participants"
      responses:
        200:
          description: Ok
          schema:
            $ref: "#/definitions/MigrationRecords"
        x-401-HSMP-802:
          description: No certificate supplied with the request
        x-401-HSMP-803:
          description: Error while parsing client certificate
        x-401-HSMP-804:
          description: Certificate expired or not yet valid
        x-401-HSMP-805:
          description: Certificate cannot be trusted by PEPPOL trustStore
        x-401-HSMP-806:
          description: Certificate environment does not match with requested environment (test or prod)
        x-401-HSMP-808:
          description: Certificate is not a PEPPOL ACCESS POINT certificate
        x-404-HSMP-001:
          description: Invalid or non-existing enterprise number + id
        x-404-HSMP-002:
          description: Inactive enterprise number + id
        x-404-HSMP-003:
          description: Already migrated  + id
        x-429-HSMP-004:
          description: Blacklisted. Please contact BOSA
        x-500-HSMP-999:
          description: The service encountered an internal error

definitions:
  Participants:
    type: "object"
    required:
      - "participant"
    properties:
      participant:
        type: "array"
        xml:
          name: "Participant"
          wrapped: false
        items:
          $ref: "#/definitions/Participant"
    xml:
      name: "Participants"
  Participant:
    type: "string"
    example: "0978645312"
    xml:
      name: "Participant"
  MigrationRecords:
    type: "object"
    required:
      - "migration"
    properties:
      migration:
        type: "array"
        xml:
          name: "MigrationRecord"
          wrapped: false
        items:
          $ref: "#/definitions/MigrationRecord"
    xml:
      name: "MigrationRecords"
  MigrationRecord:
    type: "object"
    required:
      - "participant"
      - "key"
    properties:
      participant:
        $ref: "#/definitions/Participant"
      key:
        $ref: "#/definitions/MigrationKey"
    xml:
      name: "MigrationRecord"
  MigrationKey:
    type: "string"
    example: "Hms20BE-K-{%~siJ9QNf=e0x"
    xml:
      name: "MigrationKey"