openapi: 3.0.0
info:
  description: REST API to transport signed, XER encoded InfoExchange messages between EETS
    provider and FCA
  version: 0.0.1
  title: EETS Provider API
  contact:
    name: Swiss Federal Customs Administration
    url: https://www.ezv.admin.ch
    email: eets-admin@ezv.admin.ch
tags:
  - name: receive from FCA
    description: Receive messages from FCA
  - name: send to FCA
    description: Send messages to FCA
paths:
  "/api/messages/fromFCA/{countryCode}/{providerIdentifier}":
    get:
      tags:
        - receive from FCA
      summary: Get a list of unconfirmed outgoing messages from FCA
      description: >-
        Returns a list of all unconfirmed outgoing messages from FCA for a
        specific EETS provider.
 
        * A message resists in the list of unconfirmed outgoing messages as long as the message is confirmed (s. ConfirmReceipt)
      operationId: ListMessages
      parameters:
        - name: countryCode
          in: path
          description: The country code of the EETS provider (ISO 3166-1, 3 digit numeric
            code)
          required: true
          schema:
            type: string
        - name: providerIdentifier
          in: path
          description: The identifier of the EETS provider
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: Success, the requested list of unconfirmed messages is available in
            the body
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MessageHeaderDto"
        "401":
          description: The requester could not be authenticated
        "403":
          description: The requester is not authorized to read the list of outgoing messages
        "404":
          description: The provider specified does not exist
      deprecated: false
  "/api/messages/fromFCA/{countryCode}/{providerIdentifier}/{messageId}":
    get:
      tags:
        - receive from FCA
      summary: Receive one unconfirmed outgoing message from FCA
      description: >-
        Reads a specific unconfirmed outgoing message.
 
 
        * The message remains in the list of unconfirmed outgoing messages from FCA.
 
        * One message can be read multiple times.
 
        * **A message will only removed from the list when the reception is confirmed by ConfirmReceipt.**
      operationId: GetMessage
      parameters:
        - name: countryCode
          in: path
          description: The country code of the EETS provider (ISO 3166-1, 3 digit numeric
            code)
          required: true
          schema:
            type: string
        - name: messageId
          in: path
          description: The unique identifier of the message
          required: true
          schema:
            type: string
        - name: providerIdentifier
          in: path
          description: The identifier of the EETS provider
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: Success, the message requested is available in the body
          content:
            application/xml:
              schema:
                type: string
        "401":
          description: The requester could not be authenticated
        "403":
          description: The requester is not authorized to read this outgoing message
        "404":
          description: The message requested does not exist
      deprecated: false
    delete:
      tags:
        - receive from FCA
      summary: Confirm the reception of an unconfirmed outgoing message from FCA
      description: >-
        Confirms the receipt of a specific outgoing message from FCA.
 
 
        * With this confirmation, the message is removed from the list of unconfirmed outgoing messages from FCA.
 
 
        * **Only the reception of the message is confirmed by the EETS provider.** The acceptance of the message has to be notified by a message of type AckADU.
      operationId: ConfirmReceipt
      parameters:
        - name: countryCode
          in: path
          description: The country code of the EETS provider (ISO 3166-1, 3 digit numeric
            code)
          required: true
          schema:
            type: string
        - name: messageId
          in: path
          description: The unique identifier of the message
          required: true
          schema:
            type: string
        - name: providerIdentifier
          in: path
          description: The identifier of the EETS provider
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: The message is successfully confirmed and removed from the list of
            unconfirmed outgoing messages from FCA
        "401":
          description: The requester could not be authenticated
        "403":
          description: The requester is not authorized to confirm this message
        "404":
          description: The message requested does not exist
      deprecated: false
  "/api/messages/toFCA/{countryCode}/{providerIdentifier}/{messageId}":
    put:
      tags:
        - send to FCA
      summary: Transports one message to FCA
      description: >-
        Transports one message to the FCA.
 
        Transport is successful if the message is
 
        * syntactically correct
 
        * contains a valid signature.
 
        * **A successful transport of the message does not signify that the message is acknowledged.** The acceptance of the message will be notified by AckADU from FCA.
      operationId: SendMessage
      parameters:
        - name: countryCode
          in: path
          description: The country code of the EETS provider (ISO 3166-1, 3 digit numeric
            code)
          required: true
          schema:
            type: string
        - name: messageId
          in: path
          description: The unique identifier of the message
          required: true
          schema:
            type: string
        - name: providerIdentifier
          in: path
          description: The identifier of the EETS provider
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/xml:
            schema:
              type: string
        description: The signed InfoExchange message (XML)
        required: true
      responses:
        "200":
          description: The message is syntactically correct and successfully transmitted to
            FCA
        "400":
          description: The message is syntactically not correct
        "401":
          description: The requester could not be authenticated
        "403":
          description: The requester is not authorized to send this message
        "413":
          description: The message exceeded the maximal size of an InfoExchange
        "415":
          description: The media type of the InfoExchange must be application/xml
      deprecated: false
servers:
  - url: https://linktoproductionserver
    description: Production server
  - url: http://linktoacceptanceserver
    description: Acceptance Server
components:
  schemas:
    MessageHeaderDto:
      type: object
      required:
        - aduType
        - messageId
        - published
      properties:
        messageId:
          type: string
          example: c4d4c852-c134-41c2-96b2-382ebcdac5f9
          description: the identifier of an outgoing message
        aduType:
          type: string
          description: the message type of outgoing message
          enum:
            - ACK_ADU
            - REQUEST_ADU
            - BILLING_DETAILS_ADU
            - PAYMENT_CLAIM_ADU
        published:
          type: string
          example: 2018-10-11T14:24:34.384Z
          description: the date when the message was published
      title: MessageHeaderDto
      description: The GetMessages Response Body