Μενού τεκμηρίωσης: Documents

Documents

Preview and issue fiscal documents.

Η αναφορά API είναι διαθέσιμη μόνο στα αγγλικά, όπως και το API.

Σε αυτή τη σελίδα

Issue a document
Retrieve a document
Preview a document

Issue a document #

POST /api/v1/documents

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.

Bearer API key
Idempotency-Key required

Header parameters

idempotency-keystringrequired: 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.
1 to 255 characters
Show patternHide pattern
^[\x21-\x7E]+$

Request body

merchantstringrequired

The merchant issuing the document (mer_…), created under your account.

Show pattern

^mer_[0-9A-Za-z]{22}$

documentobjectrequired

Tallio's canonical document (v0, GOBL-inspired): one shape for every provider. Amounts are integer minor units.

Show nested fields (9)

typestringrequired

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.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

issue_datestringrequired

Issue date, YYYY-MM-DD.

Format: date

currencystringrequired

ISO 4217 currency. Only EUR for now.

Always EUR

supplierobjectrequired

The merchant issuing the document, registered in Greece.

Show nested fields (4)

tax_idobjectrequired

Greek tax identity: GR plus the ΑΦΜ.

Show nested fields (2)

countrystringrequired: Country of the tax registration: GR. Suppliers are Greek merchants.
Always GR
codestringrequired: 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.
Up to 60 characters

namestring

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.

1 to 200 characters

addressobject

Postal address. Required outside Greece.

Show nested fields (4)

streetstring: Street name.
1 to 150 characters
numberstring: Street number.
1 to 20 characters
postal_codestringrequired: Postal code.
1 to 20 characters
citystringrequired: City.
1 to 150 characters

branchinteger

Branch number in the AADE registry; omit or 0 for the head office.

From 0 to 9999

customerobject

The customer. Required for 1.1, 2.1, 5.1, 5.2; not allowed on retail receipts (11.1, 11.2).

Show nested fields (4)

tax_idobjectrequired

Tax identity: country plus tax number.

Show nested fields (2)

countrystringrequired: ISO 3166-1 alpha-2 country of the tax registration: GR for Greece (not the VAT prefix EL).
Show patternHide pattern
^[A-Z]{2}$
codestringrequired: 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.
Up to 60 characters

namestring

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.

1 to 200 characters

addressobject

Postal address. Required outside Greece.

Show nested fields (4)

streetstring: Street name.
1 to 150 characters
numberstring: Street number.
1 to 20 characters
postal_codestringrequired: Postal code.
1 to 20 characters
citystringrequired: City.
1 to 150 characters

branchinteger

Branch number in the AADE registry; omit or 0 for the head office.

From 0 to 9999

original_marksstring[]

MARKs of the documents a 5.1 credit note corrects. Required for 5.1 and allowed only there.

1 to 1000 items

Each item: MARK (AADE registration number) of an issued document.

Show pattern

^[1-9]\d{0,18}$

linesobject[]required

The document's lines, from 1 to 1000.

1 to 1000 items

Each item: One line. Its net amount is quantity × unit_price, rounded half up to the cent, at most 1000000000000000.

Show nested fields (7)

descriptionstringrequired

What was sold, as printed on the document.

1 to 300 characters

quantitystringrequired

Quantity, a decimal string below 1000000000 with up to 3 decimals, greater than 0, e.g. "2" or "1.5" (kg).

Show pattern

^(0|[1-9]\d{0,8})(\.\d{1,3})?$

unitstring

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).

One of: piece, kg, litre, metre, square_metre, cubic_metre

unit_priceintegerrequired

Net price per unit in minor units (cents), at most 100000000000.

From 0 to 100000000000

vat_categorystringrequired

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.

One of: standard, reduced, super_reduced, standard_island, reduced_island, super_reduced_island, exempt

vat_exemptioninteger

myDATA VAT exemption cause (1-31), e.g. 14 for article 33 of the VAT code (Law 5144/2024). Required on exempt lines only.

From 1 to 31

income_classificationobject

Explicit myDATA income classification for the line. Omit it to have Tallio apply and report a default.

Show nested fields (2)

categorystringrequired: 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.
One of: category1_1, category1_2, category1_3, category1_4, category1_5, category1_6, category1_7, category1_8, category1_9, category1_10, category1_95
typestring: E3 income type. Required, except that category1_95 takes none or one of E3_596, E3_597.
One of: 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

paymentsobject[]

How the document is paid, up to 10 entries.

1 to 10 items

Each item: One way the document is paid.

Show nested fields (2)

methodstringrequired: 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).
One of: domestic_account, foreign_account, cash, cheque, on_credit, web_banking, pos, iris
amountintegerrequired: Amount paid this way, in minor units, at most 1250000000000000.
From 0 to 1250000000000000

totalsobjectrequired

Document totals. Tallio rejects totals that do not add up.

Show nested fields (3)

netintegerrequired: Sum of the lines' net amounts, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
vatintegerrequired: Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
grossintegerrequired: net + vat, in minor units, at most 1250000000000000.
From 0 to 1250000000000000

Request

JSON

{
  "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
    }
  }
}

curl

curl -X POST 'https://tallio.dev/api/v1/documents' \
  -H "Authorization: Bearer $TALLIO_API_KEY" \
  -H 'Idempotency-Key: order-1042' \
  -H "Content-Type: application/json" \
  -d '{
  "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
    }
  }
}'

TypeScript SDK

import { createTallioClient } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await tallio.createDocument({
  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,
    },
  },
}, {
  idempotencyKey: "order-1042",
});

Responses
Status	Description
`201`	Accepted as pending; it is issued in the background. A replay returns the first document.
4XX, 5XX	An error: see Errors below.

Response body · 201

dataobjectrequired

A fiscal document Tallio issues through a provider, with its status and history.

Show nested fields (21)

idstringrequired

Id of the document (doc_…).

Show pattern

^doc_[0-9A-Za-z]{22}$

objectstringrequired

Always "document".

Always document

merchantstringrequired

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

modestringrequired

live for a document created with a live key, test for a test key.

One of: live, test

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

typestringrequired

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.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

statusstringrequired

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).

One of: pending, issued, rejected, failed

stagestring | nullrequired

Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending.

One of: queued, submitting, awaiting_mark, reconciling

issue_datestringrequired

Issue date, YYYY-MM-DD.

Format: date

currencystringrequired

ISO 4217 currency. Only EUR for now.

Always EUR

netintegerrequired

Sum of the lines' net amounts, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

vatintegerrequired

Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

grossintegerrequired

net + vat, in minor units, at most 1250000000000000.

From 0 to 1250000000000000

markstring | nullrequired

MARK (AADE registration number) once issued, as a digit string; null before.

Show pattern

^[1-9]\d{0,18}$

uidstring | nullrequired

myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known.

Show pattern

^[0-9A-F]{40}$

qr_urlstring | nullrequired

URL the document's QR code points to; null until the provider returns one.

Format: uri

errorobject | nullrequired

Why the document was rejected or failed; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: 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
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: 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.

classificationobjectrequired

How the document was classified for myDATA.

Show nested fields (2)

sourcestringrequired: default when any line took Tallio's default, else override when any line took the merchant's override, else line.
One of: line, override, default
warningsstring[]required: What to check before issuing, e.g. that defaults were applied.

timelineobject[]required

The document's events, oldest first, at most 100.

Up to 100 items

Each item: One event in a document's history. GET /events/{id} returns the full Event.

Show nested fields (3)

idstringrequired: Id of the event (evt_…).
Show patternHide pattern
^evt_[0-9A-Za-z]{22}$
typestringrequired: 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).
One of: document.created, document.issued, document.rejected, document.failed
createdstringrequired: When the event happened.
Format: date-time

createdstringrequired

When Tallio accepted the document.

Format: date-time

updatedstringrequired

When the document last changed.

Format: date-time

Example response · 201

{
  "data": {
    "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"
  }
}

Response headers

x-request-idstring: 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.
With every response
Show patternHide 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})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 201, 400, 404, 409, 413, 415, 422, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 201, 400, 404, 409, 413, 415, 422, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 201, 400, 404, 409, 413, 415, 422, 429 · At least 0
idempotent-replayedstring: true when this answer replays an earlier request with the same Idempotency-Key (nothing new was created); absent on the request that created it.
With 201 · Always true
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`idempotency_conflict`	409	No	This idempotency key was already used with a different request.
`payload_too_large`	413	No	The request body is too large.
`unsupported_media_type`	415	No	The request body must be JSON (Content-Type: application/json).
`not_supported`	422	No	The provider or document type does not support this operation.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.

Retrieve a document #

GET /api/v1/documents/{id}

Returns a document with its status, MARK once issued, and its timeline of events.

Bearer API key

Path parameters

idstringrequired: The document's id (doc_…).

Request

curl

curl -X GET 'https://tallio.dev/api/v1/documents/doc_02y9O8rhJKVUXRvojdffcz' \
  -H "Authorization: Bearer $TALLIO_API_KEY"

TypeScript SDK

import { createTallioClient } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await tallio.getDocument("doc_02y9O8rhJKVUXRvojdffcz");

Responses
Status	Description
`200`	The document.
4XX, 5XX	An error: see Errors below.

Response body · 200

dataobjectrequired

A fiscal document Tallio issues through a provider, with its status and history.

Show nested fields (21)

idstringrequired

Id of the document (doc_…).

Show pattern

^doc_[0-9A-Za-z]{22}$

objectstringrequired

Always "document".

Always document

merchantstringrequired

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

modestringrequired

live for a document created with a live key, test for a test key.

One of: live, test

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

typestringrequired

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.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

statusstringrequired

One of: pending, issued, rejected, failed

stagestring | nullrequired

Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending.

One of: queued, submitting, awaiting_mark, reconciling

issue_datestringrequired

Issue date, YYYY-MM-DD.

Format: date

currencystringrequired

ISO 4217 currency. Only EUR for now.

Always EUR

netintegerrequired

Sum of the lines' net amounts, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

vatintegerrequired

Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

grossintegerrequired

net + vat, in minor units, at most 1250000000000000.

From 0 to 1250000000000000

markstring | nullrequired

MARK (AADE registration number) once issued, as a digit string; null before.

Show pattern

^[1-9]\d{0,18}$

uidstring | nullrequired

myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known.

Show pattern

^[0-9A-F]{40}$

qr_urlstring | nullrequired

URL the document's QR code points to; null until the provider returns one.

Format: uri

errorobject | nullrequired

Why the document was rejected or failed; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: 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
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: 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.

classificationobjectrequired

How the document was classified for myDATA.

Show nested fields (2)

sourcestringrequired: default when any line took Tallio's default, else override when any line took the merchant's override, else line.
One of: line, override, default
warningsstring[]required: What to check before issuing, e.g. that defaults were applied.

timelineobject[]required

The document's events, oldest first, at most 100.

Up to 100 items

Each item: One event in a document's history. GET /events/{id} returns the full Event.

Show nested fields (3)

idstringrequired: Id of the event (evt_…).
Show patternHide pattern
^evt_[0-9A-Za-z]{22}$
typestringrequired: 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).
One of: document.created, document.issued, document.rejected, document.failed
createdstringrequired: When the event happened.
Format: date-time

createdstringrequired

When Tallio accepted the document.

Format: date-time

updatedstringrequired

When the document last changed.

Format: date-time

Example response · 200

{
  "data": {
    "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"
  }
}

Response headers

x-request-idstring: 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.
With every response
Show patternHide 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})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 404, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 404, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 404, 429 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.

Preview a document #

POST /api/v1/documents/preview

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.

Bearer API key

Request body

typestringrequired

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.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

issue_datestringrequired

Issue date, YYYY-MM-DD.

Format: date

currencystringrequired

ISO 4217 currency. Only EUR for now.

Always EUR

supplierobjectrequired

The merchant issuing the document, registered in Greece.

Show nested fields (4)

tax_idobjectrequired

Greek tax identity: GR plus the ΑΦΜ.

Show nested fields (2)

countrystringrequired: Country of the tax registration: GR. Suppliers are Greek merchants.
Always GR
codestringrequired: 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.
Up to 60 characters

namestring

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.

1 to 200 characters

addressobject

Postal address. Required outside Greece.

Show nested fields (4)

streetstring: Street name.
1 to 150 characters
numberstring: Street number.
1 to 20 characters
postal_codestringrequired: Postal code.
1 to 20 characters
citystringrequired: City.
1 to 150 characters

branchinteger

Branch number in the AADE registry; omit or 0 for the head office.

From 0 to 9999

customerobject

The customer. Required for 1.1, 2.1, 5.1, 5.2; not allowed on retail receipts (11.1, 11.2).

Show nested fields (4)

tax_idobjectrequired

Tax identity: country plus tax number.

Show nested fields (2)

countrystringrequired: ISO 3166-1 alpha-2 country of the tax registration: GR for Greece (not the VAT prefix EL).
Show patternHide pattern
^[A-Z]{2}$
codestringrequired: 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.
Up to 60 characters

namestring

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.

1 to 200 characters

addressobject

Postal address. Required outside Greece.

Show nested fields (4)

streetstring: Street name.
1 to 150 characters
numberstring: Street number.
1 to 20 characters
postal_codestringrequired: Postal code.
1 to 20 characters
citystringrequired: City.
1 to 150 characters

branchinteger

Branch number in the AADE registry; omit or 0 for the head office.

From 0 to 9999

original_marksstring[]

MARKs of the documents a 5.1 credit note corrects. Required for 5.1 and allowed only there.

1 to 1000 items

Each item: MARK (AADE registration number) of an issued document.

Show pattern

^[1-9]\d{0,18}$

linesobject[]required

The document's lines, from 1 to 1000.

1 to 1000 items

Each item: One line. Its net amount is quantity × unit_price, rounded half up to the cent, at most 1000000000000000.

Show nested fields (7)

descriptionstringrequired

What was sold, as printed on the document.

1 to 300 characters

quantitystringrequired

Quantity, a decimal string below 1000000000 with up to 3 decimals, greater than 0, e.g. "2" or "1.5" (kg).

Show pattern

^(0|[1-9]\d{0,8})(\.\d{1,3})?$

unitstring

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).

One of: piece, kg, litre, metre, square_metre, cubic_metre

unit_priceintegerrequired

Net price per unit in minor units (cents), at most 100000000000.

From 0 to 100000000000

vat_categorystringrequired

One of: standard, reduced, super_reduced, standard_island, reduced_island, super_reduced_island, exempt

vat_exemptioninteger

myDATA VAT exemption cause (1-31), e.g. 14 for article 33 of the VAT code (Law 5144/2024). Required on exempt lines only.

From 1 to 31

income_classificationobject

Explicit myDATA income classification for the line. Omit it to have Tallio apply and report a default.

Show nested fields (2)

categorystringrequired: 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.
One of: category1_1, category1_2, category1_3, category1_4, category1_5, category1_6, category1_7, category1_8, category1_9, category1_10, category1_95
typestring: E3 income type. Required, except that category1_95 takes none or one of E3_596, E3_597.
One of: 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

paymentsobject[]

How the document is paid, up to 10 entries.

1 to 10 items

Each item: One way the document is paid.

Show nested fields (2)

methodstringrequired: 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).
One of: domestic_account, foreign_account, cash, cheque, on_credit, web_banking, pos, iris
amountintegerrequired: Amount paid this way, in minor units, at most 1250000000000000.
From 0 to 1250000000000000

totalsobjectrequired

Document totals. Tallio rejects totals that do not add up.

Show nested fields (3)

netintegerrequired: Sum of the lines' net amounts, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
vatintegerrequired: Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
grossintegerrequired: net + vat, in minor units, at most 1250000000000000.
From 0 to 1250000000000000

Request

JSON

{
  "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
  }
}

curl

curl -X POST 'https://tallio.dev/api/v1/documents/preview' \
  -H "Authorization: Bearer $TALLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}'

TypeScript SDK

import { createTallioClient } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await tallio.previewDocument({
  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
Status	Description
`200`	The preview.
4XX, 5XX	An error: see Errors below.

Response body · 200

dataobjectrequired

What issuing this document would do. Nothing has been issued.

Show nested fields (5)

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

typestringrequired

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.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

totalsobjectrequired

Document totals. Tallio rejects totals that do not add up.

Show nested fields (3)

netintegerrequired: Sum of the lines' net amounts, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
vatintegerrequired: Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.
From 0 to 1000000000000000
grossintegerrequired: net + vat, in minor units, at most 1250000000000000.
From 0 to 1250000000000000

classificationobjectrequired

How the document will be classified for myDATA.

Show nested fields (2)

sourcestringrequired: default when any line took Tallio's default, else override when any line took the merchant's override, else line.
One of: line, override, default
warningsstring[]required: What to check before issuing, e.g. that defaults were applied.

payloadobjectrequired

The request Tallio would send to the provider, in the provider's own format.

Show nested fields (1)

{key}any

Example response · 200

{
  "data": {
    "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
    }
  }
}

Response headers

x-request-idstring: 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.
With every response
Show patternHide 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})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 400, 413, 415, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 400, 413, 415, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 400, 413, 415, 429 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`payload_too_large`	413	No	The request body is too large.
`unsupported_media_type`	415	No	The request body must be JSON (Content-Type: application/json).
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.