108 lines
6.9 KiB
Markdown
108 lines
6.9 KiB
Markdown
# EXT-08 · AirCall Technology-Partner-OAuth + Live-Zugang (keine Sandbox)
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Typ** | Setup (External) |
|
|
| **Owner** | Raffael |
|
|
| **Cycle/Fenster** | Just-in-time vor der Live-Verifikation von `AK-P15a` |
|
|
| **Status** | geplant · blockiert nur den Live-Proof, nicht den Fixture-first-Bau |
|
|
|
|
> **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.
|
|
|
|
## Verifizierter Aircall-Vertrag
|
|
|
|
- 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
|
|
|
|
- **Blocks:** ausschließlich die **Live-Verifikationspunkte** von `AK-P15a` und `VA-P28d`,
|
|
nicht deren Fixture-first-Umsetzung.
|
|
|
|
## Abhängigkeiten
|
|
|
|
- **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
|
|
- [ ] 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
|
|
|
|
## 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.
|