Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,39 +1,107 @@
# EXT-08 · AirCall-Konto + API + Webhooks (kein Sandbox — an P15 gekoppelt)
# EXT-08 · AirCall Technology-Partner-OAuth + Live-Zugang (keine Sandbox)
| | |
|---|---|
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| **Cycle/Fenster** | direkt vor **P15-Bau** (AK-P15a, start 2026-06-30) · fällig 2026-06-30 |
| **Status** | geplant (erst kurz vor P15 ausführen) |
| **Cycle/Fenster** | Just-in-time vor der Live-Verifikation von `AK-P15a` |
| **Status** | geplant · blockiert nur den Live-Proof, nicht den Fixture-first-Bau |
## Wichtig: AirCall hat KEINE Sandbox (geprüft 2026-06-21)
Offizielle AirCall-Doku: *„Currently, Aircall does not offer a dedicated sandbox environment for testing."*
Anders als Legacy-Provider/Google/PandaDoc gibt es **kein gratis Sandbox-Testen**:
- Getestet wird im **echten/Trial-Account** mit **Test-Usern + Test-Nummern** (als „TEST" labeln, danach löschen).
- **Test-Nummern + Seats kosten ggf. Geld** → mit AirCall-Account-Manager Konditionen klären.
- AirCall-Trial = nur **7 Tage** → läuft lange vor P15 ab, wenn man jetzt auf Vorrat anlegt.
> **Vertragskorrektur 2026-07-15:** HiveGrid ist eine Integration für mehrere Aircall-Companies und verwendet
> deshalb den offiziellen **Technology-Partner-OAuth-Flow**. `api_id`/`api_token` per Basic Auth ist laut
> Aircall nur für eine Integration in das eigene Aircall-Konto gedacht und ist **nicht** der HiveGrid-Vertrag.
→ **Konsequenz: NICHT jetzt auf Vorrat aufsetzen.** Konto + Test-Nummern + API-Key + Webhooks **direkt vor dem
P15-Bau** (AK-P15a, ab 2026-06-30) anlegen, damit keine ungenutzten Nummern bezahlt werden.
## Verifizierter Aircall-Vertrag
## Was zu tun ist (kurz vor P15)
- **AirCall-Konto** (Trial oder bezahlt) anlegen; falls nötig Test-Nummer(n) buchen (kostenpflichtig).
- **API-Key** (`api_id`/`api_token`, Basic-Auth) erzeugen, in Coolify-Env (staging/prod) hinterlegen.
- **Webhooks** konfigurieren (Call-Events/Click-to-Dial) auf `staging-api`/`api`, HMAC-Signaturprüfung + Rate-Limit.
- Aircall bietet **keine dedizierte Sandbox**. Live-Verifikation erfolgt in einem echten Partner-/Trial-Account
mit Test-Usern und ausgewählten Test-Nummern; Seats/Nummern können kostenpflichtig sein.
- Aircall stellt für die Technology-Partner-App `client_id` und `client_secret` bereit. Diese sind
**umgebungsweite App-Secrets**, keine Tenant-Credentials, und liegen ausschließlich in den jeweiligen
Coolify-Secrets für Staging/Produktion.
- Der Authorization-Code ist zehn Minuten gültig und wird über `POST https://api.aircall.io/v1/oauth/token`
gegen einen **permanenten Bearer-`access_token`** getauscht. Der Token läuft laut Aircall-Vertrag nicht ab;
es gibt für diesen Flow **keinen Refresh-Token und keinen Refresh-Worker**.
- Installationen sind auf Aircall-Company-Ebene. Die Person, die in HiveGrid als Tenant-Admin verbindet, muss
deshalb zugleich **Admin der betreffenden Aircall-Company** sein. Andernfalls kann sie die App nicht
autorisieren.
- Nach dem Token-Tausch legt HiveGrid den Webhook über `POST https://api.aircall.io/v1/webhooks` an. Aircall
liefert dabei einen eindeutigen Webhook-`token`, der in jedem Event mitgesendet und zur Connection-Zuordnung
geprüft wird. Aircall liefert für diesen Vertrag **keine HMAC-Signatur**; HMAC darf daher nicht vorgetäuscht
werden. Pflicht bleiben TLS, Payload-/Event-Allowlist, Token-Abgleich, Idempotenz und Rate-Limit.
- Bei OAuth wählt der Aircall-Company-Admin die Aircall-Nummern aus, deren Call-Events an die Integration gehen.
Offizielle Quellen: [Aircall OAuth für Technology Partners](https://developer.aircall.io/tutorials/how-aircall-oauth-flow-works/),
[Aircall API Reference](https://developer.aircall.io/api-references/) und
[Aircall Sandbox](https://support.aircall.io/en-gb/articles/23108614387485-Aircall-Sandbox).
## Registrierte URLs
| Zweck | Produktion | Staging |
|---|---|---|
| Aircall `install_uri` | `https://app.hivegrid.de/integrations/aircall/oauth/install` | `https://staging-app.hivegrid.de/integrations/aircall/oauth/install` |
| Aircall `redirect_uri` / Callback | `https://app.hivegrid.de/integrations/aircall/oauth/callback` | `https://staging-app.hivegrid.de/integrations/aircall/oauth/callback` |
| automatisch angelegter Webhook | `https://api.hivegrid.de/v1/webhooks/telephony/aircall` | `https://staging-api.hivegrid.de/v1/webhooks/telephony/aircall` |
Der `install_uri` erzeugt einen kurzlebigen, signierten OAuth-`state` (Tenant, initiierender User, Nonce) und
leitet mit `client_id`, festem `redirect_uri`, `response_type=code`, `scope=public_api` und `state` an
`https://dashboard.aircall.io/oauth/authorize` weiter. Der Callback prüft den `state`; Tenant-Identität steht
weder im Callback- noch im Webhook-Pfad.
### Getrennter Admin-Sales-Vertrag für VA-P28d
| Zweck | Produktion | Staging |
|---|---|---|
| Aircall Admin-Connect | `https://admin.hivegrid.de/sales/settings/telephony/connect/aircall` | `https://staging-admin.hivegrid.de/sales/settings/telephony/connect/aircall` |
| Aircall Admin-Callback | `https://admin.hivegrid.de/sales/settings/telephony/callback/aircall` | `https://staging-admin.hivegrid.de/sales/settings/telephony/callback/aircall` |
| Admin-Sales-Webhook | `https://api.hivegrid.de/v1/webhooks/admin-telephony/aircall` | `https://staging-api.hivegrid.de/v1/webhooks/admin-telephony/aircall` |
Der Admin-Sales-Flow bindet OAuth-State, Connection und Call-Daten ausschließlich an einen
aktiven `AdminUser` und `AdminDataConnection`. Er verwendet weder Tenant-IDs noch Tenant-RLS
oder die produktiven Tenant-Redirects. Das Aircall-Partner-App-Setup muss beide klar getrennten
URL-Sätze registrieren; der Live-Proof für `VA-P28d` bleibt bis dahin extern blockiert.
## Was extern zu tun ist
- Technology-Partner-App bei Aircall mit den Install-/Callback-URLs registrieren und `client_id`/
`client_secret` getrennt für die vorgesehenen Umgebungen sicher bereitstellen.
- Aircall-Konto (Trial oder bezahlt) mit Aircall-Company-Admin, Test-Usern und gegebenenfalls kostenpflichtigen
Test-Nummern bereitstellen.
- Die HiveGrid-App durch den Company-Admin installieren, Nummern auswählen und den permanenten Access Token via
Callback erzeugen; danach `/v1/ping`, User-Liste und Click-to-Call live prüfen.
- Den Webhook automatisiert anlegen und mindestens die vereinbarten Call-Events live gegen Staging verifizieren.
## Fixture-first vs. Live-Verifikation
`AK-P15a` beginnt **fixture-first**: OAuth-State/Callback, Token-Tausch, API-Mapping, Webhook-Normalisierung,
Idempotenz und Fehlerpfade werden gegen versionierte Fixtures und HTTP-Fakes gebaut. `EXT-08` blockiert nur den
abschließenden Live-Proof mit echtem Aircall-Account, echter Nummernauswahl, Callback, Call und Webhook. Ohne
diesen Proof bleibt `AK-P15a` unter 100 %, der restliche Bau ist aber nicht blockiert.
## Warum / was es blockt
Telefonie-Integration (Call-Events, Click-to-Dial) braucht API-Zugang + Webhooks.
- **Blocks:** P15 (Telefonie, **AK-P15a**)
- **Blocks:** ausschließlich die **Live-Verifikationspunkte** von `AK-P15a` und `VA-P28d`,
nicht deren Fixture-first-Umsetzung.
## Abhängigkeiten
- **blocked-by:** — (aber bewusst an P15-Timing gekoppelt; kostenpflichtig, daher Just-in-time)
- **blocks:** P15 (AK-P15a)
- **blocked-by:** Aircall Technology-Partner-Onboarding und Verfügbarkeit eines Aircall-Company-Admins mit
Test-User/-Nummer (extern)
- **blocks:** `AK-P15a` Live-Proof
- **Auswirkung auf Abhängige (2026-07-15):** `AK-P15a` wird fixture-first entblockt; `D-P15` ist nach AD-28
kein Dev-Blocker. `AK-P15b` (Chat) erhält durch den Aircall-Auth-Vertrag keine technische Änderung.
- **Auswirkung auf Abhängige (2026-07-24):** `VA-P28d` verwendet einen separaten, tenantlosen
Admin-Sales-OAuth-/Webhook-Vertrag. Der Codebau bleibt fixture-first entblockt; nur der
kontrollierte Admin-Live-Proof wartet auf die zusätzliche Partner-App-Registrierung.
## Definition of Done
- [ ] AirCall-Konto + (ggf. kostenpflichtige) Test-Nummer(n)
- [ ] API-Key in Coolify-Env (staging/prod)
- [ ] Webhooks konfiguriert (HMAC + Rate-Limit)
- [ ] Technology-Partner-App/OAuth-Credentials für die benötigten Umgebungen vorhanden; Install-/Callback-URLs
sind bei Aircall registriert
- [ ] Aircall-Company-Admin + Test-User/-Nummer vorhanden und Nummernauswahl im Install-Flow durchgeführt
- [ ] Permanenter Access Token per Callback erzeugt, verschlüsselt gespeichert und mit `/v1/ping` live geprüft
- [ ] Webhook per OAuth-Bearer angelegt; Webhook-Token-Zuordnung, Rate-Limit und mindestens ein echtes Call-Event
auf Staging nachgewiesen
## Hinweis
„Sandbox" aus dem alten Ticket-Titel gestrichen — existiert bei AirCall nicht. Quelle: AirCall Help Center „Aircall Sandbox" + developer.aircall.io.
## Umsetzungs-Notiz
- **2026-07-15 · 0/4 DoD = 0 % done:** Planungsvertrag auf Technology-Partner-OAuth korrigiert. Keine DoD als
umgesetzt markiert; Live-Zugang und Live-Proof bleiben extern offen.