API, webhook-uri și server MCP · CallAgent pentru dezvoltatori

§01 API

Două sute douăzeci și una de rute documentate.

API-ul nu este un subset ținut pe lângă interfață. Consola este construită pe aceleași modele și aceleași politici, așa că un asistent, un apel, o coadă sau o campanie este același obiect fie că ajungi la el printr-un ecran, fie printr-o cerere.

Rutele sunt grupate pe domenii, fiecare în fișierul lui, și montate sub un singur prefix cu versiune, în spatele autentificării cu cheie și al rezolvării de tenant.

Grupurile de rute de mai sus sunt citite din directorul de rute la randarea paginii.[1]

Grupuri de rute 13

/v1/analytics
/v1/assistants
/v1/billing
/v1/calls
/v1/campaigns
/v1/contact-center
/v1/knowledge
/v1/mcp
/v1/platform
/v1/squads
/v1/telephony
/v1/tools
/v1/webhooks

Convențiile API-ului.
openapi	Un document OpenAPI aflat în depozit, cu 221 de căi, cu versiune pe dată. SDK-urile de server generate încă nu sunt livrate — pagina de stadiu o spune.
throttle	Limitare la 300 cereri pe minut, cheia fiind cheia de API, nu adresa IP, fiindcă mai mulți clienți pot ieși pe aceeași adresă și unul gălăgios nu are voie să îl limiteze pe altul.
errors	Un singur randator de erori, așa că o eroare are aceeași formă indiferent ce domeniu a produs-o.

§02 Chei

O cheie este o credențială cu o rază de explozie.

Cheile au domenii de acces, se pot roti și sunt legate de tenant. Rotirea emite un secret nou fără să șteargă înregistrarea cheii, așa că ce rotești este secretul, nu fiecare integrare care l-a folosit.

Rezolvarea tenantului se face înaintea legării modelelor la rute, ceea ce sună a instalație și nu este: cu ordinea invers, o cerere pentru altă organizație rezolva o înregistrare reală înainte să ruleze vreo politică. A fost găsită, reparată global și are un test de regresie.

Chei de API și tratarea cererilor.
creare	Se creează din consolă sau prin API. Secretul se arată o singură dată.
domenii de acces	Domenii de citire și scriere pe fiecare zonă, iar operațiile distructive sunt separate de scriere.
rotire	O acțiune de rotire pe cheia însăși, ca integrarea să își păstreze identitatea și urma de audit.
limite de rată	Contorizate pe cheia de API. Cererile neautentificate cad pe adresa IP, cu o limită mai mică, fiindcă este singurul identificator disponibil înainte de rezolvarea cheii.
legare de tenant	Rezolvat din cheie, apoi aplicat ca domeniu global de interogare, înainte să fie legat vreun model.
neautentificat	O cerere de API neautentificată primește o eroare JSON, nu o redirectare către o pagină de autentificare pe care nu o poate urma.

§03 Integrare

Trei căi de intrare și una de ieșire.

Webhook-urile împing către rutele tale ciclul de viață al apelului și datele de eveniment, cu înregistrări de livrare pe care le poți inspecta și retrimite, nu cu un POST aruncat în gol în care trebuie să ai încredere.

CallAgent este și server MCP. Este montat cu aceeași autentificare pe cheie și aceeași rezolvare de tenant ca API-ul REST, intenționat: un client MCP este alt consumator de API, nu unul privilegiat.

Poarta de acces vorbește cu planul de control pe canalul ei intern, cu un token comun, iar canalul acela nu este limitat la un tenant fiindcă le servește pe toate deodată. Din exact acest motiv este separat de API-ul public.

Suprafețe de integrare

POST /mcp	CallAgent expus ca server MCP, în spatele autentificării pe cheie, al rezolvării de tenant și al aceleiași limite de rată ca API-ul REST.
/v1/webhooks	Rutele tale, cu evenimentele pe care le vrei și un secret de semnare.
deliveries	Fiecare încercare consemnată cu răspunsul ei și o acțiune de retrimitere.
/api/internal/v1	Canalul porții de acces. Autentificat cu token comun, nelimitat la un tenant și niciodată expus ca API de client.

Reîncercările de webhook rulează pe o comandă programată în fiecare minut; o livrare eșuată este o înregistrare cu număr de încercări, nu un eveniment pierdut.[2]

§04 Stocare

Înregistrările pot sta în bucketul tău, nu în al nostru.

Înregistrările de apel și artefactele sunt partea din sistem cel mai probabil guvernată de politica altcuiva. Așa că destinația se configurează per organizație, iar bucketul platformei este o opțiune din cinci, nu singura.

Fișierele se servesc prin URL-uri semnate care expiră după 15 minute. Un driver al cărui pachet nu este instalat nu apare deloc în interfață, fiindcă un depozit pe care îl poți alege și nu îl poți folosi este mai rău decât unul absent — ai afla la prima înregistrare.

Drivere de stocare 8

platform
s3
s3_sts
r2
azure_blob
gcs
supabase
s3_compatible

Lista de drivere este o verificare reală de capabilitate la rulare, nu un comutator de funcționalitate.[3]

§05 Izolare

O organizație nu o poate vedea pe alta.

Fiecare model care aparține unui tenant poartă un domeniu de organizație aplicat global, iar organizația curentă este legată de panou, de middleware-ul cheii de API și explicit în interiorul sarcinilor puse la coadă — fiindcă o sarcină care rulează peste o oră nu are de la ce cerere să o moștenească.

Peste asta vin rolurile și permisiunile, un jurnal de audit, o integrare cu furnizorul de identitate și OAuth pentru conexiunile care îl cer.

Tenancy, control al accesului și identitate.
izolare	Un domeniu global de interogare pe fiecare model de tenant, plus politici, plus rezolvarea tenantului înainte de legare.
roluri	10 roluri peste un catalog de 71 de permisiuni, de la proprietar până la operator, membru și analist.
jurnal de audit	Cine ce a schimbat, ca înregistrări, nu ca rânduri de log, citibile în consolă.
SCIM	Provizionare cu token propriu, intenționat altă clasă de credențială decât cheile de API: un token care poate suspenda oameni trebuie să poată fi revocat singur.
OAuth	Rute de retur care poartă sesiune, ca să poată fi validate starea și PKCE, pentru integrările care o cer.
sarcini	Munca pusă la coadă își leagă tenantul explicit, nu îl moștenește, singurul mod în care o sarcină de peste o oră ajunge în domeniul corect.

§06 Bani

Contabilitate de cost care se închide.

Creditele trec printr-un registru care doar crește. Soldul este suma registrului, nu o coloană pe care o actualizează cineva, așa că cele două nu au cum să se contrazică, iar o comandă de reconciliere o demonstrează.

Un apel este admis doar dacă portofelul poate acoperi plauzibil 60 de secunde din el, iar rezervarea este eliberată de un colector dacă procesul care o ținea moare. Altfel o cădere în mijlocul apelului blochează pe tăcute creditul clientului.

Rutele Stripe rulează SDK-ul adevărat peste simulacre în construcția asta. Nicio plată reală nu a fost făcută.[4]

Facturare și contabilitate de cost.
registru	Intrări de credit care doar se adaugă. Nimic nu se editează, așa că un audit înseamnă o citire.
rezervări	Ținută cât durează apelul, eliberată la final și recuperată programat dacă cel care o ținea dispare.
admitere	Un apel pe care portofelul nu îl poate acoperi plauzibil nu pornește, ceea ce este mai omenos decât să fie tăiat la jumătate.
evenimente de consum	Consum pe apel, pe etapă și pe furnizor, consemnat ca evenimente, adică baza din care se calculează costul unui apel.
prețuri	Prețuri și produse cu dată de intrare în vigoare, ca o schimbare de preț să nu rescrie retroactiv luna trecută.
facturi	Facturi cu descărcare, plus reîncărcare automată și un calendar de somații pentru conturile rămase în urmă.

Note

1 Grupuri de rute: routes/api/v1/, listate din sistemul de fișiere. Document OpenAPI: docs/api/openapi.json, 221 de căi.
2 Punctele de montare și middleware-ul lor: bootstrap/app.php. Limitatoarele de rată: app/Providers/AppServiceProvider.php.
3 Driverele de stocare și verificarea de disponibilitate: app/Enums/Storage/StorageDriver.php. Durata URL-ului semnat: config/callagent.php.
4 Pragul de admitere: config/callagent.php, cheia billing.admission_minimum_seconds. Permisiuni: app/Services/Rbac/Permissions.php. Roluri: app/Services/Rbac/Roles.php.

Tot ce face consola face și API-ul.