Powered by Redocly

Smart Service Portal API Documentation (2.0.0)

API Support: info@f4d.ch

Introduction

This API is to integrate 3rd party applications with the Kanton Aargau SmartServer Portal. The API provides vendors of municipality software the ability to receive tasks of sbmitted forms and update the portal and citizen with the status of the processed tasks

Process and Scenario

The following processes from the SmartService Portal are currently supported with the API.

  1. Hauptwohnsitzbescheinigung bestellen
  2. Leumundszeugnis bestellen
  3. Heimatausweis bestellen
  4. Adressauskunft bestellen
  5. Wahlfähigkeisausweis bestellen

A sample process diagram of how the workflow for the 5 supported processes works can be found here: here.

In the process diagram, the arrows going to the blue area are the webhook calls made based on the definition in the webhook api.
The arrows that going up from the blue area to the platform are status updates made Status Update API.

There are two interactions with the process.

  1. The F4D Platform sends a message via a configured webhook on to the registered application to inform the application about an updated status (and data) originating either from the portal in case of a new case or from the payment gateway in case of a failed refund.
  2. The registered application updates existing tasks in the F4D Platform with the new status of the task. The status will then be sent back to the portal and the user. For example when a new task is changed to 'in progress'.

Prerequisite - Subscription key

All new developers must signup for a developer account to gain access to the subscription key. To get your subscription key, follow the steps below:

  1. Sign up here. If you don't yet have an account, click on 'Register now' to create a new account
  2. Upon successful login, navigate to the Products page by choosing Products on the menu.
  3. In the Products page, Select "App Integration Developers".
  4. Enter your desired product subscription name and Subscribe.
  5. You will be directed automatically to your Profile page where a list of your subscriptions are displayed. You can choose to show your keys, or regenerate new subscription keys from here.

Testing

The initial step to kick off a process is the citizens (Smart Service Portal user) to submit a form. To simulate this process, we provide a set of similar forms as the citizens sees. Those are not part of the Smart Service Portal and only link to the Development Environment for vendors. The links to the forms can be found below:

  1. Hauptwohnsitzbescheinigung bestellen
  2. Leumundszeugnis bestellen
  3. Heimatausweis bestellen
  4. Adressauskunft bestellen
  5. Wahlfähigkeisausweis bestellen

After a form has been submitted, the registered webhooks are triggered and subsequently the status can be updated.

Configuring a municipality and process to use the registered application

The API can be used to register the application for use by the municipality process. However, an administrator of the municipality needs to configure to use a registered application. To request for a test municipality, please email support.

Vendor Registration

Registering your company as a vendor in the system

Retrieve the information stored in the vendor registration

Retrieves the vendor registration details. If no providerId is passed in the parameters, then all the vendor registrations are retrieved.

Securitysubscriptionkey and bearerAuth
Request
query Parameters
providerId
string

The unique Vendor Id to be retrieved.

Responses
200

successfully executed the function and returns the vendor registration details if found.

400

Bad request

401

Unauthorized

500

A server side exception has occured, please contact support

get/vendorregistration
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create a new vendor
Used to create a new vendor registration. Only one vendor needs to be registered per Software vendor. This provides contact details for the application registered for this vendor.


Securitysubscriptionkey 
Request 
Request Body schema: application/json
providerName
string
Name of the software provider. This will be visible to the municipality to select the vendor they choose.


 
plz
string
Postcode of the vendors address


 
place
string
Name of the place of the vendors address


 
address1
string
Addressline 1


 
address2
string
Addressline 2


 
address3
string
Addressline 3


 
phone
string
Phone number of the software vendor


 
email
string
Email address of the vendor to contact for support of the application integration


 
website
string
Website of the vendor for additional information on the integrated product, service and support.


 
Responses 
200
Success - vendor data


400
invalid input, object invalid


401
Unauthorized


500
A server side exception has occured, please contact support


post/vendorregistration
Request samples 
application/json
{
  • "providerName": "string",
  • "plz": "5000",
  • "place": "string",
  • "address1": "string",
  • "address2": "string",
  • "address3": "string",
  • "phone": "string",
  • "email": "string",
  • "website": "string"
}
Response samples 
application/json
{
  • "providerId": "string",
  • "providerName": "string",
  • "plz": "5000",
  • "place": "string",
  • "address1": "string",
  • "address2": "string",
  • "address3": "string",
  • "phone": "string",
  • "email": "string",
  • "website": "string",
  • "apikey": "string"
}
Update an existing vendor registration
Update the details of an existing vendor registration. All fields need to be updated. Missing fields will be overwritten if an empty value.


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
providerId
required
string
The unique Vendor Id to be updated.


 
Request Body schema: application/json
providerName
string
Name of the software provider. This will be visible to the municipality to select the vendor they choose.


 
plz
string
Postcode of the vendors address


 
place
string
Name of the place of the vendors address


 
address1
string
Addressline 1


 
address2
string
Addressline 2


 
address3
string
Addressline 3


 
phone
string
Phone number of the software vendor


 
email
string
Email address of the vendor to contact for support of the application integration


 
website
string
Website of the vendor for additional information on the integrated product, service and support.


 
Responses 
200
app registration created


400
invalid input, object invalid


401
Unauthorized


500
A server side exception has occured, please contact support


patch/vendorregistration
Request samples 
application/json
{
  • "providerName": "string",
  • "plz": "5000",
  • "place": "string",
  • "address1": "string",
  • "address2": "string",
  • "address3": "string",
  • "phone": "string",
  • "email": "string",
  • "website": "string"
}
Response samples 
application/json
{
  • "providerId": "string",
  • "providerName": "string",
  • "plz": "5000",
  • "place": "string",
  • "address1": "string",
  • "address2": "string",
  • "address3": "string",
  • "phone": "string",
  • "email": "string",
  • "website": "string"
}
Regenarates a new API key
Regenerates a new API key. Will overwrite the api key generated initially by the POST vendorregistration api call.


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
providerId
string
The unique Vendor Id to be retrieved.


 
Responses 
200
successfully found the vendor registration


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


get/newapikey
Request samples 
Response samples 
application/json
{
  • "apikey": "string"
}
App Registration
Register an application for the Fit4Digital Platform


Retrieve application details
This action retrieves a list of configured applications for a subscription


Securitysubscriptionkey and bearerAuth 
Responses 
200
successfully found the application configuration


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


get/appregistration
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create or update an application configuration
Create or update an application configuration. If the parameter is empty, a new application configuration is created. Otherwise an existing application configuration is updated.


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
appId
string
The unique app Id to be updated. If left empty a new app registration is created.


 
Request Body schema: application/json
appName
string
 
appDescription
string
 
Array of objects (listofprocesses) 
 
Responses 
200
app registration created


400
invalid input, object invalid


401
Unauthorized


500
A server side exception has occured, please contact support


patch/appregistration
Request samples 
application/json
{
  • "appName": "Your ApplicationName",
  • "appDescription": "short description of the application",
  • "processes": [
    ]
}
Response samples 
application/json
{
  • "appid": "f8bc07f6-3e6c-4d92-97a2-82c9f2ece44b"
}
Delete an application
This action deletes an application


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
appId
required
string
The unique app Id to be be deleted.


 
Responses 
200
successfully deleted the application configuration


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


delete/appregistration
Request samples 
Supporting Function
Supporting functions


Retrieve a list of municipalities with their unique id
Retrieves a list of municipalities with their unique Id.


Securitysubscriptionkey and bearerAuth 
Responses 
200
successfull retrieved a list of municipalities


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


get/municipalities
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieve a list of processes which support 3rd party integrations
Retrieves a list of processes that support third party integrations.


Securitysubscriptionkey and bearerAuth 
Responses 
200
successfull retrieved a list of processes


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


get/processes
Request samples 
Response samples 
application/json
[
  • {
    }
]
Webhook Configuration
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'


Retrieve all or a specific webhook configurations
This action retrieves a list of configured webhooks


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
whid
string
pass an optional webhook configuration id to retrieve a selected configuration


 
Responses 
200
successfully found the webhook configuration


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


get/webhookconfig
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create a new webhook configuration
This endpoint allows you to create a new webhook. Webhooks allow you to specify a url to receive notifications for event types.


Securitysubscriptionkey and bearerAuth 
Request 
Request Body schema: application/json
whname
required
string
 
whcomment
required
string
 
applicationId
required
string
 
municipalityId
required
string
The municipalityId for which the event is triggered.


 
callbackUrl
required
string <uri> 
 
processes
required
Array of strings
One or more processId for which the webhook is called for. The processId retrieved from the processes api call.


 
required
Array of objects (WebhookItem_httprequestheaders) 
 
required
Array of objects (WebhookItem_httprequestheaders) 
 
required
Array of objects (WebhookItem_httprequestheaders) 
 
Responses 
200
webhook created


400
invalid input, object invalid


401
Unauthorized


500
A server side exception has occured, please contact support


Callbacks 
postNew - Hauptwohnsitzbescheinigung
postNew - Leumundszeugnis
postNew - Heimatausweis
postNew - Addressorder
postNew - Wahlfähigkeitszeugnis
post/webhookconfig
Request samples 
application/json
{
  • "whname": "Your Webhook Name",
  • "whcomment": "short comment on the webhook",
  • "applicationId": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "municipalityId": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "callbackUrl": "https://yourdomain.com/send/callback/here",
  • "processes": [
    ],
  • "httprequestheaders": [
    ],
  • "httprequestparameter": [
    ],
  • "httprequestbody": [
    ]
}
Response samples 
application/json
{
  • "whid:": 20
}
Callback payload samples 
application/json
{
  • "uniqueId": 123456,
  • "datereceived": "2022-12-31 23:59:59",
  • "cantonreference": "N123456",
  • "status": "new",
  • "amount": 20,
  • "paymentStatus": "paid",
  • "paymentRefId": "1234567",
  • "paymentRefundId": 1234456,
  • "paymentRefundStatus": "success",
  • "municipalityName": "Aarau",
  • "municipalityId": 1,
  • "processName": "",
  • "processId": "",
  • "personaldata": {
    },
  • "deliveryaddress": {
    },
  • "deliveryandpayment": {
    },
  • "comments": "string",
  • "documentLanguage": "de",
  • "residencesince": "string",
  • "residenceto": "string"
}
Delete a webhook configuration
This action deletes a specific webhook


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
whid
required
string
pass a webhook configuration id to delete the configuration


 
Responses 
200
webhook deleted


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


delete/webhookconfig
Request samples 
Update a new webhook configuration
This endpoint allows you to update a webhook.


Securitysubscriptionkey and bearerAuth 
Request 
query Parameters
whid
required
string
pass a webhook configuration id to update a selected configuration


 
Request Body schema: application/json
whname
required
string
 
whcomment
required
string
 
applicationId
required
string
 
municipalityId
required
string
The municipalityId for which the event is triggered.


 
callbackUrl
required
string <uri> 
 
processes
required
Array of strings
One or more processId for which the webhook is called for. The processId retrieved from the processes api call.


 
required
Array of objects (WebhookItem_httprequestheaders) 
 
required
Array of objects (WebhookItem_httprequestheaders) 
 
required
Array of objects (WebhookItem_httprequestheaders) 
 
Responses 
200
alert created


400
Bad request


401
Unauthorized


500
A server side exception has occured, please contact support


patch/webhookconfig
Request samples 
application/json
{
  • "whname": "Your Webhook Name",
  • "whcomment": "short comment on the webhook",
  • "applicationId": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "municipalityId": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "callbackUrl": "https://yourdomain.com/send/callback/here",
  • "processes": [
    ],
  • "httprequestheaders": [
    ],
  • "httprequestparameter": [
    ],
  • "httprequestbody": [
    ]
}
Response samples 
application/json
{
  • "whid": "A123123",
  • "whname": "Your Alert Name",
  • "whcomment": "short comment on the alert",
  • "applicationId": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "municipalityid": "d0db4b13-20d4-42c3-8268-37db22b36f98",
  • "callbackUrl": "https://yourdomain.com/send/callback/here",
  • "process": "process",
  • "httprequestheaders": [
    ],
  • "httprequestparameter": [
    ],
  • "httprequestbody": [
    ]
}
Status Update
Update the Status of a task


Update the status of a task in the F4D Platform
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.


Securitysubscriptionkey and bearerAuth 
Request 
Request Body schema: application/json
uniqueId
integer
The unique taskId provided by an initial webhook call. For example when receiving a status 'new'. Note, both integer and string are accepted.


 
newStatus
string
The new status of the task in the system.


 Enum: "new" "inprogress" "done" "refund"  
refundAmount
string
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.


 
Responses 
200
successfully created the status update


400
Bad Request


401
Unauthorized


500
A server side exception has occured, please contact support


post/statusUpdate
Request samples 
application/json
{
  • "uniqueId": 123,
  • "newStatus": "done"
}
Submit Document
Submit a document to an existing task


Submit a document to an existing task. This API is not active and returns always a status 500. The defintion can be used as preparation for when the MyDocument Service of the SmartServicePortal is active. Until then, no documents can be submitted.
Submit a document to an existing task. 


Securitysubscriptionkey and bearerAuth 
Request 
Request Body schema: application/json
uniqueId
string
the unique Id of the task to be submitted


 
documentName
string
The filename of the document.


 
documentType
string
Type of Document


 
documentBase64
string
The Base64 encoded document


 
Responses 
200
successfully updated the task with the document


401
Unauthorized


500
A server side exception has occured, please contact support


post/submitdocument
Request samples 
application/json
{
  • "uniqueId": "1234567",
  • "documentName": "test.pdf",
  • "documentType": "Hauptwohnsitzbescheinigung",
  • "documentBase64": "string"
}