openapi: 3.0.3
info:
  title: Core Legacy API
  version: 2.0.0
tags:
  - name: Webhook Configuration
    x-displayName: Webhook Configuration
    description: Defining webhooks for processes and status updates occuring in the portal. Information on the data submitted as part of the webhook call is defined in the POST webhookconfig under 'Callback payload samples'
  - name: Status Update
    x-displayName: Status Update
    description: Update the Status of a task
x-tagGroups:
  - name: Process interaction
    tags:
      - Webhook Configuration
      - Status Update
servers:
  - url: https://api-dev.gemeindeconnect.ch/legacy
    description: Test and Dev Environment
  - url: https://api.gemeindeconnect.ch/legacy
    description: Production Environment
security:
  - subscriptionkey: []
paths:
  /statusUpdate:
    post:
      tags:
        - Status Update
      summary: Update the status of a task in the F4D Platform
      description: >-
        Update an existing task in the platform with a new status. For example when a task was in 'new' and now has to move to 'inprogress'. The status refund can also be used for canceling or aborted tasks, even if there is no refund or is not paid via the payment provier.
      operationId: poststatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createstatusupdate'
            examples:
              Status done:
                value:
                  uniqueId: 123
                  newStatus: done
              Status inprogress:
                value:
                  uniqueId: 123
                  newStatus: inprogress
              Status refund:
                value:
                  uniqueId: 123
                  newStatus: refund
                  refundAmount: '20.10'
        required: true
      responses:
        '200':
          description: successfully created the status update
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A server side exception has occured, please contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhookconfig:
    get:
      tags:
        - Webhook Configuration
      summary: Retrieve all or a specific webhook configurations
      description: This action retrieves a list of configured webhooks
      operationId: getwebhook
      parameters:
        - name: whid
          in: query
          description: >-
            pass an optional webhook configuration id to retrieve a selected configuration
          required: false
          style: form
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: successfully found the webhook configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookItemResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A server side exception has occured, please contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Webhook Configuration
      summary: Create a new webhook configuration
      description: >-
        This endpoint allows you to create a new webhook. Webhooks allow you to specify a url to receive notifications for event types.
      operationId: createwebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookItem'
        required: true
      responses:
        '200':
          description: webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getwhResponse'
        '400':
          description: invalid input, object invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A server side exception has occured, please contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      callbacks:
        New Hauptwohnsitzbescheinigung:
          '{$request.body#/callbackUrl}':
            post:
              summary: New - Hauptwohnsitzbescheinigung
              description: Content of the webhook call for a new Hauptwohnsitzbescheinigung
              operationId: callbackNew-Hauptwohnsitzbeschreinigung
              requestBody:
                $ref: '#/components/requestBodies/hauptwohnsitzbescheinigung'
              responses:
                '200':
                  description: Your servers response if the webhook call was successfully received.
                '400':
                  description: Bad request
                '401':
                  description: Unauthorized
                '500':
                  description: Your servers response if the webhook call failed.
        New Leumundszeugnis:
          '{$request.body#/callbackUrl}':
            post:
              summary: New - Leumundszeugnis
              description: Content of the webhook call for a new Leumundszeugnis
              operationId: callbackNew-Leumundszeugnis
              requestBody:
                $ref: '#/components/requestBodies/leumundszeugnis'
              responses:
                '200':
                  description: Your servers response if the webhook call was successfully received.
                '400':
                  description: Bad request
                '401':
                  description: Unauthorized
                '500':
                  description: Your servers response if the webhook call failed.
        New Heimatausweis:
          '{$request.body#/callbackUrl}':
            post:
              summary: New - Heimatausweis
              description: Content of the webhook call for a new Heimatausweis
              operationId: callbackNew-Heimatausweis
              requestBody:
                $ref: '#/components/requestBodies/heimatausweis'
              responses:
                '200':
                  description: Your servers response if the webhook call was successfully received.
                '400':
                  description: Bad request
                '401':
                  description: Unauthorized
                '500':
                  description: Your servers response if the webhook call failed.
        New Addressorder:
          '{$request.body#/callbackUrl}':
            post:
              summary: New - Addressorder
              description: Content of the webhook call for a new Addressorder
              operationId: callbackNew-Addressorder
              requestBody:
                $ref: '#/components/requestBodies/addressorder'
              responses:
                '200':
                  description: Your servers response if the webhook call was successfully received.
                '400':
                  description: Bad request
                '401':
                  description: Unauthorized
                '500':
                  description: Your servers response if the webhook call failed.
        New electioncert:
          '{$request.body#/callbackUrl}':
            post:
              summary: New - Wahlfähigkeitszeugnis
              description: Content of the webhook call for a new Wahlfähigkeitszeugnis
              operationId: callbackNew-electioncert
              requestBody:
                $ref: '#/components/requestBodies/electioncert'
              responses:
                '200':
                  description: Your servers response if the webhook call was successfully received.
                '400':
                  description: Bad request
                '401':
                  description: Unauthorized
                '500':
                  description: Your servers response if the webhook call failed.
    delete:
      tags:
        - Webhook Configuration
      summary: Delete a webhook configuration
      description: This action deletes a specific webhook
      operationId: deletewebhook
      parameters:
        - name: whid
          in: query
          description: pass a webhook configuration id to delete the configuration
          required: true
          style: form
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: webhook deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A server side exception has occured, please contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
        - Webhook Configuration
      summary: Update a new webhook configuration
      description: This endpoint allows you to update a webhook.
      operationId: patchwebhook
      parameters:
        - name: whid
          in: query
          description: pass a webhook configuration id to update a selected configuration
          required: true
          style: form
          explode: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookItem'
        required: true
      responses:
        '200':
          description: alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookItemResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A server side exception has occured, please contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    subscriptionkey:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Retrieve your subscription key from the APIM developer portal or contact Support.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token (JWT) used to authorize API calls.
  requestBodies:
    addressorder:
      description: addressorder
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/systemfields'
              - $ref: '#/components/schemas/personaldata'
              - $ref: '#/components/schemas/deliveryaddress'
              - $ref: '#/components/schemas/paymentdata'
              - $ref: '#/components/schemas/userattributes'
              - $ref: '#/components/schemas/addressorder'
    electioncert:
      description: electioncert
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/systemfields'
              - $ref: '#/components/schemas/personaldata'
              - $ref: '#/components/schemas/deliveryaddress'
              - $ref: '#/components/schemas/paymentdata'
              - $ref: '#/components/schemas/userattributes'
              - $ref: '#/components/schemas/electioncert'
    hauptwohnsitzbescheinigung:
      description: prcertificate
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/systemfields'
              - $ref: '#/components/schemas/personaldata'
              - $ref: '#/components/schemas/deliveryaddress'
              - $ref: '#/components/schemas/paymentdata'
              - $ref: '#/components/schemas/userattributes'
              - $ref: '#/components/schemas/hauptwohnsitzbescheinigung'
    heimatausweis:
      description: heimatausweis
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/systemfields'
              - $ref: '#/components/schemas/personaldata'
              - $ref: '#/components/schemas/deliveryaddress'
              - $ref: '#/components/schemas/paymentdata'
              - $ref: '#/components/schemas/userattributes'
              - $ref: '#/components/schemas/heimatausweis'
    leumundszeugnis:
      description: leumundszeugnis
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/systemfields'
              - $ref: '#/components/schemas/personaldata'
              - $ref: '#/components/schemas/deliveryaddress'
              - $ref: '#/components/schemas/paymentdata'
              - $ref: '#/components/schemas/userattributes'
              - $ref: '#/components/schemas/leumundszeugnis'
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        details:
          type: array
          items:
            type: string
    WebhookItem:
      required:
        - applicationId
        - callbackUrl
        - processes
        - httprequestbody
        - httprequestheaders
        - httprequestparameter
        - municipalityId
        - whcomment
        - whname
      type: object
      properties:
        whname:
          type: string
          example: Your Webhook Name
        whcomment:
          type: string
          example: short comment on the webhook
        applicationId:
          type: string
          example: d0db4b13-20d4-42c3-8268-37db22b36f98
        municipalityId:
          type: string
          example: d0db4b13-20d4-42c3-8268-37db22b36f98
          description: The municipalityId for which the event is triggered.
        callbackUrl:
          type: string
          format: uri
          example: https://yourdomain.com/send/callback/here
        processes:
          type: array
          items:
            type: string
          description: One or more processId for which the webhook is called for. The processId retrieved from the processes api call.
        httprequestheaders:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
        httprequestparameter:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
        httprequestbody:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
    WebhookItemResponse:
      type: object
      properties:
        whid:
          type: string
          example: A123123
        whname:
          type: string
          example: Your Alert Name
        whcomment:
          type: string
          example: short comment on the alert
        applicationId:
          type: string
          example: d0db4b13-20d4-42c3-8268-37db22b36f98
        municipalityid:
          type: string
          example: d0db4b13-20d4-42c3-8268-37db22b36f98
          description: The municipalityId for which the event is triggered.
        callbackUrl:
          type: string
          format: uri
          example: https://yourdomain.com/send/callback/here
        process:
          type: string
          example: process
        httprequestheaders:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
        httprequestparameter:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
        httprequestbody:
          type: array
          items:
            $ref: '#/components/schemas/WebhookItem_httprequestheaders'
    WebhookItem_httprequestheaders:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    addressorder:
      type: object
      properties:
        comments:
          type: string
          description: Comment of the user provided on the form
        proofOfInterest:
          type: string
          description: A document in Base64 containing the file updlaoded by the user as proof of interest.
        personAddressOrder:
          type: object
          description: Information about the person or company which submitted the address order request
          properties:
            company:
              type: string
            salutation:
              type: string
            lastname:
              type: string
            firstname:
              type: string
            dob:
              type: string
            streetname:
              type: string
            streetnumber:
              type: string
            postcode:
              type: string
            place:
              type: string
            country:
              type: string
            phone:
              type: string
            email:
              type: string
    createstatusupdate:
      type: object
      properties:
        uniqueId:
          type: integer
          example: 1234
          description: The unique taskId provided by an initial webhook call. For example when receiving a status 'new'. Note, both integer and string are accepted.
        newStatus:
          type: string
          description: The new status of the task in the system.
          enum: [new, inprogress, done, refund]
        refundAmount:
          type: string
          description: The amount to be refunded. This values is only required for the status 'refund'. The amount needs to be equal or lower than the amount the customer paid. The refund status can also be used for services not paid via payment provider. In that case, the refundAmount should be set to 0.
    deliveryaddress:
      type: object
      properties:
        deliveryaddress:
          type: object
          properties:
            differentDeliveryaddress:
              type: boolean
              example: true
              description: Delivery Address is different from the address of the application. Is an indicator and will be set to true if a different address is required and false if it is the same address.
            company:
              type: string
              description: Name of the company
            lastname:
              type: string
            firstname:
              type: string
            street:
              type: string
            streetnumber:
              type: string
            postcode:
              type: string
            place:
              type: string
            country:
              type: string
    electioncert:
      type: object
      properties:
        comments:
          type: string
          description: Comment of the user provided on the form
    getwhResponse:
      type: object
      properties:
        'whid:':
          type: string
          example: 20
    hauptwohnsitzbescheinigung:
      type: object
      properties:
        comments:
          type: string
          description: Comment of the user provided on the form
        documentLanguage:
          type: string
          description: User selected language of the requested document.
          enum: [de, multilingual]
        residencesince:
          type: string
          description: from when a user is living at the address
        residenceto:
          type: string
          description: until when the user resided at the address
    heimatausweis:
      type: object
      properties:
        comments:
          type: string
          description: Comment of the user provided on the form
        secondaryResidence:
          type: object
          description: Information to the secondary residence
          properties:
            validFrom:
              type: string
              description: from what date the secondary residence is valid.
            street:
              type: string
              description: Street name of the secondary residence
            streetnumber:
              type: string
              description: Street number of the secondary residence
            postcode:
              type: string
              description: postalcode (PLZ) of the secondary residence
            place:
              type: string
              description: place/city for the secondary residence
            country:
              type: string
              description: country of the secondary residence
            duration:
              type: string
              description: Estimated duration at the secondary residence. The response is values 0-5. 0 indicating an unlimited timeframe. 1-5 indicates years.
            reason:
              type: string
              description: reason of the stay at the secondary residence
    leumundszeugnis:
      type: object
      properties:
        comments:
          type: string
          description: Comment of the user provided on the form
    paymentdata:
      type: object
      properties:
        deliveryandpayment:
          type: object
          properties:
            deliverymethod:
              type: string
              description: selected delivery method.
              enum: [post, email, counter, mydocuments]
              example: post
            payment:
              type: string
              description: selected payment method
              enum: [paymentprovider, counter, nofee, invoice]
    personaldata:
      type: object
      properties:
        personaldata:
          type: object
          properties:
            company:
              type: string
              example: Beispiel AG
              description: Optional company name. If the company name is not in used in a specific process, then the field will not be returned in the JSON.
            ahvNumber:
              type: string
              example: '123'
              description: 13 digit AHV number to identify the user.
            salutation:
              type: string
              example: Herr
              description: Salutation as selected on the form. Derzeit Herr and Frau are supported.
            lastname:
              type: string
              example: Mustermann
              description: The lastname of the person
            firstname:
              type: string
              example: Max
              description: The firstname of the person
            dob:
              type: string
              example: '2021-12-31'
              description: the Date of Birth of the person in format YYYY-MM-DD
            street:
              type: string
              example: Musterstrasse
              description: streetname
            streetnumber:
              type: string
              example: 10a
              description: streetnumber
            postcode:
              type: string
              example: '5000'
              description: the PLZ.
            place:
              type: string
              example: Aarau
              description: Name of the place
            country:
              type: string
              example: Schweiz
              description: Country
            phone:
              type: string
              example: +41 799 999 999
              description: Phone number. Is a freetext field on the webform and hence is not formatted.
            email:
              type: string
              example: thomas.mustermann@gmail.com
              description: email address
    systemfields:
      type: object
      properties:
        uniqueId:
          type: integer
          example: 123456
          description: A unique reference of the task in the platform. Is required when a status is sent back to the platform.
        datereceived:
          type: string
          example: '2022-12-31 23:59:59'
          description: The date and time the task has been received from the portal
        cantonreference:
          type: string
          example: N123456
          description: If the user was logged into the portal, the users login Id.
        status:
          type: string
          example: new
          description: The current status of the task. First submission is always new.
        amount:
          type: number
          example: 20.0
          description: The amount the user has to pay for the service. If 0 then the service has no cost.
        paymentStatus:
          type: string
          example: paid
          description: The payment status from payment for a service.
        paymentRefId:
          type: string
          example: '1234567'
          description: The payment transaction reference Id as used by the system.
        paymentRefundId:
          type: string
          example: 1234456
          description: Contains the payment reference if a refund was executed on this transaction.
        paymentRefundStatus:
          type: string
          example: success
          description: Contains the information if a refund has been successful or not.
        municipalityName:
          type: string
          example: Aarau
          description: The municipality name selected by the user in the form for which municipality the service is.
        municipalityId:
          type: number
          example: 1
          description: The unique system id for the municipality. This is the BFS.
        processName:
          type: string
          enum:
            - Hauptwohnsitzbescheinigung bestellen
            - Adressauskunft bestellen
            - Heimatausweis bestellen / Nebenwohnsitz melden
            - Wahlfähigkeitszeugnis bestellen
            - Leumundszeugnis bestellen
          example: ''
          description: The name of the process
        processId:
          type: string
          example: ''
          enum: ['739', '7312', '732', '7310', '733']
          description: The unique Id of the process
    userattributes:
      type: object
      properties:
        userattributes:
          type: object
          properties:
            verified:
              type: string
              description: Value “low” means the attributes are self-declared by the user. Value “substantial” or “high” means the values are verified by Swiss ID.
              enum: [low, substantial, high]
              example: low
            givenName:
              type: string
              description: Given Name of the logged in user. Can contain multiple Names and will include Middle Names
              example: Thomas
            familyName:
              type: string
              description: Family Name of the logged in user.
              example: Muster
            dob:
              type: string
              description: Date of Birth of the logged in user. Format “YYYY-MM-DD”
              example: '2000-12-31'
            gender:
              type: string
              description: Given Name of the logged in user.
              example: Thomas
            phone:
              type: string
              description: Phone number of the logged in person
              enum: [male, female]
              example: +41413709999
            streetname:
              type: string
              description: Street name and number of the logged in Person
              example: Musterstrasse 1
            postcode:
              type: string
              description: PLZ of the logged in person
              example: '5000'
            place:
              type: string
              description: Place of the logged in person
              example: Aarau
            country:
              type: string
              description: Country of the logged in person
              example: Switzerland
