API docs by Redocly

eBill Invoice API v2 (2.0.0)

Download OpenAPI specification:

External invoice API, authenticated via the shared Keycloak invoice-api realm (same realm and client credentials as API v1).

Authentication

This API uses OAuth2 Client Secret Authentication (Client Credentials Grant). Request an access token from the token endpoint, then send it as a Bearer token in the Authorization header of every request.

Token endpoint

portal.ebill-service.de/auth/realms/InvoiceApi/protocol/openid-connect/token

1. Request an access token

Send a POST request with body x-www-form-urlencoded:

POST /auth/realms/InvoiceApi/protocol/openid-connect/token HTTP/1.1
Host: portal.ebill-service.de
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

2. Receive the access token

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 300
}

3. Call the API with the token

GET /invoice/sent HTTP/1.1
Host: api-v2.ebill-service.de
Authorization: Bearer eyJhbGciOi...

Limitations: an access_token is valid for 5 minutes; rate limit is 1000 requests/second.

Troubleshooting: invalid client ID/secret, an expired token, or a token scope that doesn't cover the requested resource all result in a 401/403 response - request a fresh token and verify the client credentials if you see one.

Invoices

GET /invoice/sent

List invoices sent by the authenticated company.

Authorizations:
CustomAuthorizer
query Parameters
search
string

Free-text search across invoice number, buyer/seller name and article labels

createdDateStart
string <date-time>
createdDateEnd
string <date-time>
invoiceIssueDateStart
string <date-time>
invoiceIssueDateEnd
string <date-time>
invoicePaymentDueDateStart
string <date-time>
invoicePaymentDueDateEnd
string <date-time>
totalAmountNetFrom
number
totalAmountNetTo
number
totalAmountGrossFrom
number
totalAmountGrossTo
number
invoiceTypeCode
string
sortBy
string

Comma-separated field:asc|desc pairs, e.g. createdAt:desc

offset
integer
Default: 0

Pagination offset (zero-based index of the first item to return)

size
integer <= 100
Default: 20

Page size (max 100)

includeAttachments
boolean
Default: false

When true, includes each invoice's attachments as {name, isInvoiceFile, url} with a 5-minute presigned download URL. Off by default (adds per-item S3 presigning latency).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": null,
  • "offset": null,
  • "size": null
}

GET /invoice/received

List invoices received by the authenticated company.

Authorizations:
CustomAuthorizer
query Parameters
search
string

Free-text search across invoice number, buyer/seller name and article labels

createdDateStart
string <date-time>
createdDateEnd
string <date-time>
invoiceIssueDateStart
string <date-time>
invoiceIssueDateEnd
string <date-time>
invoicePaymentDueDateStart
string <date-time>
invoicePaymentDueDateEnd
string <date-time>
totalAmountNetFrom
number
totalAmountNetTo
number
totalAmountGrossFrom
number
totalAmountGrossTo
number
invoiceTypeCode
string
sortBy
string

Comma-separated field:asc|desc pairs, e.g. createdAt:desc

offset
integer
Default: 0

Pagination offset (zero-based index of the first item to return)

size
integer <= 100
Default: 20

Page size (max 100)

includeAttachments
boolean
Default: false

When true, includes each invoice's attachments as {name, isInvoiceFile, url} with a 5-minute presigned download URL. Off by default (adds per-item S3 presigning latency).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": null,
  • "offset": null,
  • "size": null
}

POST /invoice/draft

Create exactly one invoice draft. Otherwise identical to POST /invoice/draft/batch - the only endpoint that also accepts a pdfTemplate (base64 PDF).

Authorizations:
CustomAuthorizer
Request Body schema: application/json
required
deliveryType
string (Deliverytype)
Default: "email"

'email' or 'nop' (do not send)

autoSend
boolean (Autosend)
Default: false

Finalize and send the draft immediately after creation (mirrors the old external API's autoSendDraft). Best-effort: a failure here does not fail the draft creation itself.

Pdftemplate (string) or Pdftemplate (null) (Pdftemplate)
Default: null

Base64-encoded PDF (max 1MB) stored as the invoice's document, same as the old external API's pdfTemplate field.

required
object (InvoiceData)

Invoice payload. Only lightly validated here - full EN 16931 validation happens downstream.

Responses

Request samples

Content type
application/json
{
  • "deliveryType": "email",
  • "autoSend": false,
  • "pdfTemplate": null,
  • "invoice": {
    }
}

Response samples

Content type
application/json
{
  • "batchId": "string",
  • "invoiceId": "string",
  • "invoiceNumber": ""
}

GET /invoice/{invoiceId}

Get the full invoice record by id.

Authorizations:
CustomAuthorizer
path Parameters
invoiceId
required
string <uuid>
query Parameters
includeAttachments
boolean
Default: true

When true (the default here, unlike the list endpoints), includes attachments as {name, isInvoiceFile, url} with a 5-minute presigned download URL. Set to false to skip presigning.

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "companyId": null,
  • "direction": null,
  • "status": "string",
  • "createdAt": null,
  • "invoiceNumber": null,
  • "invoiceType": null,
  • "invoice": null
}

POST /invoice/{invoiceId}/send

Finalize and send an existing draft invoice. Fire-and-forget: a 202 response means the send was triggered, not that the invoice has been sent yet.

Authorizations:
CustomAuthorizer
path Parameters
invoiceId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "status": "string"
}

POST /invoice/draft/batch

Create up to 200 invoice drafts in a single call.

Authorizations:
CustomAuthorizer
Request Body schema: application/json
required
required
Array of objects (Invoices) [ 1 .. 200 ] items

Responses

Request samples

Content type
application/json
{
  • "invoices": [
    ]
}

Response samples

Content type
application/json
{
  • "batchId": "string",
  • "total": 0,
  • "createdCount": 0,
  • "failedCount": 0,
  • "created": [
    ],
  • "errors": [
    ]
}

GET /invoice/batch/{batchId}

List all invoices created by a single POST /invoice/draft/batch call. Proxies live to the OpenSearch-backed /invoice/search endpoint, filtered by batchId - not a separate index.

Authorizations:
CustomAuthorizer
path Parameters
batchId
required
string <uuid>
query Parameters
includeAttachments
boolean
Default: false

When true, includes each invoice's attachments as {name, isInvoiceFile, url} with a 5-minute presigned download URL. Off by default (adds per-item S3 presigning latency).

Responses

Response samples

Content type
application/json
{
  • "batchId": "string",
  • "total": 0,
  • "data": [
    ]
}