# The six ΚΕΔ progress operations — what each one asks, and where it acts

## Γλωσσάρι first — the words the rest of the page uses

| term | means | when we get it |
|---|---|---|
| **ΔΟΥ** | the tax office that registers the debt (assigned by ΚΕΔ from the debtor's ΑΦΜ) | in the submit reply (`result_doy`) |
| **ΧΚ** — Χρηματικός Κατάλογος | the collective document into which the ΔΟΥ books a day's revenues. Every βεβαίωση becomes **one γραμμή (line)** of one ΧΚ — and other φορείς' lines land in the same day's ΧΚ, which is why ① returns ΧΚ that are not ours. `mcNo` = Αριθμός Χρηματικού Καταλόγου | in the submit reply |
| **ΑΤΒ** — Αριθμός Τριπλότυπου Βεβαίωσης | the number of the official certificate stub (τριπλότυπο) the ΔΟΥ issues for the βεβαίωση. The formal proof the debt entered the books — **it does not exist until the day closes**, which is why no submit reply ever carries it | from ②, at close-day |
| **Τ.Ο.** — Ταυτότητα Οφειλής | the 30-digit identity of one debt, **one per γραμμή ΧΚ** — the same ΑΦΜ can recur on another γραμμή with a different Τ.Ο. The sole key the payments pair understands | from ②, at close-day |
| **extOrg** | our Κωδικός Πηγής / Εξωτερικού Οργανισμού — who we are at ΚΕΔ. Configuration, never user input | — |

The order of a βεβαίωση's life: submit → one γραμμή in a ΧΚ (immediately) → day closes → ΑΤΒ + one Τ.Ο. per γραμμή ΧΚ (via ①②) → collection (via ③④).

## The two pairs everyone mixes up

- **The polling pair is *index → detail*.** `retrieveVerificationProgress` asks «which
  ΧΚ did the ΔΟΥ close for this date?» — one call covers every βεβαίωση of that date,
  and it never returns Ταυτότητες Οφειλής. `retrieveCloseDay` asks «give me the ΑΤΒ and
  the Ταυτότητες Οφειλής **of this one ΧΚ**». The first finds *that closing happened*;
  only the second fetches *what closing produced*.
- **The payments pair is *υπόλοιπο → κινήσεις*.** `retrievePayProgress` is the balance
  snapshot of one debt — seven amounts, no dates, no history. `retrievePaymentData` is
  the statement lines of one debt in a date range — one row per payment event. Bank
  analogy: υπόλοιπο λογαριασμού vs κινήσεις λογαριασμού.

Both pairs key on **different things** — that is the real distinction, more than the
names:

| pair | first call keys on | second call keys on |
|---|---|---|
| polling | a **date** (+ extOrg) | a **ΧΚ** (doy + mcNo + mcDate) |
| payments | a **Ταυτότητα Οφειλής** (+ extOrg) | the same **Τ.Ο.** + a date range |

## The map

| ΚΕΔ operation | What it asks | Keyed on | Returns | Our command | Triggered by | Quota |
|---|---|---|---|---|---|---|
| `retrieveNames` (§2.6, Πίν. 8) | Accept these ≤10 signers | foreas + extOrg | the accepted count | `declare_signers` | Υπογράφοντες page · `bff:publish declare_signers` · `ked:smoke` step 1 | ✓ every call |
| `retrieveKedeAmount` (§2.1, Πίν. 2) | Certify this debt | the whole βεβαίωση | ΔΟΥ, ΧΚ, γραμμή — **never the ΑΤΒ** | `submit_beveosi` | Νέα Βεβαίωση submit / Διόρθωση & επανυποβολή · `bff:publish submit_beveosi` · `ked:smoke` step 2 (**live: `--write` only — raises a real debt**) | ✓ |
| `retrieveVerificationProgress` (§2.4, Πίν. 6) | Did the ΔΟΥ close the day? Which ΧΚ exist? | **date** + extOrg | the day's ΧΚ list (doy, mcNo, ΑΤΒ, totals) — every organisation's, ours among them | *(internal — no direct command)* | `get_beveosi_status` on a stale row (throttled) · scheduler `ked:reconcile` · `ked:smoke` step 3 | ✓ — but **one call per date**, shared by every βεβαίωση of that date |
| `retrieveCloseDay` (§2.3, Πίν. 4/5) | What did closing produce for this ΧΚ? | **doy + mcNo + mcDate** | the ΑΤΒ + **one Ταυτότητα Οφειλής per γραμμή** + per-line amounts. The list covers the whole ΧΚ — lines of other βεβαιώσεις included — so we match by `lineNo` first, ΑΦΜ only when unambiguous | *(internal — no direct command)* | same machinery, only after ① matched our ΧΚ · `ked:smoke` step 4 | ✓ per ΧΚ — one call serves every βεβαίωση on that ΧΚ |
| `retrievePayProgress` (§2.5, Πίν. 7) | The balances of this debt, right now | **Τ.Ο.** + extOrg | 7 amounts: established / paid / deleted / reduced / rest / overdue / απαιτητό | `get_payment_progress` | tracking page open + Ανανέωση · `bff:publish get_payment_progress` · `ked:smoke --payId` step 5 | ✓ per view |
| `retrievePaymentData` (§2.7, Πίν. 9) | Which payment events happened to this debt in this window? | **Τ.Ο.** + extOrg + dateFrom/dateTo | movement rows: date, poso/kef/tokoi, plus the ΧΚ/γραμμή/ΑΤΒ block | `get_payment_data` | tracking page open + **Αναζήτηση** + Ανανέωση · `bff:publish get_payment_data` · `ked:smoke --payId` step 6 | ✓ per view |
| ~~`retrieveKedeHub`~~ (§2.2) | — | — | — | **never** | — | Δημόκριτος is a plain Φορέας, not a διαμετακομιστικός κόμβος; this operation must never be called |

Everything else in the UI (`get_lookups`, drafts, `list_beveoseis`, a settled
`get_beveosi_status`, `set_beveosi_attachments`) reads or writes our own database and costs no
quota.

## The flow, and where each operation acts

```
ΥΠΟΓΡΑΦΟΝΤΕΣ           declare_signers ── retrieveNames ────────────────────────── once,
                                                                                whenever the list changes
ΥΠΟΒΟΛΗ                submit_beveosi ─── retrieveKedeAmount ──→ certified_pending_closeday
                                                                  (no ΑΤΒ exists yet)
                                                                    │
                                                                    ▼
ΠΑΡΑΚΟΛΟΥΘΗΣΗ ①②       StatusPage refresh / scheduler ked:reconcile   (throttled)
                                                                    │
        ① retrieveVerificationProgress(dateFrom)
             «did the ΔΟΥ close the day?» → the day's ΧΚ list;
             match ours by doy + mcNo, position means nothing
                                                                    │ (only if matched)
        ② retrieveCloseDay(doy, mcNo)
             «what did closing produce?» → ΑΤΒ + one Τ.Ο. per ΑΦΜ
                                                                    │
                                                                    ▼
                                                                certified  (terminal)
                                                                    │
                                                                    ▼
ΕΙΣΠΡΑΞΕΙΣ ③④          tracking page — strictly on demand, never a timer
                                                                    │
        ③ retrievePayProgress(Τ.Ο.)      «balances now»   → the six KPI cards
        ④ retrievePaymentData(Τ.Ο., from, to)  «movements»→ the table + Σύνολο
```

Why the split in **where they are triggered**:

- ①② have **no dedicated screen** — they are the Παράρτημα Ζ plumbing. The user never
  asks «did the ΔΟΥ close the day?» as a question; they ask «where is my βεβαίωση?»
  (`get_beveosi_status`), and the answer *happens* to require ① and, on a match, ②.
  The scheduler runs the same pair unattended so nobody has to be watching.
- ③④ are **user-triggered reads**: read-only, so retrying is always safe, but every call
  is real quota — and payments have no async lifecycle, so there is nothing to poll.
  One tracking-page open = exactly two ΚΕΔ calls.

## The two pairs, side by side

### `retrieveVerificationProgress` vs `retrieveCloseDay`

| | ① `retrieveVerificationProgress` | ② `retrieveCloseDay` |
|---|---|---|
| input | dateFrom, extOrg | doy, extOrg, mcNo, mcDate |
| granularity | a whole **day** | one **ΧΚ** |
| returns | the list of ΧΚ opened that day, with their ΑΤΒ numbers | the ΑΤΒ **and** one Ταυτότητα Οφειλής per ΑΦΜ, per-line amounts |
| without the other | tells you closing happened, but never the ΤΟs — useless alone | needs ① to learn the doy/mcNo to ask about (after a resend, or a lost reply) |
| skipped means | we never learn the βεβαίωση was certified — row stays `needs_reconciliation`, locked, escalated to a human | the ΧΚ is known but the ΤΟs never land — no payments door ever opens |

The subtlety ① carries: the answer lists **every organisation's** ΧΚ for that date —
ours are somewhere in the list, and only `doy + mcNo` together identify them (mcNo
alone is not unique across ΔΟΥ). That is also why the reconciler makes **one ① call per
date** and fans the answer out over every βεβαίωση of that date — the cheapest possible
polling, under an unknown daily quota.

### `retrievePayProgress` vs `retrievePaymentData`

| | ③ `retrievePayProgress` | ④ `retrievePaymentData` |
|---|---|---|
| input | payId, extOrg | payId, extOrg, dateFrom, dateTo |
| shape | one flat record — seven amounts | a list of movement rows |
| knows *when*? | **no dates at all** — a snapshot of «now» | every row carries its paymentDate |
| answers | «πόσο έχει εισπραχθεί / απομένει;» | «πότε, και με τι διάκριση κεφαλαίου–τόκων;» |
| without the other | a number with no story — you cannot build a statement from snapshots | raw lines with no current balance — you cannot say «πόσο απομένει» without ③ (and summing history is not the same: Μείωση/Διαγραφή do not appear as movements) |

The subtleties ③④ carry: the seven amounts of ③ are **never derived from one another**
(the spec's own sample has απαιτητό < υπόλοιπο — it includes συνεισπραττόμενα); and every
row of ④ carries the `dbt_*` block (ΧΚ, γραμμή, ΑΤΒ), which is what disambiguates
payments when **one ΧΚ carries several βεβαιώσεις** — the case the pilot proved real on
2026-08-07.

## A worked example, one βεβαίωση end to end

Numbers illustrative, shapes real.

1. **Submit (day D):** `submit_beveosi` for ΑΦΜ 137569280, σύνολο 600,00 →
   `retrieveKedeAmount` answers ΔΟΥ **9776**, ΧΚ **861700**, γραμμή 1. No ΑΤΒ. Status:
   `certified_pending_closeday`, locked.
2. **Poll (later on D — minutes on the pilot, end-of-day in production):** the status
   page's refresh (or the scheduler) fires ① for D. The answer lists three ΧΚ — two
   belong to other organisations; one matches our doy 9776 + ΧΚ 861700.
3. **Fetch the outcome:** ② for (9776, 861700) answers ΑΤΒ **8616752**, and per ΑΦΜ the
   Ταυτότητα Οφειλής **137569280910104229686185900017**. Status: `certified`. The Τ.Ο.
   is written onto the debtor's row — this is the moment the payments door opens.
4. **A month later, tracking page opened once:** ③ answers established 600,00 /
   paid 300,00 / rest 300,00 / ληξιπρόθεσμο 300,00 / απαιτητό 300,00. ④ for the last
   month answers one row: 2026-10-15, poso 300,00 (kef 300,00, τόκοι 0,00), on ΧΚ
   861700/γραμμή 1, ΑΤΒ 8616752. Two ΚΕΔ calls total, because the user asked.

Note what ④ *cannot* replace ③ with: if the debt had also taken a Μείωση of 100,00, ③
would show reducedAmount 100,00 — but ④ would list no «movement» for it. The snapshot
and the statement are genuinely two different questions.

5. **A Μείωση submitted the next day:** `submit_reduction` for 100,00 of ΚΑΕ 82838 on
   that same Τ.Ο. → `deleteKedeAmount` answers ΑΦΕΚ **1**, line 1, ΑΤΒ (προσωρινό)
   100002 — status `awaiting_finalization`. `get_reduction_status` polls (or the
   `ked:reduction-reconcile` sweep fires) and `deleteKedeComplete` confirms the
   εκκαθάριση — status `finalized`. **Separately**, the next time anyone calls ③ for
   this Τ.Ο., ΚΕΔ itself now answers reducedAmount 100,00 — our `afek_records` row and
   ΚΕΔ's own `reducedAmount` are two independent facts that happen to agree, not one
   writing the other (see `docs/message-contract.md`'s `PaymentProgress` note).

## What this API never tells us

The spec defines exactly seven operations (§2.1–§2.7), every one of them «Ενημέρωση
Φορέα» — *we ask, ΚΕΔ answers*. There is no notification, callback or event mechanism
anywhere in the contract, and no operation that lists «all our debts». Everything the
BFF might want to *react* to must therefore be **inferred by polling**, and polling
costs the (unknown) daily quota:

| the question | the honest answer |
|---|---|
| «πες μου όταν εξοφληθεί» | no event exists. `restAmount = 0` in ③ is the only signal — someone has to ask. Periodic polling is the sole automation, and it burns quota per check — which is why we made ③④ strictly on-demand |
| «χάθηκε η ρύθμιση;» | no status for it. It shows up as `overdueAmount` growing in ③ as δόσεις pass unpaid |
| «έγινε Μείωση / Διαγραφή;» | visible in ③ (`reducedAmount` / `deletedAmount`), computed server-side by ΚΕΔ itself — never announced here, and not written by our own `submit_reduction`/`afek_records` bookkeeping either (M4; see "The delete-service operations" below) |
| «όλα τα χρέη μας» | no listing operation. The closest is ① per date (ΧΚ-level), then ② per ΧΚ for the ΤΟs — reconstructable, at quota cost per step |
| any history of state changes | none. ΚΕΔ keeps the current state; the only history we hold is our own `ked_call_log`/`ked_audit_records` |

One consequence worth designing around: a βεβαίωση's status in **our** database is
terminal at `certified` — payment state is never a status of the βεβαίωση, only a live
answer to ③④.

## The delete-service operations (M4)

A second, genuinely separate ΚΕΔ web service — own WSDL, own namespace
(`KedeDeleteInterface`), own credential pair — for Μείωση/Διαγραφή of an already-certified
debt. Three operations are relevant (`deleteKedeHub` is the διαμετακομιστικός-κόμβος role,
N/A for Demokritos, same exclusion as `retrieveKedeHub` above):

| ΚΕΔ operation | What it asks | Keyed on | Returns | Our command | Triggered by |
|---|---|---|---|---|---|
| `deleteKedeAmount` (§2.1) | Reduce/delete this amount | the target debt (deptId/atbNo/mcNo/lineNo) + ΚΑΕ list | new ΑΦΕΚ no. + provisional ΑΤΒ | `submit_reduction` | Μείωση submit · `ked:smoke-delete` |
| `deleteKedeProgress` (§2.3) | Which ΑΦΕΚ progressed in this window | a date range + extOrg | one row per ΑΦΕΚ | `get_reduction_progress` | on-demand only, see below |
| `deleteKedeComplete` (§2.4) | Finalize this one ΑΦΕΚ | doy/year/afekNo/lineNo (the response's own, from ①) | assessDate + confirmed ΑΤΒ | (internal — `get_reduction_status` / `ked:reduction-reconcile`) | poll or sweep |

Structurally this is submit → poll → fetch-finalization, the same shape as ①②③ above, but
**not a two-step gate the way retrieveVerificationProgress → retrieveCloseDay is**:
`deleteKedeComplete`'s inputs are all already known the instant `deleteKedeAmount` succeeds —
no date discovery needed. So `deleteKedeProgress` is wired as a separate, on-demand,
read-only cross-check/audit screen, not a prerequisite.

**No locking guide exists for this service at all** — unlike Παράρτημα Ζ for the progress
service, the delete-service spec has zero mentions of κλείδωμα/duplicate-detection guidance.
`afek_records`' locking and `duplicate_guard` scheme is designed by analogy to
`beveosi_certifications`, not derived from spec text — see `docs/data-model.md`.

**Where a Μείωση becomes visible.** The original certified debt is never flagged or removed —
deleting our `afek_records` row would not touch anything at ΚΕΔ either. The only place the
effect becomes visible is indirectly, through ③ (`retrievePayProgress`'s `reducedAmount` /
`deletedAmount`), computed by ΚΕΔ from its own records — independent of, and not written by,
our local `afek_records` bookkeeping. See the worked example above, step 5.

## Driving each operation from the CLI

`bff:publish` speaks exactly what the BFF speaks — that is the true test, since the
sample UI is not a deliverable. Prerequisite for the first two: a declared signer.

```bash
# retrieveNames
./vendor/bin/sail artisan bff:publish declare_signers \
  --params='{"signers":[{"afm":"003067224","firstName":"ΕΥΓΕΝ","lastName":"ΧΡΙΣΤΟΠΟΥΛΟΥ"}],"auditUserId":"u","auditUserIp":"127.0.0.1"}'

# retrieveKedeAmount — LIVE THIS CERTIFIES A REAL (PILOT) DEBT
./vendor/bin/sail artisan bff:publish submit_beveosi --params=@tests/fixtures/beveosi.json

# ① + ② — no direct command; poll the status (throttled) or let the scheduler do it
./vendor/bin/sail artisan bff:publish get_beveosi_status --params='{"auditProtocol":"<protocol>"}'

# ③ — read-only, safe live
./vendor/bin/sail artisan bff:publish get_payment_progress \
  --params='{"payId":"<το 30 ψηφία>","auditUserId":"u","auditUserIp":"127.0.0.1"}'

# ④ — read-only, safe live
./vendor/bin/sail artisan bff:publish get_payment_data \
  --params='{"payId":"<το 30 ψηφία>","dateFrom":"2026-01-01","dateTo":"2026-12-31","auditUserId":"u","auditUserIp":"127.0.0.1"}'
```

`ked:smoke` drives the operations directly, client-level, no RabbitMQ:

```bash
./vendor/bin/sail artisan ked:smoke --fresh          # all six, in order, on the fake
KED_DRIVER=soap ./vendor/bin/sail artisan ked:smoke --payId=<Τ.Ο.>
                                                     # live: only ③④ — exactly two
                                                     # read-only pilot calls, no gate
```

The wire-level details of each command (params, validation, response shapes) live in
[`message-contract.md`](message-contract.md); the state machine that ①② drive, in
[`data-model.md`](data-model.md).
