{"openapi":"3.1.0","info":{"title":"Tallio API","version":"0.1.0","description":"Tallio issues e-invoicing documents through the licensed provider a merchant already uses.\n\nSuccess bodies are `{ data }`. Every failure has one shape:\n`{ code, message, provider_code, provider_message, retryable, provider_raw? }`.\n\nOperations that create something require an `Idempotency-Key` header; retrying with the same key\nand body returns the first result.\n\nThis document is generated from the Zod schemas in `packages/schema`; a test fails when it is stale."},"servers":[{"url":"/"}],"tags":[{"name":"documents","description":"Preview and issue fiscal documents."},{"name":"meta","description":"This API's own description."}],"paths":{"/api/v1/documents":{"post":{"operationId":"createDocument","summary":"Issue a document","description":"Issue a document for a merchant. Tallio validates and classifies it at once, stores it as pending and issues it through the merchant's provider in the background.","tags":["documents"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant":{"type":"string","pattern":"^mer_[0-9A-Za-z]{22}$","description":"The merchant issuing the document (mer_…), created under your account.","example":"mer_02y9O8rh7F50tGi0QcWRrx"},"document":{"type":"object","properties":{"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"supplier":{"type":"object","properties":{"tax_id":{"type":"object","properties":{"country":{"type":"string","const":"GR","description":"Country of the tax registration: GR. Suppliers are Greek merchants."},"code":{"description":"Tax number without a country prefix: the 9-digit ΑΦΜ for GR, 2 to 30 letters and digits elsewhere. Spaces, hyphens and dots are removed and letters upper-cased before it is checked.","example":"555555559","type":"string","maxLength":60}},"required":["country","code"],"description":"Greek tax identity: GR plus the ΑΦΜ."},"name":{"description":"Legal name. Required outside Greece. Optional for Greek parties, whose name AADE holds; adapters drop it when they send a Greek party straight to myDATA, which rejects it.","type":"string","minLength":1,"maxLength":200},"address":{"description":"Postal address. Required outside Greece.","type":"object","properties":{"street":{"description":"Street name.","type":"string","minLength":1,"maxLength":150},"number":{"description":"Street number.","type":"string","minLength":1,"maxLength":20},"postal_code":{"type":"string","minLength":1,"maxLength":20,"description":"Postal code."},"city":{"type":"string","minLength":1,"maxLength":150,"description":"City."}},"required":["postal_code","city"]},"branch":{"description":"Branch number in the AADE registry; omit or 0 for the head office.","type":"integer","minimum":0,"maximum":9999}},"required":["tax_id"],"description":"The merchant issuing the document, registered in Greece."},"customer":{"description":"The customer. Required for 1.1, 2.1, 5.1, 5.2; not allowed on retail receipts (11.1, 11.2).","type":"object","properties":{"tax_id":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country of the tax registration: GR for Greece (not the VAT prefix EL).","example":"GR"},"code":{"description":"Tax number without a country prefix: the 9-digit ΑΦΜ for GR, 2 to 30 letters and digits elsewhere. Spaces, hyphens and dots are removed and letters upper-cased before it is checked.","example":"555555559","type":"string","maxLength":60}},"required":["country","code"],"description":"Tax identity: country plus tax number."},"name":{"description":"Legal name. Required outside Greece. Optional for Greek parties, whose name AADE holds; adapters drop it when they send a Greek party straight to myDATA, which rejects it.","type":"string","minLength":1,"maxLength":200},"address":{"description":"Postal address. Required outside Greece.","type":"object","properties":{"street":{"description":"Street name.","type":"string","minLength":1,"maxLength":150},"number":{"description":"Street number.","type":"string","minLength":1,"maxLength":20},"postal_code":{"type":"string","minLength":1,"maxLength":20,"description":"Postal code."},"city":{"type":"string","minLength":1,"maxLength":150,"description":"City."}},"required":["postal_code","city"]},"branch":{"description":"Branch number in the AADE registry; omit or 0 for the head office.","type":"integer","minimum":0,"maximum":9999}},"required":["tax_id"]},"original_marks":{"description":"MARKs of the documents a 5.1 credit note corrects. Required for 5.1 and allowed only there.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"}},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":300,"description":"What was sold, as printed on the document."},"quantity":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,3})?$","description":"Quantity, a decimal string below 1000000000 with up to 3 decimals, greater than 0, e.g. \"2\" or \"1.5\" (kg).","example":"1.5"},"unit":{"type":"string","enum":["piece","kg","litre","metre","square_metre","cubic_metre"],"description":"Unit the quantity is measured in: piece (myDATA 1), kg (myDATA 2), litre (myDATA 3), metre (myDATA 4), square_metre (myDATA 5), cubic_metre (myDATA 6)."},"unit_price":{"type":"integer","minimum":0,"maximum":100000000000,"description":"Net price per unit in minor units (cents), at most 100000000000."},"vat_category":{"type":"string","enum":["standard","reduced","super_reduced","standard_island","reduced_island","super_reduced_island","exempt"],"description":"Greek VAT category of the line, which fixes its rate: standard 24% (myDATA 1), reduced 13% (myDATA 2), super_reduced 6% (myDATA 3), standard_island 17% (myDATA 4), reduced_island 9% (myDATA 5), super_reduced_island 4% (myDATA 6), exempt 0% (myDATA 7). An exempt line needs vat_exemption."},"vat_exemption":{"type":"integer","minimum":1,"maximum":31,"description":"myDATA VAT exemption cause (1-31), e.g. 14 for article 33 of the VAT code (Law 5144/2024). Required on exempt lines only."},"income_classification":{"type":"object","properties":{"category":{"type":"string","enum":["category1_1","category1_2","category1_3","category1_4","category1_5","category1_6","category1_7","category1_8","category1_9","category1_10","category1_95"],"description":"myDATA income classification category, e.g. category1_1 sale of goods, category1_2 sale of products, category1_3 provision of services, category1_95 other income information."},"type":{"description":"E3 income type. Required, except that category1_95 takes none or one of E3_596, E3_597.","type":"string","enum":["E3_106","E3_205","E3_210","E3_305","E3_310","E3_318","E3_561_001","E3_561_002","E3_561_003","E3_561_004","E3_561_005","E3_561_006","E3_561_007","E3_562","E3_563","E3_564","E3_565","E3_566","E3_567","E3_568","E3_570","E3_595","E3_596","E3_597","E3_880_001","E3_880_002","E3_880_003","E3_880_004","E3_881_001","E3_881_002","E3_881_003","E3_881_004","E3_598_001","E3_598_003"]}},"required":["category"],"description":"Explicit myDATA income classification for the line. Omit it to have Tallio apply and report a default."}},"required":["description","quantity","unit_price","vat_category"],"description":"One line. Its net amount is quantity × unit_price, rounded half up to the cent, at most 1000000000000000."},"description":"The document's lines, from 1 to 1000."},"payments":{"description":"How the document is paid, up to 10 entries.","minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["domestic_account","foreign_account","cash","cheque","on_credit","web_banking","pos","iris"],"description":"How the document is paid: domestic_account (myDATA 1), foreign_account (myDATA 2), cash (myDATA 3), cheque (myDATA 4), on_credit (myDATA 5), web_banking (myDATA 6), pos (myDATA 7), iris (myDATA 8)."},"amount":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"Amount paid this way, in minor units, at most 1250000000000000."}},"required":["method","amount"],"description":"One way the document is paid."}},"totals":{"type":"object","properties":{"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."}},"required":["net","vat","gross"],"description":"Document totals. Tallio rejects totals that do not add up."}},"required":["type","issue_date","currency","supplier","lines","totals"],"description":"Tallio's canonical document (v0, GOBL-inspired): one shape for every provider. Amounts are integer minor units."}},"required":["merchant","document"],"description":"Issue a document for a merchant. Tallio validates and classifies it at once, stores it as pending and issues it through the merchant's provider in the background.","examples":[{"merchant":"mer_02y9O8rh7F50tGi0QcWRrx","document":{"type":"1.1","issue_date":"2026-10-10","currency":"EUR","supplier":{"tax_id":{"country":"GR","code":"555555559"}},"customer":{"tax_id":{"country":"GR","code":"666666662"},"name":"Kafeneio Lemonia IKE"},"lines":[{"description":"Olive oil, bulk","quantity":"1.5","unit":"litre","unit_price":1000,"vat_category":"reduced","income_classification":{"category":"category1_1","type":"E3_561_001"}},{"description":"Delivery","quantity":"1","unit_price":1000,"vat_category":"standard"}],"payments":[{"method":"cash","amount":2935}],"totals":{"net":2500,"vat":435,"gross":2935}}}]}}}},"responses":{"201":{"description":"Accepted as pending; it is issued in the background. A replay returns the first document.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"ratelimit-limit":{"$ref":"#/components/headers/RatelimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RatelimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RatelimitReset"},"idempotent-replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","pattern":"^doc_[0-9A-Za-z]{22}$","description":"Id of the document (doc_…).","example":"doc_02y9O8rh7F50tGi0QcWRrx"},"object":{"type":"string","const":"document","description":"Always \"document\"."},"merchant":{"type":"string","pattern":"^mer_[0-9A-Za-z]{22}$","description":"Id of the merchant (mer_…).","example":"mer_02y9O8rh7F50tGi0QcWRrx"},"mode":{"type":"string","enum":["live","test"],"description":"live for a document created with a live key, test for a test key."},"provider":{"type":"string","enum":["sandbox","mydata","wrapp","impact","epsilon","softone","prosvasis"],"description":"The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document."},"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"status":{"type":"string","enum":["pending","issued","rejected","failed"],"description":"Where the document stands: pending (Tallio accepted it; not yet issued, see stage), issued (has a MARK), rejected (the provider or AADE refused it), failed (Tallio could not deliver it to the provider)."},"stage":{"anyOf":[{"type":"string","enum":["queued","submitting","awaiting_mark","reconciling"],"description":"Where a pending document is: queued (waiting to be sent), submitting (being sent to the provider), awaiting_mark (the provider accepted it, MARK not yet assigned), reconciling (the outcome of a send is unknown and is being checked with the provider before any resend)."},{"type":"null"}],"description":"Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."},"mark":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"},{"type":"null"}],"description":"MARK (AADE registration number) once issued, as a digit string; null before."},"uid":{"anyOf":[{"type":"string","pattern":"^[0-9A-F]{40}$","example":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F"},{"type":"null"}],"description":"myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known."},"qr_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"URL the document's QR code points to; null until the provider returns one."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","not_found","idempotency_conflict","idempotency_in_progress","payload_too_large","unsupported_media_type","rate_limited","not_supported","provider_rejected","provider_unavailable","internal_error"],"description":"Stable machine-readable error code. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to a developer."},"provider_code":{"description":"The provider's own error code, or null when the error did not come from a provider.","type":["string","null"]},"provider_message":{"description":"The provider's own error message, verbatim, or null when the error did not come from a provider.","type":["string","null"]},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."},"provider_raw":{"description":"The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload."}},"required":["code","message","provider_code","provider_message","retryable"],"additionalProperties":false,"description":"The error shape as embedded in a Document, an Event or a webhook: provider_raw is size-bounded."},{"type":"null"}],"description":"Why the document was rejected or failed; null otherwise."},"classification":{"type":"object","properties":{"source":{"type":"string","enum":["line","override","default"],"description":"default when any line took Tallio's default, else override when any line took the merchant's override, else line."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to check before issuing, e.g. that defaults were applied."}},"required":["source","warnings"],"additionalProperties":false,"description":"How the document was classified for myDATA."},"timeline":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[0-9A-Za-z]{22}$","description":"Id of the event (evt_…).","example":"evt_02y9O8rh7F50tGi0QcWRrx"},"type":{"type":"string","enum":["document.created","document.issued","document.rejected","document.failed"],"description":"What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it)."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the event happened.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","type","created"],"additionalProperties":false,"description":"One event in a document's history. GET /events/{id} returns the full Event."},"description":"The document's events, oldest first, at most 100."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When Tallio accepted the document.","example":"2026-10-11T09:30:00.000Z"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the document last changed.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","object","merchant","mode","provider","type","status","stage","issue_date","currency","net","vat","gross","mark","uid","qr_url","error","classification","timeline","created","updated"],"additionalProperties":false,"description":"A fiscal document Tallio issues through a provider, with its status and history.","examples":[{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"pending","stage":"queued","issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":null,"uid":null,"qr_url":null,"error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:00.000Z"}]}},"required":["data"],"additionalProperties":false,"description":"Success envelope: the result is under `data`."}}}},"400":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`validation_failed`: Request validation failed."},"401":{"$ref":"#/components/responses/Unauthorized","description":"`unauthorized`: Authentication is required."},"404":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`not_found`: The requested resource was not found."},"409":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`idempotency_conflict`: This idempotency key was already used with a different request."},"413":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`payload_too_large`: The request body is too large."},"415":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`unsupported_media_type`: The request body must be JSON (Content-Type: application/json)."},"422":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`not_supported`: The provider or document type does not support this operation."},"429":{"$ref":"#/components/responses/RateLimited","description":"`rate_limited`: A rate limit was reached. Retry later."},"500":{"$ref":"#/components/responses/ApiError","description":"`internal_error`: An unexpected server error occurred."}},"security":[{"apiKey":[]}],"x-tallio-error-codes":[{"code":"validation_failed","status":400},{"code":"payload_too_large","status":413},{"code":"unsupported_media_type","status":415},{"code":"unauthorized","status":401},{"code":"idempotency_conflict","status":409},{"code":"not_found","status":404},{"code":"not_supported","status":422},{"code":"rate_limited","status":429},{"code":"internal_error","status":500}]}},"/api/v1/documents/{id}":{"get":{"operationId":"getDocument","summary":"Retrieve a document","description":"Returns a document with its status, MARK once issued, and its timeline of events.","tags":["documents"],"parameters":[{"name":"id","in":"path","required":true,"description":"The document's id (doc_…).","schema":{"type":"string","example":"doc_02y9O8rhJKVUXRvojdffcz"}}],"responses":{"200":{"description":"The document.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"ratelimit-limit":{"$ref":"#/components/headers/RatelimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RatelimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RatelimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","pattern":"^doc_[0-9A-Za-z]{22}$","description":"Id of the document (doc_…).","example":"doc_02y9O8rh7F50tGi0QcWRrx"},"object":{"type":"string","const":"document","description":"Always \"document\"."},"merchant":{"type":"string","pattern":"^mer_[0-9A-Za-z]{22}$","description":"Id of the merchant (mer_…).","example":"mer_02y9O8rh7F50tGi0QcWRrx"},"mode":{"type":"string","enum":["live","test"],"description":"live for a document created with a live key, test for a test key."},"provider":{"type":"string","enum":["sandbox","mydata","wrapp","impact","epsilon","softone","prosvasis"],"description":"The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document."},"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"status":{"type":"string","enum":["pending","issued","rejected","failed"],"description":"Where the document stands: pending (Tallio accepted it; not yet issued, see stage), issued (has a MARK), rejected (the provider or AADE refused it), failed (Tallio could not deliver it to the provider)."},"stage":{"anyOf":[{"type":"string","enum":["queued","submitting","awaiting_mark","reconciling"],"description":"Where a pending document is: queued (waiting to be sent), submitting (being sent to the provider), awaiting_mark (the provider accepted it, MARK not yet assigned), reconciling (the outcome of a send is unknown and is being checked with the provider before any resend)."},{"type":"null"}],"description":"Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."},"mark":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"},{"type":"null"}],"description":"MARK (AADE registration number) once issued, as a digit string; null before."},"uid":{"anyOf":[{"type":"string","pattern":"^[0-9A-F]{40}$","example":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F"},{"type":"null"}],"description":"myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known."},"qr_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"URL the document's QR code points to; null until the provider returns one."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","not_found","idempotency_conflict","idempotency_in_progress","payload_too_large","unsupported_media_type","rate_limited","not_supported","provider_rejected","provider_unavailable","internal_error"],"description":"Stable machine-readable error code. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to a developer."},"provider_code":{"description":"The provider's own error code, or null when the error did not come from a provider.","type":["string","null"]},"provider_message":{"description":"The provider's own error message, verbatim, or null when the error did not come from a provider.","type":["string","null"]},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."},"provider_raw":{"description":"The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload."}},"required":["code","message","provider_code","provider_message","retryable"],"additionalProperties":false,"description":"The error shape as embedded in a Document, an Event or a webhook: provider_raw is size-bounded."},{"type":"null"}],"description":"Why the document was rejected or failed; null otherwise."},"classification":{"type":"object","properties":{"source":{"type":"string","enum":["line","override","default"],"description":"default when any line took Tallio's default, else override when any line took the merchant's override, else line."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to check before issuing, e.g. that defaults were applied."}},"required":["source","warnings"],"additionalProperties":false,"description":"How the document was classified for myDATA."},"timeline":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[0-9A-Za-z]{22}$","description":"Id of the event (evt_…).","example":"evt_02y9O8rh7F50tGi0QcWRrx"},"type":{"type":"string","enum":["document.created","document.issued","document.rejected","document.failed"],"description":"What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it)."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the event happened.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","type","created"],"additionalProperties":false,"description":"One event in a document's history. GET /events/{id} returns the full Event."},"description":"The document's events, oldest first, at most 100."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When Tallio accepted the document.","example":"2026-10-11T09:30:00.000Z"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the document last changed.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","object","merchant","mode","provider","type","status","stage","issue_date","currency","net","vat","gross","mark","uid","qr_url","error","classification","timeline","created","updated"],"additionalProperties":false,"description":"A fiscal document Tallio issues through a provider, with its status and history.","examples":[{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"issued","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":"900000000000001","uid":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F","qr_url":"https://sandbox.tallio.invalid/qr/900000000000001","error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","type":"document.issued","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"}]}},"required":["data"],"additionalProperties":false,"description":"Success envelope: the result is under `data`."}}}},"401":{"$ref":"#/components/responses/Unauthorized","description":"`unauthorized`: Authentication is required."},"404":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`not_found`: The requested resource was not found."},"429":{"$ref":"#/components/responses/RateLimited","description":"`rate_limited`: A rate limit was reached. Retry later."},"500":{"$ref":"#/components/responses/ApiError","description":"`internal_error`: An unexpected server error occurred."}},"security":[{"apiKey":[]}],"x-tallio-error-codes":[{"code":"unauthorized","status":401},{"code":"not_found","status":404},{"code":"rate_limited","status":429},{"code":"internal_error","status":500}]}},"/api/v1/documents/preview":{"post":{"operationId":"previewDocument","summary":"Preview a document","description":"Preview a document without issuing it: Tallio validates it, applies classification defaults and returns the payload the provider would receive. Nothing is sent to the provider or to AADE.","tags":["documents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"supplier":{"type":"object","properties":{"tax_id":{"type":"object","properties":{"country":{"type":"string","const":"GR","description":"Country of the tax registration: GR. Suppliers are Greek merchants."},"code":{"description":"Tax number without a country prefix: the 9-digit ΑΦΜ for GR, 2 to 30 letters and digits elsewhere. Spaces, hyphens and dots are removed and letters upper-cased before it is checked.","example":"555555559","type":"string","maxLength":60}},"required":["country","code"],"description":"Greek tax identity: GR plus the ΑΦΜ."},"name":{"description":"Legal name. Required outside Greece. Optional for Greek parties, whose name AADE holds; adapters drop it when they send a Greek party straight to myDATA, which rejects it.","type":"string","minLength":1,"maxLength":200},"address":{"description":"Postal address. Required outside Greece.","type":"object","properties":{"street":{"description":"Street name.","type":"string","minLength":1,"maxLength":150},"number":{"description":"Street number.","type":"string","minLength":1,"maxLength":20},"postal_code":{"type":"string","minLength":1,"maxLength":20,"description":"Postal code."},"city":{"type":"string","minLength":1,"maxLength":150,"description":"City."}},"required":["postal_code","city"]},"branch":{"description":"Branch number in the AADE registry; omit or 0 for the head office.","type":"integer","minimum":0,"maximum":9999}},"required":["tax_id"],"description":"The merchant issuing the document, registered in Greece."},"customer":{"description":"The customer. Required for 1.1, 2.1, 5.1, 5.2; not allowed on retail receipts (11.1, 11.2).","type":"object","properties":{"tax_id":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country of the tax registration: GR for Greece (not the VAT prefix EL).","example":"GR"},"code":{"description":"Tax number without a country prefix: the 9-digit ΑΦΜ for GR, 2 to 30 letters and digits elsewhere. Spaces, hyphens and dots are removed and letters upper-cased before it is checked.","example":"555555559","type":"string","maxLength":60}},"required":["country","code"],"description":"Tax identity: country plus tax number."},"name":{"description":"Legal name. Required outside Greece. Optional for Greek parties, whose name AADE holds; adapters drop it when they send a Greek party straight to myDATA, which rejects it.","type":"string","minLength":1,"maxLength":200},"address":{"description":"Postal address. Required outside Greece.","type":"object","properties":{"street":{"description":"Street name.","type":"string","minLength":1,"maxLength":150},"number":{"description":"Street number.","type":"string","minLength":1,"maxLength":20},"postal_code":{"type":"string","minLength":1,"maxLength":20,"description":"Postal code."},"city":{"type":"string","minLength":1,"maxLength":150,"description":"City."}},"required":["postal_code","city"]},"branch":{"description":"Branch number in the AADE registry; omit or 0 for the head office.","type":"integer","minimum":0,"maximum":9999}},"required":["tax_id"]},"original_marks":{"description":"MARKs of the documents a 5.1 credit note corrects. Required for 5.1 and allowed only there.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"}},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":300,"description":"What was sold, as printed on the document."},"quantity":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,3})?$","description":"Quantity, a decimal string below 1000000000 with up to 3 decimals, greater than 0, e.g. \"2\" or \"1.5\" (kg).","example":"1.5"},"unit":{"type":"string","enum":["piece","kg","litre","metre","square_metre","cubic_metre"],"description":"Unit the quantity is measured in: piece (myDATA 1), kg (myDATA 2), litre (myDATA 3), metre (myDATA 4), square_metre (myDATA 5), cubic_metre (myDATA 6)."},"unit_price":{"type":"integer","minimum":0,"maximum":100000000000,"description":"Net price per unit in minor units (cents), at most 100000000000."},"vat_category":{"type":"string","enum":["standard","reduced","super_reduced","standard_island","reduced_island","super_reduced_island","exempt"],"description":"Greek VAT category of the line, which fixes its rate: standard 24% (myDATA 1), reduced 13% (myDATA 2), super_reduced 6% (myDATA 3), standard_island 17% (myDATA 4), reduced_island 9% (myDATA 5), super_reduced_island 4% (myDATA 6), exempt 0% (myDATA 7). An exempt line needs vat_exemption."},"vat_exemption":{"type":"integer","minimum":1,"maximum":31,"description":"myDATA VAT exemption cause (1-31), e.g. 14 for article 33 of the VAT code (Law 5144/2024). Required on exempt lines only."},"income_classification":{"type":"object","properties":{"category":{"type":"string","enum":["category1_1","category1_2","category1_3","category1_4","category1_5","category1_6","category1_7","category1_8","category1_9","category1_10","category1_95"],"description":"myDATA income classification category, e.g. category1_1 sale of goods, category1_2 sale of products, category1_3 provision of services, category1_95 other income information."},"type":{"description":"E3 income type. Required, except that category1_95 takes none or one of E3_596, E3_597.","type":"string","enum":["E3_106","E3_205","E3_210","E3_305","E3_310","E3_318","E3_561_001","E3_561_002","E3_561_003","E3_561_004","E3_561_005","E3_561_006","E3_561_007","E3_562","E3_563","E3_564","E3_565","E3_566","E3_567","E3_568","E3_570","E3_595","E3_596","E3_597","E3_880_001","E3_880_002","E3_880_003","E3_880_004","E3_881_001","E3_881_002","E3_881_003","E3_881_004","E3_598_001","E3_598_003"]}},"required":["category"],"description":"Explicit myDATA income classification for the line. Omit it to have Tallio apply and report a default."}},"required":["description","quantity","unit_price","vat_category"],"description":"One line. Its net amount is quantity × unit_price, rounded half up to the cent, at most 1000000000000000."},"description":"The document's lines, from 1 to 1000."},"payments":{"description":"How the document is paid, up to 10 entries.","minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["domestic_account","foreign_account","cash","cheque","on_credit","web_banking","pos","iris"],"description":"How the document is paid: domestic_account (myDATA 1), foreign_account (myDATA 2), cash (myDATA 3), cheque (myDATA 4), on_credit (myDATA 5), web_banking (myDATA 6), pos (myDATA 7), iris (myDATA 8)."},"amount":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"Amount paid this way, in minor units, at most 1250000000000000."}},"required":["method","amount"],"description":"One way the document is paid."}},"totals":{"type":"object","properties":{"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."}},"required":["net","vat","gross"],"description":"Document totals. Tallio rejects totals that do not add up."}},"required":["type","issue_date","currency","supplier","lines","totals"],"description":"Preview a document without issuing it: Tallio validates it, applies classification defaults and returns the payload the provider would receive. Nothing is sent to the provider or to AADE.","examples":[{"type":"1.1","issue_date":"2026-10-10","currency":"EUR","supplier":{"tax_id":{"country":"GR","code":"555555559"}},"customer":{"tax_id":{"country":"GR","code":"666666662"},"name":"Kafeneio Lemonia IKE"},"lines":[{"description":"Olive oil, bulk","quantity":"1.5","unit":"litre","unit_price":1000,"vat_category":"reduced","income_classification":{"category":"category1_1","type":"E3_561_001"}},{"description":"Delivery","quantity":"1","unit_price":1000,"vat_category":"standard"}],"payments":[{"method":"cash","amount":2935}],"totals":{"net":2500,"vat":435,"gross":2935}}]}}}},"responses":{"200":{"description":"The preview.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"ratelimit-limit":{"$ref":"#/components/headers/RatelimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RatelimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RatelimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["sandbox","mydata","wrapp","impact","epsilon","softone","prosvasis"],"description":"The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document."},"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"totals":{"type":"object","properties":{"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."}},"required":["net","vat","gross"],"additionalProperties":false,"description":"Document totals. Tallio rejects totals that do not add up."},"classification":{"type":"object","properties":{"source":{"type":"string","enum":["line","override","default"],"description":"default when any line took Tallio's default, else override when any line took the merchant's override, else line."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to check before issuing, e.g. that defaults were applied."}},"required":["source","warnings"],"additionalProperties":false,"description":"How the document will be classified for myDATA."},"payload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The request Tallio would send to the provider, in the provider's own format."}},"required":["provider","type","totals","classification","payload"],"additionalProperties":false,"description":"What issuing this document would do. Nothing has been issued.","examples":[{"provider":"sandbox","type":"1.1","totals":{"net":2500,"vat":435,"gross":2935},"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"payload":{"invoice_type":"1.1","currency":"EUR","line_count":2,"total_gross":2935}}]}},"required":["data"],"additionalProperties":false,"description":"Success envelope: the result is under `data`."}}}},"400":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`validation_failed`: Request validation failed."},"401":{"$ref":"#/components/responses/Unauthorized","description":"`unauthorized`: Authentication is required."},"413":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`payload_too_large`: The request body is too large."},"415":{"$ref":"#/components/responses/ApiErrorWithBudget","description":"`unsupported_media_type`: The request body must be JSON (Content-Type: application/json)."},"429":{"$ref":"#/components/responses/RateLimited","description":"`rate_limited`: A rate limit was reached. Retry later."},"500":{"$ref":"#/components/responses/ApiError","description":"`internal_error`: An unexpected server error occurred."}},"security":[{"apiKey":[]}],"x-tallio-error-codes":[{"code":"validation_failed","status":400},{"code":"payload_too_large","status":413},{"code":"unsupported_media_type","status":415},{"code":"unauthorized","status":401},{"code":"rate_limited","status":429},{"code":"internal_error","status":500}]}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"Fetch this OpenAPI document","description":"Returns the OpenAPI 3.1 description of this API, the same file the SDKs are generated from. Public, because a client needs the spec before it can authenticate.","tags":["meta"],"responses":{"200":{"description":"The OpenAPI document.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string","description":"The OpenAPI version, `3.1.0`."},"info":{"type":"object","properties":{"title":{"type":"string","description":"The API's name."},"version":{"type":"string","description":"The API version."}},"required":["title","version"],"additionalProperties":{},"description":"Title, version and overview of the API."},"paths":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Every operation, by path and method."},"components":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Shared schemas, responses, parameters and headers."}},"required":["openapi","info","paths","components"],"additionalProperties":{},"description":"The OpenAPI 3.1 description of this API."}}}},"429":{"$ref":"#/components/responses/RateLimited","description":"`rate_limited`: A rate limit was reached. Retry later."},"500":{"$ref":"#/components/responses/ApiError","description":"`internal_error`: An unexpected server error occurred."}},"security":[],"x-tallio-error-codes":[{"code":"rate_limited","status":429},{"code":"internal_error","status":500}]}}},"webhooks":{"document.created":{"post":{"operationId":"webhookDocumentCreated","summary":"The document.created event","description":"Sent to every endpoint subscribed to document.created or *. Answer 2xx; anything else is retried.","security":[],"parameters":[{"name":"tallio-signature","in":"header","required":true,"description":"t=<unix seconds>,v1=<signature>[,v1=…]. The signature is the lowercase hex HMAC-SHA256 of `<t>.<raw body bytes>`, keyed with the endpoint's full secret string (whsec_ included) as UTF-8. Use a constant-time comparison; any one of up to 8 v1 values may match (a secret rolling). Ignore elements you do not know. Reject a t more than 300 seconds away from now.","schema":{"type":"string","pattern":"^t=\\d+(?:,[a-z0-9]+=[^,\\s]+)+$","example":"t=1760175000,v1=5555555555555555555555555555555555555555555555555555555555555555"},"x-tallio-tolerance-sec":300,"x-tallio-max-signatures":8,"x-tallio-signature-scheme":"v1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"properties":{"type":{"const":"document.created"}}}],"examples":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","object":"event","type":"document.created","created":"2026-10-11T09:30:00.000Z","api_version":"0.1.0","livemode":false,"data":{"object":{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"pending","stage":"queued","issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":null,"uid":null,"qr_url":null,"error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:00.000Z"}},"request":{"id":"req_0192f4c1-7a40-7c42-9b1d-4e5f6a7b8c9d","idempotency_key":"order-1042"}}]}}}},"responses":{"2XX":{"description":"Received."}}}},"document.issued":{"post":{"operationId":"webhookDocumentIssued","summary":"The document.issued event","description":"Sent to every endpoint subscribed to document.issued or *. Answer 2xx; anything else is retried.","security":[],"parameters":[{"name":"tallio-signature","in":"header","required":true,"description":"t=<unix seconds>,v1=<signature>[,v1=…]. The signature is the lowercase hex HMAC-SHA256 of `<t>.<raw body bytes>`, keyed with the endpoint's full secret string (whsec_ included) as UTF-8. Use a constant-time comparison; any one of up to 8 v1 values may match (a secret rolling). Ignore elements you do not know. Reject a t more than 300 seconds away from now.","schema":{"type":"string","pattern":"^t=\\d+(?:,[a-z0-9]+=[^,\\s]+)+$","example":"t=1760175000,v1=5555555555555555555555555555555555555555555555555555555555555555"},"x-tallio-tolerance-sec":300,"x-tallio-max-signatures":8,"x-tallio-signature-scheme":"v1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"properties":{"type":{"const":"document.issued"}}}],"examples":[{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","object":"event","type":"document.issued","created":"2026-10-11T09:30:02.000Z","api_version":"0.1.0","livemode":false,"data":{"object":{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"issued","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":"900000000000001","uid":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F","qr_url":"https://sandbox.tallio.invalid/qr/900000000000001","error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","type":"document.issued","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"},"previous_attributes":{"status":"pending","stage":"awaiting_mark","mark":null,"uid":null,"qr_url":null,"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"updated":"2026-10-11T09:30:00.000Z"}},"request":null}]}}}},"responses":{"2XX":{"description":"Received."}}}},"document.rejected":{"post":{"operationId":"webhookDocumentRejected","summary":"The document.rejected event","description":"Sent to every endpoint subscribed to document.rejected or *. Answer 2xx; anything else is retried.","security":[],"parameters":[{"name":"tallio-signature","in":"header","required":true,"description":"t=<unix seconds>,v1=<signature>[,v1=…]. The signature is the lowercase hex HMAC-SHA256 of `<t>.<raw body bytes>`, keyed with the endpoint's full secret string (whsec_ included) as UTF-8. Use a constant-time comparison; any one of up to 8 v1 values may match (a secret rolling). Ignore elements you do not know. Reject a t more than 300 seconds away from now.","schema":{"type":"string","pattern":"^t=\\d+(?:,[a-z0-9]+=[^,\\s]+)+$","example":"t=1760175000,v1=5555555555555555555555555555555555555555555555555555555555555555"},"x-tallio-tolerance-sec":300,"x-tallio-max-signatures":8,"x-tallio-signature-scheme":"v1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"properties":{"type":{"const":"document.rejected"}}}],"examples":[{"id":"evt_02y9O8s1a8ymJqpmAy0nLf","object":"event","type":"document.rejected","created":"2026-10-11T09:30:02.000Z","api_version":"0.1.0","livemode":false,"data":{"object":{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"rejected","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":null,"uid":null,"qr_url":null,"error":{"code":"provider_rejected","message":"The provider rejected the document.","provider_code":"228","provider_message":"Invalid counterpart VAT number.","retryable":false},"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLf","type":"document.rejected","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"},"previous_attributes":{"status":"pending","stage":"awaiting_mark","error":null,"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"updated":"2026-10-11T09:30:00.000Z"}},"request":null}]}}}},"responses":{"2XX":{"description":"Received."}}}},"document.failed":{"post":{"operationId":"webhookDocumentFailed","summary":"The document.failed event","description":"Sent to every endpoint subscribed to document.failed or *. Answer 2xx; anything else is retried.","security":[],"parameters":[{"name":"tallio-signature","in":"header","required":true,"description":"t=<unix seconds>,v1=<signature>[,v1=…]. The signature is the lowercase hex HMAC-SHA256 of `<t>.<raw body bytes>`, keyed with the endpoint's full secret string (whsec_ included) as UTF-8. Use a constant-time comparison; any one of up to 8 v1 values may match (a secret rolling). Ignore elements you do not know. Reject a t more than 300 seconds away from now.","schema":{"type":"string","pattern":"^t=\\d+(?:,[a-z0-9]+=[^,\\s]+)+$","example":"t=1760175000,v1=5555555555555555555555555555555555555555555555555555555555555555"},"x-tallio-tolerance-sec":300,"x-tallio-max-signatures":8,"x-tallio-signature-scheme":"v1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"properties":{"type":{"const":"document.failed"}}}],"examples":[{"id":"evt_02y9O8s1a8ymJqpmAy0nLg","object":"event","type":"document.failed","created":"2026-10-11T09:30:02.000Z","api_version":"0.1.0","livemode":false,"data":{"object":{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"failed","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":null,"uid":null,"qr_url":null,"error":{"code":"provider_unavailable","message":"The provider is temporarily unavailable.","provider_code":null,"provider_message":null,"retryable":true},"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLg","type":"document.failed","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"},"previous_attributes":{"status":"pending","stage":"submitting","error":null,"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"updated":"2026-10-11T09:30:00.000Z"}},"request":null}]}}}},"responses":{"2XX":{"description":"Received."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_… or sk_test_…","description":"A vendor secret key, `sk_live_…` or `sk_test_…`, sent as `Authorization: Bearer <key>`."}},"parameters":{"IdempotencyKey":{"name":"idempotency-key","in":"header","required":true,"description":"A key you choose (1-255 printable ASCII characters, e.g. a UUID) that makes a create request safe to retry: the same key with the same body returns the first result instead of creating a second document.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7E]+$","example":"order-1042"}}},"schemas":{"ApiError":{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","not_found","idempotency_conflict","idempotency_in_progress","payload_too_large","unsupported_media_type","rate_limited","not_supported","provider_rejected","provider_unavailable","internal_error"],"description":"Stable machine-readable error code. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to a developer."},"provider_code":{"description":"The provider's own error code, or null when the error did not come from a provider.","type":["string","null"]},"provider_message":{"description":"The provider's own error message, verbatim, or null when the error did not come from a provider.","type":["string","null"]},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."},"provider_raw":{"description":"The provider's error response body as received. Present whenever the error came from a provider; never holds request headers, credentials or the request payload."}},"required":["code","message","provider_code","provider_message","retryable"],"additionalProperties":false,"description":"The one error shape every endpoint returns, whichever provider is involved."},"Event":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[0-9A-Za-z]{22}$","description":"Id of the event (evt_…).","example":"evt_02y9O8rh7F50tGi0QcWRrx"},"object":{"type":"string","const":"event","description":"Always \"event\"."},"type":{"type":"string","enum":["document.created","document.issued","document.rejected","document.failed"],"description":"What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it)."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the event happened.","example":"2026-10-11T09:30:00.000Z"},"api_version":{"type":"string","description":"The API version data.object is rendered in, e.g. 0.1.0."},"livemode":{"type":"boolean","description":"True for an event from live mode, false for test mode."},"data":{"type":"object","properties":{"object":{"type":"object","properties":{"id":{"type":"string","pattern":"^doc_[0-9A-Za-z]{22}$","description":"Id of the document (doc_…).","example":"doc_02y9O8rh7F50tGi0QcWRrx"},"object":{"type":"string","const":"document","description":"Always \"document\"."},"merchant":{"type":"string","pattern":"^mer_[0-9A-Za-z]{22}$","description":"Id of the merchant (mer_…).","example":"mer_02y9O8rh7F50tGi0QcWRrx"},"mode":{"type":"string","enum":["live","test"],"description":"live for a document created with a live key, test for a test key."},"provider":{"type":"string","enum":["sandbox","mydata","wrapp","impact","epsilon","softone","prosvasis"],"description":"The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document."},"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"status":{"type":"string","enum":["pending","issued","rejected","failed"],"description":"Where the document stands: pending (Tallio accepted it; not yet issued, see stage), issued (has a MARK), rejected (the provider or AADE refused it), failed (Tallio could not deliver it to the provider)."},"stage":{"anyOf":[{"type":"string","enum":["queued","submitting","awaiting_mark","reconciling"],"description":"Where a pending document is: queued (waiting to be sent), submitting (being sent to the provider), awaiting_mark (the provider accepted it, MARK not yet assigned), reconciling (the outcome of a send is unknown and is being checked with the provider before any resend)."},{"type":"null"}],"description":"Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."},"mark":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"},{"type":"null"}],"description":"MARK (AADE registration number) once issued, as a digit string; null before."},"uid":{"anyOf":[{"type":"string","pattern":"^[0-9A-F]{40}$","example":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F"},{"type":"null"}],"description":"myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known."},"qr_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"URL the document's QR code points to; null until the provider returns one."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","not_found","idempotency_conflict","idempotency_in_progress","payload_too_large","unsupported_media_type","rate_limited","not_supported","provider_rejected","provider_unavailable","internal_error"],"description":"Stable machine-readable error code. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to a developer."},"provider_code":{"description":"The provider's own error code, or null when the error did not come from a provider.","type":["string","null"]},"provider_message":{"description":"The provider's own error message, verbatim, or null when the error did not come from a provider.","type":["string","null"]},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."},"provider_raw":{"description":"The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload."}},"required":["code","message","provider_code","provider_message","retryable"],"additionalProperties":false,"description":"The error shape as embedded in a Document, an Event or a webhook: provider_raw is size-bounded."},{"type":"null"}],"description":"Why the document was rejected or failed; null otherwise."},"classification":{"type":"object","properties":{"source":{"type":"string","enum":["line","override","default"],"description":"default when any line took Tallio's default, else override when any line took the merchant's override, else line."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to check before issuing, e.g. that defaults were applied."}},"required":["source","warnings"],"additionalProperties":false,"description":"How the document was classified for myDATA."},"timeline":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[0-9A-Za-z]{22}$","description":"Id of the event (evt_…).","example":"evt_02y9O8rh7F50tGi0QcWRrx"},"type":{"type":"string","enum":["document.created","document.issued","document.rejected","document.failed"],"description":"What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it)."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the event happened.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","type","created"],"additionalProperties":false,"description":"One event in a document's history. GET /events/{id} returns the full Event."},"description":"The document's events, oldest first, at most 100."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When Tallio accepted the document.","example":"2026-10-11T09:30:00.000Z"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the document last changed.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","object","merchant","mode","provider","type","status","stage","issue_date","currency","net","vat","gross","mark","uid","qr_url","error","classification","timeline","created","updated"],"additionalProperties":false,"description":"The document as it was right after the event.","examples":[{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"issued","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":"900000000000001","uid":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F","qr_url":"https://sandbox.tallio.invalid/qr/900000000000001","error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","type":"document.issued","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"}]},"previous_attributes":{"type":"object","properties":{"id":{"type":"string","pattern":"^doc_[0-9A-Za-z]{22}$","description":"Id of the document (doc_…).","example":"doc_02y9O8rh7F50tGi0QcWRrx"},"object":{"type":"string","const":"document","description":"Always \"document\"."},"merchant":{"type":"string","pattern":"^mer_[0-9A-Za-z]{22}$","description":"Id of the merchant (mer_…).","example":"mer_02y9O8rh7F50tGi0QcWRrx"},"mode":{"type":"string","enum":["live","test"],"description":"live for a document created with a live key, test for a test key."},"provider":{"type":"string","enum":["sandbox","mydata","wrapp","impact","epsilon","softone","prosvasis"],"description":"The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document."},"type":{"type":"string","enum":["1.1","2.1","5.1","5.2","11.1","11.2"],"description":"AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt."},"status":{"type":"string","enum":["pending","issued","rejected","failed"],"description":"Where the document stands: pending (Tallio accepted it; not yet issued, see stage), issued (has a MARK), rejected (the provider or AADE refused it), failed (Tallio could not deliver it to the provider)."},"stage":{"anyOf":[{"type":"string","enum":["queued","submitting","awaiting_mark","reconciling"],"description":"Where a pending document is: queued (waiting to be sent), submitting (being sent to the provider), awaiting_mark (the provider accepted it, MARK not yet assigned), reconciling (the outcome of a send is unknown and is being checked with the provider before any resend)."},{"type":"null"}],"description":"Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending."},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Issue date, YYYY-MM-DD.","example":"2026-10-11"},"currency":{"type":"string","const":"EUR","description":"ISO 4217 currency. Only EUR for now."},"net":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' net amounts, in minor units, at most 1000000000000000."},"vat":{"type":"integer","minimum":0,"maximum":1000000000000000,"description":"Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000."},"gross":{"type":"integer","minimum":0,"maximum":1250000000000000,"description":"net + vat, in minor units, at most 1250000000000000."},"mark":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$","description":"MARK (AADE registration number) of an issued document.","example":"400001234567890"},{"type":"null"}],"description":"MARK (AADE registration number) once issued, as a digit string; null before."},"uid":{"anyOf":[{"type":"string","pattern":"^[0-9A-F]{40}$","example":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F"},{"type":"null"}],"description":"myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known."},"qr_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"URL the document's QR code points to; null until the provider returns one."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","not_found","idempotency_conflict","idempotency_in_progress","payload_too_large","unsupported_media_type","rate_limited","not_supported","provider_rejected","provider_unavailable","internal_error"],"description":"Stable machine-readable error code. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to a developer."},"provider_code":{"description":"The provider's own error code, or null when the error did not come from a provider.","type":["string","null"]},"provider_message":{"description":"The provider's own error message, verbatim, or null when the error did not come from a provider.","type":["string","null"]},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."},"provider_raw":{"description":"The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload."}},"required":["code","message","provider_code","provider_message","retryable"],"additionalProperties":false,"description":"The error shape as embedded in a Document, an Event or a webhook: provider_raw is size-bounded."},{"type":"null"}],"description":"Why the document was rejected or failed; null otherwise."},"classification":{"type":"object","properties":{"source":{"type":"string","enum":["line","override","default"],"description":"default when any line took Tallio's default, else override when any line took the merchant's override, else line."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to check before issuing, e.g. that defaults were applied."}},"required":["source","warnings"],"additionalProperties":false,"description":"How the document was classified for myDATA."},"timeline":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[0-9A-Za-z]{22}$","description":"Id of the event (evt_…).","example":"evt_02y9O8rh7F50tGi0QcWRrx"},"type":{"type":"string","enum":["document.created","document.issued","document.rejected","document.failed"],"description":"What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it)."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the event happened.","example":"2026-10-11T09:30:00.000Z"}},"required":["id","type","created"],"additionalProperties":false,"description":"One event in a document's history. GET /events/{id} returns the full Event."},"description":"The document's events, oldest first, at most 100."},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When Tallio accepted the document.","example":"2026-10-11T09:30:00.000Z"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the document last changed.","example":"2026-10-11T09:30:00.000Z"}},"additionalProperties":false,"description":"The values the changed fields had before the event; absent for an event that changed nothing."}},"required":["object"],"additionalProperties":false,"description":"The object the event is about."},"request":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","pattern":"^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$","description":"Request id (the x-request-id response header) of the API call that caused it.","example":"req_0192f4c1-7a40-7c42-9b1d-4e5f6a7b8c9d"},"idempotency_key":{"anyOf":[{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7E]+$","description":"A key you choose (1-255 printable ASCII characters, e.g. a UUID) that makes a create request safe to retry: the same key with the same body returns the first result instead of creating a second document.","example":"order-1042"},{"type":"null"}],"description":"The Idempotency-Key that call sent, or null."}},"required":["id","idempotency_key"],"additionalProperties":false},{"type":"null"}],"description":"The API call that caused the event; null when Tallio caused it, e.g. issuing in the background."}},"required":["id","object","type","created","api_version","livemode","data","request"],"additionalProperties":false,"description":"Something that happened in your account. Webhooks deliver these; consumers dedupe on id.","examples":[{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","object":"event","type":"document.issued","created":"2026-10-11T09:30:02.000Z","api_version":"0.1.0","livemode":false,"data":{"object":{"id":"doc_02y9O8rhJKVUXRvojdffcz","object":"document","merchant":"mer_02y9O8rh7F50tGi0QcWRrx","mode":"test","provider":"sandbox","type":"1.1","status":"issued","stage":null,"issue_date":"2026-10-10","currency":"EUR","net":2500,"vat":435,"gross":2935,"mark":"900000000000001","uid":"4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F","qr_url":"https://sandbox.tallio.invalid/qr/900000000000001","error":null,"classification":{"source":"default","warnings":["No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."]},"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"},{"id":"evt_02y9O8s1a8ymJqpmAy0nLe","type":"document.issued","created":"2026-10-11T09:30:02.000Z"}],"created":"2026-10-11T09:30:00.000Z","updated":"2026-10-11T09:30:02.000Z"},"previous_attributes":{"status":"pending","stage":"awaiting_mark","mark":null,"uid":null,"qr_url":null,"timeline":[{"id":"evt_02y9O8rhJ2Z2v1fOH2XiSH","type":"document.created","created":"2026-10-11T09:30:00.000Z"}],"updated":"2026-10-11T09:30:00.000Z"}},"request":null}]}},"headers":{"RequestId":{"description":"The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.","schema":{"type":"string","pattern":"^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$","example":"req_0192f4c1-7a40-7c42-9b1d-4e5f6a7b8c9d"}},"RatelimitLimit":{"description":"Requests allowed in the current window for the bucket this request counted against.","schema":{"type":"integer","minimum":1}},"RatelimitRemaining":{"description":"Requests left in the current window; 0 means the next one is refused until the window resets.","schema":{"type":"integer","minimum":0}},"RatelimitReset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","minimum":0}},"RetryAfter":{"description":"Seconds to wait before retrying a request refused with 429 `rate_limited`.","schema":{"type":"integer","minimum":1}},"IdempotentReplayed":{"description":"true when this answer replays an earlier request with the same Idempotency-Key (nothing new was created); absent on the request that created it.","schema":{"type":"string","const":"true"}}},"responses":{"ApiError":{"description":"Error","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ApiErrorWithBudget":{"description":"Error, with the budget the request was charged","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"ratelimit-limit":{"$ref":"#/components/headers/RatelimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RatelimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RatelimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"Missing or invalid API key","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"www-authenticate":{"description":"The bearer challenge: send a vendor secret key as `Authorization: Bearer <key>`.","schema":{"type":"string","const":"Bearer realm=\"tallio\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit reached","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"retry-after":{"$ref":"#/components/headers/RetryAfter"},"ratelimit-limit":{"$ref":"#/components/headers/RatelimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RatelimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RatelimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}