# Diagrams

> Flows worth having in your head before you integrate.

Source: /docs/reference/diagrams

## Outgoing invoice

```mermaid
flowchart LR
  A[POST /invoices] --> B{PINT AE valid?}
  B -- no, draftOnly --> D[draft]
  B -- no --> E[400 E_VALIDATION]
  B -- yes --> V[validated]
  V -- submit --> S[submitted]
  S --> L[delivered]
  L --> R[accepted / reported]
  S --> X[rejected]
  L --> X
  X -- fix & resubmit --> V
  R -- credit / debit note --> A
```

## Incoming invoice

```mermaid
flowchart LR
  U[Upload / email / Peppol / API] --> P[Import record]
  P --> T{UBL?}
  T -- yes --> V[Parse + validate PINT AE + buyer TRN]
  T -- PDF/image --> X[AI extraction or manual]
  V -- duplicate / invalid --> F[failed 422]
  V -- ok --> D[incoming invoice draft]
  X --> D
  D --> R{Review}
  R -- accept --> A[accepted, locked, payable]
  R -- reject --> J[rejected]
  A --> M[payments → paid]
```

## Webhook delivery

```mermaid
sequenceDiagram
  participant DB as Database trigger
  participant Q as Outbox
  participant W as Worker
  participant T as Your endpoint
  DB->>Q: emit event → one delivery per subscriber
  W->>Q: take due deliveries
  W->>T: POST signed JSON (10 s timeout)
  alt 2xx
    T-->>W: ok
    W->>Q: delivered
  else error / timeout
    W->>Q: retry in 1m, 5m, 30m, 2h, 12h; then failed
  end
```

## Keys and permissions

```mermaid
flowchart TD
  K[API key sk_live / sk_test] --> S[Scopes]
  S --> R1[invoices:read/write]
  S --> R2[incoming:read/write]
  S --> R3[customers, products, metadata, settings]
  S --> R4[webhooks:manage]
  K --> O[Organization]
  O -. X-Organization-Id .-> C[Managed client organization]
```