{"openapi":"3.1.0","info":{"title":"Rechnungskit API","version":"1.0.0","description":"Push orders and fulfillment events, inspect invoice status, and retrieve archived PDF/XML documents."},"externalDocs":{"description":"Quickstart and integration flows","url":"https://rechnungskit.de/api"},"servers":[{"url":"https://api.rechnungskit.de/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/orders":{"post":{"summary":"Create or update an order","description":"Use your stable orderNo as the correlation key. The returned id is an internal order ID, not an invoice ID. Poll GET /orders/{orderNo} to discover generated invoices.","security":[{"bearerAuth":["orders:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"200":{"description":"Order updated or idempotently replayed"},"201":{"description":"Order created"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/orders/{orderNo}":{"get":{"summary":"Inspect an API order and its invoices","description":"Preferred invoice discovery flow. Once invoicing starts, invoices[] contains the exact UUID, document number, status, and metadata URL for each document linked to the order.","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"name":"orderNo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order status"},"404":{"description":"Not found"}}}},"/fulfillments":{"post":{"summary":"Report fulfillment status","security":[{"bearerAuth":["orders:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentInput"}}}},"responses":{"200":{"description":"Fulfillment accepted"}}}},"/invoices":{"get":{"summary":"List invoices with cursor pagination","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["created","archived","failed"]}},{"name":"number","in":"query","schema":{"type":"string"}},{"name":"orderNo","in":"query","schema":{"type":"string"}},{"name":"paymentRef","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice page"}}}},"/invoices/{reference}":{"get":{"summary":"Get invoice metadata by UUID, number, order number, or payment reference","description":"For orders with corrections or multiple documents, discover invoices through GET /orders/{orderNo} and use the returned UUID to address one exact document.","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/InvoiceReference"}],"responses":{"200":{"description":"Invoice metadata"},"404":{"description":"Not found"}}}},"/invoices/{reference}/pdf":{"get":{"summary":"Download the archived invoice as PDF","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/InvoiceReference"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}}}}},"/invoices/{reference}/xml":{"get":{"summary":"Download the archived EN 16931 XML","description":"Not available for reduced § 33 UStDV small-amount invoices.","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/InvoiceReference"}],"responses":{"200":{"description":"XML","content":{"application/xml":{"schema":{"type":"string"}}}},"409":{"description":"Not archived yet or XML is not applicable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_*"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}},"InvoiceReference":{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"ValidationError":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Address":{"type":"object","required":["country_code"],"properties":{"name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"vat_id":{"type":["string","null"]},"street":{"type":["string","null"]},"additional_address_line":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"country_code":{"type":"string","pattern":"^[A-Z]{2}$"}}},"OrderInput":{"type":"object","required":["orderNo","billingAddress","items"],"properties":{"orderNo":{"type":"string"},"paymentRef":{"type":["string","null"]},"paymentGateway":{"type":["string","null"],"description":"Gateway identifier. For invoice-first orders it must match a gateway enabled in the project Connect settings."},"financialStatus":{"type":["string","null"],"description":"External financial status such as pending or paid."},"email":{"type":["string","null"],"format":"email"},"currency":{"type":"string","default":"EUR"},"requiresShipping":{"type":"boolean","default":false},"billingAddress":{"$ref":"#/components/schemas/Address"},"shippingAddress":{"$ref":"#/components/schemas/Address"},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["name","quantity"],"properties":{"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unitNetCents":{"type":"integer"},"unitGrossCents":{"type":"integer"},"taxRate":{"type":["number","null"]},"giftCard":{"type":"boolean"}},"anyOf":[{"required":["unitNetCents"]},{"required":["unitGrossCents"]}]}}}},"FulfillmentInput":{"type":"object","required":["orderNo"],"properties":{"orderNo":{"type":"string"},"status":{"type":"string","enum":["unfulfilled","partial","fulfilled"]},"shippedAt":{"type":["string","null"],"format":"date-time"},"trackingNumber":{"type":["string","null"]}}},"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}},"requestId":{"type":"string"}}}}}}