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.

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

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

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

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

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

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 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)

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

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

Instalment Bill

instalmentBill.​referenceNumberstringrequired
instalmentBill.​businessCaseDatestring(date)required
instalmentBill.​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.

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

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 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)

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

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

Donation Inquiry

donationInquiry.​referenceNumberstringrequired
donationInquiry.​businessCaseDatestring(date)required
donationInquiry.​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.

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

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.

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)

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

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 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)

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

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

Credit Note

creditNote.​referenceNumberstringrequired
creditNote.​businessCaseDatestring(date)required
creditNote.​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.

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

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 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)

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

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

bill.​referenceNumberstringrequired
bill.​businessCaseDatestring(date)required
bill.​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.

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

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.

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)

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

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 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)

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

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

advice.​referenceNumberstringrequired
advice.​businessCaseDatestring(date)required
advice.​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.

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

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

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