# Dibito REST API 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. Version: 1.1 ## Servers Generated server url ``` https://app.dibito.ch ``` ## Security ### X-API-Key API key via Header Type: apiKey In: header Name: X-API-Key ## Download OpenAPI description [Dibito REST API](https://apis.codeblock.ch/_spec/Dibito/api-docs.yaml) ## 00 Examples ### getExampleReminder - [GET /api/v1/examples/reminder](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplereminder.md) ### getExampleReminderWithWorkflow - [GET /api/v1/examples/reminder-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplereminderwithworkflow.md) ### getExampleInstalmentBill - [GET /api/v1/examples/instalment-bill](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampleinstalmentbill.md) ### getExampleInstalmentBillWithWorkflow - [GET /api/v1/examples/instalment-bill-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampleinstalmentbillwithworkflow.md) ### getExampleDonationInquiry - [GET /api/v1/examples/donation-inquiry](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampledonationinquiry.md) ### getExampleDonationInquiryWithWorkflow - [GET /api/v1/examples/donation-inquiry-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampledonationinquirywithworkflow.md) ### getExampleCreditNote - [GET /api/v1/examples/credit-note](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplecreditnote.md) ### getExampleCreditNoteWithWorkflow - [GET /api/v1/examples/credit-note-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplecreditnotewithworkflow.md) ### getExampleBill - [GET /api/v1/examples/bill](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplebill.md) ### getExampleBillWithWorkflow - [GET /api/v1/examples/bill-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexamplebillwithworkflow.md) ### getExampleAdvice - [GET /api/v1/examples/advice](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampleadvice.md) ### getExampleAdviceWithWorkflow - [GET /api/v1/examples/advice-with-workflow](https://apis.codeblock.ch/dibito/api-docs/00-examples/getexampleadvicewithworkflow.md) ## 10 Business Cases ### Submit business case - [POST /api/v1/business-cases](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/submitbusinesscase.md): 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. ### Submit Reminder - [POST /api/v1/business-cases/reminder](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/reminder.md): 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. ### Submit Reminder - [POST /api/v1/business-cases/reminder/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/remindermultipart.md): 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. ### Submit Instalment Bill - [POST /api/v1/business-cases/instalment-bill](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/instalmentbill.md): 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. ### Submit Instalment Bill - [POST /api/v1/business-cases/instalment-bill/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/instalmentbillmultipart.md): 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. ### Submit Donation Inquiry - [POST /api/v1/business-cases/donation-inquiry](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/donationinquiry.md): 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. ### Submit Donation Inquiry - [POST /api/v1/business-cases/donation-inquiry/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/donationinquirymultipart.md): 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. ### Submit Credit Note - [POST /api/v1/business-cases/credit-note](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/creditnote.md): 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. ### Submit Credit Note - [POST /api/v1/business-cases/credit-note/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/creditnotemultipart.md): 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. ### Submit bill - [POST /api/v1/business-cases/bill](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/bill.md): 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. ### Submit bill - [POST /api/v1/business-cases/bill/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/billmultipart.md): 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. ### Submit advice - [POST /api/v1/business-cases/advice](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/advice.md): 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. ### Submit advice - [POST /api/v1/business-cases/advice/multipart](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/advicemultipart.md): 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. ### Get business case - [GET /api/v1/business-cases/{businessCaseId}](https://apis.codeblock.ch/dibito/api-docs/10-business-cases/getbusinesscase.md): 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. ## 20 Bill Recipients ### Search for multiple bill recipients - [POST /api/v1/bill-recipients/search](https://apis.codeblock.ch/dibito/api-docs/20-bill-recipients/searchbillrecipients.md): For each item in the request body, the endpoint will respond if it is allowed to submit a business case for a bill recipient with the provided ID. In addition to the provided ID, the response will always contain the billRecipientId, if a business case submission is allowed. ### Get bill recipient by SIX ID - [GET /api/v1/bill-recipients/{billRecipientSixId}](https://apis.codeblock.ch/dibito/api-docs/20-bill-recipients/getbillrecipientbysixid.md): Verify if a bill recipient is part of the eBill infrastructure by its billRecipientSixId. The call will return the billRecipientSixId if the bill recipient has been found in the eBill infrastructure. Receiving a billRecipientSixId does not necessary mean that the corresponding bill recipient is an active eBill user, it only means that this billRecipientSixId exists in the eBill infrastructure. ## 21 Bill-Recipient Subscriptions ### Confirm bill recipient subscription initiation - [PUT /api/v1/bill-recipient-subscriptions/initiations/{subscriptionInitiationToken}](https://apis.codeblock.ch/dibito/api-docs/21-bill-recipient-subscriptions/confirmbillrecipientsubscriptioninitiation.md): This endpoint verifies the combination of subscription initiation token and activation code. If the combination is valid, it creates an active biller relation. Only the primary network partner of a biller is allowed to confirm the subscription at the biller initiation. ### Initiate bill recipient subscription - [POST /api/v1/bill-recipient-subscriptions/initiations](https://apis.codeblock.ch/dibito/api-docs/21-bill-recipient-subscriptions/createbillrecipientsubscriptioninitiation.md): This endpoint initiates the "Bill recipient driven subscription (Subscription at the biller)" process, returns a subscription initiation token to the caller and sends a verification code to the eBill subscribers email address. Only the primary network partner of a biller is allowed to initiate the subscription at the biller. ## 30 Events ### Find events for business cases that changed processing status - [GET /api/v1/events/processing-status-changed](https://apis.codeblock.ch/dibito/api-docs/30-events/findprocessingstatuschangedevents.md): Events business cases that changed processing status ## 31 SIX Events ### Find events for instalments which changed status - [GET /api/v1/events/six/instalment-status-changed](https://apis.codeblock.ch/dibito/api-docs/31-six-events/findinstalmentstatuschangedevents.md): Events for status changes of instalment bills only. ### Find events for business cases which changed status - [GET /api/v1/events/six/business-case-status-changed](https://apis.codeblock.ch/dibito/api-docs/31-six-events/findbusinesscasestatuschangedevents.md): Events for status changes of bills, reminders and donation inquiries. ### Find events for bill recipient subscriptions which changed status - [GET /api/v1/events/six/bill-recipient-subscription-status-changed](https://apis.codeblock.ch/dibito/api-docs/31-six-events/findbillrecipientsubscriptionstatuschangedevents.md) ### Find events for bill recipients email address changes - [GET /api/v1/events/six/bill-recipient-email-address-changed](https://apis.codeblock.ch/dibito/api-docs/31-six-events/findbillrecipientemailaddresschangedevent.md): This event is triggered after a biller has submitted a business case with an outdated, so called historically available email address. It notifies about the changed email address of a bill recipient, which has been adjusted in eBill. An email address is considered to be historically available if it was present up to 15 months prior to the submission time. The billers are able to submit business cases with historically available email addresses of a bill recipient. However, latest 15 months after the email address changed, the billers are required to submit the business cases with the currently valid email address of the bill recipient. ## 40 Webhook Management ### Create a webhook - [POST /api/v1/webhook/events](https://apis.codeblock.ch/dibito/api-docs/40-webhook-management/create.md): Create a new webhook for a specified type of event. The webhook will instantaneously become active and receive events. See the webhook definitions in the section ### Get all webhooks - [GET /api/v1/webhook](https://apis.codeblock.ch/dibito/api-docs/40-webhook-management/getall.md): Get all webhooks for this biller ### Delete webhook - [DELETE /api/v1/webhook](https://apis.codeblock.ch/dibito/api-docs/40-webhook-management/delete.md): Delete an existing webhook ## 90 PDF ### Converts a PDF to a PDF/A-3b document if possible - [POST /api/v1/pdf/pdfa3b/convert](https://apis.codeblock.ch/dibito/api-docs/90-pdf/convertpdftopdfa3b.md) ### Converts a PDF to a PDF/A-3b document if possible - [POST /api/v1/pdf/pdfa3b/convert/file](https://apis.codeblock.ch/dibito/api-docs/90-pdf/convertpdftopdfa3bfile.md) ## 98 Health Check ### eBill platform health check - [GET /api/v1/healthcheck/ebill](https://apis.codeblock.ch/dibito/api-docs/98-health-check/ebillhealthcheck.md): Returns a status message of the eBill system managed by SIX ## 99 Authentication ### Check if API key is valid - [HEAD /api/v1/apikey](https://apis.codeblock.ch/dibito/api-docs/99-authentication/checkapikey.md) ## endpoint-controller ### serveEndpoint - [POST /connect/{endpoint}/{method}](https://apis.codeblock.ch/dibito/api-docs/endpoint-controller/serveendpoint.md) ## Other ### Bill Recipient Email Address Changed Event - [POST Bill Recipient Email Address Changed Event](https://apis.codeblock.ch/dibito/api-docs/webhooks/paths/bill%20recipient%20email%20address%20changed%20event/post.md) ### Bill Recipient Subscription Status Changed Event - [POST Bill Recipient Subscription Status Changed Event](https://apis.codeblock.ch/dibito/api-docs/webhooks/paths/bill%20recipient%20subscription%20status%20changed%20event/post.md) ### Business Case Status Changed Event - [POST Business Case Status Changed Event](https://apis.codeblock.ch/dibito/api-docs/webhooks/paths/business%20case%20status%20changed%20event/post.md) ### Instalment Status Changed Event - [POST Instalment Status Changed Event](https://apis.codeblock.ch/dibito/api-docs/webhooks/paths/instalment%20status%20changed%20event/post.md) ### Processing Status Changed Event - [POST Processing Status Changed Event](https://apis.codeblock.ch/dibito/api-docs/webhooks/paths/processing%20status%20changed%20event/post.md)