openapi: 3.0.3
info:
  title: NymusApiXpress
  description: >
    The "NymusApiXpress" API enables interaction with the Peppol Network,
    offering features to manage participants (sender/receiver), document types,
    document sending and receiving and document status. Security is maintained
    through API key authentication. Responses provide information of the
    processing.
  contact:
    email: support@nymus.be
  version: 1.0.0
externalDocs:
  description: Our in-depth documentation
  url: https://docs.nymus.eu
servers:
  - url: https://test-api.nymus.eu
  - url: https://api.nymus.eu
  - url: http://localhost:9001
tags:
  - name: Peppol
    description: Everything related to the Peppol Network
    externalDocs:
      description: Our in-depth documentation
      url: https://docs.nymus.eu
paths:
  /v1/nymusapixpress/peppol/participants:
    get:
      tags:
        - Peppol
      summary: Retrieves the buyers/suppliers in your environment.
      description: >-
        Retrieves the configuration of the buyers/suppliers of your Nymus
        environment.
      operationId: getParticipants
      responses:
        '200':
          description: The configuration of the buyers/suppliers of your environment.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Participant'
        '401':
          description: Missing or invalid Api Key
      security:
        - apiKey: []
    post:
      tags:
        - Peppol
      summary: Registers a new buyer/supplier in your environment.
      description: >-
        Registers a new buyer/supplier in your Nymus environment. The
        registration allows you to specify the capability to send to the Peppol
        Network. Also to specify the document types that can be received via the
        Peppol Network for that specific buyer/supplier.
      operationId: registerParticipant
      requestBody:
        description: Registers a new buyer/supplier in your environment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
        required: true
      responses:
        '200':
          description: Buyer/supplier is successfully registered in your environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          description: Invalid ID supplied
        '401':
          description: Missing or invalid API Key
        '409':
          description: Buyer/supplier is already registered in your environment.
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/participants/{participantId}:
    get:
      tags:
        - Peppol
      summary: Retrieves a buyer/supplier in your environment.
      description: >-
        Retrieves the configuration of a buyer/supplier in your Nymus
        environment. It includes the capability to send to the Peppol Network.
        Also to specify the document types that can be received via the Peppol
        Network for that specific buyer/supplier.
      operationId: getParticipant
      parameters:
        - name: participantId
          in: path
          description: Buyer/supplier to retrieve in your environment.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The configuration of the buyer/supplier in your environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '401':
          description: Missing or invalid API Key
        '404':
          description: Provided participant ID is not found in your environment.
      security:
        - apiKey: []
    put:
      tags:
        - Peppol
      summary: Updates a buyer/supplier in your environment.
      description: >-
        Updates a buyer/supplier in your Nymus environment. The entire
        configuration is overwritten. 
      operationId: updateParticipant
      parameters:
        - name: participantId
          in: path
          description: Buyer/supplier to update in your environment.
          required: true
          schema:
            type: string
      requestBody:
        description: Update a buyer/supplier in your Nymus environment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
        required: true
      responses:
        '200':
          description: Buyer/supplier successfully updated in your environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          description: Invalid ID supplied
        '401':
          description: Missing or invalid API Key
        '404':
          description: Buyer/supplier not found in your environment.
      security:
        - apiKey: []
    delete:
      tags:
        - Peppol
      summary: Deletes a buyer/supplier in your environment.
      description: >-
        Deletes a buyer/supplier in your Nymus environment. This buyer/supplier
        will be deleted on both the sending and receiving side. Also the Peppol
        Network registration is deleted.
      operationId: deleteParticipant
      parameters:
        - name: participantId
          in: path
          description: Buyer/supplier to remove in your environment.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The deleted buyer/supplier in your environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '401':
          description: Missing or invalid API Key
        '404':
          description: Provided participantId is not found in your environment.
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/participants/{participantId}/add-documents:
    post:
      tags:
        - Peppol
      summary: Adds document types to your buyer/supplier.
      description: >-
        Adds to your buyer/supplier additional document types you want to
        receive via the Peppol Network. This will not overwrite your current
        supported documents but will append the new document types. Either
        peppolDocumentTypeIdentifiers or documentType is required.
      operationId: addParticipantDocuments
      parameters:
        - name: participantId
          in: path
          description: ParticipantId to add documents to.
          required: true
          schema:
            type: string
      requestBody:
        description: Document types to add to your buyer/supplier.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PeppolDocumentType'
        required: true
      responses:
        '200':
          description: Document types successfully added to your buyer/supplier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          description: Invalid ID supplier
        '401':
          description: Missing or invalid API Key
        '404':
          description: Buyer/supplier not registered as receiving participant yet.
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/participants/{participantId}/remove-documents:
    post:
      tags:
        - Peppol
      summary: Removes document types from your buyer/supplier.
      description: >-
        Removes from your buyer/supplier the document types you no longer want
        to receive via the Peppol Network. This will not overwrite your current
        supported documents but will remove the specified document types. One of
        either peppolDocumentTypeIdentifiers or documentType is required.
      operationId: removeParticipantDocuments
      parameters:
        - name: participantId
          in: path
          description: Participant Id to add documents to.
          required: true
          schema:
            type: string
      requestBody:
        description: Document types to remove from your buyer/supplier.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PeppolDocumentType'
        required: true
      responses:
        '200':
          description: Document types successfully removed from your buyer/supplier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '400':
          description: Invalid ID supplier
        '401':
          description: Missing or invalid API Key
        '404':
          description: Buyer/supplier not registered as receiving participant yet.
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/lookup/{participantId}:
    get:
      tags:
        - Peppol
      summary: >-
        Retrieves the registration info of a buyer/supplier on the Peppol
        Network.
      description: >-
        Retrieves the receiving document types supported by a Peppol
        buyer/supplier. This can be used to check if your business parties can
        receive certain Peppol document types.
      operationId: lookupPeppolParticipant
      parameters:
        - name: participantId
          in: path
          description: >-
            Participant ID of the buyer/supplier to look up on the Peppol
            Network.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Information about the receiving document types supported by this
            Peppol Participant. The OpenPeppol eDEC Dode List can be found <a
            href='https://docs.peppol.eu/edelivery/codelists/'
            target='_blank'>here</a>
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PeppolDocumentType'
        '401':
          description: Missing or invalid Api Key
        '404':
          description: Buyer/supplier not found on the Peppol Network
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/send:
    post:
      tags:
        - Peppol
      summary: Sends an UBL through the Peppol Network
      description: >-
        Sends an UBL through the Peppol Network. In order to successfully send
        an UBL on the Peppol Network 1) the sending party must be registered on
        your environment 2) the receiving party must be registered on the Peppol
        Network for the document type specified in your UBL 3) the UBL must be a
        valid Peppol supported UBL format. All these checks are performed in the
        background when using this endpoint before transmitting the UBL on the
        Peppol Network. If all the checks pass then an unique document ID will
        be returned.
      operationId: sendPeppolUbl
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                ubl:
                  type: string
                  format: binary
      responses:
        '200':
          description: >-
            All checks passed and an unique document ID is returned to use for
            your future reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeppolTransmissionResponse'
              example:
                documentId: string
                validSender: true
                validReceiver: true
                validUBL: true
                ublErrors: null
        '400':
          description: UBL did not pass validation check
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeppolTransmissionResponse'
              example:
                documentId: null
                validSender: true
                validReceiver: false
                validUBL: true
                ublErrors: null
        '401':
          description: Missing or invalid API Key
        '404':
          description: >-
            Receiver not registered to the Peppol Network or Sending party not
            registered in your environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeppolTransmissionResponse'
              example:
                documentId: null
                validSender: true
                validReceiver: true
                validUBL: false
                ublErrors:
                  - string
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/incoming:
    get:
      tags:
        - Peppol
      summary: Retrieves where your incoming Peppol documents will be forwarded to
      description: >-
        Retrieves the configuration where your incoming Peppol documents will be
        forwarded to.
      operationId: getIncomingConfig
      responses:
        '200':
          description: Incoming flow data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPeppolFlow'
        '401':
          description: Missing or invalid Api key
        '404':
          description: No incoming flow registered
      security:
        - apiKey: []
    post:
      tags:
        - Peppol
      summary: >-
        Registers or updates where your incoming Peppol documents should be
        forwarded to
      description: >-
        Registers or updates the configuration where your incoming Peppol
        documents should be forwarded to. Possible options are 1) a webhook
        endpoint 2) a FTP-server 3) an e-mail address
      operationId: registerIncomingConfig
      requestBody:
        description: >-
          Registers or updates where your incoming Peppol documents should be
          forwarded to
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingPeppolFlow'
        required: true
      responses:
        '200':
          description: Incoming flow registered or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPeppolFlow'
        '401':
          description: Missing or invalid API key
      security:
        - apiKey: []
    delete:
      tags:
        - Peppol
      summary: Deletes where your incoming Peppol documents should be forwarded to
      description: >-
        Deletes the configuration where the incoming Peppol documents should be
        forwarded to.
      operationId: removeIncomingConfig
      responses:
        '200':
          description: Incoming flow removed
        '401':
          description: Missing or invalid Api key
      security:
        - apiKey: []
  /v1/nymusapixpress/peppol/{documentId}/status:
    get:
      tags:
        - Peppol
      summary: Retrieves the status of a sent Peppol document.
      description: Retrieves the delivery information and status of a sent Peppol document.
      operationId: getPeppolDocumentStatus
      parameters:
        - name: documentId
          in: path
          description: Document ID of the document to retrieve the status of.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Peppol document status information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PeppolDocumentStatus'
        '401':
          description: Missing or invalid API Key
        '404':
          description: Document not found
      security:
        - apiKey: []
components:
  schemas:
    PeppolDocumentStatus:
      required:
        - updates
      type: object
      properties:
        updates:
          type: array
          items:
            $ref: '#/components/schemas/PeppolStatusUpdate'
    PeppolStatusUpdate:
      required:
        - time
        - status
      properties:
        time:
          type: string
          example: string
        status:
          type: string
          example: SENT
          enum:
            - SENT
            - NOT_SENT
            - ACKNOWLEDGED
            - IN_PROCESS
            - UNDER_QUERY
            - COND_ACCEPTED
            - REJECTED
            - ACCEPTED
            - PAID
        message:
          type: string
          example: string
    Participant:
      required:
        - participantId
        - participantName
        - countryCode
      type: object
      properties:
        participantId:
          type: string
          example: string
        participantName:
          type: string
          example: string
        countryCode:
          type: string
          example: BE
        isSender:
          type: boolean
          example: true
        isReceiver:
          type: boolean
          example: true
        documentTypes:
          type: array
          items:
            $ref: '#/components/schemas/PeppolDocumentType'
    PeppolDocumentType:
      required:
        - peppolDocumentTypeIdentifier
        - documentType
      type: object
      properties:
        peppolDocumentTypeIdentifier:
          type: string
          example: >-
            urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1
        documentType:
          type: string
          example: BIS_BILLING_INVOICE_V3
          enum:
            - BIS_BILLING_INVOICE_V3
            - BIS_BILLING_CREDIT_NOTE_V3
            - INVOICE_RESPONSE_3_0
            - ORDER_3_0
            - ORDER_AGREEMENT_3_0
            - ORDER_RESPONSE_3_0
            - CATALOGUE_3_0
            - CATALOGUE_RESPONSE_3_0
            - PUNCH_OUT_3_0
            - DESPATCH_ADVICE_3_0
            - MESSAGE_LEVEL_RESPONSE_3_0
            - ORDER_CHANGE
            - ORDER_CANCELLATION
            - ORDER_RESPONSE_ADVANCED
            - UNKNOWN
    PeppolTransmissionResponse:
      type: object
      properties:
        documentId:
          type: string
          example: string
        validSender:
          type: boolean
          example: true
        validReceiver:
          type: boolean
          example: true
        validUBL:
          type: boolean
          example: true
        ublErrors:
          type: array
          items:
            type: string
            example: null
    IncomingPeppolFlow:
      type: object
      properties:
        webhookConfig:
          $ref: '#/components/schemas/WebhookConfiguration'
        emailConfig:
          $ref: '#/components/schemas/EmailConfiguration'
        ftpConfig:
          $ref: '#/components/schemas/FtpConfiguration'
    WebhookConfiguration:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          example: string
    EmailConfiguration:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          example: string
    FtpConfiguration:
      type: object
      required:
        - url
        - location
        - user
        - password
        - ftpType
        - ftpPort
      properties:
        url:
          type: string
          example: string
        location:
          type: string
          example: string
        user:
          type: string
          example: string
        password:
          type: string
          example: string
        ftpType:
          type: string
          example: FTP
          enum:
            - FTP
            - FTPS
            - SFTP
        ftpPort:
          type: number
          example: 21
  requestBodies:
    Participant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Participant'
  securitySchemes:
    apiKey:
      type: apiKey
      name: apiKey
      in: header
