{"openapi":"3.1.0","info":{"title":"CastPDF API","version":"1.0.0","description":"Generate PDFs from templates or HTML. Reference: https://castpdf.com/docs/api","contact":{"name":"CastPDF support","url":"https://castpdf.com/contact"}},"servers":[{"url":"https://api.castpdf.com"}],"security":[{"apiKey":[]}],"tags":[{"name":"PDFs"},{"name":"Documents"},{"name":"Templates"},{"name":"Batches"},{"name":"Spreadsheets"},{"name":"Webhooks"},{"name":"Account"}],"paths":{"/v1/pdf":{"post":{"tags":["PDFs"],"summary":"Create a PDF","operationId":"createPdf","description":"Renders a template (template_id) or raw html. response: binary (default, the PDF) or url (JSON with a signed link). With async: true the answer is 202 and the result arrives as pdf.created or pdf.failed. deliver.email emails the PDF. test: true makes a watermarked test document (not counted) even with a live key. e_invoice issues a structured invoice as Factur-X / ZUGFeRD (a PDF/A-3b with the XML embedded) or XRechnung (the XML itself, application/xml); see the EInvoice schema. merge_data is for no-code forms (GET /v1/templates/{id}/fields, tree): its empty values (null, empty strings, empty objects and arrays) are dropped and the rest is deep-merged over data. The JSON answer (response: url) carries every Document field, plus filename, metadata, warnings and blocked_resources.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. The same key and body within 24 hours return the first result instead of doing the work again.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"template_id":{"type":"string","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"template_version":{"type":"integer","minimum":1},"html":{"type":"string","minLength":1},"css":{"type":"string"},"data":{"type":"object"},"merge_data":{"type":"object"},"mode":{"type":"string","enum":["fast","print"]},"format":{"anyOf":[{"type":"string","enum":["A4","A5","Letter","Legal"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"},"height":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"}}}]},"orientation":{"type":"string","enum":["portrait","landscape"]},"margins":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))(?: (?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))){0,3}$"},"filename":{"type":"string","maxLength":100},"response":{"type":"string","enum":["binary","url"]},"metadata":{"type":"object","maxProperties":20},"async":{"type":"boolean"},"deliver":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"string","minLength":3,"maxLength":254},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":5000},"reply_to":{"type":"string","minLength":3,"maxLength":254}}}}},"test":{"type":"boolean"},"e_invoice":{"$ref":"#/components/schemas/EInvoice"}}}}}},"responses":{"200":{"description":"The PDF (response: binary) or its JSON (response: url). An XRechnung e_invoice answers with the XML (application/xml). E-invoices carry the header x-e-invoice: <standard>/<profile>.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"filename":{"type":"string"},"metadata":{"type":["object","null"]},"warnings":{"type":"array","items":{"type":"object"}},"blocked_resources":{"type":"array","items":{"type":"string"}},"e_invoice":{"type":"object","description":"Only for an e_invoice request.","properties":{"standard":{"type":"string"},"profile":{"type":"string"},"xml_filename":{"type":"string"}}}}}]}}}},"202":{"description":"Queued (async: true).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pdf/{id}":{"get":{"tags":["PDFs"],"summary":"Get a document","operationId":"getPdf","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents":{"get":{"tags":["Documents"],"summary":"List documents (newest first)","operationId":"listDocuments","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"The previous page's next_before.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"next_before":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/{id}":{"get":{"tags":["Documents"],"summary":"Download a stored PDF (signed link)","operationId":"downloadFile","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"exp","in":"query","required":false,"description":"Expiry (from the signed url).","schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"description":"Signature (from the signed url).","schema":{"type":"string"}},{"name":"download","in":"query","required":false,"description":"1 to download instead of opening inline.","schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF (or the XML of an XRechnung e-invoice).","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/xml":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/thumbnails/documents/{file}":{"get":{"tags":["Documents"],"summary":"First-page thumbnail of a stored PDF (signed link, as thumbnail_url)","operationId":"documentThumbnail","parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string"},"description":"The document id and .png."},{"name":"exp","in":"query","required":false,"description":"Expiry (from the signed url).","schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"description":"Signature (from the signed url).","schema":{"type":"string"}}],"responses":{"200":{"description":"A PNG, 480 px wide.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/thumbnails/templates/{file}":{"get":{"tags":["Documents"],"summary":"First-page thumbnail of a template version (signed link, as thumbnail_url)","operationId":"templateThumbnail","parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string"},"description":"The template id and .png."},{"name":"v","in":"query","required":false,"description":"Template version (from the signed url).","schema":{"type":"string"}},{"name":"exp","in":"query","required":false,"description":"Expiry (from the signed url).","schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"description":"Signature (from the signed url).","schema":{"type":"string"}}],"responses":{"200":{"description":"A PNG, 480 px wide.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/brand-assets/{file}":{"get":{"tags":["Documents"],"summary":"Your team's logo or an uploaded font (signed link, as brand.logo_url)","operationId":"downloadBrandAsset","parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string"},"description":"The asset id and extension, e.g. 0b6f...7a10.png."},{"name":"sig","in":"query","required":false,"description":"Signature (from the signed url).","schema":{"type":"string"}}],"responses":{"200":{"description":"The file: image/png or image/jpeg for a logo (an SVG logo is stored as a PNG), font/woff2, font/ttf or font/otf for a font.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/account":{"get":{"tags":["Account"],"summary":"The team and the calling key","operationId":"getAccount","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"},"key":{"type":"object"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account/usage":{"get":{"tags":["Account"],"summary":"Usage of the current period","operationId":"getUsage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Who this key is (connection test)","operationId":"getMe","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"docs_per_period":{"type":"integer"},"rate_limit_per_min":{"type":"integer"},"webhooks":{"type":"boolean"},"batch_max_items":{"type":"integer"},"emails_per_day":{"type":"integer"}}},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"prefix":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates":{"get":{"tags":["Templates"],"summary":"List templates","operationId":"listTemplates","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 50).","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSummary"}},"has_more":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Templates"],"summary":"Create a template (live keys)","operationId":"createTemplate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","html"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"html":{"type":"string","minLength":1},"css":{"type":"string"},"sample_data":{"type":"object"},"settings":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["fast","print"]},"format":{"anyOf":[{"type":"string","enum":["A4","A5","Letter","Legal"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"},"height":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"}}}]},"orientation":{"type":"string","enum":["portrait","landscape"]},"margin":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))(?: (?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))){0,3}$"}}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates/{id}":{"get":{"tags":["Templates"],"summary":"Get a template","operationId":"getTemplate","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"version","in":"query","required":false,"description":"A version number (default: the current one).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Templates"],"summary":"Update a template (a new version)","operationId":"updateTemplate","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"html":{"type":"string","minLength":1},"css":{"type":["string","null"]},"sample_data":{"type":"object"},"settings":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["fast","print"]},"format":{"anyOf":[{"type":"string","enum":["A4","A5","Letter","Legal"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"},"height":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"}}}]},"orientation":{"type":"string","enum":["portrait","landscape"]},"margin":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))(?: (?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))){0,3}$"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Templates"],"summary":"Delete a template","operationId":"deleteTemplate","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates/{id}/pin":{"post":{"tags":["Templates"],"summary":"Pin a version (null unpins)","operationId":"pinTemplate","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["version"],"properties":{"version":{"type":["integer","null"],"minimum":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates/{id}/fields":{"get":{"tags":["Templates"],"summary":"The template's fields (from its sample data)","operationId":"getTemplateFields","description":"What no-code tools show as form fields, read from the version's sample data: scalar fields by dotted path, arrays of scalars as list, arrays of objects as line_items with the fields of one item. Up to 200 fields, 6 levels deep. tree has the same fields as a nested form, keys kept exactly. Without sample data the arrays are empty.","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"version","in":"query","required":false,"description":"A version number (default: the current one).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFields"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates/{id}/versions":{"get":{"tags":["Templates"],"summary":"List versions","operationId":"listTemplateVersions","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"version":{"type":"integer"},"created_at":{"type":"string"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates/{id}/preview":{"post":{"tags":["Templates"],"summary":"Watermarked preview PDF (not counted)","operationId":"previewTemplate","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"version":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches":{"get":{"tags":["Batches"],"summary":"List batches (newest first)","operationId":"listBatches","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"The previous page's next_before.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Batch"}},"next_before":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Batches"],"summary":"Create a batch","operationId":"createBatch","description":"One PDF per item (or spreadsheet row) from one template, rendered in the background. batch.completed is sent when every item is done; the ZIP link is on the batch.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. The same key and body within 24 hours return the first result instead of doing the work again.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["template_id"],"properties":{"template_id":{"type":"string","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"template_version":{"type":"integer","minimum":1},"items":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"object"},"filename":{"type":"string","maxLength":100},"metadata":{"type":"object","maxProperties":20},"deliver":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"string","minLength":3,"maxLength":254},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":5000},"reply_to":{"type":"string","minLength":3,"maxLength":254}}}}}}}},"spreadsheet":{"type":"object","additionalProperties":false,"required":["filename","content_base64"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content_base64":{"type":"string","minLength":1},"mapping":{"type":"object","additionalProperties":{"type":"string","maxLength":255},"maxProperties":500},"email_column":{"type":"string","minLength":1,"maxLength":255}}},"filename_pattern":{"type":"string","minLength":1,"maxLength":200},"mode":{"type":"string","enum":["fast","print"]},"format":{"anyOf":[{"type":"string","enum":["A4","A5","Letter","Legal"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"},"height":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))$"}}}]},"orientation":{"type":"string","enum":["portrait","landscape"]},"margins":{"type":"string","pattern":"^(?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))(?: (?:0|\\d+(?:\\.\\d+)?(?:mm|cm|in|px|pt))){0,3}$"},"deliver":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"string","minLength":3,"maxLength":254},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":5000},"reply_to":{"type":"string","minLength":3,"maxLength":254}}}}},"metadata":{"type":"object","maxProperties":20},"test":{"type":"boolean"}}}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{id}":{"get":{"tags":["Batches"],"summary":"Get a batch","operationId":"getBatch","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{id}/items":{"get":{"tags":["Batches"],"summary":"List the items of a batch (item order)","operationId":"listBatchItems","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"The previous page's next_after.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"filename":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"document_url":{"type":["string","null"],"format":"uri"}}}},"next_after":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{id}/cancel":{"post":{"tags":["Batches"],"summary":"Cancel the queued items of a batch","operationId":"cancelBatch","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{id}/zip":{"get":{"tags":["Batches"],"summary":"Download the ZIP of a batch (signed link)","operationId":"downloadBatchZip","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"exp","in":"query","required":false,"description":"Expiry (from zip.url).","schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"description":"Signature (from zip.url).","schema":{"type":"string"}}],"responses":{"200":{"description":"The ZIP.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/spreadsheets/parse":{"post":{"tags":["Spreadsheets"],"summary":"Read a CSV or XLSX file: columns, preview, template fields and a suggested mapping","operationId":"parseSpreadsheet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["filename","content_base64"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content_base64":{"type":"string","minLength":1},"template_id":{"type":"string","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["csv","xlsx"]},"columns":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer"},"max_rows":{"type":"integer"},"preview":{"type":"array","items":{"type":"object"}},"fields":{"type":"array","items":{"type":"string"}},"mapping":{"type":"object","additionalProperties":{"type":["string","null"]}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","operationId":"listWebhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint (the secret is shown only here)","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url","events"],"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"events":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["pdf.created","pdf.failed","batch.completed"]}},"mode":{"type":"string","enum":["live","test"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook endpoint","operationId":"getWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Webhooks"],"summary":"Update, disable or enable a webhook endpoint","operationId":"updateWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"events":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["pdf.created","pdf.failed","batch.completed"]}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret (the old one signs too for 24 hours)","operationId":"rotateWebhookSecret","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test event","operationId":"sendTestWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","format":"uuid"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"The delivery log (30 days)","operationId":"listWebhookDeliveries","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"The previous page's next_before.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_before":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"tags":["Webhooks"],"summary":"Send a finished delivery once more","operationId":"retryWebhookDelivery","parameters":[{"name":"id","in":"path","required":true,"description":"The id (UUID).","schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"description":"The delivery id.","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","format":"uuid"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"pdf.created":{"post":{"summary":"A PDF was created","description":"Sent to your endpoint as a POST. Answer 2xx within 10 seconds; anything else is retried for about 24 hours.","parameters":[{"name":"CastPDF-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the endpoint secret>; a second v1 for 24 hours after a secret rotation."},{"name":"CastPDF-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"CastPDF-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","livemode","data"],"properties":{"id":{"type":"string","description":"evt_ followed by 32 hex characters; the same for every endpoint receiving it."},"type":{"const":"pdf.created"},"created_at":{"type":"string","format":"date-time"},"livemode":{"type":"boolean"},"test_event":{"type":"boolean","description":"Present (true) only on events sent with \"Send test event\"."},"data":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"filename":{"type":"string"},"metadata":{"type":["object","null"]},"batch_id":{"type":["string","null"]},"error_message":{"type":"string"}}}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event."}}}},"pdf.failed":{"post":{"summary":"A PDF failed","description":"Sent to your endpoint as a POST. Answer 2xx within 10 seconds; anything else is retried for about 24 hours.","parameters":[{"name":"CastPDF-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the endpoint secret>; a second v1 for 24 hours after a secret rotation."},{"name":"CastPDF-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"CastPDF-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","livemode","data"],"properties":{"id":{"type":"string","description":"evt_ followed by 32 hex characters; the same for every endpoint receiving it."},"type":{"const":"pdf.failed"},"created_at":{"type":"string","format":"date-time"},"livemode":{"type":"boolean"},"test_event":{"type":"boolean","description":"Present (true) only on events sent with \"Send test event\"."},"data":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"filename":{"type":"string"},"metadata":{"type":["object","null"]},"batch_id":{"type":["string","null"]},"error_message":{"type":"string"}}}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event."}}}},"batch.completed":{"post":{"summary":"Every item of a batch is done","description":"Sent to your endpoint as a POST. Answer 2xx within 10 seconds; anything else is retried for about 24 hours.","parameters":[{"name":"CastPDF-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the endpoint secret>; a second v1 for 24 hours after a secret rotation."},{"name":"CastPDF-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"CastPDF-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","livemode","data"],"properties":{"id":{"type":"string","description":"evt_ followed by 32 hex characters; the same for every endpoint receiving it."},"type":{"const":"batch.completed"},"created_at":{"type":"string","format":"date-time"},"livemode":{"type":"boolean"},"test_event":{"type":"boolean","description":"Present (true) only on events sent with \"Send test event\"."},"data":{"$ref":"#/components/schemas/Batch"}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key: cpdf_live_... or cpdf_test_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","docs_url"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_e_invoice","invalid_api_key","unauthenticated","invalid_credentials","invalid_token","plan_limit_reached","spending_cap_reached","payment_failed","feature_not_available","forbidden","email_not_verified","not_found","template_not_found","document_not_found","webhook_not_found","batch_not_found","email_taken","idempotency_conflict","subscription_exists","no_subscription","no_customer","subscription_locked","checkout_in_progress","file_expired","document_too_large","payload_too_large","template_render_error","render_failed","content_lost","idempotency_mismatch","rate_limited","storage_limit_reached","email_limit_reached","internal_error","billing_provider_error","service_busy","render_timeout"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"},"details":{"type":"object"}}}}},"Team":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"plan":{"type":"string"}}},"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"pages":{"type":["integer","null"]},"bytes":{"type":["integer","null"]},"mode":{"type":["string","null"],"enum":["fast","print",null]},"test":{"type":"boolean"},"template_id":{"type":["string","null"]},"template_version":{"type":["integer","null"]},"error_code":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"url":{"type":["string","null"],"format":"uri","description":"Signed download link, valid until expires_at."},"thumbnail_url":{"type":["string","null"],"format":"uri","description":"Signed PNG of the first page (480 px wide) while the PDF is stored; made on first request. In GET /v1/pdf/{id} and GET /v1/documents, not in webhook events."},"delivery":{"anyOf":[{"type":"null"},{"type":"object","properties":{"email":{"type":"object","properties":{"status":{"type":"string","enum":["queued","sent","failed","suppressed"]},"reason":{"type":"string","enum":["over_limit","not_stored","send_failed"],"description":"Why a failed email was not delivered."}}}}}]}}},"Batch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","completed","canceled"]},"livemode":{"type":"boolean"},"source":{"type":"string","enum":["api","spreadsheet"]},"template_id":{"type":"string","format":"uuid"},"template_version":{"type":"integer"},"total":{"type":"integer"},"queued":{"type":"integer"},"processing":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"canceled":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"zip":{"anyOf":[{"type":"null"},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"bytes":{"type":"integer"}}}]},"metadata":{"type":["object","null"]}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string","enum":["pdf.created","pdf.failed","batch.completed"]}},"mode":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["enabled","disabled"]},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null]},"secret_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string"},"event_type":{"type":"string","enum":["pdf.created","pdf.failed","batch.completed"]},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"response_status":{"type":["integer","null"]},"response_body":{"type":["string","null"]},"last_error":{"type":["string","null"]},"duration_ms":{"type":["integer","null"]},"test_event":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"event":{"type":"object","description":"The event exactly as it was sent: { id, type, created_at, livemode, data }."}}},"TemplateSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"current_version":{"type":"integer"},"pinned_version":{"type":["integer","null"]},"updated_at":{"type":"string","format":"date-time"},"thumbnail_url":{"type":"string","format":"uri","description":"Signed PNG of the current version first page (480 px wide, rendered with its sample data); made on first request, the url changes with each version."}}},"Template":{"allOf":[{"$ref":"#/components/schemas/TemplateSummary"},{"type":"object","properties":{"version":{"type":"integer"},"html":{"type":"string"},"css":{"type":["string","null"]},"sample_data":{"type":["object","null"]},"settings":{"type":"object"}}}]},"TemplateFields":{"type":"object","properties":{"template_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"fields":{"type":"array","items":{"type":"object","required":["key","type","sample"],"properties":{"key":{"type":"string","description":"The dotted path in the data, e.g. customer.name (inside a line item: relative to the item)."},"type":{"type":"string","enum":["string","number","boolean","list"]},"sample":{"description":"The value in the sample data."}}}},"line_items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"fields":{"type":"array","items":{"type":"object","required":["key","type","sample"],"properties":{"key":{"type":"string","description":"The dotted path in the data, e.g. customer.name (inside a line item: relative to the item)."},"type":{"type":"string","enum":["string","number","boolean","list"]},"sample":{"description":"The value in the sample data."}}}},"sample_count":{"type":"integer"}}}},"tree":{"type":"array","description":"The same fields as a ready-made nested form (the shape Make uses for parameters): name is the data key exactly as in the sample data (spaces and dots included, never a path); objects are collections, arrays of objects are arrays whose spec is the fields of one item (line items, also inside objects), arrays of values are arrays with one value field. Send what such a form produces as merge_data on POST /v1/pdf.","items":{"$ref":"#/components/schemas/TemplateTreeField"}},"tree_truncated":{"type":"boolean","description":"True when fields were left out of tree: more than 200, deeper than 6 levels, or arrays that mix values and objects."}}},"TemplateTreeField":{"type":"object","required":["name","label","type","help"],"properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","boolean","collection","array"]},"help":{"type":"string"},"spec":{"description":"collection: its fields; array of objects: the fields of one item; array of values: the value field.","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/TemplateTreeField"}},{"type":"object","properties":{"type":{"type":"string","enum":["text","number","boolean"]},"label":{"type":"string"}}}]}}},"EInvoice":{"type":"object","description":"Issue a structured invoice as an EU e-invoice. data may be left out (the template data is derived from the invoice), and so may template_id and html (the built-in invoice template is used). Counts as one document.","required":["standard","invoice"],"properties":{"standard":{"type":"string","description":"factur-x and zugferd: a PDF/A-3b with the CII XML embedded (factur-x.xml). xrechnung-cii and xrechnung-ubl: the XRechnung 3.0 XML itself (application/xml), nothing rendered.","enum":["factur-x","zugferd","xrechnung-cii","xrechnung-ubl"]},"profile":{"type":"string","description":"factur-x: minimum, basic-wl, basic, en16931 (default) or extended. zugferd: the same, or xrechnung (the XRechnung CII embedded as xrechnung.xml). xrechnung-*: xrechnung.","enum":["minimum","basic-wl","basic","en16931","extended","xrechnung"]},"invoice":{"type":"object","required":["number","issue_date","currency","seller","buyer","lines"],"properties":{"number":{"type":"string","description":"BT-1 invoice number."},"type_code":{"type":"string","description":"BT-3, UNTDID 1001. Default 380 (invoice); 381 credit note, 384 corrected invoice, 389 self-billed. XRechnung allows 326, 380, 381, 384, 389, 875, 876, 877."},"issue_date":{"type":"string","format":"date","description":"BT-2. YYYY-MM-DD."},"currency":{"type":"string","description":"BT-5, ISO 4217, for example EUR."},"buyer_reference":{"type":"string","description":"BT-10. For XRechnung this is the Leitweg-ID and it is required."},"purchase_order_reference":{"type":"string","description":"BT-13."},"sales_order_reference":{"type":"string","description":"BT-14."},"contract_reference":{"type":"string","description":"BT-12."},"project_reference":{"type":"string","description":"BT-11."},"preceding_invoice":{"type":"object","description":"BG-3: the invoice a credit note or correction refers to.","required":["number"],"properties":{"number":{"type":"string","description":"BT-25."},"issue_date":{"type":"string","format":"date","description":"BT-26. YYYY-MM-DD."}}},"delivery_date":{"type":"string","format":"date","description":"BT-72 actual delivery date. YYYY-MM-DD."},"billing_period":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date","description":"BT-73. YYYY-MM-DD."},"end":{"type":"string","format":"date","description":"BT-74. YYYY-MM-DD."}}},"notes":{"type":"array","items":{"type":"string"},"description":"BT-22."},"seller":{"type":"object","required":["name","address"],"properties":{"name":{"type":"string","description":"BT-27 / BT-44 legal name."},"trading_name":{"type":"string","description":"BT-28 / BT-45."},"id":{"type":"string","description":"BT-29 / BT-46 party identifier."},"id_scheme":{"type":"string","description":"ISO 6523 scheme of id, for example 0088 (GLN)."},"legal_registration_id":{"type":"string","description":"BT-30 / BT-47 company register number."},"legal_registration_scheme":{"type":"string","description":"ISO 6523 scheme of legal_registration_id."},"vat_id":{"type":"string","description":"BT-31 / BT-48 VAT identification number with country prefix, for example DE123456789."},"tax_number":{"type":"string","description":"BT-32 (seller): national tax number (Steuernummer)."},"legal_info":{"type":"string","description":"BT-33 (seller): additional legal information."},"electronic_address":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"BT-34 / BT-49."},"scheme":{"type":"string","description":"CEF EAS code: EM email (default), 0204 Leitweg-ID, 9930 German VAT number, 0088 GLN."}}},"address":{"type":"object","required":["country_code"],"properties":{"line1":{"type":"string","description":"BT-35 / BT-50 street and number."},"line2":{"type":"string","description":"BT-36 / BT-51."},"line3":{"type":"string","description":"BT-162 / BT-163."},"city":{"type":"string","description":"BT-37 / BT-52."},"postal_code":{"type":"string","description":"BT-38 / BT-53."},"subdivision":{"type":"string","description":"BT-39 / BT-54 region or state."},"country_code":{"type":"string","description":"BT-40 / BT-55, ISO 3166-1 alpha-2.","pattern":"^[A-Z0-9]{2}$"}}},"contact":{"type":"object","properties":{"name":{"type":"string","description":"BT-41 / BT-56."},"phone":{"type":"string","description":"BT-42 / BT-57."},"email":{"type":"string","description":"BT-43 / BT-58."}}}}},"buyer":{"type":"object","required":["name","address"],"properties":{"name":{"type":"string","description":"BT-27 / BT-44 legal name."},"trading_name":{"type":"string","description":"BT-28 / BT-45."},"id":{"type":"string","description":"BT-29 / BT-46 party identifier."},"id_scheme":{"type":"string","description":"ISO 6523 scheme of id, for example 0088 (GLN)."},"legal_registration_id":{"type":"string","description":"BT-30 / BT-47 company register number."},"legal_registration_scheme":{"type":"string","description":"ISO 6523 scheme of legal_registration_id."},"vat_id":{"type":"string","description":"BT-31 / BT-48 VAT identification number with country prefix, for example DE123456789."},"tax_number":{"type":"string","description":"BT-32 (seller): national tax number (Steuernummer)."},"legal_info":{"type":"string","description":"BT-33 (seller): additional legal information."},"electronic_address":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"BT-34 / BT-49."},"scheme":{"type":"string","description":"CEF EAS code: EM email (default), 0204 Leitweg-ID, 9930 German VAT number, 0088 GLN."}}},"address":{"type":"object","required":["country_code"],"properties":{"line1":{"type":"string","description":"BT-35 / BT-50 street and number."},"line2":{"type":"string","description":"BT-36 / BT-51."},"line3":{"type":"string","description":"BT-162 / BT-163."},"city":{"type":"string","description":"BT-37 / BT-52."},"postal_code":{"type":"string","description":"BT-38 / BT-53."},"subdivision":{"type":"string","description":"BT-39 / BT-54 region or state."},"country_code":{"type":"string","description":"BT-40 / BT-55, ISO 3166-1 alpha-2.","pattern":"^[A-Z0-9]{2}$"}}},"contact":{"type":"object","properties":{"name":{"type":"string","description":"BT-41 / BT-56."},"phone":{"type":"string","description":"BT-42 / BT-57."},"email":{"type":"string","description":"BT-43 / BT-58."}}}}},"delivery":{"type":"object","description":"BG-13 deliver-to.","properties":{"name":{"type":"string","description":"BT-70."},"address":{"type":"object","required":["country_code"],"properties":{"line1":{"type":"string","description":"BT-35 / BT-50 street and number."},"line2":{"type":"string","description":"BT-36 / BT-51."},"line3":{"type":"string","description":"BT-162 / BT-163."},"city":{"type":"string","description":"BT-37 / BT-52."},"postal_code":{"type":"string","description":"BT-38 / BT-53."},"subdivision":{"type":"string","description":"BT-39 / BT-54 region or state."},"country_code":{"type":"string","description":"BT-40 / BT-55, ISO 3166-1 alpha-2.","pattern":"^[A-Z0-9]{2}$"}}}}},"payment":{"type":"object","properties":{"means_code":{"type":"string","description":"BT-81, UNTDID 4461. Default 58 (SEPA credit transfer) with an iban, else 1."},"means_text":{"type":"string","description":"BT-82."},"iban":{"type":"string","description":"BT-84; the check digits are verified."},"account_name":{"type":"string","description":"BT-85."},"bic":{"type":"string","description":"BT-86."},"reference":{"type":"string","description":"BT-83 remittance information. Default: the invoice number."},"terms":{"type":"string","description":"BT-20 payment terms."},"due_date":{"type":"string","format":"date","description":"BT-9. Either due_date or terms is required when an amount is due. YYYY-MM-DD."},"mandate_reference":{"type":"string","description":"BT-89 SEPA direct debit mandate."},"creditor_id":{"type":"string","description":"BT-90 SEPA creditor identifier."},"debited_iban":{"type":"string","description":"BT-91 debited account."}}},"lines":{"type":"array","minItems":1,"maxItems":2000,"items":{"type":"object","required":["name","quantity","unit_price","vat"],"properties":{"id":{"type":"string","description":"BT-126; default the position (1, 2, …)."},"name":{"type":"string","description":"BT-153 item name."},"description":{"type":"string","description":"BT-154 item description."},"note":{"type":"string","description":"BT-127."},"seller_item_id":{"type":"string","description":"BT-155."},"buyer_item_id":{"type":"string","description":"BT-156."},"standard_item_id":{"type":"string","description":"BT-157, with standard_item_scheme (0160 = GTIN)."},"standard_item_scheme":{"type":"string","description":"ISO 6523 scheme of standard_item_id."},"quantity":{"type":["number","string"],"description":"BT-129. A JSON number or a decimal string such as \"19.99\"."},"unit_code":{"type":"string","description":"BT-130, UN/ECE Rec 20: C62 piece (default), HUR hour, DAY day, KGM kilogram, MTR metre, LS lump sum."},"unit_price":{"type":["number","string"],"description":"BT-146 net price per unit (after any price discount); not negative. A JSON number or a decimal string such as \"19.99\"."},"price_base_quantity":{"type":["number","string"],"description":"BT-149: the price is for this many units. Default 1. A JSON number or a decimal string such as \"19.99\"."},"order_line_reference":{"type":"string","description":"BT-132."},"period":{"type":"object","description":"BG-26 line period.","required":["start","end"],"properties":{"start":{"type":"string","format":"date","description":"Start. YYYY-MM-DD."},"end":{"type":"string","format":"date","description":"End. YYYY-MM-DD."}}},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":["number","string"],"description":"BT-136 / BT-141, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as \"19.99\"."},"percent":{"type":["number","string"],"description":"Percent of the line amount (quantity x net price). A JSON number or a decimal string such as \"19.99\"."},"reason":{"type":"string","description":"BT-139 / BT-144. A reason or a reason_code is required."},"reason_code":{"type":"string","description":"UNTDID 5189 (allowances, 95 = discount) or UNTDID 7161 (charges)."}}}},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":["number","string"],"description":"BT-136 / BT-141, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as \"19.99\"."},"percent":{"type":["number","string"],"description":"Percent of the line amount (quantity x net price). A JSON number or a decimal string such as \"19.99\"."},"reason":{"type":"string","description":"BT-139 / BT-144. A reason or a reason_code is required."},"reason_code":{"type":"string","description":"UNTDID 5189 (allowances, 95 = discount) or UNTDID 7161 (charges)."}}}},"vat":{"type":"object","description":"The VAT of a line or of a document allowance or charge.","properties":{"category":{"type":"string","description":"UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.","enum":["S","Z","E","AE","K","G","O","L","M"]},"rate":{"type":["number","string"],"description":"Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as \"19.99\"."}}}}}},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":["number","string"],"description":"BT-92 / BT-99, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as \"19.99\"."},"percent":{"type":["number","string"],"description":"Percent of base_amount. A JSON number or a decimal string such as \"19.99\"."},"base_amount":{"type":["number","string"],"description":"Default: the sum of the line net amounts. A JSON number or a decimal string such as \"19.99\"."},"reason":{"type":"string","description":"BT-97 / BT-104. A reason or a reason_code is required."},"reason_code":{"type":"string","description":"UNTDID 5189 (allowances) or UNTDID 7161 (charges)."},"vat":{"type":"object","description":"Required when the lines use more than one VAT category or rate; otherwise the lines' VAT.","properties":{"category":{"type":"string","description":"UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.","enum":["S","Z","E","AE","K","G","O","L","M"]},"rate":{"type":["number","string"],"description":"Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as \"19.99\"."}}}}},"description":"BG-20 document level allowances."},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":["number","string"],"description":"BT-92 / BT-99, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as \"19.99\"."},"percent":{"type":["number","string"],"description":"Percent of base_amount. A JSON number or a decimal string such as \"19.99\"."},"base_amount":{"type":["number","string"],"description":"Default: the sum of the line net amounts. A JSON number or a decimal string such as \"19.99\"."},"reason":{"type":"string","description":"BT-97 / BT-104. A reason or a reason_code is required."},"reason_code":{"type":"string","description":"UNTDID 5189 (allowances) or UNTDID 7161 (charges)."},"vat":{"type":"object","description":"Required when the lines use more than one VAT category or rate; otherwise the lines' VAT.","properties":{"category":{"type":"string","description":"UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.","enum":["S","Z","E","AE","K","G","O","L","M"]},"rate":{"type":["number","string"],"description":"Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as \"19.99\"."}}}}},"description":"BG-21 document level charges."},"prepaid_amount":{"type":["number","string"],"description":"BT-113. A JSON number or a decimal string such as \"19.99\"."},"rounding_amount":{"type":["number","string"],"description":"BT-114 (EN 16931, EXTENDED and XRechnung only). A JSON number or a decimal string such as \"19.99\"."},"tax_exemptions":{"type":"object","description":"VAT exemption reason per category (BT-120 text, BT-121 VATEX code). Required for E; AE, K, G and O have defaults.","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","description":"BT-120."},"code":{"type":"string","description":"BT-121, for example VATEX-EU-132-1A."}}}},"totals":{"type":"object","description":"Optional: totals you computed. Each one given is compared with the totals computed from the lines (EN 16931: each line rounded to cents, VAT once per category and rate); a difference is a 400 that names the field.","properties":{"line_total":{"type":["number","string"],"description":"BT-106. A JSON number or a decimal string such as \"19.99\"."},"allowance_total":{"type":["number","string"],"description":"BT-107. A JSON number or a decimal string such as \"19.99\"."},"charge_total":{"type":["number","string"],"description":"BT-108. A JSON number or a decimal string such as \"19.99\"."},"tax_basis_total":{"type":["number","string"],"description":"BT-109. A JSON number or a decimal string such as \"19.99\"."},"tax_total":{"type":["number","string"],"description":"BT-110. A JSON number or a decimal string such as \"19.99\"."},"grand_total":{"type":["number","string"],"description":"BT-112. A JSON number or a decimal string such as \"19.99\"."},"prepaid":{"type":["number","string"],"description":"BT-113. A JSON number or a decimal string such as \"19.99\"."},"rounding":{"type":["number","string"],"description":"BT-114. A JSON number or a decimal string such as \"19.99\"."},"due_payable":{"type":["number","string"],"description":"BT-115. A JSON number or a decimal string such as \"19.99\"."}}}}}}}}}}