ETA Document Flow

Egyptian Tax Authority (ETA) documents share one policy: EtaActionPolicy in the shared library. The same rules disable Actions in Blazor (EtaActionGate / EtaActionMenuItem) and reject illegal calls on the API.

This guide documents implemented behavior for:

• E-Invoices — sent invoices (Direction = Sent, Kind = Invoice)
• E-Received Invoices — inbound supplier invoices (Direction = Received, Kind = Invoice)
• E-Receipts — sent receipts (Kind = Receipt; use return, not cancel)

Parent hub: Target Document Flow.

• Draft / Validated / Queued
• Submitted
• Valid
• Invalid / Rejected
• Cancelled / Returned

#Status catalog

Statuses are stored as strings on the document and mapped to EtaDocumentStatus.

* Receipts do not use recipient Reject / Decline Cancellation; reverse with Create Return Or Cancel Receipt.

#Lifecycle overview

Core path — prepare, submit, ETA result

flowchart TB
  subgraph Prepare["1 - Prepare"]
    direction TB
    Draft[Draft]
    Validated[Validated]
    Queued[Queued - receipts]
    Draft -->|Validate| Validated
  end

  subgraph Authority["2 - Authority"]
    Submitted[Submitted]
  end

  subgraph Result["3 - Result"]
    direction TB
    Valid[Valid]
    Invalid[Invalid]
  end

  Start((Create)) --> Draft
  Draft -->|Submit| Submitted
  Validated -->|Submit| Submitted
  Queued -->|Submit| Submitted
  Submitted -->|ETA accept| Valid
  Submitted -->|ETA refuse| Invalid
  Draft -.->|Submit refused| Invalid
  Validated -.->|Submit refused| Invalid
  Invalid -->|Edit| Draft
  Invalid -->|Resubmit| Submitted

  class Start egkStart
  class Draft,Validated,Queued egkDraft
  class Submitted egkActive
  class Valid egkSuccess
  class Invalid egkError

Terminal paths from Valid — cancel, reject, or return

flowchart TB
  Valid[Valid]
  Valid -->|Cancel on ETA| Cancelled[Cancelled]
  Valid -->|Reject invoice| Rejected[Rejected]
  Valid -->|Create return| Returned[Returned]
  Cancelled --> DoneNode((Done))
  Rejected --> DoneNode
  Returned --> DoneNode

  class Valid egkSuccess
  class Cancelled,Rejected,Returned egkTerminal
  class DoneNode egkStart

#Direction split (invoices)

ETA gives each side one reversal verb. Receipts use Create Return Or Cancel Receipt, not Cancel On Eta.

Issuer vs recipient reversal actions

flowchart TB
  subgraph Issuer["Issuer - E-Invoices"]
    direction TB
    S1[Valid] -->|Cancel on ETA| S2[Cancelled]
    S1 -->|Decline rejection| S3[Reinstate / clear pending]
  end
  subgraph Recipient["Recipient - E-Received Invoices"]
    direction TB
    R1[Valid] -->|Reject invoice| R2[Rejected]
    R1 -->|Decline cancellation| R3[Reinstate / clear pending]
  end

  class S1,R1 egkSuccess
  class S2,R2 egkTerminal
  class S3,R3 egkActive

#Action availability matrix

Legend: Y = allowed when other flags permit · — = never for this kind/direction · C = conditional (see notes)

#Decision trees

#When is Cancel On Eta enabled?

Cancel On Eta — policy gates

flowchart TB
  A[Cancel On Eta] --> B{Kind = Invoice?}
  B -->|No| X1[Denied - use return]
  B -->|Yes| C{Direction = Sent?}
  C -->|No| X2[Denied - sender only]
  C -->|Yes| D{Pending cancellation?}
  D -->|Yes| X3[Denied - already requested]
  D -->|No| E{Pending rejection?}
  E -->|Yes| X4[Denied - rejection pending]
  E -->|No| F{Status = Valid?}
  F -->|No| X5[Denied - not Valid]
  F -->|Yes| G{Reversal window closed?}
  G -->|Yes| X6[Denied - window closed]
  G -->|No| OK[Allowed]

  class A egkActive
  class B,C,D,E,F,G egkDecision
  class OK egkSuccess
  class X1,X2,X3,X4,X5,X6 egkError

#When is Decline Rejection enabled?

Decline Rejection — policy gates

flowchart TB
  A[Decline Rejection] --> B{Invoice + Sent?}
  B -->|No| X1[Denied - wrong kind]
  B -->|Yes| C{Has ETA UUID?}
  C -->|No| X2[Denied - not submitted]
  C -->|Yes| D{Already declined?}
  D -->|Yes| X3[Denied - already declined]
  D -->|No| E{Pending rejection or Rejected?}
  E -->|No| X4[Denied - no rejection]
  E -->|Yes| F{Status}
  F -->|Valid| G{Decline window closed?}
  G -->|Yes| X5[Denied - window closed]
  G -->|No| OK[Allowed]
  F -->|Rejected or Cancelled| OK
  F -->|Other| X4

  class A egkActive
  class B,C,D,E,F,G egkDecision
  class OK egkSuccess
  class X1,X2,X3,X4,X5 egkError

#After-action UI behavior (ETA screens)

A refused action refreshes the same as an accepted one. A refusal usually means the document had already moved on — cancelled by someone else, or past its window — which is exactly the case where the row on screen is the stale thing that offered the action. A refused submission also still writes to the document: the reason ETA gave, and the attempt in the audit trail. So the screen after a refusal shows the authority's current answer rather than the state you clicked from, and no manual refresh is needed to find out what is still possible.

Validate is included in this, despite the read-only name: a draft that passes validation is promoted to Validated and saved, which changes what the Actions menu should offer.

EntityTable CanUpdateEntityFunc / CanDeleteEntityFunc also call EtaActionPolicy so built-in Edit/Delete match the Actions menu.

#Scenario catalog

#Sequence: submit sent invoice

Submit path — gate → API → ETA → UI sync

sequenceDiagram
  autonumber
  participant UI as Invoices grid
  participant Gate as EtaActionGate
  participant API as Invoice API
  participant Svc as Submission service
  participant ETA as Tax authority
  participant DB as Database

  UI->>Gate: Evaluate Submit
  Gate-->>UI: Allow or deny + tooltip
  UI->>API: POST /{id}/submit
  API->>Svc: SubmitInvoiceToEta
  Svc->>DB: Read invoice
  Svc->>ETA: Submit document
  ETA-->>Svc: UUID / validation result
  Svc->>DB: Persist StatusId + UUID
  API-->>UI: Outcome
  UI->>UI: Reload grid + re-gate Actions

#Denial reasons (tooltips)

Denial keys resolve through the module localizer. Examples:

• Action Denied Locked By Eta
• Action Denied Already Submitted
• Action Denied Only Valid Can Be Cancelled
• Action Denied Cancellation Already Requested
• Action Denied Decline Window Closed
• Action Denied Decline Rejection Is Sender Only
• Action Denied Decline Cancellation Is Receiver Only
• Action Denied Receipts Use Return

#Official PDF archival

ETA portal PDFs may disappear after a short retention window. EGKits therefore archives the official English and Arabic printouts locally as soon as a document is eligible:

• Sales (E-Invoices) — after status sync once a UUID exists and the document was submitted to ETA
• Received (E-Received Invoices) — after retrieval for Valid / Rejected / Cancelled documents

Work runs on Hangfire (eta-pdf-archive:drain / eta-pdf-archive:reconcile). The invoice UI Documents / Archive panel shows EN/AR status and allows View / Download / Retry without exposing server paths. Details: Document Archive Document Flow.

#ERP integration: AR ↔ ETA bridge and historical back-fill

E-invoices are the fiscal mirror of Accounts Receivable documents, never a second business transaction. Every ETA document raised by the bridge carries PartnerId, ArInvoiceId / ArCreditNoteId and SourceModule = AccountsReceivable; every AR document raised from an ETA document carries SourceModule = EtaBackfill and the key ETA:{uuid}.

Two directions, one document each way

flowchart LR
  AR[AR Invoice Sent] -->|bridge, key AR-{invoiceId}| EI[E-invoice draft]
  EI -->|AutoValidate / AutoSubmit| ETA((ETA))
  ETA -->|Valid / Cancelled / Rejected| AR
  H[Historical ETA document Valid] -->|back-fill, key ETA:{uuid}| ARH[AR Invoice / Credit Note]
  ARH --> GL[GL journal on issue date]

  class AR,ARH,GL egkSuccess
  class EI egkDraft
  class H egkActive

Guides: Sales Document Flow (hand-off), Recurring Document Flow (periodic generation).

#E-invoice or e-receipt? One decision for every sale

EGKITS decides the ETA document type once, in the same place, for invoices, POS sales, credit notes and recurring contracts. The e-receipt is a fiscal mirror exactly like the e-invoice: it never posts revenue, tax, receivables or cash on its own.

Document-type decision

flowchart TB
  S((Sale)) --> B{Bridge enabled?}
  B -->|No| N[No ETA document]
  B -->|Yes| C{Channel}
  C -->|Point of sale| R[E-receipt]
  C -->|Invoice| T{Business with tax id or foreign?}
  T -->|Yes| I[E-invoice]
  T -->|Individual| P{Consumer document setting}
  P -->|E-invoice| I
  P -->|E-receipt| R
  P -->|None| N

  class S egkStart
  class I,R egkSuccess
  class N egkTerminal

#Related guides

• Target Document Flow
• Sales Document Flow
• Recurring Document Flow
• E-Invoices
• E-Received Invoices
• E-Receipts
• Document Archive Document Flow