openapi: 3.0.1
info:
  title: PeppolEDGE Platform API
  description: REST API for PeppolEDGE Platform
  version: 1.0.0
tags:
- name: Documents
  description: Document retrieval operations
- name: Integration Executions
  description: Execute integrations with payload processing
- name: Peppol Document Validations
  description: Validate and identify Peppol documents
- name: Peppol Registered Participants
  description: Get information about Peppol registered participants
paths:
  /api/v1/documents/{documentId}:
    get:
      tags:
      - Documents
      summary: Get document details
      description: Retrieves the details and status of a specific document
      operationId: getDocument
      parameters:
      - name: documentId
        in: path
        description: Document identifier
        required: true
        schema:
          $ref: "#/components/schemas/Document"
      responses:
        "200":
          description: Document found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "403":
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "404":
          description: Document not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
  /api/v1/documents/{documentId}/dispatching-status:
    get:
      tags:
      - Documents
      summary: Get document dispatching status
      description: Retrieves the current dispatching status and event history for
        a specific document
      operationId: getDocumentDispatchingStatus
      parameters:
      - name: documentId
        in: path
        description: Document identifier
        required: true
        schema:
          $ref: "#/components/schemas/Document"
      responses:
        "200":
          description: Dispatching status found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentDispatchingStatus"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "403":
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "404":
          description: Document not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
  /api/v1/integrations/{integrationId}/executions:
    post:
      tags:
      - Integration Executions
      summary: Execute integration with payload
      description: |
        Creates a new execution of the specified integration with the provided payload and submits it for document processing through the PeppolEDGE platform.

        ## Integration Flow

        ### Step 1: Submit Document
        Send your Peppol BIS V3 document to this endpoint:
        ```
        POST https://<your-peppoledge-hostname>/api/v1/integrations/<integrationId>/executions
        ```

        **Required Parameters:**
        - integrationId: Your integration identifier (in URL path)
        - file: Your Peppol BIS V3 document file (multipart/form-data)
        - your-bearer-token: Your Peppol EDGE bearer token for authentication (in Authorization header)
        - your-peppoledge-hostname: The hostname of your PeppolEDGE instance (e.g., mycompany.peppoledge.com)

        **Example cURL:**
        ```bash
        curl -X POST \
          "https://<your-peppoledge-hostname>/api/v1/integrations/<integrationId>/executions" \
          -H "Content-Type: multipart/form-data" \
          -H "Authorization: Bearer <your-bearer-token>" \
          -F "file=@/path/to/your/invoice.xml" \
          -i
        ```

        ### Step 2: Process Response (201 Created)
        Upon successful submission, you'll receive a 201 Created response:
        ```json
        {
          "id": "4524567-e89b-12d3-a456-426614174450",
          "documents": ["123e4567-e89b-12d3-a456-426614174000"],
        }
        ```

        **Important:** Save the URL from either:
        - The 'Location' header in the response (if a single payload was processed)
        - The 'locations' array in the JSON response

        ### Step 3: Track Document Dispatching Status
        Use the URL to monitor dispatching status:
        ```
        GET "https://<your-peppoledge-hostname>/api/v1/documents/123e4567-e89b-12d3-a456-426614174000/dispatching-status"
        ```
        More information about document dispatching status can be found in the [Document API](#/Documents/getDocumentDispatchingStatus).

        ## Example Invoice File Format
        ```xml
        <?xml version="1.0" encoding="UTF-8"?>
        <Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
                 xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
                 xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
            <cbc:ID>INV-2024-001</cbc:ID>
            <cbc:IssueDate>2024-09-15</cbc:IssueDate>
            <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
            <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
            <cac:AccountingSupplierParty>
                <cac:Party>
                    <cac:PartyName>
                        <cbc:Name>Supplier Company Ltd</cbc:Name>
                    </cac:PartyName>
                    <cac:PartyIdentification>
                        <cbc:ID schemeID="0088">1234567890</cbc:ID>
                    </cac:PartyIdentification>
                </cac:Party>
            </cac:AccountingSupplierParty>
            <cac:AccountingCustomerParty>
                <cac:Party>
                    <cac:PartyName>
                        <cbc:Name>Customer Corp</cbc:Name>
                    </cac:PartyName>
                </cac:Party>
            </cac:AccountingCustomerParty>
            <!-- Additional invoice content... -->
        </Invoice>
        ```
      operationId: executeIntegration
      parameters:
      - name: integrationId
        in: path
        description: Integration identifier
        required: true
        schema:
          $ref: "#/components/schemas/Integration"
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/FormDataMultiPart"
      responses:
        "201":
          description: Payload received successfully (synchronous validation)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntegrationExecutionResponse"
        "400":
          description: Invalid request or validation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "403":
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "404":
          description: Integration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
  /api/v1/peppol/document-validations:
    post:
      tags:
      - Peppol Document Validations
      summary: Validate Peppol document
      description: |
        Validates a Peppol document and returns document type identification or validation errors.

        **Example:**
        ```bash
        curl -X POST \
          "https://hostname/api/v1/peppol/document-validations" \
          -H "Authorization: Bearer token" \
          -F "file=@invoice.xml"
        ```
      operationId: validateDocument
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              type: object
              properties:
                file:
                  $ref: "#/components/schemas/FormDataBodyPart"
      responses:
        "200":
          description: Document validation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeppolDocumentValidationResponse"
        "400":
          description: Invalid request or malformed document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "403":
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
  /api/v1/peppol/registered-participants/{participantId}:
    get:
      tags:
      - Peppol Registered Participants
      summary: Get registered participant information
      description: |
        Retrieves information about a registered Peppol participant.
      operationId: getRegisteredParticipantInfo
      parameters:
      - name: participantId
        in: path
        description: Peppol participant ID
        required: true
        schema:
          type: string
      - name: environment
        in: query
        description: Peppol environment (TEST or PRODUCTION)
        schema:
          type: string
      responses:
        "200":
          description: Registered participant information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeppolRegisteredParticipantResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "403":
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "404":
          description: Participant not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
components:
  schemas:
    Correlations:
      type: object
      properties:
        empty:
          type: boolean
      description: Event correlations
      example:
        DISPATCH_ID: DISP-12345
        INTEGRATION: 12345abc-6976-4123-8456-789012345678
    Document:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Uid"
        entityType:
          type: string
    DocumentFields:
      type: object
      properties:
        empty:
          type: boolean
      description: Document business fields extracted
      example:
        SUPPLIER_NAME: Supplier Inc.
        TRANSMISSION_DATE: 2025-09-10T12:00:00Z
    ApiErrorResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique error identifier for tracking and support
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        timestamp:
          type: string
          description: ISO-8601 timestamp when the error occurred
          format: date-time
          example: 2025-09-11T10:30:00Z
        type:
          type: string
          description: Error type code for programmatic handling
          example: VALIDATION_FAILED
          enum:
          - BAD_REQUEST
          - VALIDATION_FAILED
          - NOT_FOUND
          - METHOD_NOT_ALLOWED
          - ACCESS_DENIED
          - NOT_IMPLEMENTED
          - INTERNAL_SERVER_ERROR
          - UNAUTHORIZED
          - UNSUPPORTED_MEDIA_TYPE
          - USER_NOT_PROVISIONED
          - BAD_REQUEST
          - VALIDATION_FAILED
          - NOT_FOUND
          - METHOD_NOT_ALLOWED
          - ACCESS_DENIED
          - NOT_IMPLEMENTED
          - INTERNAL_SERVER_ERROR
          - UNAUTHORIZED
          - UNSUPPORTED_MEDIA_TYPE
        title:
          type: string
          description: Human-readable error title
          example: Request validation failed
        status:
          type: integer
          description: HTTP status code
          format: int32
          example: 400
        details:
          type: array
          description: List of detailed validation errors (empty if no field-level
            errors)
          items:
            $ref: "#/components/schemas/FieldError"
      description: API error response with tracking information
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: Field path that failed validation
          example: metadata.sender
        message:
          type: string
          description: Validation error message
          example: sender is required
      description: Field-level validation error details
    Uid:
      type: object
      properties:
        value:
          type: string
          format: uuid
    DocumentDispatchingEvent:
      type: object
      properties:
        id:
          type: string
          description: Event ID
          example: e5f7g8h9-i0j1-k2l3-m4n5-o6p7q8r9s0t1
        type:
          type: string
          description: |
            Type of dispatching event. Possible values:
            - DISPATCH_TASK_AWAITING: Document dispatch task is awaiting execution
            - DISPATCH_TASK_COMPLETED: Document dispatch task completed successfully
            - DISPATCH_TASK_FAILED: Document dispatch task failed and may be retried
            - DISPATCH_TASK_RESCHEDULED: Document dispatch task was rescheduled for later execution
          example: DISPATCH_TASK_COMPLETED
          enum:
          - DISPATCH_TASK_AWAITING
          - DISPATCH_TASK_COMPLETED
          - DISPATCH_TASK_FAILED
          - DISPATCH_TASK_RESCHEDULED
        createdAt:
          type: string
          description: Event creation timestamp
          format: date-time
          example: 2025-09-11T10:00:00Z
        data:
          $ref: "#/components/schemas/EventData"
        correlations:
          $ref: "#/components/schemas/Correlations"
      description: Information about an event that occurred during document dispatching
    DocumentDispatchingStatus:
      type: object
      properties:
        status:
          type: string
          description: Current dispatching status
          example: COMPLETED
          enum:
          - PENDING
          - COMPLETED
          - FAILED
        description:
          type: string
          description: Status description
          example: Document successfully dispatched
        events:
          type: array
          description: List of events that occurred for the dispatching of this document
          items:
            $ref: "#/components/schemas/DocumentDispatchingEvent"
        lastUpdated:
          type: string
          description: Timestamp of last event
          format: date-time
          example: 2024-10-01T12:34:56Z
      description: Document dispatching status information
    EventData:
      type: object
      properties:
        empty:
          type: boolean
      description: Data associated with this event
      example:
        SOURCE: SOURCE-1001
        ERROR_MESSAGE: File not found
    IntegrationExecutionResponse:
      type: object
      properties:
        id:
          type: string
          description: IngestExecution ID
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        documents:
          type: array
          description: List of created documents. Can be used to get the created documents'
            dispatching status
          example: "['3fa85f64-5717-4562-b3fc-2c963f66afa6', '4gb96g75-6828-5673-c4gd-3d074g77bgb7']"
          items:
            type: string
            description: List of created documents. Can be used to get the created
              documents' dispatching status
            example: "['3fa85f64-5717-4562-b3fc-2c963f66afa6', '4gb96g75-6828-5673-c4gd-3d074g77bgb7']"
      description: Integration execution response
    Integration:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Uid"
        entityType:
          type: string
    BodyPart:
      type: object
      properties:
        contentDisposition:
          $ref: "#/components/schemas/ContentDisposition"
        entity:
          type: object
        headers:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              type: string
        mediaType:
          $ref: "#/components/schemas/MediaType"
        messageBodyWorkers:
          $ref: "#/components/schemas/MessageBodyWorkers"
        parent:
          $ref: "#/components/schemas/MultiPart"
        providers:
          $ref: "#/components/schemas/Providers"
        parameterizedHeaders:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ParameterizedHeader"
    ContentDisposition:
      type: object
      properties:
        type:
          type: string
        parameters:
          type: object
          additionalProperties:
            type: string
        fileName:
          type: string
        creationDate:
          type: string
          format: date-time
        modificationDate:
          type: string
          format: date-time
        readDate:
          type: string
          format: date-time
        size:
          type: integer
          format: int64
    FormDataBodyPart:
      type: object
      properties:
        contentDisposition:
          $ref: "#/components/schemas/ContentDisposition"
        entity:
          type: object
        headers:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              type: string
        mediaType:
          $ref: "#/components/schemas/MediaType"
        messageBodyWorkers:
          $ref: "#/components/schemas/MessageBodyWorkers"
        parent:
          $ref: "#/components/schemas/MultiPart"
        providers:
          $ref: "#/components/schemas/Providers"
        formDataContentDisposition:
          $ref: "#/components/schemas/FormDataContentDisposition"
        name:
          type: string
        value:
          type: string
        content:
          type: object
        fileName:
          type: string
        simple:
          type: boolean
        parameterizedHeaders:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ParameterizedHeader"
    FormDataContentDisposition:
      type: object
      properties:
        type:
          type: string
        parameters:
          type: object
          additionalProperties:
            type: string
        fileName:
          type: string
        creationDate:
          type: string
          format: date-time
        modificationDate:
          type: string
          format: date-time
        readDate:
          type: string
          format: date-time
        size:
          type: integer
          format: int64
        name:
          type: string
    FormDataMultiPart:
      type: object
      properties:
        contentDisposition:
          $ref: "#/components/schemas/ContentDisposition"
        entity:
          type: object
        headers:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              type: string
        mediaType:
          $ref: "#/components/schemas/MediaType"
        messageBodyWorkers:
          $ref: "#/components/schemas/MessageBodyWorkers"
        parent:
          $ref: "#/components/schemas/MultiPart"
        providers:
          $ref: "#/components/schemas/Providers"
        bodyParts:
          type: array
          items:
            $ref: "#/components/schemas/BodyPart"
        fields:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/FormDataBodyPart"
        parameterizedHeaders:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ParameterizedHeader"
    MediaType:
      type: object
      properties:
        type:
          type: string
        subtype:
          type: string
        parameters:
          type: object
          additionalProperties:
            type: string
        wildcardType:
          type: boolean
        wildcardSubtype:
          type: boolean
    MessageBodyWorkers:
      type: object
    MultiPart:
      type: object
      properties:
        contentDisposition:
          $ref: "#/components/schemas/ContentDisposition"
        entity:
          type: object
        headers:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              type: string
        mediaType:
          $ref: "#/components/schemas/MediaType"
        messageBodyWorkers:
          $ref: "#/components/schemas/MessageBodyWorkers"
        parent:
          $ref: "#/components/schemas/MultiPart"
        providers:
          $ref: "#/components/schemas/Providers"
        bodyParts:
          type: array
          items:
            $ref: "#/components/schemas/BodyPart"
        parameterizedHeaders:
          type: object
          properties:
            empty:
              type: boolean
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ParameterizedHeader"
    MultivaluedMapStringParameterizedHeader:
      type: object
      properties:
        empty:
          type: boolean
      additionalProperties:
        type: array
        items:
          $ref: "#/components/schemas/ParameterizedHeader"
    MultivaluedMapStringString:
      type: object
      properties:
        empty:
          type: boolean
      additionalProperties:
        type: array
        items:
          type: string
    ParameterizedHeader:
      type: object
      properties:
        value:
          type: string
        parameters:
          type: object
          additionalProperties:
            type: string
    Providers:
      type: object
    ExecutionError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_DOCUMENT_TYPE
        field:
          type: string
          description: Field name where the error occurred
          example: document
        severity:
          type: string
          description: Error severity level
          example: ERROR
        location:
          type: string
          description: Location where the error occurred
          example: documentElement
        message:
          type: string
          description: Human-readable error message
          example: Unable to classify UBL document
      description: Execution error details
    PeppolDocumentType:
      type: object
      properties:
        type:
          type: string
          description: Document type (human-readable format)
          example: Peppol BIS Billing UBL Invoice V3
        category:
          type: string
          description: Document category (human-readable format)
          example: Invoice
        profileId:
          type: string
          description: Document Profile identifier (URN)
          example: urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice
        customizationId:
          type: string
          description: Document Customization identifier (URN)
          example: urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0
        version:
          type: string
          description: Document Version
          example: "2.1"
      description: Peppol document type details
    PeppolDocumentValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
          description: Indicates if the document is valid (no errors)
          example: true
        documentType:
          $ref: "#/components/schemas/PeppolDocumentType"
        validationErrors:
          type: array
          description: Validation errors
          items:
            $ref: "#/components/schemas/ExecutionError"
        validationWarnings:
          type: array
          description: Validation warnings
          items:
            $ref: "#/components/schemas/ExecutionError"
      description: Peppol document validation response
    PeppolRegisteredParticipantResponse:
      type: object
      properties:
        participantId:
          type: string
          description: Participant ID
          example: 9908:123456789
        supportedDocumentTypes:
          type: array
          description: Participant Document Types
          items:
            $ref: "#/components/schemas/PeppolDocumentType"
      description: Peppol registered participant response
