# Παράρτημα Ζ και συνοδευτικά — working notes

Transcribed 2026-08-06 from `docs/source_docs/specs/ked-progress-api_101.pdf`
(«Προδιαγραφές Web Service — Υπηρεσίες Βεβαίωσης Εσόδων υπέρ Δημοσίου και τρίτων μέσω ΚΕΔ»,
Version 1.01 – 12/03/2025), Παράρτημα Ζ σελ. 47–48, plus Παράρτημα Γ (σελ. 33–34),
§4 Αντιμετώπιση Λαθών (σελ. 16–19) and the `retrieveKedeAmount` input table (σελ. 4–5).

The PDF text *is* machine-extractable — earlier plans said otherwise. `pdftotext` is not on the
host, but a throwaway container does it:

```bash
docker run --rm -v "$PWD":/w -v /tmp/out:/out -w /w alpine:3.20 \
  sh -c "apk add --no-cache poppler-utils >/dev/null && \
         pdftotext -layout -enc UTF-8 ked-progress-api_101.pdf /out/ked.txt"
```

---

## 1. Παράρτημα Ζ — Οδηγός χρήσης των WS από τις εφαρμογές των Φορέων

Verbatim points, in the order the spec gives them:

- **`retrieveNames`** declares the people authorised to sign Βεβαιώσεις. It is called again
  **only when the signer list changes**, and must carry **the whole valid list, not just the
  changes**. Not used by a διαμετακομιστικός κόμβος.
- **`retrieveKedeAmount`** is called when there are certifications to send. From its response the
  Φορέας records **ΔΟΥ, αριθμό ΧΚ and γραμμή for each certified debt**.
- **`retrieveVerificationProgress`** gives the ΧΚ numbers and ΑΤΒ details opened at the ΔΟΥ on a
  given date. Quote:

  > Η χρήση της μεθόδου είναι σημαντική, καθώς αν συμβεί απώλεια σύνδεσης κατά την αποστολή
  > βεβαιώσεων ο φορέας μπορεί να μην έχει ενημερωθεί με την απάντηση για τον ΧΚ που άνοιξε στη ΔΟΥ.
  > **Επανάληψη αποστολής Βεβαιώσεων θα πρέπει να γίνεται μόνο αν ο Φορέας βεβαιωθεί ότι η βεβαίωση
  > δεν ολοκληρώθηκε, καθώς μπορεί να δημιουργηθεί διπλό χρέος στη ΔΟΥ.**

- **`retrieveCloseDay`** then supplies ΑΦΜ, ποσά and ΧΚ lines for the ΧΚ obtained from
  `retrieveVerificationProgress`, so the Φορέας can cross-check against what it sent and against
  the `retrieveKedeAmount` responses, in order to:
  1. record/confirm **ΑΤΒ και ΤΟ** for every certification,
  2. **repeat** the certifications that were not registered in TAXIS,
  3. take **corrective action** for any that were registered twice.
- **The locking rule** (this is the one the state machine implements):

  > Για την αποφυγή αποστολής διπλών βεβαιώσεων προτείνεται ο Φορέας να υλοποιήσει στην εφαρμογή
  > του έλεγχο ώστε να «κλειδώνει» κάθε βεβαίωση από τη στιγμή που θα σταλεί στο ΚΕ.Δ.
  > Προτείνεται η βεβαίωση να ξεκλειδώνει συστημικά **μόνο αν δεν έχει ληφθεί απάντηση** από το
  > ΚΕ.Δ. **και αν** από τα αποτελέσματα ελέγχου με τις μεθόδους `retrieveVerificationProgress`
  > και `retrieveCloseDay` **αποδειχθεί ότι δεν έχει βεβαιωθεί** το χρέος στο TAXIS.

- **Unique local id:** every certification must be uniquely identified in the Φορέας' system, and
  that unique value must be carried to ΚΕΔ in **`AUDIT_PROTOCOL`**, so ΚΕΔ can see duplicates.
- A διαμετακομιστικός κόμβος skips `retrieveNames` (but must keep its own logging of which employee
  sent each certification) and uses `retrieveKedeHub` instead. **Not our case** — Δημόκριτος is a
  plain Φορέας.

### Consequences for our state machine — confirmed

The planned machine survives the reading, with one sharpening:

| Situation | State | Locked? |
|---|---|---|
| Row created, not yet sent | `pending` | no |
| Sent to ΚΕΔ | `sent` | **yes, from the moment of sending** |
| Response with ΔΟΥ/mcNo/lineNo | `certified_pending_closeday` | yes |
| ΑΤΒ + ΤΟ matched from `retrieveCloseDay` | `certified` | yes (terminal) |
| **Answer received** and it is a business error | `failed` | **no** — resendable, reusing the same `audit_protocol` |
| **No answer received** (SoapFault, timeout, connection loss) | `needs_reconciliation` | **yes** |
| `needs_reconciliation` + proven absent from both `retrieveVerificationProgress` and `retrieveCloseDay` | `failed` | no — now resendable |

The sharpening: the spec's automatic-unlock precondition is **conjunctive** — «δεν έχει ληφθεί
απάντηση» **and** «αποδειχθεί ότι δεν έχει βεβαιωθεί». A row that *did* get a clean business error
back is already proof the debt was not registered, so it unlocks immediately without a
reconciliation round-trip. Only the no-answer case needs proof of absence. Absence of the ΧΚ in a
single `retrieveVerificationProgress` call for one date is **not** proof on its own — the ΧΚ may
open on a later date; `ReconciliationService` must therefore treat "not found yet" as *stay
locked*, never as *proven absent*, and only conclude absence after the certification's date window
has closed. Until we have a rule from Δημόκριτος for how long that window is, the safe behaviour
is: **never auto-unlock; leave `needs_reconciliation` for a human, and let `ked:reconcile` only
promote rows it can positively match.**

Also note §4's retry advice: «Στην περίπτωση που αποτύχει η σύνδεση κατά την επικοινωνία με το
Web Service, επαναλαμβάνεται η κλήση από τη μεριά του client.» That is a *transport*-level retry
(connection never established). It must not be applied blindly to `retrieveKedeAmount` — a
timeout after the request was accepted is exactly the ambiguous case above. Retry only where we
can prove the request never left, and never automatically.

---

## 2. Παράρτημα Γ — audit record. **All six fields are mandatory here**

> τα δύο πρώτα πεδία (auditTransactionId και auditTransactionDate) είναι υποχρεωτικά ενώ **στη
> συγκεκριμένη διαδικτυακή υπηρεσία θεωρούνται υποχρεωτικά και τα πεδία audit_unit,
> audit_protocol, audit_user_id, audit_user_ip.**

**This contradicts `CLAUDE.md`**, which currently says `auditUserId`/`auditUserIp` are optional and
that we populate them only "for traceability". For *this* service the spec makes all six
mandatory. `CLAUDE.md` should be corrected.

| Field | Type | Meaning |
|---|---|---|
| `AUDIT_TRANSACTION_ID` | VARCHAR2(100) | Unique call id from our client app; we must be able to answer, from it, who the real end user was and why they called |
| `AUDIT_TRANSACTION_DATE` | TIMESTAMP(6), `yyyy-mm-ddThh:mm:ssZ` | Timestamp **from our server**, explicitly not the end user's PC clock |
| `AUDIT_UNIT` | VARCHAR2(100) | Name of the calling Φορέας (e.g. «ΙΚΑ», «Δήμος Αθηναίων») |
| `AUDIT_PROTOCOL` | VARCHAR2(100) | Πρωτόκολλο, e.g. `"1123/10-10-2016"`; **our unique per-certification id** (Παράρτημα Ζ) |
| `AUDIT_USER_ID` | VARCHAR2(100) | End-user identifier, e.g. `"user1"` |
| `AUDIT_USER_IP` | VARCHAR2(20) | End user's IP, e.g. `"10.18.24.13"` |

Keeping the call journal with all six fields per call is itself an obligation on the Φορέας — that
is what `ked_call_log` is for.

**Open item for the BFF team:** their wire format (`command|http_build_query(...)`) has no token or
header slot, so `auditUserId` and `auditUserIp` have to arrive as ordinary command params. They are
mandatory, so a missing value is a validation error, not a silent omission.

---

## 3. Συνυπόχρεοι — the `code`/`category` values (open question, now closed)

The `AFM` list carries `{afm, code, category, amount}`. Ζero συνυποχρέωση → `code` and `category`
are NULL. The permitted pairs, verbatim from σελ. 5, are written `category-ΚΑΤΗΓΟΡΙΑ-code-ΣΧΕΣΗ`:

| `category` | Κατηγορία | `code` | Σχέση |
|---|---|---|---|
| 2 | ΕΠΙΧΕΙΡΗΜΑΤΙΚΗ | 1 | ΔΙΑΧΕΙΡΙΣΤΗΣ |
| 2 | ΕΠΙΧΕΙΡΗΜΑΤΙΚΗ | 2 | ΔΙΕΥ/ΝΩΝ ΣΥΜΒΟΥΛΟΣ |
| 2 | ΕΠΙΧΕΙΡΗΜΑΤΙΚΗ | 8 | ΕΚΚΑΘΑΡΙΣΤΗΣ |
| 2 | ΕΠΙΧΕΙΡΗΜΑΤΙΚΗ | 19 | ΔΙΕΥΘΥΝΤΗΣ |
| 3 | ΕΚΠΡΟΣΩΠΗΣΗΣ | 10 | ΚΛΗΡΟΝΟΜΟΣ |
| 3 | ΕΚΠΡΟΣΩΠΗΣΗΣ | 11 | ΕΓΓΥΗΤΗΣ |
| 3 | ΕΚΠΡΟΣΩΠΗΣΗΣ | 20 | ΑΛΛΗΛΕΓΓΥΩΣ ΚΑΙ ΕΙΣ ΟΛΟΚΛΗΡΟΝ |

The ordering is confirmed by the Παράρτημα Β sample (σελ. 23): `<code>20</code>` with
`<category>3</category>` — i.e. ΑΛΛΗΛΕΓΓΥΩΣ. Note these are exactly the seven relationships the
Δημόκριτος mockup lists, in the same order, so the UI dropdown maps 1:1 onto this table.

An invalid combination comes back as `WS_PROCEDURE_ERROR` / «Μη αποδεκτή σχέση».

---

## 4. `txtCode` (Είδος φόρου) — not a public code list

Παράρτημα Ε: «Οι φορείς κάνουν δοκιμές στο test με τις τιμές Κωδικός Εξωτερικού Οργανισμού
(extOrg), KAE και Είδος Φόρου (txtCode) **που τους έχουν δοθεί από την ΑΑΔΕ** για την παραγωγική
λειτουργία.» So `txtCode` is assigned to Δημόκριτος by ΑΑΔΕ, exactly like `extOrg` and the ΚΑΕ
set — it is **configuration, not a user choice**. The mockup's `FPA`/`EOF`/`AK`/`TEL` dropdown is
invented; the Postman collection uses `4102`.

**The values are already known** (confirmed by the owner 2026-08-06, and visible in the sanitized
Postman collection): `extOrg` = `82838`, `txtCode` = `4102`, `foreasAfm` = `090085651`, and the
ΚΑΕ in use is `82838` — the same number as `extOrg`, which is confusing but correct. These are the
values ΑΑΔΕ gave Δημόκριτος for the pilot, and Παράρτημα Ε says the pilot is exercised with the
production values, so expect them to carry over.

They are org identifiers, not credentials: they live in `.env.example` and `phpunit.xml`, unlike
`KED_PROGRESS_USER`/`PASS`, which stay empty everywhere but a local `.env`.

Action: `txtCode` is config (`KED_TXT_CODE`), never a user-facing dropdown — the mockup's
`FPA`/`EOF`/`AK`/`TEL` selector must not survive into our form.

Rejected value → `WS_PROCEDURE_ERROR` / «Μη επιτρεπτό είδος φόρου».

---

## 5. Pilot test data (Παράρτημα Ε) — safe to use, not credentials

Signer ΑΦΜ available for `retrieveNames` on the pilot:

```
003067224 ΧΡΙΣΤΟΠΟΥΛΟΥ ΕΥΓΕΝ    010020485 ΠΙΠΕΡΑΚΗΣ ΕΜΜΑΝ     010800987 ΣΤΑΘΟΠΟΥΛΟΣ ΕΛΕΥΘ
010820206 ΜΑΝΩΛΑΚΟΣ ΑΝΑΡΓ       011564265 ΠΑΡΑΣΚΕΥΑΣ ΔΗΜΗΤΡ   011586270 ΛΟΥΚΙΣΣΑΣ ΕΜΜΑΝ
013349550 ΣΤΑΜΑΤΗΣ ΓΕΩΡΓ        013379910 ΚΑΡΑΒΑΣΙΛΗΣ ΧΑΡΑΛ   014075592 ΛΟΥΚΑΙΤΟΥ ΕΛΠΙΣ
014193897 ΠΑΠΑΓΕΩΡΓΙΟΥ ΓΕΩΡΓ
```
Plus `012703950 ΧΡΙΣΤΟΔΟΥΛΟΥ ΝΙΚΟΛ` — flagged «πεθαμένος», i.e. the fixture for
`WS_PROCEDURE_ERROR_DEAD`.

Debtor ΑΦΜ usable with `retrieveKedeAmount`:
```
137569280 001303242 028633507 139267407 139269609 139281402 038573262 137664663 137671863
099062654 099803657 099556992 099339555 099631554 073943479 034051630 140404502 054454734
018617850 137231140 027527018 046403980 066111650 036607380 003842491
```
These are pilot dummies published in the spec, not personal data of real debtors, and not
credentials — safe for fixtures and the fake driver.

---

## 6. Error codes (§4) — what the parser and the outcome mapping need

**Πίνακας 1 — generic ΚΕΔ errors (any method):**

| Code | Meaning |
|---|---|
| `GEN_AUDIT_VALIDATION_INV_DATA_OR_UNAUTH_OPER` | SoapHeader credentials not authorised for this operation |
| `GEN_AUDIT_VALIDATION_INVALID_AUDIT_DATA` | Audit fields missing/empty/malformed (e.g. bad `auditTransactionDate` format) |
| `GEN_INVALID_DATA` | Input-field validation failure (details in the description) |
| `GEN_COMMUNICATION_ERROR` | Error talking to the external body's service |
| `GEN_DATABASE_CONNECTION_ERROR` | ΚΕΔ database connection failure |
| `GEN_GENERAL_ERROR` | Unspecified ΚΕΔ error |
| `GET_AUTHORIZATION_MAX_OPEN_CALLS_EXCEEDED` | Daily call quota exceeded |

**Πίνακας 2 — `retrieveKedeAmount`**, all under `WS_PROCEDURE_ERROR`, distinguished only by
description: Ο φορέας/πηγή δεν υπάρχει · Γενικότερο πρόβλημα – Απότομη έξοδος · Μη επιτρεπτό είδος
φόρου · **Δοθέν σύνολο διαφορετικό του συνόλου δόσεων** · Το ΑΦΜ δεν βρέθηκε · Ο υπογράφων δεν
υπάρχει · Υπάρχουν τουλάχιστον ένα κενό ή μηδενικό ποσό δόσης · Μη αποδεκτός ΚΑΕ · Ύπαρξη ΚΑΕ με
μηδενικό ποσό · Μη αποδεκτή σχέση · Το πεδίο extOrg δεν είναι έγκυρο.

Three of those are cheaply preventable **before** we ever send — and preventing them matters,
because a rejected send still consumes the daily call quota:
- `sunolo` must equal the sum of the δόσεις (and of the ΚΑΕ lines),
- no δόση may have an empty or zero amount,
- no ΚΑΕ line may have a zero amount.

`SubmitBeveosiRules` will enforce all three.

**Πίνακας 4/5 — `retrieveCloseDay`** uses *numeric* codes, not `WS_*` names:

| Code | Meaning |
|---|---|
| `0` | **Όλα ΟΚ** — success, despite a non-empty `errorRecord` |
| `802` | Δεν υπάρχει αυτός ο ΧΚ |
| `803` | Δεν πληρούνται τα κριτήρια απόδοσης ΑΤΒ |
| `804` | Έχει ήδη ΑΤΒ |
| `402` | Ανύπαρκτος πίνακας ή γενικό πρόβλημα |
| `999` | Rollback – γενικό πρόβλημα |
| `WS_PROCEDURE_ERROR` | Το πεδίο extOrg δεν είναι έγκυρο |

This is why `KedeResult::isSuccess()` must treat **both** an empty `<errorRecord/>` **and**
`errorCode === '0'` as success. `803` and `804` are informative rather than fatal during
reconciliation: `804` in particular means the ΑΤΒ exists already — evidence the debt *was*
certified, so the row must stay locked.

**Πίνακας 6 — `retrieveVerificationProgress`:** `WS_PROCEDURE_ERROR` with «Προσοχή! Ο εξ.
Οργανισμός ΧΧΧ δεν είναι υπαρκτός» / «**Δεν βρέθηκαν δεδομένα που να ικανοποιούν τα κριτήρια**» /
«Το πεδίο extOrg δεν είναι έγκυρο». The middle one is the empty-result case and must **not** be
treated as proof of absence (see §1).

**Πίνακας 8 — `retrieveNames`** has its own richer code set, worth surfacing verbatim to the user:
`WS_PROCEDURE_ERROR` (empty ΑΦΜ/extOrg/ypiresiaDesc/date/Επώνυμο, invalid extOrg, invalid πλήθος),
`WS_PROCEDURE_ERROR_DATE` (η ημερομηνία πρέπει να είναι η τρέχουσα — **`inputDate` must be today**),
`WS_PROCEDURE_ERROR_DEACT` (deactivated ΑΦΜ / signer), `WS_PROCEDURE_ERROR_INI` (ΑΦΜ not a legal
entity; signer's ΑΦΜ inactive), `WS_PROCEDURE_ERROR_DEAD` (signer deceased),
`WS_PROCEDURE_ERROR_NO_DATA` (ΑΦΜ not found), `WS_PROCEDURE_ERROR_PLITHOS` (no signer; count
mismatch; too many names), `WS_PROCEDURE_ERROR_EPONYMO` (wrong surname).

Two rules fall out for `declare_signers`: send **today's** date as `inputDate`, and make
`plithosYpogr` exactly the number of `YPOGR` rows (≤10).

**Πίνακας 7 — `retrievePayProgress`** (§2.5, σελ. 11): `WS_PROCEDURE_ERROR` only — «Προσοχή! Η
Τ.Ο. ΧΧΧ δεν είναι υπαρκτή» / «Προσοχή! Ο εξ. Οργανισμός ΧΧΧ δεν είναι υπαρκτός» / «Το πεδίο
extOrg δεν είναι έγκυρο» — plus Πίνακας 1. Input: `auditRecord` +
`retrievePayProgressInputRecord{payId CHAR(30), extOrg CHAR(5)}`. Output record is FLAT:
`firstEstablishedAmount` (αρχικό βεβαιωθέν — the xlsx flags the printed CHAR(4) as a typo, it
is money), `paidAmount` (κεφάλαιο + συνεισπραττόμενα), `deletedAmount`, `reducedAmount`,
`restAmount` (υπόλοιπο κεφαλαίου), `overdueAmount` (ληξιπρόθεσμο από δόσεις που έχουν λήξει),
`totalAmount` (απαιτητό = υπόλοιπο + συνεισπραττόμενα) — all DECIMAL(17,2). Παράρτημα Β Κλήση
5's own sample sends `600` with no decimals and has `totalAmount` (100.74) < `restAmount`
(600): amounts are passed through verbatim, never derived from one another, and normalised to
two decimals with bcmath.

**Πίνακας 9 — `retrievePaymentData`** (§2.7, σελ. 13): the longest error list of any op, all
`WS_PROCEDURE_ERROR` — invalid Τ.Ο. · «H Τ.Ο πρέπει να αποτελείται μόνο από ψηφία» · unknown
εξ. Οργανισμός · «ΑΦΜ/ΔΟΥ/χρέος δεν βρέθηκε για την Τ.Ο.» · «Το χρέος ανήκει σε άλλο Εξ.
Οργανισμό» · «Ύπαρξη ΚΑΕ με μηδενικό ποσό» · «Μη αποδεκτή σχέση» · «Το πεδίο extOrg δεν είναι
έγκυρο». Input: `auditRecord` + `retrievePaymentDataInputRecord{payId CHAR(30), extOrg CHAR(5),
dateFrom DATE, dateTo DATE}`. Output: a **Payment List** whose rows are
`dbtDoy` CHAR(4) · `dbtDept` · `dbtMctCode` (=1) · `dbtSctCode` (=98) · `dbtYear` · `dbtSrcCode`
· `dbtMcNo` (the ΧΚ) · `dbtMcLine` · `dbtAtbNo` (≤20 digits) · `dbtAtbYear` · `dbtAtbDate` ·
`dbtAfmDebtor` CHAR(12) (leading zeros) · `outTo` (the Τ.Ο.) · `paymentDate` · `posoPlirwmhs` ·
`kefPlirwmhs` · `tokoiPlirwmhs`. Παράρτημα Β Κλήση 7's sample wraps the rows as
`<paymentList><paymentRecord>…</paymentRecord></paymentList>` INSIDE
`retrievePaymentDataOutputRecord` — the names the parser's LISTS map relies on, and the first
thing to check when a live answer arrives.

**Calibration flags for both (no wire sample exists — Postman predates them):** the
`paymentList`/`paymentRecord` element names (spec sample only); empty-range behaviour (assumed
success + empty list; Πίνακας 9 has no «Δεν βρέθηκαν δεδομένα» row, unlike Πίνακας 6); whether
`dateFrom`/`dateTo` are truly mandatory (spec silent; we require both); `totalAmount`
semantics; `dbtAfmDebtor` zero- vs space-padding (the parser trims either). Element ORDER in
our request envelopes follows the Πίνακας 7/9 input tables — verify against the first live
response, since SOAP cares about child order and the «προαιρετικό» caveat of §7a applies.

**OBSERVED live, 2026-09-25 (pilot):** an unknown Τ.Ο. on `retrievePayProgress` answers
`WS_PROCEDURE_ERROR` with **«Το χρέος που αντιστοιχεί στην Τ.Ο. δεν υπάρχει στο σύστημα.
Ελέξτε την Τ.Ο.»** — not the spec's «Προσοχή! Η Τ.Ο. ΧΧΧ δεν είναι υπαρκτή», and with no Τ.Ο.
echo in the text. Same lesson as §7a: the descriptions are indicative, the code is the
contract. The request envelope was accepted (a shape error would have been `GEN_INVALID_DATA`),
so the element order of Πίνακας 7 is confirmed live too. The fake still sends the spec wording
— it tests our handling either way.

**OBSERVED live, 2026-09-30 (pilot), real Τ.Ο. of the evidence run** — first SUCCESS
replies for the payment pair (`ked:smoke --payId=137569280910104229686185900017`):

- `retrievePayProgress` → SUCCESS, real `callSequenceId`: established **600**, paid **0**,
  rest **600**, απαιτητό **600**. Amounts arrive **without decimals** («600», not «600.00»)
  — the bcmath normalisation in `PaymentPresenter` is not defensive polish, it is the
  actual wire format.
- `overdueAmount` is **omitted entirely** when no δόση has matured (first δόση of the
  evidence debts falls due end of October 2026) — the parser reads absence as null, the
  UI shows «—», never a fake zero. Re-check once a δόση lapses: overdue should appear.
- `retrievePaymentData` (7-day window) → **SUCCESS with an empty paymentList** — the
  assumed empty-range behaviour is confirmed live (success, not the Πίνακας 6-style
  «Δεν βρέθηκαν δεδομένα» error).
- **Still unproven:** the `paymentList`/`paymentRecord` element names and every `dbt_*`
  field — an empty list exercises none of them. They need one movement row: either an
  ΑΑΔΕ-side test είσπραξη on a pilot Τ.Ο. (ask; nothing in the pilot collects on its
  own), or a Μείωση via the delete service once M4 exists (visible as `reducedAmount`).

---

## 7. Other input-table details worth pinning down

- **First δόση default:** «Η πρώτη δόση ορίζεται στο τέλος του επόμενου μήνα. Σε περίπτωση που
  είναι αργία, ορίζεται η αμέσως προηγούμενη εργάσιμη.» The δόση dates follow `lastDayRule`.
- **`lastDayRule`**: `1` = κανόνας τελευταίας εργάσιμης, `2` = κανόνας τακτής ημερομηνίας.
  «Τακτή Ημ/νία» is only usable if a legal provision has been notified to ΑΑΔΕ at `foreas@aade.gr`
  and enabled for the specific φορέας **and** είδος φόρου. So the UI must default to `1`, and `2`
  should be flagged as requiring prior activation.
- **`insFrequency`**: 1 = monthly, 2 = every two months, and so on.
- **`discountDate`** is mandatory when `discountPcg` is present, and must be the payment date of
  the first δόση. (`discountAmt` is marked «ΔΕΝ χρησιμοποιείται» in the xlsx.)
- **`fiscalYear`** must be `>= 2010` and `<=` the current year.
- **`comments`** must contain the Έτος and Αριθμός of the απόφαση.
- **`doyFlag`**: NULL when absent; `1` means the certification goes to the ΔΟΥ of the property
  given in `doy` — functionality used by Δ/νση Κρατικών Εγγυήσεων, so almost certainly not ours.
- **`afmYpogr`/`nameYpogr`** must have been declared both in the ΑΑΔΕ certification and via
  `retrieveNames` — which is why `declare_signers` has to run before any submit, and why we keep
  a local `declared_signers` table to validate against before spending a ΚΕΔ call.

---

## 7a. Where the spec and the pilot disagree — OBSERVED

Both of these were found by running against `test.gsis.gr` on 2026-08-07. The spec is wrong or
stale on each; trust the pilot.

| Spec says | Pilot does | Consequence |
|---|---|---|
| `doyFlag` — «Όταν δεν υπάρχει δηλώνεται NULL» (σελ. 5), i.e. omit the element | Rejects the βεβαίωση: `GEN_INVALID_DATA` / «Το πεδίο doy_flag είναι υποχρεωτικό και δεν μπορεί να είναι κενό» (callSequenceId 10070982948) | `CertificationService::buildInput()` now always sends it, defaulting to `0`, matching the Postman sample |
| Παράρτημα Ε flags ΑΦΜ `012703950` (ΧΡΙΣΤΟΔΟΥΛΟΥ ΝΙΚΟΛ) as «πεθαμένος», so `retrieveNames` should answer `WS_PROCEDURE_ERROR_DEAD` | **Accepted** the signer without complaint | The fake driver's `WS_PROCEDURE_ERROR_DEAD` scenario is modelled on the spec text, not on observed behaviour. It still exercises our error handling, but it does not reproduce today's pilot |
| (nothing — spec is silent on it) | Pilot **cross-checks the signer's surname against the ΑΦΜ registry**: `139270450` → `WS_PROCEDURE_ERROR` / «Λανθασμένο Επώνυμο Υπογράφοντος»; unknown ΑΦΜ `800915091` → «Δεν βρέθηκε ο ΑΦΜ» (2026-09-03, call log #37/#38) | `declare_signers` names must match the registry exactly — the BFF form cannot invent spellings. The pilot rejects the WHOLE list for one bad signer, so a typo costs a round-trip |

Re-confirmed 2026-09-03: the pilot accepted `012703950` again, four times in a row
(call log #33/#34/#36/#39, seq 10086552433…10086579177) — the «πεθαμένος» flag is not
enforced there. `docs/test-data.md` already says the DEAD scenario is fake-driver-only.

**Debtors — observed 2026-09-18, re-confirmed 2026-10-27 (campaign) and 2026-10-28 (deploy
smoke tests):** `retrieveKedeAmount` **positively resolves the debtor ΑΦΜ** against the
pilot registry; it is not a flag-only check:

- «ΑΠΟΒΙΩΣΑΣ ΑΦΜ» for Παράρτημα Ε `028633507`/`139281402` (2026-10-09) and `001303242`/
  `139267407`/`137664663` (2026-09-18, again 2026-10-27); `003842491` answers
  «ΠΡΟΒΛΗΜΑΤΙΚΟΣ ΑΦΜ».
- `543543543` (unlisted) → `WS_PROCEDURE_ERROR` / «Δεν βρέθηκε ο ΑΦΜ» — registry
  membership is the gate, not syntax (both `123456789` and `543543543` fail the checksum;
  the listed one certifies anyway).
- `123456789` → **accepted and certified**: an *undocumented* live registry entry. Zero
  hits across the whole spec PDF (Παράρτημα Ε pp. 45–46 included), the MySQL xlsx, the
  Postman collection and every .docx we hold. The «ΝΙΚΟΣ ΝΙΚΟΥ» seen on prod row 106 is
  typed `debtorName` data — debtor names never cross the SOAP wire in either direction
  (`retrieveKedeAmount` sends only `afm`/`code`/`category`/`amount` per debtor;
  `retrieveNames` is the signers operation). Do not build on `123456789`: an unpublished
  registry entry can vanish without notice.
- Its Τ.Ο. at `retrievePayProgress` → «Πληκτρολογήσατε λάθος Α.Φ.Μ.» — the payment
  endpoint validates the ΑΦΜ far more strictly than submit.
- Signers, 2026-10-27: `011586270` ΛΟΥΚΙΣΣΑΣ rejected with «Υπογράφων με ΑΦΜ πεθαμένου»
  (whole list), while `012703950` stays accepted — the «πεθαμένος» flag is enforced
  selectively. Proven-alive signer set as of 27-10: ΧΡΙΣΤΟΠΟΥΛΟΥ, ΠΙΠΕΡΑΚΗΣ,
  ΣΤΑΘΟΠΟΥΛΟΣ, ΜΑΝΩΛΑΚΟΣ, ΠΑΡΑΣΚΕΥΑΣ.

Open question for ΑΑΔΕ (fold into the pending pilot email): what exactly is in the pilot
debtor registry, and can fresh live test debtors be added? Five of the published
Παράρτημα Ε debtors are dead.

The general lesson for the remaining operations: **the spec's «προαιρετικό» is not reliable.**
Where Postman sends an element, send it — the Postman collection is a record of calls that were
actually accepted, and it outranks the prose.

## 8. Actions arising

1. Correct `CLAUDE.md`: for this service all six audit fields are mandatory (§2).
2. `SubmitBeveosiRules` enforces `sunolo` = Σ(δόσεις) = Σ(ΚΑΕ), no zero/empty amounts, `fiscalYear`
   in `[2010, current]`, valid `code`/`category` pair from §3, `afmYpogr` present in
   `declared_signers`.
3. `txtCode`, `extOrg` and `foreasAfm` are configuration, with the assigned values already in
   `.env.example` (§4). Only the ΚΕΔ username/password are still missing.
4. `declare_signers` sends today's date and a matching `plithosYpogr`.
5. `ReconciliationService` never auto-unlocks on an empty `retrieveVerificationProgress`; only a
   positive match promotes a row, and `804` on `retrieveCloseDay` keeps it locked.

## 9. `kedeDeleteService` (M4) — no Παράρτημα Ζ guide, and one confirmed landmine

This document transcribes the **progress-service** spec's Παράρτημα Ζ. The **delete-service**
spec (`Kede_Delete_Amount_Service_K___v_0.99.pdf`) has no equivalent at all — its own
Παράρτημα Ζ is only document-version history, and the whole PDF has zero mentions of
κλείδωμα/διπλ/lock. `app/Ked/Delete/AfekStatus.php`'s locking scheme is designed by analogy to
§1-§6 above, not derived from this spec.

Audit fields ARE identical, though: diffed Παράρτημα Γ wording in both PDFs — same six
mandatory fields, same exact clause.

**Observed 2026-10-08, against `test.gsis.gr`:** `deleteKedeAmount`'s `approvalDate` is marked
`<!--Optional:-->` in the spec's own sample, exactly like `doyFlag` on the progress side — and
exactly like `doyFlag`, the pilot rejects its absence: `GEN_INVALID_DATA` / «Το πεδίο
approvalDate είναι υποχρεωτικό και δεν μπορεί να είναι κενό». Fixed in
`KedeDeleteRequestBuilder` (always-send) and `DeleteKedeAmountRules` (now `required`). The
general lesson from §7a holds for this service too: the spec's «προαιρετικό» is not reliable.
