Reference

OpenAPI Specification

Unsere vollständige API ist als OpenAPI 3.1 Spezifikation verfügbar. Nutze sie für Code-Generierung, API-Clients oder interaktive Dokumentation.

Download

OpenAPI YAML

Menschenlesbar, gut für Git

openapi.yaml

OpenAPI JSON

Für Tools und Code-Gen

openapi.json

Postman Collection

Direkt in Postman importieren

postman-collection.json

Swagger UI

Interaktiv im Browser

Swagger UI öffnen

Vorschau

Auszug aus der OpenAPI Spezifikation:

yaml

1openapi: 3.1.0
2info:
3  title: invoice.xhub API
4  version: 1.0.0
5  description: E-Rechnung API für XRechnung, ZUGFeRD und Peppol
6 
7servers:
8  - url: https://api.xhub.io/v1
9    description: Production
10  - url: https://sandbox.api.xhub.io/v1
11    description: Sandbox
12 
13paths:
14  /invoices:
15    post:
16      summary: Create Invoice
17      operationId: createInvoice
18      tags: [Creator]
19      security:
20        - bearerAuth: []
21      requestBody:
22        required: true
23        content:
24          application/json:
25            schema:
26              $ref: '#/components/schemas/CreateInvoiceRequest'
27      responses:
28        '200':
29          description: Invoice created successfully
30          content:
31            application/json:
32              schema:
33                $ref: '#/components/schemas/Invoice'
34 
35  /validate:
36    post:
37      summary: Validate Invoice
38      operationId: validateInvoice
39      tags: [Validator]
40      # ...
41 
42components:
43  securitySchemes:
44    bearerAuth:
45      type: http
46      scheme: bearer
47 
48  schemas:
49    CreateInvoiceRequest:
50      type: object
51      required: [format, seller, buyer, items]
52      properties:
53        format:
54          type: string
55          enum: [xrechnung-3.0, zugferd-2.1, factur-x-1.0]
56        invoiceNumber:
57          type: string
58        # ...

Import in API-Clients

Postman

bash

1# Via URL importieren
21. Öffne Postman
32. Klicke auf "Import" (oben links)
43. Wähle "Link" Tab
54. Füge ein: https://api.xhub.io/openapi.yaml
65. Klicke "Continue" → "Import"
7 
8# Alternativ: Collection herunterladen
9curl -O https://api.xhub.io/postman-collection.json

Insomnia

bash

1# Via URL importieren
21. Öffne Insomnia
32. Application → Preferences → Data
43. "Import Data" → "From URL"
54. URL: https://api.xhub.io/openapi.yaml
65. "Fetch and Import"

Code-Generierung

Generiere typsichere API-Clients aus der OpenAPI Spezifikation:

bash

1# TypeScript/JavaScript mit openapi-typescript
2npx openapi-typescript https://api.xhub.io/openapi.yaml -o ./types/api.d.ts
3 
4# Python mit openapi-python-client
5pip install openapi-python-client
6openapi-python-client generate --url https://api.xhub.io/openapi.yaml
7 
8# Go mit oapi-codegen
9go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
10oapi-codegen -package api https://api.xhub.io/openapi.yaml > api/api.gen.go

Empfohlene Tools

Postman

Beliebter API-Client mit Collection-Support

Insomnia

Open-Source REST-Client

Swagger UI

Interaktive API-Dokumentation

Redoc

Schöne API-Dokumentation aus OpenAPI

Versionierung

Die OpenAPI Spezifikation wird bei API-Änderungen aktualisiert. Nutze die Versionsnummer in der Spec, um Kompatibilität sicherzustellen. Breaking Changes werden im Changelog angekündigt.

Weiterführende Dokumentation

Quickstart

Erste Schritte

Authentication

API Keys einrichten

Creator API

Rechnungen erstellen

Playground

API interaktiv testen