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

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"

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' \
  -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

any

Response

application/json

null

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)

Reminder

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

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": "Bill",
  "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

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

reminder.referenceNumberstringrequired

reminder.businessCaseDatestring(date)required

reminder.totalAmountobject(EBillFormatAmountType)required

The amount of the business case (amount incl. VAT + currency code, e.g. CHF 1183.46). Must be matching with the total amount (totalAmount), if business case is an invoice, reminder or donation inquiry.

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

Information about the account and reference of the invoice issuer.

reminder.singlePayment.paymentInformation.accountAndReference.accountHolderobject(EBillFormatAccountHolderType)

In case the account holder differs from the biller use this element to provide the account holder name and address.

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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)

Instalment Bill

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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

Instalment Bill

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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)

Donation Inquiry

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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

Donation Inquiry

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

Information about the account and reference of the invoice issuer.

donationInquiry.singlePayment.paymentInformation.accountAndReference.accountHolderobject(EBillFormatAccountHolderType)

In case the account holder differs from the biller use this element to provide the account holder name and address.

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.

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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)

Credit Note

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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

Credit Note

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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)

Bill

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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

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

Information about the account and reference of the invoice issuer.

bill.singlePayment.paymentInformation.accountAndReference.accountHolderobject(EBillFormatAccountHolderType)

In case the account holder differs from the biller use this element to provide the account holder name and address.

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.

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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)

Advice

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

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

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)

Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

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"

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)

The business case can only reference bills or instalment bills.

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

An amount whose value may be omitted.

totalAmount.valuenumber

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": "Bill",
  "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

any

Response

No response example

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

Dibito REST API (1.1)

Product Website

API Key

Further Informations

00 Examples

10 Business Cases

Submit business case

Request

Responses

Submit Reminder

RequestExpand all

Responses

Submit Reminder

RequestExpand all

Responses

Submit Instalment Bill

RequestExpand all

Responses

Submit Instalment Bill

RequestExpand all

Responses

Submit Donation Inquiry

RequestExpand all

Responses

Submit Donation Inquiry

RequestExpand all

Responses

Submit Credit Note

RequestExpand all

Responses

Submit Credit Note

RequestExpand all

Responses

Submit bill

RequestExpand all

Responses

Submit bill

RequestExpand all

Responses

Submit advice

RequestExpand all

Responses

Submit advice

RequestExpand all

Responses

Get business case

Request

Responses

20 Bill Recipients

21 Bill-Recipient Subscriptions

30 Events

31 SIX Events

40 Webhook Management

90 PDF

98 Health Check

99 Authentication

webhooks

endpoint-controller

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request