API docs by Redocly

eBill Invoice API v2 (2.0.0)

Download OpenAPI specification:

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

https://portal-int.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-int.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": [
    ]
}