# Getting started — a guide for the BFF team

Read this before the full contract ([`message-contract.md`](message-contract.md), field-by-
field: what you send, what comes back). This page: how to connect, which commands actually
reach ΚΕΔ, what each status corresponds to in ΚΕΔ's own answers, and where to start.

## Connecting

Dev integration broker:

```
RABBITMQ_HOST=rmq-ms-gov-dev.logicea.xyz
RABBITMQ_PORT=5672
RABBITMQ_USER=gov_ked
RABBITMQ_PASSWORD=21c3f31b28c77a042aa2b84295c536bc
```

The same credentials log into the management UI at
[`https://rmq-ms-gov-dev.logicea.xyz/`](https://rmq-ms-gov-dev.logicea.xyz/) — useful for
watching the `gov_ked` queue directly (message counts, consumers) while you're testing.

Publish to the `gov_ked` queue (declared non-durable by our consumer — nothing survives a
broker restart, so don't rely on persistence here). Set AMQP's `reply_to` to an exclusive
queue of your own and we reply there, echoing the `correlation_id` you sent so you can match
the answer to the request. Body format, and everything about what each command expects and
returns: `message-contract.md`.

## Which commands reach ΚΕΔ, and which operation

Verified against the code (which classes actually call the SOAP client), not just documented:

| Command | Reaches ΚΕΔ? | ΚΕΔ operation |
|---|---|---|
| `ping` | No | — |
| `get_lookups` | No | — |
| `declare_signers` | **Always** | `retrieveNames` |
| `save_beveosi_draft` | No | — |
| `delete_beveosi_draft` | No | — |
| `submit_beveosi` | **Always** | `retrieveKedeAmount` |
| `get_beveosi_status` | Only if the row is still pending and hasn't been checked recently (throttled) | `retrieveVerificationProgress` + `retrieveCloseDay` |
| `list_beveoseis` | No | — |
| `get_payment_progress` | Only once the selector (payId, or id/auditProtocol+afm) resolves to a Ταυτότητα Οφειλής | `retrievePayProgress` |
| `get_payment_data` | Same | `retrievePaymentData` |
| `set_beveosi_attachments` | No — local metadata only | — |
| `submit_reduction` | **Always** (not ready to integrate against yet — see below) | `deleteKedeAmount` |
| `get_reduction_status` | Same throttle as `get_beveosi_status` | `deleteKedeComplete` |
| `list_reductions` | No | — |
| `get_reduction_progress` | **Always** (on-demand cross-check, not a gate) | `deleteKedeProgress` |

`declare_signers`, `submit_beveosi`, `submit_reduction` and `get_reduction_progress` always
spend one call against ΚΕΔ's daily quota. The rest only when they genuinely need to.

## Status ↔ what ΚΕΔ actually answered

A βεβαίωση's status isn't our own invention — it records a specific answer (or lack of one)
from ΚΕΔ:

| `status` | Came from | Locked? |
|---|---|---|
| `draft` | No call has been made yet. | no |
| `sent` | `retrieveKedeAmount` was sent; transitional — the answer is processed in the same call. | yes |
| `certified_pending_closeday` | `retrieveKedeAmount` answered success. The ΑΤΒ does not exist yet. | yes |
| `certified` | `retrieveVerificationProgress` found the ΧΚ **and** `retrieveCloseDay` returned the ΑΤΒ. Terminal. | yes |
| `failed` | `retrieveKedeAmount` answered with a business error — nothing was registered. | no — correct & resend, or delete |
| `needs_reconciliation` | `retrieveKedeAmount` failed at the network level (no answer) — outcome unknown. | yes — never resend |

One subtlety on `certified`: **the ΑΤΒ belongs to the ΧΚ, not to the βεβαίωση.** The ΔΟΥ
batches same-day certifications for the same debtor into a single ΧΚ (observed on the
pilot), so several of your βεβαιώσεις can share one ΑΤΒ. What uniquely identifies the
payable debt is the **Ταυτότητα Οφειλής** — `debtors[].taftotitaOfeilis`, one per ΧΚ line.
Worked example with real values: [`bff-call-examples.md`](bff-call-examples.md) §3a.

For the ΑΦΕΚ (Μείωση/Διαγραφή — see below, not ready to integrate against yet):

| `status` | Came from | Locked? |
|---|---|---|
| `sent` | `deleteKedeAmount` was sent, transitional. | yes |
| `awaiting_finalization` | `deleteKedeAmount` answered success — the ΑΦΕΚ number is known. | yes |
| `finalized` | `deleteKedeComplete` confirmed the εκκαθάριση. Terminal. | yes |
| `failed` | `deleteKedeAmount` answered with a business error. | no |
| `needs_reconciliation` | `deleteKedeAmount` failed at the network level. **Note:** a failed `deleteKedeComplete` does NOT land here — it just increments the retry count and the row stays `awaiting_finalization`. | yes |

## Ready to integrate against

Already exercised live against the ΚΕΔ pilot with real responses (certified βεβαιώσεις, a real
ΑΤΒ): `declare_signers`, `save_beveosi_draft`, `delete_beveosi_draft` (works on `draft`
**and** `failed`), `submit_beveosi`, `get_beveosi_status`, `list_beveoseis`,
`get_payment_progress`, `get_payment_data`, `set_beveosi_attachments`.

Recommended order, same lifecycle as `message-contract.md`:

1. `declare_signers` — once, before any βεβαίωση.
2. `submit_beveosi` — the response does **not** contain the ΑΤΒ yet; it does contain the
   **`hashId`** (SHA-256 of the `auditProtocol`): key your MinIO object names on it, and use it
   as the selector for status, attachments and resends. **`unitId` is required on submission** —
   the μονάδα that submitted it, stored by us, never sent to ΚΕΔ; `unitAcronym` is optional,
   display-only.
3. `get_beveosi_status` — poll until `pending: false` (select by `id`, `auditProtocol` **or**
   `hashId`).
4. `list_beveoseis` — filter by `unitId` (prefix match on the id **or** the acronym) to show
   one μονάδα's rows.
5. `get_payment_progress` / `get_payment_data` — once a Ταυτότητα Οφειλής exists from step 3.

Concrete command+params examples, with real Παράρτημα Ε test ΑΦΜ: see
[`bff-call-examples.md`](bff-call-examples.md).

### Attachments

- Send `attachments` (`[{title, filepath}]`, up to 10) **with the first `save_beveosi_draft` or
  `submit_beveosi`**. You don't need to save first or have an `auditProtocol`. `filepath` is your
  own MinIO key; upload the file first, then send the path. **Build the key on the `hashId`**
  from the reply (e.g. `<hashId>/apofasi.pdf`) — it is stable and unique per βεβαίωση.
- `set_beveosi_attachments` is only for **changing** the list later. It works at any status,
  including on a certified (locked) row.
- On save/submit, `attachments` present means replace the whole list; absent means keep it.
- Attachments are never sent to ΚΕΔ. They come back in every full-record reply (`submit_beveosi`,
  `save_beveosi_draft`, `get_beveosi_status`, `set_beveosi_attachments`), but not in
  `list_beveoseis` rows.

### Testing failure paths on the pilot

Observed, reproducible rejections — not invented, real pilot answers: a signer whose surname
doesn't match the ΑΦΜ registry, or a signer ΑΦΜ outside the registry, both answer
`WS_PROCEDURE_ERROR` and reject the whole signer list. Examples in `bff-call-examples.md`.

**There is no reliable way to deliberately trigger "no answer."** That outcome is a network-
timing artifact on a real external system, not something a specific input value controls —
don't look for a button for it.

## kedeDeleteService (Μείωση/Διαγραφή) — proven live, one rule to remember

Four commands (`submit_reduction`, `get_reduction_status`, `list_reductions`,
`get_reduction_progress`) are fully built, documented in `message-contract.md`, and **proven
end to end against the pilot on 2026-11-04**: fresh certification → reduction → finalization
in under six minutes (ΑΦΕΚ no. 1, οριστικό ΑΒΚΤ 404946). The one rule: **certifications with
only 5-digit ΚΑΕ (no ΑΛΕ) must submit `afekType: "2"`** (ΚΕΔ guidance 2026-11-03 — `1` is
rejected on such debts); with our granted ΚΑΕ set, `2` is always the right value. Earlier
business rejections were all `afekType: "1"` submissions, not a pilot limitation.

## Errors, briefly

- `status: 1` — succeeded, use `data`.
- `status: 4` — business error: something the user can act on. `errors[0]` is a ready-to-show
  sentence; `extraData.fields` has the per-field messages. **Check `extraData.resendable`
  before offering a retry** — when it's `false` (outcome unknown), a retry could raise a
  duplicate debt at the ΔΟΥ.
- `status: 3` — unexpected error; log it, don't offer an automatic retry.

Full table and examples: `message-contract.md` → "How to read the status".
