{"openapi":"3.1.0","info":{"title":"billmatic API","version":"1.0.0","description":"The billmatic API, as far as an API key reaches: documents (invoices, offers, dunning notices, cancellations, credit notes, the archive), customers, products and recurring schedules of **one company**.\n\n## Every request\n\n- `Authorization: Bearer bm_…` — the API key. An owner or administrator creates it in billmatic under Organisation → API-Schlüssel, with a read and a write checkbox per resource.\n- `Accept: application/ld+json` — answers as JSON-LD. Without it the API answers in JSON:API.\n- `Content-Type: application/ld+json` on POST, `application/merge-patch+json` on PATCH. The body is a plain JSON object with the fields documented per operation.\n- Every path starts with `/api/v1/companies/{companyId}`. `{companyId}` is the UUID of the company the key belongs to; it is shown next to the key list. Any other company answers 404.\n\n## Answers\n\n- An item is a JSON object with the documented fields plus `@id` and `@type`. A list carries its entries in `member` and the total in `totalItems`; it is paged with `?page=` and `?itemsPerPage=`, and `view.next` names the next page while there is one.\n- Amounts are decimal strings (`\"1469.13\"`), never JSON numbers. Dates are ISO 8601.\n- GET needs the read permission; POST, PATCH and DELETE need write, which includes read. Products and recurring schedules also need the feature booked in the subscription.\n\n## Errors\n\n`401` the key is missing, wrong or revoked · `403` the key does not cover this (not ticked, not booked, or not reachable with a key at all; the reason is in `detail`) · `404` not found, or another company · `409` the state does not allow it, e.g. a document already published · `422` invalid fields, listed in `violations` with `propertyPath` and `message`. Refusals are worded in German.\n\n## Careful with documents\n\nPublishing gives a document its number and makes it a legal record that can only be corrected by a cancellation or a credit note. `send-mail` sends a real e-mail to the customer. Neither can be undone. Everything a key does is attributed to the person who created it."},"servers":[{"url":"https://api.billmatic.de"}],"paths":{"/api/v1/companies/{companyId}/archive":{"get":{"operationId":"api_v1companies_companyIdarchive_get_collection","tags":["Archive"],"responses":{"200":{"description":"ArchiveEntry collection","content":{"application/ld+json":{"schema":{"type":"object","description":"ArchiveEntry.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchema"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/ArchiveEntry.jsonld"}}}}]}}}}},"summary":"The company's archived documents, newest first","description":"Filter with `type`, page with `page` and `itemsPerPage`.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"page","in":"query","description":"The collection page number","required":false,"deprecated":false,"schema":{"type":"integer","default":1},"style":"form","explode":true},{"name":"itemsPerPage","in":"query","description":"The number of items per page","required":false,"deprecated":false,"schema":{"type":"integer","default":50,"minimum":0,"maximum":200},"style":"form","explode":true},{"name":"type","in":"query","description":"Optional type filter.","required":false,"deprecated":false,"schema":{"type":"string"},"style":"form","explode":true}]}},"/api/v1/companies/{companyId}/archive/{id}/pdf":{"get":{"operationId":"api_v1companies_companyIdarchive_idpdf_get","tags":["Archive"],"responses":{"200":{"description":"ArchiveEntry resource","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}}},"summary":"The archived PDF/A-3","description":"The archived PDF/A-3","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"ArchiveEntry identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/archive/{id}/xml":{"get":{"operationId":"api_v1companies_companyIdarchive_idxml_get","tags":["Archive"],"responses":{"200":{"description":"ArchiveEntry resource","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}}},"summary":"The archived XML","description":"The archived XML","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"ArchiveEntry identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/customers":{"get":{"operationId":"api_v1companies_companyIdcustomers_get_collection","tags":["Customer"],"responses":{"200":{"description":"Customer collection","content":{"application/ld+json":{"schema":{"type":"object","description":"Customer.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchema"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/Customer.jsonld"}}}}]}}}}},"summary":"Search customers","description":"Matches company, first name, last name, customer number and email. Use the returned `id` as `customerId` when creating a document. Page with `page` and `itemsPerPage`.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"page","in":"query","description":"The collection page number","required":false,"deprecated":false,"schema":{"type":"integer","default":1},"style":"form","explode":true},{"name":"itemsPerPage","in":"query","description":"The number of items per page","required":false,"deprecated":false,"schema":{"type":"integer","default":20,"minimum":0,"maximum":50},"style":"form","explode":true},{"name":"q","in":"query","description":"Optional search term.","required":false,"deprecated":false,"schema":{"type":"string","example":"Weidner"},"style":"form","explode":true}]},"post":{"operationId":"api_v1companies_companyIdcustomers_post","tags":["Customer"],"responses":{"201":{"description":"Customer resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Customer.jsonld"}}}}},"summary":"Create a customer","description":"When `number` is omitted, the next number from this company's own range is assigned.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new Customer resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Customer.CustomerCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/customers/{id}":{"get":{"operationId":"api_v1companies_companyIdcustomers_id_get","tags":["Customer"],"responses":{"200":{"description":"Customer resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Customer.jsonld"}}}}},"summary":"One customer","description":"One customer","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Customer identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"delete":{"operationId":"api_v1companies_companyIdcustomers_id_delete","tags":["Customer"],"responses":{"204":{"description":"Customer resource deleted"}},"summary":"Delete a customer","description":"Refused with 409 when the customer appears on any document.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Customer identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"patch":{"operationId":"api_v1companies_companyIdcustomers_id_patch","tags":["Customer"],"responses":{"200":{"description":"Customer resource updated","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Customer.jsonld"}}}}},"summary":"Change a customer","description":"Change a customer","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Customer identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The updated Customer resource","content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/Customer.CustomerUpdateInput.jsonMergePatch"}}},"required":true}}},"/api/v1/companies/{companyId}/cancellations/{id}":{"get":{"operationId":"api_v1companies_companyIdcancellations_id_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Get one cancellation invoice","description":"Get one cancellation invoice","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/credit-notes/{id}":{"get":{"operationId":"api_v1companies_companyIdcredit-notes_id_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Get one credit note","description":"Get one credit note","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/documents":{"get":{"operationId":"api_v1companies_companyIddocuments_get_collection","tags":["Document"],"responses":{"200":{"description":"Document collection","content":{"application/ld+json":{"schema":{"type":"object","description":"Document.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchema"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/Document.jsonld"}}}}]}}}}},"summary":"List all documents of a company","description":"Returns invoices, offers, cancellation invoices, credit notes and Mahnungen in one list, newest first. Filter with `type` and `status`, page with `page` and `itemsPerPage`.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"page","in":"query","description":"The collection page number","required":false,"deprecated":false,"schema":{"type":"integer","default":1},"style":"form","explode":true},{"name":"itemsPerPage","in":"query","description":"The number of items per page","required":false,"deprecated":false,"schema":{"type":"integer","default":50,"minimum":0,"maximum":200},"style":"form","explode":true},{"name":"type","in":"query","description":"Optional document type filter.","required":false,"deprecated":false,"schema":{"type":"string","enum":["INVOICE","CANCELLATION","CREDIT_NOTE","OFFER","DUNNING_NOTICE"]},"style":"form","explode":true},{"name":"status","in":"query","description":"Optional status filter.","required":false,"deprecated":false,"schema":{"type":"string","enum":["DRAFT","PUBLISHED","PAID","CANCELLED"]},"style":"form","explode":true}]}},"/api/v1/companies/{companyId}/documents/{id}/archive":{"post":{"operationId":"api_v1companies_companyIddocuments_idarchive_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Move a published document into the archive","description":"Move a published document into the archive","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/documents/{id}/pdf":{"get":{"operationId":"api_v1companies_companyIddocuments_idpdf_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}}},"summary":"The PDF/A-3 hybrid","description":"Answers application/pdf. Published documents only.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/documents/{id}/publish":{"post":{"operationId":"api_v1companies_companyIddocuments_idpublish_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Publish a draft — number, snapshots, totals, e-invoice, archive entry","description":"One operation that either fully happens or does not. A failed KOSIT validation consumes no number.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/documents/{id}/send-mail":{"post":{"operationId":"api_v1companies_companyIddocuments_idsend-mail_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Send the document to its recipient","description":"Uses this document type's own subject and template. A send failure leaves the document published and sets emailStatus to FAILED.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/documents/{id}/xml":{"get":{"operationId":"api_v1companies_companyIddocuments_idxml_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}}},"summary":"The XRechnung/ZUGFeRD XML","description":"Answers application/xml. Published documents only.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/dunning-notices/{id}":{"get":{"operationId":"api_v1companies_companyIddunning-notices_id_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Get one Mahnung","description":"Get one Mahnung","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/invoices":{"post":{"operationId":"api_v1companies_companyIdinvoices_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Create an invoice draft","description":"Creates a draft. It gets no number and is not a legal document until it is published.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.DocumentCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/invoices/{id}":{"get":{"operationId":"api_v1companies_companyIdinvoices_id_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Get one invoice","description":"Get one invoice","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"delete":{"operationId":"api_v1companies_companyIdinvoices_id_delete","tags":["Document"],"responses":{"204":{"description":"Document resource deleted"}},"summary":"Delete an invoice draft","description":"Draft only. A published invoice is refused with 409 — correct it with a cancellation.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"patch":{"operationId":"api_v1companies_companyIdinvoices_id_patch","tags":["Document"],"responses":{"200":{"description":"Document resource updated","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Change an invoice draft","description":"Draft only. Sending `lineItems` replaces every position.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The updated Document resource","content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/Document.DocumentUpdateInput.jsonMergePatch"}}},"required":true}}},"/api/v1/companies/{companyId}/invoices/{id}/cancellation":{"post":{"operationId":"api_v1companies_companyIdinvoices_idcancellation_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Derive a cancellation invoice from a published invoice","description":"Takes no body: the cancellation carries the original positions. It reverses the invoice when it is published, not when it is created.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/invoices/{id}/credit-note":{"post":{"operationId":"api_v1companies_companyIdinvoices_idcredit-note_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Derive a credit note from a cancelled, paid invoice","description":"Refused unless the invoice was cancelled and the money had actually been received — there is no refund to make otherwise.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/invoices/{id}/dunning-notices":{"post":{"operationId":"api_v1companies_companyIdinvoices_iddunning-notices_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Derive a Mahnung from an overdue invoice","description":"Refused with 409 unless the invoice is published, unpaid, uncancelled and past its `dueOn`, and unless `level` is the next Mahnstufe for it. Three positions at 0 %: the invoice's gross, the Mahngebühr and the Verzugszinsen, the last two omitted when zero. The invoice is never touched.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.DunningNoticeCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/invoices/{id}/duplicate":{"post":{"operationId":"api_v1companies_companyIdinvoices_idduplicate_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Duplicate an invoice — the copy is a draft","description":"Takes no body. The copy carries recipient, title, service period, texts and positions, and none of the publication: no number, no snapshots, no dates from the original. A draft duplicates too.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/invoices/{id}/mark-paid":{"post":{"operationId":"api_v1companies_companyIdinvoices_idmark-paid_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Mark a published invoice as paid","description":"Mark a published invoice as paid","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/invoices/{id}/mark-unpaid":{"post":{"operationId":"api_v1companies_companyIdinvoices_idmark-unpaid_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Undo a payment mark","description":"Undo a payment mark","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/offers":{"post":{"operationId":"api_v1companies_companyIdoffers_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Create an offer draft","description":"Create an offer draft","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.DocumentCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/offers/{id}":{"get":{"operationId":"api_v1companies_companyIdoffers_id_get","tags":["Document"],"responses":{"200":{"description":"Document resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Get one offer","description":"Get one offer","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"delete":{"operationId":"api_v1companies_companyIdoffers_id_delete","tags":["Document"],"responses":{"204":{"description":"Document resource deleted"}},"summary":"Delete an offer draft","description":"Delete an offer draft","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"patch":{"operationId":"api_v1companies_companyIdoffers_id_patch","tags":["Document"],"responses":{"200":{"description":"Document resource updated","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Change an offer draft","description":"Change an offer draft","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The updated Document resource","content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/Document.DocumentUpdateInput.jsonMergePatch"}}},"required":true}}},"/api/v1/companies/{companyId}/offers/{id}/duplicate":{"post":{"operationId":"api_v1companies_companyIdoffers_idduplicate_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Duplicate an offer — the copy is a draft","description":"As for an invoice, with the validity recomputed from today. Duplicating is not converting: the copy is an offer again and records no relation to its origin.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/offers/{id}/invoice":{"post":{"operationId":"api_v1companies_companyIdoffers_idinvoice_post","tags":["Document"],"responses":{"201":{"description":"Document resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Document.jsonld"}}}}},"summary":"Create an invoice draft from a published offer","description":"Copies the positions. The offer is unchanged and is not consumed.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Document identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/dunning-candidates":{"get":{"operationId":"api_v1companies_companyIddunning-candidates_get_collection","tags":["DunningCandidate"],"responses":{"200":{"description":"DunningCandidate collection","content":{"application/ld+json":{"schema":{"type":"object","description":"DunningCandidate.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchemaNoPagination"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/DunningCandidate.jsonld"}}}}]}}}}},"summary":"The overdue invoices of a company, most overdue first","description":"Published, unpaid, uncancelled invoices whose `dueOn` has passed, each with the Mahnstufe it has already reached and the one that would come next. Computed per request and stored nowhere; nothing is sent automatically.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]}},"/api/v1/companies/{companyId}/products":{"get":{"operationId":"api_v1companies_companyIdproducts_get_collection","tags":["Product"],"responses":{"200":{"description":"Product collection","content":{"application/ld+json":{"schema":{"type":"object","description":"Product.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchema"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/Product.jsonld"}}}}]}}}}},"summary":"Search products","description":"Matches name, description and Artikelnummer. Use the returned `productNumber` as a line item's `productNumber`. Page with `page` and `itemsPerPage`.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"page","in":"query","description":"The collection page number","required":false,"deprecated":false,"schema":{"type":"integer","default":1},"style":"form","explode":true},{"name":"itemsPerPage","in":"query","description":"The number of items per page","required":false,"deprecated":false,"schema":{"type":"integer","default":20,"minimum":0,"maximum":50},"style":"form","explode":true},{"name":"q","in":"query","description":"Optional search term.","required":false,"deprecated":false,"schema":{"type":"string","example":"Wartung"},"style":"form","explode":true}]},"post":{"operationId":"api_v1companies_companyIdproducts_post","tags":["Product"],"responses":{"201":{"description":"Product resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Product.jsonld"}}}}},"summary":"Create a product","description":"When `productNumber` is omitted, the next number from this company's own range is assigned.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new Product resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Product.ProductCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/products/{id}":{"get":{"operationId":"api_v1companies_companyIdproducts_id_get","tags":["Product"],"responses":{"200":{"description":"Product resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Product.jsonld"}}}}},"summary":"One product","description":"One product","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Product identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"delete":{"operationId":"api_v1companies_companyIdproducts_id_delete","tags":["Product"],"responses":{"204":{"description":"Product resource deleted"}},"summary":"Delete a product","description":"Never refused. No document points at a product, so nothing is left dangling.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Product identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"patch":{"operationId":"api_v1companies_companyIdproducts_id_patch","tags":["Product"],"responses":{"200":{"description":"Product resource updated","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Product.jsonld"}}}}},"summary":"Change a product","description":"Changes no document a position was already filled from — the position carries its own copy.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"Product identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The updated Product resource","content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/Product.ProductUpdateInput.jsonMergePatch"}}},"required":true}}},"/api/v1/companies/{companyId}/recurring-schedules":{"get":{"operationId":"api_v1companies_companyIdrecurring-schedules_get_collection","tags":["RecurringSchedule"],"responses":{"200":{"description":"RecurringSchedule collection","content":{"application/ld+json":{"schema":{"type":"object","description":"RecurringSchedule.jsonld collection.","allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchema"},{"type":"object","required":["member"],"properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/RecurringSchedule.jsonld"}}}}]}}}}},"summary":"List the recurring schedules","description":"Readable whether or not `RECURRING_INVOICES` is booked. When it is not, every entry carries `readOnlyReason`. Page with `page` and `itemsPerPage`.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"page","in":"query","description":"The collection page number","required":false,"deprecated":false,"schema":{"type":"integer","default":1},"style":"form","explode":true},{"name":"itemsPerPage","in":"query","description":"The number of items per page","required":false,"deprecated":false,"schema":{"type":"integer","default":20,"minimum":0,"maximum":50},"style":"form","explode":true}]},"post":{"operationId":"api_v1companies_companyIdrecurring-schedules_post","tags":["RecurringSchedule"],"responses":{"201":{"description":"RecurringSchedule resource created","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/RecurringSchedule.jsonld"}}}}},"summary":"Create a recurring schedule","description":"Refused with 403 when `RECURRING_INVOICES` is not booked. The first run is `startDate` itself; no proration and no partial first period.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The new RecurringSchedule resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/RecurringSchedule.RecurringScheduleCreateInput"}}},"required":true}}},"/api/v1/companies/{companyId}/recurring-schedules/{id}":{"get":{"operationId":"api_v1companies_companyIdrecurring-schedules_id_get","tags":["RecurringSchedule"],"responses":{"200":{"description":"RecurringSchedule resource","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/RecurringSchedule.jsonld"}}}}},"summary":"One recurring schedule","description":"Carries the template positions and the invoices generated so far.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"RecurringSchedule identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"delete":{"operationId":"api_v1companies_companyIdrecurring-schedules_id_delete","tags":["RecurringSchedule"],"responses":{"204":{"description":"RecurringSchedule resource deleted"}},"summary":"Delete a recurring schedule","description":"The invoices it issued are untouched and keep their numbers — `recurring_schedule_id` is set to NULL on them, never cascaded.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"RecurringSchedule identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}]},"patch":{"operationId":"api_v1companies_companyIdrecurring-schedules_id_patch","tags":["RecurringSchedule"],"responses":{"200":{"description":"RecurringSchedule resource updated","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/RecurringSchedule.jsonld"}}}}},"summary":"Change a recurring schedule","description":"Changes no invoice it has already issued — every one of those carries its own copy. Sending `lineItems` replaces the whole template.","parameters":[{"name":"companyId","in":"path","description":"UUID of the company the API key belongs to. Any other company answers 404.","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false},{"name":"id","in":"path","description":"RecurringSchedule identifier","required":true,"deprecated":false,"schema":{"type":"string"},"style":"simple","explode":false}],"requestBody":{"description":"The updated RecurringSchedule resource","content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/RecurringSchedule.RecurringScheduleUpdateInput.jsonMergePatch"}}},"required":true}}}},"components":{"schemas":{"ArchiveEntry.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"type":"string"},"companyId":{"description":"The company this entry belongs to.","type":"string"},"type":{"example":"invoice","type":"string"},"number":{"type":["string","null"]},"issuedOn":{"type":["string","null"]},"totalNet":{"type":["string","null"]},"totalVat":{"type":["string","null"]},"totalGross":{"type":["string","null"]},"sha256":{"description":"SHA-256 of the archived PDF — what makes the record verifiable.","type":"string"},"hasXml":{"type":"boolean"},"archivedAt":{"type":"string"}}}],"description":"The GoBD archive: an immutable record of what was issued, kept for ten years."},"Customer.CustomerCreateInput":{"type":"object","description":"Customers — the recipients a Company bills.","properties":{"company":{"example":"DB","type":["string","null"]},"salutation":{"enum":["Herr","Frau","Divers"],"description":"Required salutation. Allowed values are `Herr`, `Frau` and `Divers`.","example":"Herr","type":["string","null"]},"firstName":{"example":"Peter","type":["string","null"]},"lastName":{"example":"Fuchs","type":["string","null"]},"number":{"description":"Optional customer number. When omitted, Billmatic generates the next available customer number for the company.","example":"10007","type":["string","null"]},"street":{"example":"Main Street 1","type":["string","null"]},"zipCode":{"example":"01067","type":["string","null"]},"city":{"example":"Dresden","type":["string","null"]},"country":{"description":"Required ISO 3166-1 alpha-2 country code.","example":"DE","type":["string","null"]},"email":{"format":"email","externalDocs":{"url":"https://schema.org/email"},"example":"customer@example.test","type":["string","null"]},"phone":{"example":"+49 351 123456","type":["string","null"]},"mobile":{"example":"+49 170 1234567","type":["string","null"]},"taxId":{"description":"Optional tax ID. Required by Billmatic validation when the country is not Germany.","example":"DE123456789","type":["string","null"]},"isPublicAuthority":{"description":"Whether the customer is a public authority. If true, `buyerReferenceId` is required.","example":false,"type":"boolean"},"buyerReferenceId":{"description":"Optional buyer reference / Leitweg-ID. Required for public authorities.","example":"991-12345-67","type":["string","null"]}},"required":["salutation","firstName","lastName","street","zipCode","city","country","email"]},"Customer.CustomerUpdateInput.jsonMergePatch":{"type":"object","description":"Customers — the recipients a Company bills.","properties":{"company":{"type":["string","null"]},"salutation":{"enum":["Herr","Frau","Divers"],"description":"Allowed values are `Herr`, `Frau` and `Divers`; null clears it.","example":"Divers","type":["string","null"]},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"number":{"type":["string","null"]},"street":{"type":["string","null"]},"zipCode":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"mobile":{"type":["string","null"]},"taxId":{"type":["string","null"]},"isPublicAuthority":{"type":["boolean","null"]},"buyerReferenceId":{"description":"Leitweg-ID. Required for a public authority.","type":["string","null"]}}},"Customer.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"description":"Customer UUID. Use this value as `customerId` when creating a document.","example":"1f083991-caf1-4e2d-843d-4520d3fd5391","type":"string"},"companyId":{"description":"The company this customer belongs to — the `{companyId}` of every route that reaches them.","type":"string"},"displayName":{"description":"Human-readable display name.","example":"Weidner Bau GmbH","type":"string"},"number":{"description":"Customer number.","example":"10007","type":["string","null"]},"company":{"description":"Company name, if available.","example":"Weidner Bau GmbH","type":["string","null"]},"firstName":{"description":"First name, if available.","example":"Peter","type":["string","null"]},"lastName":{"description":"Last name, if available.","example":"Fuchs","type":["string","null"]},"email":{"description":"Email address, if available.","example":"buchhaltung@weidner-bau.de","type":["string","null"]},"city":{"description":"City.","example":"Dresden","type":["string","null"]},"country":{"description":"Country code.","example":"DE","type":["string","null"]},"salutation":{"description":"Salutation.","example":"mr","type":["string","null"]},"street":{"description":"Street and number.","example":"Bautzner Straße 41","type":["string","null"]},"zipCode":{"description":"Postal code.","example":"01099","type":["string","null"]},"phone":{"description":"Phone number.","example":"+49 351 4820","type":["string","null"]},"mobile":{"description":"Mobile number.","type":["string","null"]},"taxId":{"description":"VAT identifier of the customer.","example":"DE123456789","type":["string","null"]},"isPublicAuthority":{"description":"A public authority needs a Leitweg-ID on every e-invoice.","type":"boolean"},"buyerReferenceId":{"description":"Leitweg-ID / buyer reference.","example":"991-33333TEST-33","type":["string","null"]},"paymentTermDays":{"description":"Payment term in days; null falls back to the Company default.","example":14,"type":["integer","null"]}}}],"description":"Customers — the recipients a Company bills."},"Document.DocumentCreateInput":{"type":"object","description":"The document — everything you can read from one and everything you can do to one.","required":["customerId"],"properties":{"customerId":{"description":"UUID of an existing customer of this company.","type":"string"},"title":{"type":["string","null"]},"issuedOn":{"type":["string","null"],"format":"date-time"},"dueOn":{"description":"Invoices only. Defaults to the agreed payment term.","type":["string","null"],"format":"date-time"},"expiresOn":{"description":"Offers only. Defaults to 14 days.","type":["string","null"],"format":"date-time"},"servicePeriodFrom":{"type":["string","null"],"format":"date-time"},"servicePeriodTo":{"type":["string","null"],"format":"date-time"},"introText":{"description":"Overrides the default text template for this document type.","type":["string","null"]},"closingText":{"type":["string","null"]},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/DocumentLineItemInput"}}}},"Document.DocumentUpdateInput.jsonMergePatch":{"type":"object","description":"The document — everything you can read from one and everything you can do to one.","properties":{"customerId":{"description":"UUID of a customer of this company.","type":["string","null"]},"title":{"type":["string","null"]},"issuedOn":{"type":["string","null"],"format":"date-time"},"dueOn":{"description":"Invoices only.","type":["string","null"],"format":"date-time"},"expiresOn":{"description":"Offers only.","type":["string","null"],"format":"date-time"},"servicePeriodFrom":{"type":["string","null"],"format":"date-time"},"servicePeriodTo":{"type":["string","null"],"format":"date-time"},"introText":{"type":["string","null"]},"closingText":{"type":["string","null"]},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/DocumentLineItemInput"}}}},"Document.DunningNoticeCreateInput":{"type":"object","description":"The document — everything you can read from one and everything you can do to one.","properties":{"level":{"minimum":1,"maximum":3,"description":"The Mahnstufe — 1 is the Zahlungserinnerung. Must be the next one for this invoice.","example":1,"type":"integer"},"fee":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Mahngebühr as a decimal string in Euro, two places. Zero leaves the position off.","example":"5.00","type":"string"},"interest":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Verzugszinsen as a decimal string in Euro, two places. Zero leaves the position off.","example":"2.35","type":"string"}}},"Document.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"description":"Document UUID.","type":"string"},"number":{"description":"Null while the document is a draft.","example":"RE-2026-00000001","type":["string","null"]},"type":{"example":"INVOICE","type":"string"},"status":{"example":"PUBLISHED","type":"string"},"displayStatus":{"description":"The stored status folded together with the two questions whose answer depends on the day they are asked: an invoice past its `dueOn` reads `overdue`, an unconverted offer past its `expiresOn` reads `expired`. Computed per request, never stored — `status` stays the truth.","example":"overdue","type":"string","enum":["draft","open","paid","overdue","cancelled","converted","expired"]},"isCancellable":{"description":"Whether a Storno may be derived from this document right now — the domain rule behind `POST …/invoices/{id}/cancellation`, so the interface never re-derives it.","type":"boolean"},"isCreditNoteCreatable":{"description":"Whether a Gutschrift may be derived from this document right now — the domain rule behind `POST …/invoices/{id}/credit-note`, including the cap that refuses a second one.","type":"boolean"},"isDuplicable":{"description":"Whether this document may be duplicated — the domain rule behind `POST …/duplicate`: true on an invoice and on an offer, draft or published, false on the three kinds that cannot exist without the invoice they refer to.","type":"boolean"},"hasElectronicInvoice":{"description":"Whether this kind carries an XRechnung payload at all. False on an offer and on a Mahnung, and then `…/documents/{id}/xml` has nothing to answer with.","type":"boolean"},"title":{"type":["string","null"]},"companyId":{"type":"string"},"customerId":{"type":["string","null"]},"customerName":{"type":["string","null"]},"issuedOn":{"type":["string","null"]},"dueOn":{"type":["string","null"]},"expiresOn":{"type":["string","null"]},"servicePeriodFrom":{"type":["string","null"]},"servicePeriodTo":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"paidAt":{"type":["string","null"]},"archivedAt":{"type":["string","null"]},"emailStatus":{"type":"string"},"net":{"description":"Exact decimal string, never a JSON number.","example":"1234.56","type":"string"},"tax":{"type":"string"},"total":{"description":"Always positive.","example":"1469.13","type":"string"},"signedTotal":{"description":"Negative for a cancellation invoice and a credit note.","example":"-1469.13","type":"string"},"introText":{"type":["string","null"]},"closingText":{"type":["string","null"]},"originalInvoiceId":{"type":["string","null"]},"originalInvoiceNumber":{"type":["string","null"]},"dunningLevel":{"description":"The Mahnstufe, on a Mahnung and nowhere else. 1 is the Zahlungserinnerung.","example":1,"type":["integer","null"]},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/DocumentLineItemOutput.jsonld"}},"taxGroups":{"type":"array","items":{"$ref":"#/components/schemas/DocumentTaxGroupOutput.jsonld"}}}}],"description":"The document — everything you can read from one and everything you can do to one."},"DocumentLineItemInput":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":["string","null"]},"quantity":{"pattern":"^(\\d+(\\.\\d{1,4})?)$","description":"Decimal string, up to four places.","example":"7.35","type":"string"},"unitPrice":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Decimal string in Euro, two places.","example":"125.00","type":"string"},"unit":{"type":["string","null"],"enum":["YEAR","MONTH","WEEK","DAY","HOUR","MINUTE","CENTIMETER","METER","KILOMETER","SQUARE_CENTIMETER","SQUARE_METER","HECTARE","CUBIC_CENTIMETER","LITER","CUBIC_METER","TON","KILOGRAM","GRAM","KILOWATT_HOUR","PIECE","NUMBER_OF_ARTICLES","PAIRS","SET","PACKAGE","FLAT_RATE","PERCENTAGE",null]},"taxRate":{"type":["integer","null"],"enum":[0,7,19,null]},"productNumber":{"type":["string","null"]}}},"DocumentLineItemOutput.jsonld":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"integer"},"title":{"type":"string"},"description":{"type":["string","null"]},"quantity":{"description":"Exact decimal string with up to four places.","example":"7.3500","type":"string"},"unit":{"type":["string","null"]},"unitPrice":{"example":"125.00","type":"string"},"taxRate":{"description":"Percent.","example":19,"type":"integer"},"net":{"description":"Quantity times unit price, rounded to the cent.","example":"918.75","type":"string"},"productNumber":{"description":"The Artikelstamm entry this position was filled from, if any. A plain string, not a reference — editing or deleting that product changes nothing here.","example":"10000","type":["string","null"]}}},"DocumentTaxGroupOutput.jsonld":{"type":"object","properties":{"rate":{"description":"Percent.","example":19,"type":"integer"},"net":{"description":"The taxable base for this rate.","example":"1000.00","type":"string"},"tax":{"description":"Rounded once, from the base above.","example":"190.00","type":"string"}}},"DunningCandidate.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"description":"The overdue invoice. The candidate has no identity of its own — this is the invoice's id.","type":"string"},"companyId":{"type":"string"},"number":{"example":"RE-2026-00000001","type":["string","null"]},"customerName":{"type":["string","null"]},"issuedOn":{"type":["string","null"]},"dueOn":{"type":["string","null"]},"daysOverdue":{"description":"Whole days since `dueOn` passed. One on the first day the invoice is late.","example":17,"type":"integer"},"total":{"description":"Exact decimal string, never a JSON number.","example":"1469.13","type":"string"},"highestLevelIssued":{"description":"The highest Mahnstufe already written for this invoice, drafts included. Zero where there is none.","example":0,"type":"integer"},"nextLevel":{"description":"The Mahnstufe the derive endpoint would accept right now.","example":1,"type":"integer"}}}],"description":"The invoices that are asking to be dunned — a work list, not a table."},"HydraCollectionBaseSchema":{"allOf":[{"$ref":"#/components/schemas/HydraCollectionBaseSchemaNoPagination"},{"type":"object","properties":{"view":{"type":"object","properties":{"@id":{"type":"string","format":"iri-reference"},"@type":{"type":"string"},"first":{"type":"string","format":"iri-reference"},"last":{"type":"string","format":"iri-reference"},"previous":{"type":"string","format":"iri-reference"},"next":{"type":"string","format":"iri-reference"}},"example":{"@id":"string","@type":"string","first":"string","last":"string","previous":"string","next":"string"}}}}]},"HydraCollectionBaseSchemaNoPagination":{"type":"object","properties":{"totalItems":{"type":"integer","minimum":0},"search":{"type":"object","properties":{"@type":{"type":"string"},"template":{"type":"string"},"variableRepresentation":{"type":"string"},"mapping":{"type":"array","items":{"type":"object","properties":{"@type":{"type":"string"},"variable":{"type":"string"},"property":{"type":["string","null"]},"required":{"type":"boolean"}}}}}}}},"HydraItemBaseSchema":{"type":"object","properties":{"@context":{"oneOf":[{"type":"string"},{"type":"object","properties":{"@vocab":{"type":"string"},"hydra":{"type":"string","enum":["http://www.w3.org/ns/hydra/core#"]}},"required":["@vocab","hydra"],"additionalProperties":true}]},"@id":{"type":"string"},"@type":{"type":"string"}},"required":["@id","@type"]},"Product.ProductCreateInput":{"type":"object","description":"Products — the Artikelstamm a Company fills its positions from.","required":["name","unit","taxRate"],"properties":{"name":{"example":"Wartung, Support (Juli)","type":["string","null"]},"description":{"example":"Monatliche Wartung inklusive Fernzugriff.","type":["string","null"]},"unitPrice":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Decimal string in Euro, two places.","example":"125.00","type":"string"},"unit":{"description":"Unit code. The same closed set a document position takes.","example":"HOUR","type":["string","null"],"enum":["YEAR","MONTH","WEEK","DAY","HOUR","MINUTE","CENTIMETER","METER","KILOMETER","SQUARE_CENTIMETER","SQUARE_METER","HECTARE","CUBIC_CENTIMETER","LITER","CUBIC_METER","TON","KILOGRAM","GRAM","KILOWATT_HOUR","PIECE","NUMBER_OF_ARTICLES","PAIRS","SET","PACKAGE","FLAT_RATE","PERCENTAGE",null]},"taxRate":{"description":"Percent — 0, 7 or 19.","example":19,"type":["integer","null"],"enum":[0,7,19,null]},"productNumber":{"description":"Optional Artikelnummer. When omitted, billmatic assigns the next free number of this company.","example":"10000","type":["string","null"]}}},"Product.ProductUpdateInput.jsonMergePatch":{"type":"object","description":"Products — the Artikelstamm a Company fills its positions from.","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"unitPrice":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Decimal string in Euro, two places. An explicit null is 0,00 €.","example":"125.00","type":["string","null"]},"unit":{"type":["string","null"],"enum":["YEAR","MONTH","WEEK","DAY","HOUR","MINUTE","CENTIMETER","METER","KILOMETER","SQUARE_CENTIMETER","SQUARE_METER","HECTARE","CUBIC_CENTIMETER","LITER","CUBIC_METER","TON","KILOGRAM","GRAM","KILOWATT_HOUR","PIECE","NUMBER_OF_ARTICLES","PAIRS","SET","PACKAGE","FLAT_RATE","PERCENTAGE",null]},"taxRate":{"description":"Percent — 0, 7 or 19.","example":19,"type":["integer","null"],"enum":[0,7,19,null]},"productNumber":{"type":["string","null"]}}},"Product.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"description":"Product UUID.","example":"1f083991-caf1-4e2d-843d-4520d3fd5391","type":"string"},"companyId":{"description":"The company whose catalogue this entry belongs to — the `{companyId}` of every route that reaches it.","type":"string"},"productNumber":{"description":"Artikelnummer, unique within the company. What a filled position carries as `productNumber`.","example":"10000","type":"string"},"name":{"description":"What the filled position is called.","example":"Wartung, Support (Juli)","type":"string"},"description":{"description":"The longer text, copied onto the position.","example":"Monatliche Wartung inklusive Fernzugriff.","type":["string","null"]},"unitPrice":{"description":"Decimal string in Euro, two places.","example":"125.00","type":"string"},"unit":{"description":"Unit code, from the same closed set a position takes.","example":"HOUR","type":["string","null"]},"taxRate":{"description":"Percent — 0, 7 or 19.","example":19,"type":["integer","null"]}}}],"description":"Products — the Artikelstamm a Company fills its positions from."},"RecurringSchedule.RecurringScheduleCreateInput":{"type":"object","description":"Abo-Rechnungen — the schedules that issue invoices on their own.","required":["recipientId","interval","startDate"],"properties":{"recipientId":{"description":"UUID of a customer of this company.","type":["string","null"]},"interval":{"description":"MONTHLY | QUARTERLY | HALF_YEARLY | YEARLY.","example":"MONTHLY","type":["string","null"],"enum":["MONTHLY","QUARTERLY","HALF_YEARLY","YEARLY",null]},"startDate":{"description":"The first period. Its day of the month anchors every later one.","example":"2026-01-31","type":["string","null"],"format":"date-time"},"endDate":{"description":"Inclusive. Omitted, the schedule runs until it is paused or deleted.","example":"2026-12-31","type":["string","null"],"format":"date-time"},"isActive":{"description":"False creates the schedule paused.","type":"boolean"},"introText":{"type":["string","null"]},"closingText":{"type":["string","null"]},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/RecurringScheduleLineItemInput"}}}},"RecurringSchedule.RecurringScheduleUpdateInput.jsonMergePatch":{"type":"object","description":"Abo-Rechnungen — the schedules that issue invoices on their own.","properties":{"recipientId":{"description":"UUID of a customer of this company.","type":["string","null"]},"interval":{"description":"MONTHLY | QUARTERLY | HALF_YEARLY | YEARLY.","example":"MONTHLY","type":["string","null"],"enum":["MONTHLY","QUARTERLY","HALF_YEARLY","YEARLY",null]},"startDate":{"example":"2026-01-31","type":["string","null"],"format":"date-time"},"endDate":{"description":"Inclusive. An explicit null lets the schedule run on indefinitely.","example":"2026-12-31","type":["string","null"],"format":"date-time"},"isActive":{"description":"False pauses the schedule; true resumes it.","type":["boolean","null"]},"introText":{"type":["string","null"]},"closingText":{"type":["string","null"]},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/RecurringScheduleLineItemInput"}}}},"RecurringSchedule.jsonld":{"allOf":[{"$ref":"#/components/schemas/HydraItemBaseSchema"},{"type":"object","properties":{"id":{"description":"Schedule UUID.","example":"1f083991-caf1-4e2d-843d-4520d3fd5391","type":"string"},"companyId":{"description":"The company issuing — the `{companyId}` of every route that reaches it.","type":"string"},"recipientId":{"type":"string"},"recipientName":{"description":"The recipient as the list shows them.","example":"Kundin Kunze","type":"string"},"interval":{"description":"MONTHLY | QUARTERLY | HALF_YEARLY | YEARLY.","example":"MONTHLY","type":"string"},"startDate":{"description":"The first period, and the anchor every later one is measured from.","example":"2026-01-31","type":"string"},"endDate":{"description":"Inclusive. A period whose run date falls after it is not generated.","example":"2026-12-31","type":["string","null"]},"nextRunOn":{"description":"The period the next run generates.","example":"2026-02-28","type":"string"},"isActive":{"description":"False pauses the schedule without deleting it. A paused schedule accumulates no back-invoices.","type":"boolean"},"introText":{"type":["string","null"]},"closingText":{"type":["string","null"]},"lastRunAt":{"description":"When the runner last considered this schedule.","example":"2026-02-28T03:00:00+00:00","type":["string","null"]},"lastSkipReason":{"description":"Why the last run produced nothing, or null when it produced an invoice.","example":"FEATURE_NOT_BOOKED","type":["string","null"]},"readOnlyReason":{"description":"Why this schedule is read-only, ready to show — or null when it may be changed.","type":["string","null"]},"net":{"description":"The template net, with tax rounded once per rate.","example":"99.00","type":"string"},"tax":{"example":"18.81","type":"string"},"total":{"description":"What each invoice this schedule issues will come to.","example":"117.81","type":"string"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/RecurringScheduleLineItemOutput.jsonld"}},"invoices":{"type":"array","items":{"$ref":"#/components/schemas/RecurringScheduleInvoiceOutput.jsonld"}}}}],"description":"Abo-Rechnungen — the schedules that issue invoices on their own."},"RecurringScheduleInvoiceOutput.jsonld":{"type":"object","properties":{"id":{"type":"string"},"number":{"description":"Null while the invoice is still a draft — a refused publication leaves one behind.","type":["string","null"]},"period":{"description":"The period this invoice covers. The schedule's own run date.","example":"2026-01-31","type":"string"},"issuedOn":{"description":"The Rechnungsdatum: the day the run happened, which differs from the period when a run caught up.","example":"2026-01-31","type":["string","null"]},"total":{"example":"117.81","type":"string"},"status":{"description":"DRAFT | PUBLISHED | PAID | CANCELLED.","example":"PUBLISHED","type":"string"},"emailStatus":{"description":"UNSENT | SENT | FAILED.","example":"SENT","type":"string"}}},"RecurringScheduleLineItemInput":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":["string","null"]},"quantity":{"pattern":"^(\\d+(\\.\\d{1,4})?)$","description":"Decimal string, up to four places.","example":"1","type":"string"},"unitPrice":{"pattern":"^(\\d+(\\.\\d{1,2})?)$","description":"Decimal string in Euro, two places.","example":"99.00","type":"string"},"unit":{"type":["string","null"],"enum":["YEAR","MONTH","WEEK","DAY","HOUR","MINUTE","CENTIMETER","METER","KILOMETER","SQUARE_CENTIMETER","SQUARE_METER","HECTARE","CUBIC_CENTIMETER","LITER","CUBIC_METER","TON","KILOGRAM","GRAM","KILOWATT_HOUR","PIECE","NUMBER_OF_ARTICLES","PAIRS","SET","PACKAGE","FLAT_RATE","PERCENTAGE",null]},"taxRate":{"description":"Percent — 0, 7 or 19.","example":19,"type":["integer","null"],"enum":[0,7,19,null]},"productNumber":{"type":["string","null"]}}},"RecurringScheduleLineItemOutput.jsonld":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"integer"},"title":{"type":"string"},"description":{"type":["string","null"]},"quantity":{"description":"Exact decimal string with up to four places.","example":"1.0000","type":"string"},"unit":{"type":["string","null"]},"unitPrice":{"example":"99.00","type":"string"},"taxRate":{"description":"Percent — 0, 7 or 19.","example":19,"type":["integer","null"]},"net":{"description":"Quantity times unit price, rounded to the cent.","example":"99.00","type":"string"},"productNumber":{"description":"The Artikelstamm entry this template was filled from, if any. A plain string, not a reference.","example":"10000","type":["string","null"]}}}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Value for the http bearer parameter.","scheme":"bearer","bearerFormat":"API key"}}},"security":[{"bearerAuth":[]}]}