API docs by Redocly

Billte eBill SWP API (1.0.0)

Download OpenAPI specification:Download

URL: https://guard-api.ebill.billte.ch License: MIT

The application programming interface for software partners (Software Partner API) allows communication with an eBill Network Partner. The eBill service comprises of electronic bills, reminders, credit notes and advices which are summarized under the term "business case". Business cases are delivered from software partners via network partners to the SIX eBill infrastructure and can be received online by bill recipients.

Documentation and Open API licence of the Software Partner API can be found on https://ebill-swp.org

Examples and extra information - https://github.com/billte-engineering/ebill-swp-redoc.

Examples include:

  • submitting an invoice
  • submitting a reminder
  • submitting an installment
  • submitting payableAmount

General Note

These APIs are based on the work of the Working Group eBill-SWP-API. Biller is a member of the group and an active contributer.

This documentation has been compiled with the greatest care, but may nevertheless contain errors or inaccuracies. Working Group eBill-SWP-API cannot assume any legal responsibility or any liability for erroneous information or its consequences.

If you notice any errors in this documentation or have any suggestions for improvements, we would be grateful to receive your feedback; please open an issue on our website : https://github.com/billte-engineering/ebill-swp-redoc.

Environments

Billers

All operations that are associated with a biller are located within the biller resource, including the creation of business cases.

Authenticate Biller

Returns an authentication token for the biller to be used in other APIs.

Request Body schema: application/json
billerPid
required
string = 17 characters ([0=9])*

Biller PiD provided by the system

billerSecret
required
string = 36 characters

Biller secret key provided by the system

Responses

Request samples

Content type
application/json
{
  • "billerPid": "41NN00BBBBBBBBBPP",
  • "billerSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response samples

Content type
application/json
{
  • "billerPid": "41NN00BBBBBBBBBPP",
  • "expiresIn": "3600",
  • "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...",
  • "type": "BILLER"
}

Search for bill recipients for this biller

Returns a list of one or more bill recipients.

The response will only list a bill recipient if he allows bills in his online banking to be posted by the biller or allows bills to be posted in general. It will always return the billRecipientId and optionally any other provided parameter.

The call will return an empty list if no matching bill recipient is found or the biller is not allowed to send bills to the bill recipient.

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Request Body schema: application/json

Parameters for the search, at least one of the parameters is required in addition to the mandatory "billerPid". It is recommended to use "billRecipientId" since it is a permenant id of each recipient in the SIX infrastructure.

billRecipientId
string [ 1 .. 17 ] characters ([0-9])*

id of the bill recipient

billerPid
required
string = 17 characters ([0=9])*

Biller PiD provided by the system

emailAddress
string <email> [ 1 .. 256 ] characters

email address of the bill recipient

enterpriseIdentificationNumber
string <= 12 characters CHE[0-9]{9}

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

Responses

Request samples

Content type
application/json
{
  • "billRecipientId": "41010560425610173",
  • "billerPid": "41NN00BBBBBBBBBPP",
  • "emailAddress": "peter@muster.ch",
  • "enterpriseIdentificationNumber": "CHE123456789"
}

Response samples

Content type
application/json
{
  • "billRecipientId": "41010560425610173",
  • "emailAddress": "peter@muster.ch",
  • "enterpriseIdentificationNumber": "CHE123456789",
  • "submissionStatus": "ALLOWED"
}

Get Business Case

Depending on the accept header, this operation either returns a JSON business case object or the original PDF. The returned JSON object contains one of the business case subtypes - Bill, InstalmentBill, Reminder, CreditNote or Advice.

query Parameters
billerPid
required
string <= 17 characters 41[0-9]{15}

biller PID Maximal length: '17' Example: '"41NN00BBBBBBBBBPP"' Pattern: '41[0-9]{15}'

businessCaseId
required
string <= 39 characters NWPBCID[0-9A-Z]{32}

business case id Maximal length: '39' Example: '"NWPBCID0FB909852BBC4D06AD8336AAE87D7FC9"' Pattern: 'NWPBCID[0-9A-Z]{32}'

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
{
  • "id": "NWPBCID0FB909852BBC4D06AD8336AAE87D7FC9",
  • "status": "NWP_PENDING"
}

Create business case

The creation of a business case in PDF/A-3b format works with a simple POST request where the PDF is the binary payload of the request. Note that only one PDF can be submitted at a time.

Validation of the submitted data will take place immediately and the response either confirms the successful creation of the business case on the NWP or contains the error details of the validation.

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Request Body schema: application/pdf

Request body for the creation of business case. Required objects depend on type of business case.

required
object (BillRecipient)
required
object (Biller)
businessCaseDate
required
string

Date of the business case in TZ format.
At time of submission, cannot be older than 90 days.
At time of submission, cannot be in the future. Example: '2022-11-29T09:53:31.814795Z'

businessCaseType
required
string (BusinessCaseType)
Enum: "Bill" "Reminder" "CreditNote" "Advice" "InstalmentBill"
content
required
string

Business Case PDF file encoded in base64 String

fileIdentifier
required
string

Name for the Business Case PDF file.
Example: "invoice-123456789", For a PDF document "invoice-123456789.pdf"

Array of objects (PaymentByInstalments)

Possibility to offer payment of the invoice in instalments.
Instalment invoices can be submitted as multi-group-invoices or single-group-invoices.

Multi-Groups - Invoices with several instalment groups to choose from.
The invoice recipient can decide with which instalment option the invoice will be paid. One of the instalments groups can contain a total instalment to be used for the payment of the entire invoice (isTotalPaymentOption, can only be set to true in one instalment group).

Single-groups - Invoice with only one instalment group.
The invoice recipient can only pay with this instalment option

referenceNumber
string

Reference number of the referenced business case.
If the referenced invoice is found, it will be substituted with the new credit note, notification, or invoice.
In case of a reminder, the referenced invoice will not be substituted; at time of approval, the invoice recipient decides whether to pay the original invoice or the reminder.
If the referenced invoice is not found, a new business case is created.

object (ReferenceBill)
object (SinglePayment)
required
object (TotalAmount)
object (WorkFlow)

Responses

Response samples

Content type
application/json
{
  • "id": "NWPBCID0FB909852BBC4D06AD8336AAE87D7FC9"
}

Events

Notification Events The event resource allows the software partner to retrieve changes for the event type 'Subscription status changes'.

Find events for bill recipients email address changes

This event is triggered after any billerPid registered with the requesting SWP 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.

query Parameters
lastEventId
string <= 39 characters NWPEVID[0-9A-Z]{32}

Id of the last received event. If omitted, the result starts with the oldest available event. Example: '"NWPEVID82A65938766547EBBBA39BA6F7B07F24"' Maximal length: '39' Pattern: '"NWPEVID[0-9A-Z]{32}"'

limit
integer <= 10000
Default: 1000

Maximum number of events one wants to receive (technical maximum is 10000, no more will be returned at once and you have to fetch again to check if there are more)

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find events for bill recipient subscriptions which changed status

Events for status changes on bill recipient subscriptions to any billerPid registered with the requesting SWP, regardless if subscriptions have been done without registration form (event from infrastructure) or with registration form (no event from infrastructure).

query Parameters
lastEventId
string <= 39 characters NWPEVID[0-9A-Z]{32}

Id of the last received event. If omitted, the result starts with the oldest available event. Example: '"NWPEVID82A65938766547EBBBA39BA6F7B07F24"' Maximal length: '39' Pattern: '"NWPEVID[0-9A-Z]{32}"'

limit
integer <= 10000
Default: 1000

Maximum number of events one wants to receive (technical maximum is 10000, no more will be returned at once and you have to fetch again to check if there are more)

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find events for business cases which changed status

Events for status changes of bills, advices, credit notes and reminders which belong to any billerPid registered with the requesting SWP.

query Parameters
lastEventId
string <= 39 characters NWPEVID[0-9A-Z]{32}

Id of the last received event. If omitted, the result starts with the oldest available event. Example: '"NWPEVID82A65938766547EBBBA39BA6F7B07F24"' Maximal length: '39' Pattern: '"NWPEVID[0-9A-Z]{32}"'

limit
integer <= 10000
Default: 1000

Maximum number of events one wants to receive (technical maximum is 10000, no more will be returned at once and you have to fetch again to check if there are more)

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find events for instalments which changed status

Events for status changes of instalment bills only which belong to any billerPid registered with the requesting SWP.

query Parameters
lastEventId
string <= 39 characters NWPEVID[0-9A-Z]{32}

Id of the last received event. If omitted, the result starts with the oldest available event. Example: '"NWPEVID82A65938766547EBBBA39BA6F7B07F24"' Maximal length: '39' Pattern: '"NWPEVID[0-9A-Z]{32}"'

limit
integer <= 10000
Default: 1000

Maximum number of events one wants to receive (technical maximum is 10000, no more will be returned at once and you have to fetch again to check if there are more)

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sectors

Industry Sector Industry sectors are valid system wide. Each biller will reference one or several industry sectors.

Find Sectors

Get the industry sector list of the eBill infrastructure. The sectors are more or less static and can therefore be cached.

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Healthcheck

System Healthcheck This allows to check the basic state of the system (can it be reached, does authentication and auhorization work, does it respond). As some infrastructures block certain HTTP methods by default, the healthcheck allows to test if all required methods (GET, POST) work across all layers.

Health check using GET method

Returns a status message of the system.

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "1.0.23",
  • "applicationVersion": "1.4.3.0-desire-20180927091004161-71-5e3ca91",
  • "environmentStage": "XE",
  • "message": "The healthcheck GET resp. POST request was successfully received and processed",
  • "receivedHeaders": [
    ],
  • "requestDateTime": "2018-10-03T16:03:09.101+02:00"
}

Health check using POST method

Returns the request body. This operation will not modify the system.

header Parameters
Authorization
required
string

Access-Token with the prefix "Bearer".

Request Body schema: application/json

Any message which is expected in the response

message
required
string [ 1 .. 100 ] characters

expected response message from health check

Responses

Request samples

Content type
application/json
{
  • "message": "any String"
}

Response samples

Content type
application/json
{
  • "apiVersion": "1.0.23",
  • "applicationVersion": "1.4.3.0-desire-20180927091004161-71-5e3ca91",
  • "environmentStage": "XE",
  • "message": "The healthcheck GET resp. POST request was successfully received and processed",
  • "receivedHeaders": [
    ],
  • "requestDateTime": "2018-10-03T16:03:09.101+02:00"
}