Dibito REST API (1.1)

The Dibito REST API provides services to submit, verify and deliver eBills. The API is designed to be used by biller integrations.

Product Website

https://www.dibito.ch

API Key

This API requires an API key to be passed in the `X-API-Key` header.
Generate your API key in the Dibito application under "Dibito -> API Keys".

Further Informations

Consult our documentation for futher informations about creating and handling eBills.

Download OpenAPI description

api-docs.json

api-docs.yaml

Overview

URL

https://www.codeblock.ch

Codeblock GmbH

contact@codeblock.ch

Servers

Generated server url

https://app.dibito.ch/

00 Examples

Operations

10 Business Cases

Operations

20 Bill Recipients

Operations

21 Bill-Recipient Subscriptions

Operations

Confirm bill recipient subscription initiation

Request

This endpoint verifies the combination of subscription initiation token and activation code. If the combination is valid, it creates an active biller relation. Only the primary network partner of a biller is allowed to confirm the subscription at the biller initiation.

Security

X-API-Key

Path

subscriptionInitiationTokenstringrequired

subscription initiation token

Bodyapplication/jsonrequired

activationCodestring= 6 charactersrequired

activation code provided by the user

Example: 123456

curl -i -X PUT \
  'https://app.dibito.ch/api/v1/bill-recipient-subscriptions/initiations/{subscriptionInitiationToken}' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "activationCode": 123456
  }'

Responses

Bill recipient relation initiated

Bodyapplication/json

emailAddressstring[ 1 .. 256 ] characters

email address of the bill recipient

Example: "peter@muster.ch"

billRecipientSixIdstring[ 1 .. 17 ] characters([0-9])*required

SIX ID of the bill recipient

Example: 41010560425610180

enterpriseIdentificationNumberstring[ 0 .. 12 ] charactersCHE[0-9]{9}

Swiss enterprise identification number (UID) without dashes, dots or extension. Note that this has to contain the swiss enterprise identification number (UID) from the commercial register (Handelsregister) which may be different from the VAT UID (Mehrwertsteuer UID).

Example: "CHE123456789"

typestringrequired

the type of the bill recipient

Enum"PRIVATE""COMPANY"

namestring[ 1 .. 70 ] charactersrequired

last name, if private bill recipient company name, if company bill recipient

Example: "for private bill recipient: Muster, for company name: Muster AG"

firstNamestring[ 0 .. 35 ] characters

first name, if private bill recipient empty, if company bill recipient

Example: "Peter"

correspondenceLanguagestring[ 1 .. 3 ] charactersrequired

language for correspondence with this bill recipient ISO-639-2/B

Example: "ger"

addressobject(RecipientAddress)required

address.streetNamestring[ 1 .. 70 ] charactersrequired

street name

Example: "Neustadtstrasse"

address.postalCodestring[ 1 .. 9 ] charactersrequired

postal code

Example: 6025

address.citystring[ 1 .. 35 ] charactersrequired

city name

Example: "Neudorf"

address.countryCodestring[ 0 .. 2 ] characters[A-Z]{2}required

in format ISO 3166-1 alpha 2

Example: "CH"

Response

application/json

{
  "emailAddress": "peter@muster.ch",
  "billRecipientSixId": 41010560425610180,
  "enterpriseIdentificationNumber": "CHE123456789",
  "type": "PRIVATE",
  "name": "for private bill recipient: Muster, for company name: Muster AG",
  "firstName": "Peter",
  "correspondenceLanguage": "ger",
  "address": {
    "streetName": "Neustadtstrasse",
    "postalCode": 6025,
    "city": "Neudorf",
    "countryCode": "CH"
  }
}

Initiate bill recipient subscription

Request

This endpoint initiates the "Bill recipient driven subscription (Subscription at the biller)" process, returns a subscription initiation token to the caller and sends a verification code to the eBill subscribers email address. Only the primary network partner of a biller is allowed to initiate the subscription at the biller.

Security

X-API-Key

Bodyapplication/jsonrequired

emailAddressstring[ 1 .. 256 ] charactersrequired

Email address the user entered for subscription initiation

Example: "hansmuster@muster.info"

curl -i -X POST \
  https://app.dibito.ch/api/v1/bill-recipient-subscriptions/initiations \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "emailAddress": "hansmuster@muster.info"
  }'

Responses

subscription initiation token which was send to the user

Bodyapplication/json

subscriptionInitiationTokenstring= 36 charactersrequired

subscription initiation token which will be used to confirm the subscription initiation

Example: "0dc2ff79-db4c-4635-a4aa-f93f36ab5dbf"

Response

application/json

{
  "subscriptionInitiationToken": "0dc2ff79-db4c-4635-a4aa-f93f36ab5dbf"
}

30 Events

Operations

31 SIX Events

Operations

40 Webhook Management

Operations

90 PDF

Operations

98 Health Check

Operations

99 Authentication

Operations

webhooks

Webhooks

endpoint-controller

Operations