Skip to content

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.
Please refer to the API tutorial for your first eBill submission.

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".

Top level overview

  • Create bills by posting either a QR-Invoice as PDF to the /v1/business-cases` endpoint or a fully populated JSON object to one of the business case type endpoints.
  • If the request succeeds, it passed validation and can be delivered to the eBill recipients.
  • Use the webhook endpoints to be notified about changes to your recipient subscriptions or business case statuses.

Referencing existing bills

If you pass one of the reference parameters or fill in the referenced bills section in your business case, the submitted eBill will:
  • In case of a reminder: Add a reminder to the eBill portal of the reciepient for the referenced bill.
  • In case of a donation inquiry: Will do nothing. Donation inquiries cannot be referenced.
  • In any other case: Replace the referenced bill with the new one in the eBill portal of the recipient. (Hint: Use advices to effectively cancel delivered eBills.)

Product Website

https://www.dibito.ch

Further Informations

Consult our documentation for further 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

Languages
Servers
Generated server url

https://app.dibito.ch/

00 Examples

Operations

10 Business Cases

Operations

Submit business case

Request

This operation accepts either a QR-Invoice PDF or a PDF in the eBill Format, containing the business case information as XML attachment included in the PDF. The specific business case type (bill, advice...) is specified in the XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
refByEBillReferenceNumberstringrequired

eBill Reference Number which this business case references to (For reminders and replacements)

refByReferenceStructuredstringrequired

Structured payment reference number which this business case references to

refByDibitoIDinteger(int32)required

Dibito business case ID which this business case references to

Headers
x-filenamestring[ 1 .. 99 ] characters

Filename for the business case PDF. This is only used for analytical purposes and support. The filename is not visible for the bill recipient. Minimal length: 1 Maximal length: 99

x-anomaly-detectionstring

If the optional header is provided with the value 'SKIP', the anomaly detection does not prevent business case submission

Bodyapplication/pdfrequired
bodystring(binary)

PDF as binary data

curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases?processingMode=STAGE&refByEBillReferenceNumber=string&refByReferenceStructured=string&refByDibitoID=0' \
  -H 'Content-Type: application/pdf' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -H 'x-anomaly-detection: string' \
  -H 'x-filename: string' \
  -d '[object Object]'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Reminder

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatReminder)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/reminder?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "singlePayment": {
        "paymentMode": "EBILL",
        "paymentInformation": {
          "accountAndReference": {
            "accountHolder": {
              "name": "string",
              "structuredAddress": {
                "street": "string",
                "buildingNumber": "string",
                "city": "string",
                "postalCode": "string",
                "countryCode": "string"
              }
            },
            "generic": {
              "referenceType": "QRR",
              "referenceStructured": "string",
              "referenceUnstructured": "string",
              "iban": "CH9300762011623852957"
            }
          },
          "amount": {
            "value": 0,
            "currencyCode": "string"
          },
          "dueDate": "2019-08-24",
          "payableAmountCanBeModified": true
        }
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Reminder

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

reminderobject(EBillFormatReminder)required
reminder.​referenceNumberstringrequired
reminder.​businessCaseDatestring(date)required
reminder.​totalAmountobject(EBillFormatAmountType)required
reminder.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
reminder.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

reminder.​referencedBillobject(EBillFormatReferencedBill)
reminder.​billRecipientobject(EBillFormatBillRecipient)required
reminder.​billRecipient.​emailAddressstring
reminder.​billRecipient.​enterpriseIdentificationNumberstring
reminder.​billRecipient.​billRecipientSixIdstring
reminder.​billRecipient.​namestringrequired
reminder.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
reminder.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
reminder.​singlePaymentobject(EBillFormatSinglePayment)required
reminder.​singlePayment.​paymentModestringrequired
Default "EBILL"
Enum"EBILL""EBILL_DEBIT"
reminder.​singlePayment.​paymentInformationobject(EBillFormatPaymentInformation)required
reminder.​singlePayment.​paymentInformation.​accountAndReferenceobject(EBillFormatAccountAndReference)required
reminder.​singlePayment.​paymentInformation.​accountAndReference.​accountHolderobject(EBillFormatAccountHolderType)
reminder.​singlePayment.​paymentInformation.​accountAndReference.​genericobject(EBillFormatAccountIBANAndReference)required
reminder.​singlePayment.​paymentInformation.​amountobject(EBillFormatAmountType)required
reminder.​singlePayment.​paymentInformation.​amount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
reminder.​singlePayment.​paymentInformation.​amount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

reminder.​singlePayment.​paymentInformation.​dueDatestring(date)required

Due date. In the case of donation inquiries, the due date acts as a proposal for the payment date.

At time of submission, cannot be set to more than 3 years in the future (1095 days) for payment mode ebill. At time of submission, cannot be set to more than 30 days in the future for payment mode ebill debit. At time of submission, cannot be older than 90 days.

reminder.​singlePayment.​paymentInformation.​payableAmountCanBeModifiedbooleanrequired

If true, then the provided invoice amount is permitted to be altered. If the invoice amount is not provided, the value must be set to true.

reminder.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/reminder/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'reminder[referenceNumber]=string' \
  -F 'reminder[businessCaseDate]=2019-08-24' \
  -F 'reminder[totalAmount][value]=0' \
  -F 'reminder[totalAmount][currencyCode]=string' \
  -F 'reminder[referencedBill][referenceNumber]=string' \
  -F 'reminder[billRecipient][emailAddress]=string' \
  -F 'reminder[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'reminder[billRecipient][billRecipientSixId]=string' \
  -F 'reminder[billRecipient][name]=string' \
  -F 'reminder[billRecipient][address][structuredAddress][street]=string' \
  -F 'reminder[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'reminder[billRecipient][address][structuredAddress][city]=string' \
  -F 'reminder[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'reminder[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'reminder[singlePayment][paymentMode]=EBILL' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][name]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][street]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][buildingNumber]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][city]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][postalCode]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][countryCode]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][generic][referenceType]=QRR' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][generic][referenceStructured]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][generic][referenceUnstructured]=string' \
  -F 'reminder[singlePayment][paymentInformation][accountAndReference][generic][iban]=CH9300762011623852957' \
  -F 'reminder[singlePayment][paymentInformation][amount][value]=0' \
  -F 'reminder[singlePayment][paymentInformation][amount][currencyCode]=string' \
  -F 'reminder[singlePayment][paymentInformation][dueDate]=2019-08-24' \
  -F 'reminder[singlePayment][paymentInformation][payableAmountCanBeModified]=true' \
  -F 'reminder[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'reminder[workflow][deliveryDateStart]=2019-08-24' \
  -F 'reminder[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'reminder[workflow][netAmount][value]=0' \
  -F 'reminder[workflow][netAmount][currencyCode]=string' \
  -F 'reminder[workflow][amountPaid][value]=0' \
  -F 'reminder[workflow][amountPaid][currencyCode]=string' \
  -F 'reminder[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'reminder[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'reminder[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'reminder[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'reminder[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'reminder[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Instalment Bill

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatInstalmentBill)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/instalment-bill?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "paymentsByInstalments": {
        "paymentByInstalments": [
          {
            "externalPaymentByInstalmentsId": "string",
            "description": "string",
            "isTotalAmountHidden": true,
            "isTotalPaymentOption": true,
            "instalments": {
              "instalment": [
                {}
              ]
            }
          }
        ]
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Instalment Bill

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

instalmentBillobject(EBillFormatInstalmentBill)required
instalmentBill.​referenceNumberstringrequired
instalmentBill.​businessCaseDatestring(date)required
instalmentBill.​totalAmountobject(EBillFormatAmountType)required
instalmentBill.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
instalmentBill.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

instalmentBill.​referencedBillobject(EBillFormatReferencedBill)
instalmentBill.​billRecipientobject(EBillFormatBillRecipient)required
instalmentBill.​billRecipient.​emailAddressstring
instalmentBill.​billRecipient.​enterpriseIdentificationNumberstring
instalmentBill.​billRecipient.​billRecipientSixIdstring
instalmentBill.​billRecipient.​namestringrequired
instalmentBill.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
instalmentBill.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
instalmentBill.​paymentsByInstalmentsobject(EBillFormatPaymentsByInstalments)required
instalmentBill.​paymentsByInstalments.​paymentByInstalmentsArray of objects(EBillFormatPaymentByInstalments)required
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​externalPaymentByInstalmentsIdstringrequired
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​descriptionstring
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​isTotalAmountHiddenboolean
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​isTotalPaymentOptionboolean
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​instalmentsobject(EBillFormatInstalments)required
instalmentBill.​paymentsByInstalments.​paymentByInstalments[].​instalments.​instalmentArray of objects(EBillFormatInstalment)required
instalmentBill.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/instalment-bill/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'instalmentBill[referenceNumber]=string' \
  -F 'instalmentBill[businessCaseDate]=2019-08-24' \
  -F 'instalmentBill[totalAmount][value]=0' \
  -F 'instalmentBill[totalAmount][currencyCode]=string' \
  -F 'instalmentBill[referencedBill][referenceNumber]=string' \
  -F 'instalmentBill[billRecipient][emailAddress]=string' \
  -F 'instalmentBill[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'instalmentBill[billRecipient][billRecipientSixId]=string' \
  -F 'instalmentBill[billRecipient][name]=string' \
  -F 'instalmentBill[billRecipient][address][structuredAddress][street]=string' \
  -F 'instalmentBill[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'instalmentBill[billRecipient][address][structuredAddress][city]=string' \
  -F 'instalmentBill[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'instalmentBill[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][externalPaymentByInstalmentsId]=string' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][description]=string' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][isTotalAmountHidden]=true' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][isTotalPaymentOption]=true' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][instalments][instalment][0][externalInstalmentId]=undefined' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][instalments][instalment][0][description]=undefined' \
  -F 'instalmentBill[paymentsByInstalments][paymentByInstalments][0][instalments][instalment][0][paymentInformation]=undefined' \
  -F 'instalmentBill[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'instalmentBill[workflow][deliveryDateStart]=2019-08-24' \
  -F 'instalmentBill[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'instalmentBill[workflow][netAmount][value]=0' \
  -F 'instalmentBill[workflow][netAmount][currencyCode]=string' \
  -F 'instalmentBill[workflow][amountPaid][value]=0' \
  -F 'instalmentBill[workflow][amountPaid][currencyCode]=string' \
  -F 'instalmentBill[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'instalmentBill[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'instalmentBill[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'instalmentBill[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'instalmentBill[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'instalmentBill[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Donation Inquiry

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatDonationInquiry)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/donation-inquiry?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "singlePayment": {
        "paymentMode": "EBILL",
        "paymentInformation": {
          "accountAndReference": {
            "accountHolder": {
              "name": "string",
              "structuredAddress": {
                "street": "string",
                "buildingNumber": "string",
                "city": "string",
                "postalCode": "string",
                "countryCode": "string"
              }
            },
            "generic": {
              "referenceType": "QRR",
              "referenceStructured": "string",
              "referenceUnstructured": "string",
              "iban": "CH9300762011623852957"
            }
          },
          "amount": {
            "value": 0,
            "currencyCode": "string"
          },
          "dueDate": "2019-08-24",
          "payableAmountCanBeModified": true
        }
      },
      "proposedDonationAmounts": {
        "proposedDonationAmount": [
          {
            "value": 0,
            "currencyCode": "string"
          }
        ]
      },
      "donationPurposes": {
        "donationPurpose": [
          {
            "externalDonationPurposeId": "string",
            "label": "string"
          }
        ]
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Donation Inquiry

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

donationInquiryobject(EBillFormatDonationInquiry)required
donationInquiry.​referenceNumberstringrequired
donationInquiry.​businessCaseDatestring(date)required
donationInquiry.​totalAmountobject(EBillFormatAmountType)required
donationInquiry.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
donationInquiry.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

donationInquiry.​referencedBillobject(EBillFormatReferencedBill)
donationInquiry.​billRecipientobject(EBillFormatBillRecipient)required
donationInquiry.​billRecipient.​emailAddressstring
donationInquiry.​billRecipient.​enterpriseIdentificationNumberstring
donationInquiry.​billRecipient.​billRecipientSixIdstring
donationInquiry.​billRecipient.​namestringrequired
donationInquiry.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
donationInquiry.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
donationInquiry.​singlePaymentobject(EBillFormatSinglePayment)required
donationInquiry.​singlePayment.​paymentModestringrequired
Default "EBILL"
Enum"EBILL""EBILL_DEBIT"
donationInquiry.​singlePayment.​paymentInformationobject(EBillFormatPaymentInformation)required
donationInquiry.​singlePayment.​paymentInformation.​accountAndReferenceobject(EBillFormatAccountAndReference)required
donationInquiry.​singlePayment.​paymentInformation.​accountAndReference.​accountHolderobject(EBillFormatAccountHolderType)
donationInquiry.​singlePayment.​paymentInformation.​accountAndReference.​genericobject(EBillFormatAccountIBANAndReference)required
donationInquiry.​singlePayment.​paymentInformation.​amountobject(EBillFormatAmountType)required
donationInquiry.​singlePayment.​paymentInformation.​amount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
donationInquiry.​singlePayment.​paymentInformation.​amount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

donationInquiry.​singlePayment.​paymentInformation.​dueDatestring(date)required

Due date. In the case of donation inquiries, the due date acts as a proposal for the payment date.

At time of submission, cannot be set to more than 3 years in the future (1095 days) for payment mode ebill. At time of submission, cannot be set to more than 30 days in the future for payment mode ebill debit. At time of submission, cannot be older than 90 days.

donationInquiry.​singlePayment.​paymentInformation.​payableAmountCanBeModifiedbooleanrequired

If true, then the provided invoice amount is permitted to be altered. If the invoice amount is not provided, the value must be set to true.

donationInquiry.​proposedDonationAmountsobject(EBillFormatProposedDonationAmountsType)
donationInquiry.​donationPurposesobject(EBillFormatDonationPurposesType)
donationInquiry.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/donation-inquiry/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'donationInquiry[referenceNumber]=string' \
  -F 'donationInquiry[businessCaseDate]=2019-08-24' \
  -F 'donationInquiry[totalAmount][value]=0' \
  -F 'donationInquiry[totalAmount][currencyCode]=string' \
  -F 'donationInquiry[referencedBill][referenceNumber]=string' \
  -F 'donationInquiry[billRecipient][emailAddress]=string' \
  -F 'donationInquiry[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'donationInquiry[billRecipient][billRecipientSixId]=string' \
  -F 'donationInquiry[billRecipient][name]=string' \
  -F 'donationInquiry[billRecipient][address][structuredAddress][street]=string' \
  -F 'donationInquiry[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'donationInquiry[billRecipient][address][structuredAddress][city]=string' \
  -F 'donationInquiry[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'donationInquiry[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'donationInquiry[singlePayment][paymentMode]=EBILL' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][name]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][street]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][buildingNumber]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][city]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][postalCode]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][countryCode]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][generic][referenceType]=QRR' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][generic][referenceStructured]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][generic][referenceUnstructured]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][accountAndReference][generic][iban]=CH9300762011623852957' \
  -F 'donationInquiry[singlePayment][paymentInformation][amount][value]=0' \
  -F 'donationInquiry[singlePayment][paymentInformation][amount][currencyCode]=string' \
  -F 'donationInquiry[singlePayment][paymentInformation][dueDate]=2019-08-24' \
  -F 'donationInquiry[singlePayment][paymentInformation][payableAmountCanBeModified]=true' \
  -F 'donationInquiry[proposedDonationAmounts][proposedDonationAmount][0][value]=0' \
  -F 'donationInquiry[proposedDonationAmounts][proposedDonationAmount][0][currencyCode]=string' \
  -F 'donationInquiry[donationPurposes][donationPurpose][0][externalDonationPurposeId]=string' \
  -F 'donationInquiry[donationPurposes][donationPurpose][0][label]=string' \
  -F 'donationInquiry[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'donationInquiry[workflow][deliveryDateStart]=2019-08-24' \
  -F 'donationInquiry[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'donationInquiry[workflow][netAmount][value]=0' \
  -F 'donationInquiry[workflow][netAmount][currencyCode]=string' \
  -F 'donationInquiry[workflow][amountPaid][value]=0' \
  -F 'donationInquiry[workflow][amountPaid][currencyCode]=string' \
  -F 'donationInquiry[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'donationInquiry[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'donationInquiry[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'donationInquiry[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'donationInquiry[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'donationInquiry[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Credit Note

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatCreditNote)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/credit-note?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit Credit Note

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

creditNoteobject(EBillFormatCreditNote)required
creditNote.​referenceNumberstringrequired
creditNote.​businessCaseDatestring(date)required
creditNote.​totalAmountobject(EBillFormatAmountType)required
creditNote.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
creditNote.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

creditNote.​referencedBillobject(EBillFormatReferencedBill)
creditNote.​billRecipientobject(EBillFormatBillRecipient)required
creditNote.​billRecipient.​emailAddressstring
creditNote.​billRecipient.​enterpriseIdentificationNumberstring
creditNote.​billRecipient.​billRecipientSixIdstring
creditNote.​billRecipient.​namestringrequired
creditNote.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
creditNote.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
creditNote.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/credit-note/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'creditNote[referenceNumber]=string' \
  -F 'creditNote[businessCaseDate]=2019-08-24' \
  -F 'creditNote[totalAmount][value]=0' \
  -F 'creditNote[totalAmount][currencyCode]=string' \
  -F 'creditNote[referencedBill][referenceNumber]=string' \
  -F 'creditNote[billRecipient][emailAddress]=string' \
  -F 'creditNote[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'creditNote[billRecipient][billRecipientSixId]=string' \
  -F 'creditNote[billRecipient][name]=string' \
  -F 'creditNote[billRecipient][address][structuredAddress][street]=string' \
  -F 'creditNote[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'creditNote[billRecipient][address][structuredAddress][city]=string' \
  -F 'creditNote[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'creditNote[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'creditNote[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'creditNote[workflow][deliveryDateStart]=2019-08-24' \
  -F 'creditNote[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'creditNote[workflow][netAmount][value]=0' \
  -F 'creditNote[workflow][netAmount][currencyCode]=string' \
  -F 'creditNote[workflow][amountPaid][value]=0' \
  -F 'creditNote[workflow][amountPaid][currencyCode]=string' \
  -F 'creditNote[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'creditNote[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'creditNote[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'creditNote[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'creditNote[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'creditNote[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit bill

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatBill)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/bill?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "singlePayment": {
        "paymentMode": "EBILL",
        "paymentInformation": {
          "accountAndReference": {
            "accountHolder": {
              "name": "string",
              "structuredAddress": {
                "street": "string",
                "buildingNumber": "string",
                "city": "string",
                "postalCode": "string",
                "countryCode": "string"
              }
            },
            "generic": {
              "referenceType": "QRR",
              "referenceStructured": "string",
              "referenceUnstructured": "string",
              "iban": "CH9300762011623852957"
            }
          },
          "amount": {
            "value": 0,
            "currencyCode": "string"
          },
          "dueDate": "2019-08-24",
          "payableAmountCanBeModified": true
        }
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit bill

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

billobject(EBillFormatBill)required
bill.​referenceNumberstringrequired
bill.​businessCaseDatestring(date)required
bill.​totalAmountobject(EBillFormatAmountType)required
bill.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
bill.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

bill.​referencedBillobject(EBillFormatReferencedBill)
bill.​billRecipientobject(EBillFormatBillRecipient)required
bill.​billRecipient.​emailAddressstring
bill.​billRecipient.​enterpriseIdentificationNumberstring
bill.​billRecipient.​billRecipientSixIdstring
bill.​billRecipient.​namestringrequired
bill.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
bill.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
bill.​singlePaymentobject(EBillFormatSinglePayment)required
bill.​singlePayment.​paymentModestringrequired
Default "EBILL"
Enum"EBILL""EBILL_DEBIT"
bill.​singlePayment.​paymentInformationobject(EBillFormatPaymentInformation)required
bill.​singlePayment.​paymentInformation.​accountAndReferenceobject(EBillFormatAccountAndReference)required
bill.​singlePayment.​paymentInformation.​accountAndReference.​accountHolderobject(EBillFormatAccountHolderType)
bill.​singlePayment.​paymentInformation.​accountAndReference.​genericobject(EBillFormatAccountIBANAndReference)required
bill.​singlePayment.​paymentInformation.​amountobject(EBillFormatAmountType)required
bill.​singlePayment.​paymentInformation.​amount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
bill.​singlePayment.​paymentInformation.​amount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

bill.​singlePayment.​paymentInformation.​dueDatestring(date)required

Due date. In the case of donation inquiries, the due date acts as a proposal for the payment date.

At time of submission, cannot be set to more than 3 years in the future (1095 days) for payment mode ebill. At time of submission, cannot be set to more than 30 days in the future for payment mode ebill debit. At time of submission, cannot be older than 90 days.

bill.​singlePayment.​paymentInformation.​payableAmountCanBeModifiedbooleanrequired

If true, then the provided invoice amount is permitted to be altered. If the invoice amount is not provided, the value must be set to true.

bill.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/bill/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'bill[referenceNumber]=string' \
  -F 'bill[businessCaseDate]=2019-08-24' \
  -F 'bill[totalAmount][value]=0' \
  -F 'bill[totalAmount][currencyCode]=string' \
  -F 'bill[referencedBill][referenceNumber]=string' \
  -F 'bill[billRecipient][emailAddress]=string' \
  -F 'bill[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'bill[billRecipient][billRecipientSixId]=string' \
  -F 'bill[billRecipient][name]=string' \
  -F 'bill[billRecipient][address][structuredAddress][street]=string' \
  -F 'bill[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'bill[billRecipient][address][structuredAddress][city]=string' \
  -F 'bill[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'bill[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'bill[singlePayment][paymentMode]=EBILL' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][name]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][street]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][buildingNumber]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][city]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][postalCode]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][accountHolder][structuredAddress][countryCode]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][generic][referenceType]=QRR' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][generic][referenceStructured]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][generic][referenceUnstructured]=string' \
  -F 'bill[singlePayment][paymentInformation][accountAndReference][generic][iban]=CH9300762011623852957' \
  -F 'bill[singlePayment][paymentInformation][amount][value]=0' \
  -F 'bill[singlePayment][paymentInformation][amount][currencyCode]=string' \
  -F 'bill[singlePayment][paymentInformation][dueDate]=2019-08-24' \
  -F 'bill[singlePayment][paymentInformation][payableAmountCanBeModified]=true' \
  -F 'bill[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'bill[workflow][deliveryDateStart]=2019-08-24' \
  -F 'bill[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'bill[workflow][netAmount][value]=0' \
  -F 'bill[workflow][netAmount][currencyCode]=string' \
  -F 'bill[workflow][amountPaid][value]=0' \
  -F 'bill[workflow][amountPaid][currencyCode]=string' \
  -F 'bill[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'bill[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'bill[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'bill[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'bill[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'bill[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit advice

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Body
required
pdfstring(byte)
businessCaseobject(EBillFormatAdvice)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/advice?processingMode=STAGE' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "pdf": "string",
    "businessCase": {
      "referenceNumber": "string",
      "businessCaseDate": "2019-08-24",
      "totalAmount": {
        "value": 0,
        "currencyCode": "string"
      },
      "referencedBill": {
        "referenceNumber": "string"
      },
      "billRecipient": {
        "emailAddress": "string",
        "enterpriseIdentificationNumber": "string",
        "billRecipientSixId": "string",
        "name": "string",
        "address": {
          "structuredAddress": {
            "street": "string",
            "buildingNumber": "string",
            "city": "string",
            "postalCode": "string",
            "countryCode": "string"
          }
        }
      },
      "workflow": {
        "vatEnterpriseIdentificationNumbers": {
          "vatEnterpriseIdentificationNumber": [
            "string"
          ]
        },
        "deliveryDateStart": "2019-08-24",
        "deliveryDateEnd": "2019-08-24",
        "netAmount": {
          "value": 0,
          "currencyCode": "string"
        },
        "amountPaid": {
          "value": 0,
          "currencyCode": "string"
        },
        "vatRates": {
          "vatRate": [
            {
              "percentage": 0,
              "taxBaseAmount": {
                "value": 0,
                "currencyCode": "string"
              },
              "taxAmount": {
                "value": 0,
                "currencyCode": "string"
              }
            }
          ]
        },
        "caseReferenceForBillRecipient": "string"
      }
    }
  }'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Submit advice

Request

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Security
X-API-Key
Query
processingModestringrequired

STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient

Enum"STAGE""DELIVER"
Bodymultipart/form-data
filestring(binary)required

PDF file

adviceobject(EBillFormatAdvice)required
advice.​referenceNumberstringrequired
advice.​businessCaseDatestring(date)required
advice.​totalAmountobject(EBillFormatAmountType)required
advice.​totalAmount.​valuenumber
  • max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
  • min. - 99'999'999.99, max 99'999'999.99 for advices
  • Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
  • Amount must be ≥ 0 for credit notes.
  • If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).
advice.​totalAmount.​currencyCodestringrequired

Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

advice.​referencedBillobject(EBillFormatReferencedBill)
advice.​billRecipientobject(EBillFormatBillRecipient)required
advice.​billRecipient.​emailAddressstring
advice.​billRecipient.​enterpriseIdentificationNumberstring
advice.​billRecipient.​billRecipientSixIdstring
advice.​billRecipient.​namestringrequired
advice.​billRecipient.​addressobject(EBillFormatBillRecipientAddress)required
advice.​billRecipient.​address.​structuredAddressobject(EBillFormatPostalAddress)
advice.​workflowobject(EBillFormatWorkflow)
curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases/advice/multipart?processingMode=STAGE' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -F file=string \
  -F 'advice[referenceNumber]=string' \
  -F 'advice[businessCaseDate]=2019-08-24' \
  -F 'advice[totalAmount][value]=0' \
  -F 'advice[totalAmount][currencyCode]=string' \
  -F 'advice[referencedBill][referenceNumber]=string' \
  -F 'advice[billRecipient][emailAddress]=string' \
  -F 'advice[billRecipient][enterpriseIdentificationNumber]=string' \
  -F 'advice[billRecipient][billRecipientSixId]=string' \
  -F 'advice[billRecipient][name]=string' \
  -F 'advice[billRecipient][address][structuredAddress][street]=string' \
  -F 'advice[billRecipient][address][structuredAddress][buildingNumber]=string' \
  -F 'advice[billRecipient][address][structuredAddress][city]=string' \
  -F 'advice[billRecipient][address][structuredAddress][postalCode]=string' \
  -F 'advice[billRecipient][address][structuredAddress][countryCode]=string' \
  -F 'advice[workflow][vatEnterpriseIdentificationNumbers][vatEnterpriseIdentificationNumber]=string' \
  -F 'advice[workflow][deliveryDateStart]=2019-08-24' \
  -F 'advice[workflow][deliveryDateEnd]=2019-08-24' \
  -F 'advice[workflow][netAmount][value]=0' \
  -F 'advice[workflow][netAmount][currencyCode]=string' \
  -F 'advice[workflow][amountPaid][value]=0' \
  -F 'advice[workflow][amountPaid][currencyCode]=string' \
  -F 'advice[workflow][vatRates][vatRate][0][percentage]=0' \
  -F 'advice[workflow][vatRates][vatRate][0][taxBaseAmount][value]=0' \
  -F 'advice[workflow][vatRates][vatRate][0][taxBaseAmount][currencyCode]=string' \
  -F 'advice[workflow][vatRates][vatRate][0][taxAmount][value]=0' \
  -F 'advice[workflow][vatRates][vatRate][0][taxAmount][currencyCode]=string' \
  -F 'advice[workflow][caseReferenceForBillRecipient]=string'

Responses

Business case created

Bodyapplication/json
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
application/json
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

Get business case

Request

Depending on the accept header, this operation either returns a JSON business case object or the PDF document (PDF/A-3b. The returned JSON object contains one of the business case subtypes: Bill, InstalmentBill, Reminder, CreditNote, Advice or DonationInquiry.

Security
X-API-Key
Path
businessCaseIdinteger(int32)required

business case ID Example: "12345"

curl -i -X GET \
  'https://app.dibito.ch/api/v1/business-cases/{businessCaseId}' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Business case found

Body
idinteger(int32)required

A unique SIX ID for this business case. Property must not be given when creating a new business case.

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
typestringrequired

the type of the business case

Enum"Bill""InstalmentBill""Advice""CreditNote""Reminder""DonationInquiry"
Discriminator
billerSixIdstring[ 0 .. 14 ] charactersBIID[0-9]{10}required

Biller SIX ID

Example: "BIID0000123456"
referenceNumberstring[ 1 .. 120 ] characters

A business case reference given by the biller. Must be unique in combination with the billerId.

Example: "2018-123456-22"
referencedBillobject(ReferencedBill)
businessCaseDatestring(date)required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Example: "Fri Dec 22 01:00:00 CET 2017"
statusstring

the status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED"
processingStatusstring

the processing status of the business case

Enum"STAGED""INVALID""PROCESSING""FAILED""DELIVERED"
totalAmountobject(OptionalAmountWithCurrency)required
totalAmount.​valuenumber

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java). Maximum value: 99'999'999.99 Maximal length: 10

Example: 99.99
totalAmount.​currencyCodestring[ 0 .. 3 ] characters[A-Z]{3}required

The amount currency code according to ISO-4217.

Example: "CHF"
Response
{
  "id": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
  "type": "Advice",
  "billerSixId": "BIID0000123456",
  "referenceNumber": "2018-123456-22",
  "referencedBill": {
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "referenceNumber": "2018-123456-22"
  },
  "businessCaseDate": "Fri Dec 22 01:00:00 CET 2017",
  "status": "OPEN",
  "processingStatus": "STAGED",
  "totalAmount": {
    "value": 99.99,
    "currencyCode": "CHF"
  }
}

20 Bill Recipients

Operations

21 Bill-Recipient Subscriptions

Operations

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