Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user