# Call examples — command + params

Concrete payloads for each command, using real **Παράρτημα Ε** test data from the ΚΕΔ spec —
published by ΑΑΔΕ specifically for the pilot environment, not real debtors. Each block shows
`command` + `params`; send them however your own client already encodes them
(`command|http_build_query(params)`, see `message-contract.md`).

## 1. Signers — `declare_signers`

**Prerequisite for every βεβαίωση.** Send this first, wait for acceptance.

Accepted signer ΑΦΜ (Παράρτημα Ε):

| ΑΦΜ | Name |
|---|---|
| `003067224` | ΧΡΙΣΤΟΠΟΥΛΟΥ ΕΥΓΕΝ |
| `010020485` | ΠΙΠΕΡΑΚΗΣ ΕΜΜΑΝ |
| `010800987` | ΣΤΑΘΟΠΟΥΛΟΣ ΕΛΕΥΘ |
| `010820206` | ΜΑΝΩΛΑΚΟΣ ΑΝΑΡΓ |
| `011564265` | ΠΑΡΑΣΚΕΥΑΣ ΔΗΜΗΤΡ |
| `013379910` | ΚΑΡΑΒΑΣΙΛΗΣ ΧΑΡΑΛ |
| `014075592` | ΛΟΥΚΑΙΤΟΥ ΕΛΠΙΣ |
| `014193897` | ΠΑΠΑΓΕΩΡΓΙΟΥ ΓΕΩΡΓ |

Use the surname exactly **as published** (already truncated, e.g. `ΠΑΡΑΣΚΕΥΑΣ ΔΗΜΗΤΡ`) — the
pilot checks the surname against the ΑΦΜ registry and rejects **the whole list** if it doesn't
match.

```json
{
    "command": "declare_signers",
    "params": {
        "signers": [{ "afm": "003067224", "firstName": "ΕΥΓΕΝ", "lastName": "ΧΡΙΣΤΟΠΟΥΛΟΥ" }],
        "auditUserId": "demo-user",
        "auditUserIp": "127.0.0.1"
    }
}
```

**Observed pilot rejections** — a reproducible failure scenario, rejects the whole signer list:

| ΑΦΜ | What we sent | Response |
|---|---|---|
| `139270450` | surname ≠ registry | `WS_PROCEDURE_ERROR` / "Λανθασμένο Επώνυμο Υπογράφοντος" |
| `800915091` | ΑΦΜ outside the registry | `WS_PROCEDURE_ERROR` / "Δεν βρέθηκε ο ΑΦΜ" |

## 2. Certification — `submit_beveosi`

All amounts are **text with 2 decimals** (`"600.00"`), never a number. `sunolo` must equal
**both** the sum of the installments **and** the sum of the ΚΑΕ lines.

```json
{
    "command": "submit_beveosi",
    "params": {
        "afm": "137569280",
        "sunolo": "600.00",
        "kaeLines": [{ "kae": "82838", "amount": "600.00" }],
        "installments": [{ "aa": "1", "dueDate": "<last working day of next month>", "amount": "600.00" }],
        "fiscalYear": "<current year>",
        "apofNoEtos": "10/2026",
        "comments": "Απόφαση 10/2026",
        "afmYpogr": "003067224",
        "nameYpogr": "ΧΡΙΣΤΟΠΟΥΛΟΥ ΕΥΓΕΝ",
        "unitId": "1204",
        "unitAcronym": "ΙΝΡΑ",
        "insFrequency": "1",
        "lastDayRule": "1",
        "doyFlag": "0",
        "attachments": [{ "title": "Απόφαση 10/2026", "filepath": "minio://beveoseis/10-2026.pdf" }],
        "auditUserId": "demo-user",
        "auditUserIp": "127.0.0.1"
    }
}
```

**Attachments go with this first call.** No prior save and no `auditProtocol` are needed.
`attachments` is optional, up to 10 `{title, filepath}` items; `filepath` is your own MinIO key,
which we store as-is and never fetch. Upload the file to MinIO first, then send its path here.
Attachments are never sent to ΚΕΔ.

**Response** (`status: 1`): the full record, the same object as `get_beveosi_status`, so
what you sent comes back, `attachments` included. Shortened:

```json
{
    "data": {
        "id": 1,
        "auditProtocol": "1/06-08-2026",
        "hashId": "88468689707b4599be6efd959c4f241ed94449725881d8b0db35a55c140cd8ac",
        "status": "certified_pending_closeday",
        "locked": true,
        "afm": "137569280",
        "debtorName": "ΠΑΠΑΔΟΠΟΥΛΟΣ ΙΩΑΝΝΗΣ",
        "unitId": "1204",
        "unitAcronym": "ΙΝΡΑ",
        "sunolo": "600.00",
        "atbNo": null,
        "taftotites": [],
        "debtors": [{ "afm": "137569280", "position": 0, "isPrimary": true, "amount": "600.00", "taftotitaOfeilis": null }],
        "installments": [{ "aa": "1", "dueDate": "2026-09-30", "amount": "600.00" }],
        "kaeLines": [{ "kae": "82838", "amount": "600.00" }],
        "attachments": [{ "title": "Απόφαση 10/2026", "filepath": "minio://beveoseis/10-2026.pdf" }],
        "message": "Η βεβαίωση καταχωρήθηκε. …"
    },
    "status": 1,
    "type": "single"
}
```

Keep the `auditProtocol` (or `id`, or `hashId`) from this reply: any of the three names the
βεβαίωση to `get_beveosi_status`, `set_beveosi_attachments` and a resend. **Key your MinIO
object names on the `hashId`** — it is the SHA-256 of the `auditProtocol`, computed once by us,
stable for the life of the row.
The ΑΤΒ and the Ταυτότητες Οφειλής are **not** here yet; they appear in `get_beveosi_status`
once the ΔΟΥ closes the day. A rejection (`status: 4`) carries the same full record in
`extraData`, plus `resendable`. Full shapes: `message-contract.md`.

Other accepted debtor ΑΦΜ (Παράρτημα Ε) — swap `afm` for any of these:

```
137569280 139269609 038573262 137671863
099062654 099803657 099556992 099339555 099631554 073943479 034051630 140404502 054454734
018617850 137231140 027527018 046403980 066111650 036607380
```

The pilot **positively checks the debtor ΑΦΜ against its registry** — unknown ΑΦΜs fail with
«Δεν βρέθηκε ο ΑΦΜ». Six Παράρτημα Ε entries are therefore **excluded from the list above**
(observed 2026-09-18 → 2026-10-27): `001303242`, `028633507`, `139267407`, `139281402`,
`137664663` answer «ΑΠΟΒΙΩΣΑΣ ΑΦΜ» and `003842491` answers «ΠΡΟΒΛΗΜΑΤΙΚΟΣ ΑΦΜ» — do not use
them as debtors. Proven-alive as of 27-10: `137569280`, `099631554`, `137231140`, `099803657`.
(`123456789` also certifies, but it is an unpublished registry entry — do not build on it.)

With a co-liable party (συνυπόχρεος):

```json
"synypochreoi": [{ "afm": "063745180", "code": "1", "category": "2", "amount": "150.00" }]
```

**Local validation** (rejected before it ever reaches ΚΕΔ, regardless of driver):

| Field | Value | Result |
|---|---|---|
| `kaeLines[].kae` | anything other than a granted ΚΑΕ | "Μη αποδεκτός ΚΑΕ" |
| `afmYpogr` | not declared | "Ο υπογράφων δεν έχει δηλωθεί στο ΚΕΔ" |
| `sunolo` vs installments/ΚΑΕ | mismatched | "Το σύνολο δεν ισούται..." |
| `doyFlag` | `1` | "not supported" |
| `fiscalYear` | `<2010` or `>current year` | "must be between 2010 and the current year" |

## 2a. Draft — `save_beveosi_draft`

Same payload as `submit_beveosi`, but nothing is sent to ΚΕΔ. Attachments can go with the
**first** save too, with no `id`/`auditProtocol`, since the row doesn't exist yet:

```json
{
    "command": "save_beveosi_draft",
    "params": {
        "afm": "137569280",
        "sunolo": "600.00",
        "attachments": [{ "title": "Απόφαση 10/2026", "filepath": "minio://beveoseis/10-2026.pdf" }],
        "auditUserId": "demo-user",
        "auditUserIp": "127.0.0.1"
    }
}
```

The reply is the full record (with `id`, `auditProtocol` and `attachments`).

**To update the draft, send its `id` (or `auditProtocol`) plus the whole form, not just the
changed fields.** A draft update rewrites the debtors, installments and ΚΑΕ lines from what
you send, so anything you leave out is removed. The one exception is `attachments`: **present
means replace the whole list, absent means keep it**, so leave it out of an update that
doesn't touch the files.

To certify the draft, call `submit_beveosi` with just its `id`. Submit by `id` works the other
way round: it reuses everything stored (debtors with their names and phone, installments, ΚΑΕ
lines, attachments) and only the fields you send override it. The same applies to correcting
and resending a rejected βεβαίωση: send its `id` plus only the corrected fields.

## 3. `get_beveosi_status`

```json
{ "command": "get_beveosi_status", "params": { "auditProtocol": "1/06-08-2026" } }
```

`pending: true` while the status is `sent`, `certified_pending_closeday` or
`needs_reconciliation`. Poll every 10-30s; stop once `pending: false`.

## 3a. Worked example — same ΑΦΜ twice in one day: one ΧΚ, one ΑΤΒ, two Ταυτότητες

Observed on the pilot (2026-10-26): two βεβαιώσεις for debtor ΑΦΜ `137569280`, certified
minutes apart (αποφάσεις 811/2026 and 812/2026). The ΔΟΥ **batched them into one ΧΚ** —
normal behaviour, not an anomaly; expect it whenever the same debtor is certified twice in
a day. (They may also land in separate ΧΚs; both outcomes are fine, the rules below hold
either way.)

The two submit replies, side by side:

| Reply field | Submit #1 (811/2026) | Submit #2 (812/2026) |
|---|---|---|
| `status` | `certified_pending_closeday` | `certified_pending_closeday` |
| `mcNo` | `21` | `21` — **the same ΧΚ** |
| `debtors[0].lineNo` | `1` | `2` |

Once the ΔΟΥ closes the day, `get_beveosi_status` answers, per βεβαίωση:

| Field | βεβαίωση 811/2026 | βεβαίωση 812/2026 |
|---|---|---|
| `atbNo` | `862011` | `862011` — shared, because the ΑΤΒ belongs to the ΧΚ |
| `debtors[0].lineNo` | `1` | `2` |
| `debtors[0].taftotitaOfeilis` | `137569280910104268686201100001` | `137569280910104265686201100002` |

Rules to build against:

- **The ΑΤΒ identifies the ΧΚ, not the βεβαίωση.** Several of your βεβαιώσεις can share one
  ΑΤΒ. Never key anything on it being unique.
- **The Ταυτότητα Οφειλής identifies the γραμμή** — this is the value you pass to
  `get_payment_progress` / `get_payment_data`. Two βεβαιώσεις with the same ΑΤΒ *and* the
  same ΑΦΜ still carry **different** Ταυτότητες.
- `lineNo` is already in the submit reply (`debtors[0].lineNo`); the ΑΤΒ and the Ταυτότητα
  follow with the day close, through `get_beveosi_status`.

## 4. `list_beveoseis`

```json
{ "command": "list_beveoseis", "params": { "status": "certified", "unitId": "1204", "page": "1", "page_size": "10" } }
```

Optional filters: `status`, `afm` (prefix match), `unitId` (prefix match on the id **or** the
acronym you sent with the βεβαίωση), `dateFrom`/`dateTo` (**not** `date_from`/
`date_to` — those get rewritten by the interpreter).

## 5. `delete_beveosi_draft`

Works on `draft` **and** on `failed` (ΚΕΔ rejected it — nothing was registered). Deleting a
`failed` row forfeits the `auditProtocol` a resend would otherwise reuse — prefer correct &
resend when you intend to try again.

```json
{ "command": "delete_beveosi_draft", "params": { "id": "7" } }
```

## 6. `get_payment_progress` / `get_payment_data`

Once a Ταυτότητα Οφειλής exists (from `get_beveosi_status`):

```json
{
    "command": "get_payment_progress",
    "params": { "auditProtocol": "1/06-08-2026", "afm": "137569280", "auditUserId": "demo-user", "auditUserIp": "127.0.0.1" }
}
```

```json
{
    "command": "get_payment_data",
    "params": {
        "auditProtocol": "1/06-08-2026", "afm": "137569280",
        "dateFrom": "2026-01-01", "dateTo": "2026-12-31",
        "auditUserId": "demo-user", "auditUserIp": "127.0.0.1"
    }
}
```

Alternatively, with the 30-digit Ταυτότητα Οφειλής directly: `"payId": "..."` instead of
`auditProtocol`+`afm`.

## 7. Change attachments afterwards — `set_beveosi_attachments`

**Not needed for the first save:** attachments go with `save_beveosi_draft` /
`submit_beveosi` (sections 2 and 2a). Use this command only to change the list later, for
example on a certified row, where save/submit no longer accept edits.

Local metadata, no ΚΕΔ call, works at any status. The list sent is the list stored — send
`"attachments": ""` (empty string, not `[]`) to clear it. The reply is the full record.

```json
{
    "command": "set_beveosi_attachments",
    "params": {
        "auditProtocol": "1/06-08-2026",
        "attachments": [{ "title": "Απόφαση 10/2026", "filepath": "minio://beveoseis/10-2026.pdf" }]
    }
}
```

## Which replies show what

| Command | Reply carries |
|---|---|
| `submit_beveosi`, `save_beveosi_draft`, `get_beveosi_status`, `set_beveosi_attachments` | the **full record**: summary fields plus `comments`, `debtors`, `installments`, `kaeLines`, `attachments` |
| `list_beveoseis` | the **summary** per row only: no debtors, installments, ΚΑΕ lines or attachments — but the row carries `debtorName`, so the table shows the οφειλέτης without a detail call. Call `get_beveosi_status` for one row's detail. |

## ΚΑΕ, extOrg, txtCode

Values assigned by ΑΑΔΕ to the φορέας — not a user choice. `kae` comes from `get_lookups`;
`extOrg`/`txtCode` are fixed configuration. An undeclared ΚΑΕ answers "Μη αποδεκτός ΚΑΕ".

---

## kedeDeleteService (Μείωση/Διαγραφή) — proven live end to end (2026-11-04)

Certification → reduction → finalization ran against the pilot in under six minutes (ΑΦΕΚ no.
1, οριστικό ΑΒΚΤ 404946). One rule: **only 5-digit ΚΑΕ (no ΑΛΕ) ⇒ `afekType: "2"`** — ΚΕΔ
guidance of 2026-11-03; every `afekType: "1"` submission on such debts was rejected. The
`submit_reduction` example below shows the working live payload (identifiers updated to the
certification it reduced):

```json
{
    "command": "submit_reduction",
    "params": {
        "auditProtocol": "564/04-11-2026",
        "afm": "137569280",
        "afekType": "2",
        "comments": "Απόφαση 934/2026",
        "deptId": "137569280910104214686205000001",
        "approvalDate": "2026-11-04",
        "fiscalYear": "2026",
        "atbNo": "862050",
        "mcNo": "26",
        "lineNo": "1",
        "adtCode": "4",
        "decYear": "2026",
        "decisionNum": "934",
        "afkDoy": "9776",
        "kaeLines": [{ "kae": "82838", "amount": "100.00" }],
        "afmYpogr": "003067224",
        "nameYpogr": "ΧΡΙΣΤΟΠΟΥΛΟΥ ΕΥΓΕΝ",
        "auditUserId": "demo-user",
        "auditUserIp": "127.0.0.1"
    }
}
```

This exact payload succeeded on 2026-11-04 (`callSequenceId` 10091590754): ΑΦΕΚ no. 1 minted,
`awaiting_finalization`; the scheduled finalization then returned assessDate 2026-11-04 and
οριστικό ΑΒΚΤ **404946** (`callSequenceId` 10091590768). Selector: `debtorId` alone, or
`id`/`auditProtocol` (the certification) plus `afm`.

```json
{ "command": "get_reduction_status", "params": { "id": "1" } }
{ "command": "list_reductions", "params": { "certificationId": "1" } }
{ "command": "get_reduction_progress", "params": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31", "auditUserId": "demo-user", "auditUserIp": "127.0.0.1" } }
```
