API-ul CrioX PBX

Integrează centrala CrioX cu aplicațiile tale: citește istoricul apelurilor prin API și primește prin webhook-uri un eveniment la fiecare apel.

Integrarea are două componente, care descriu apelurile cu același obiect și aceleași câmpuri:

API-ul REST răspunde cererilor trimise de aplicația ta, de exemplu lista apelurilor dintr-o perioadă sau detaliile unui apel. Este descris pe această pagină și în referința apelurilor.
Webhook-urile sunt cereri HTTP pe care CrioX le trimite serverului tău când un apel primit este preluat și când un apel se încheie. Sunt descrise în pagina Evenimente.

De regulă, cele două se folosesc împreună: evenimentul anunță apelul încheiat, iar prin API îl poți citi din nou oricând, după id.

ApeluriLista apelurilor, cu filtre și paginare, un apel după id și descrierea fiecărui câmp. EvenimenteTipurile de evenimente, formatul, verificarea semnăturii și reîncercările. NoutățiModificările API-ului, cu data și versiunea fiecăreia.

Cheia API

Fiecare cerere se autentifică cu o cheie API. Cheile se creează în CrioX, pe pagina Integrări, în panoul API, cu butonul „Cheie nouă”. Dă fiecărei chei numele aplicației care o folosește.

Cheia completă este afișată o singură dată, la creare, și nu mai poate fi recuperată ulterior, nici de tine, nici de echipa CrioX. Copiaz-o înainte să închizi fereastra. Dacă o pierzi, creează o cheie nouă și revoc-o pe cea veche.

Cheia începe cu cxk_ și se trimite în antetul Authorization al fiecărei cereri:

Authorization: Bearer cxk_7Qp2mX9aK3vT8nL1wB4cR6dF0gH2jM5pQ9sU7xZ1aC

Gestionarea cheilor

Păstrează cheia pe server. Ea dă acces la istoricul apelurilor, inclusiv la numerele și numele apelanților, iar dacă o incluzi în codul unei pagini web sau al unei aplicații mobile, oricine o poate citi. Un formular de pe site trimite datele serverului tău, iar serverul tău apelează API-ul.
În prezent, o cheie are o singură permisiune: calls:read, citirea apelurilor. Prin API nu se poate modifica nimic pe centrală.
Revocarea are efect imediat și nu poate fi anulată. După ce apeși „Revocă”, cererile făcute cu acea cheie primesc 401 key_revoked.
Folosește câte o cheie pentru fiecare aplicație, ca să poți revoca una fără să întrerupi celelalte integrări.
Doar administratorii contului pot crea și revoca chei. Lista arată, pentru fiecare cheie, numele, primele caractere, data creării și data ultimei utilizări.

Prima cerere

Pentru a verifica o cheie, apelează GET /v1/account. Ruta returnează contul și cheia cu care a fost făcută cererea. Nu depinde de centrală, deci răspunde imediat.

GET/v1/account

curl https://api.criox.ro/v1/account \
  -H "Authorization: Bearer cxk_…"

Răspuns:

{
  "account_id": "3f0c1d2e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "account_name": "Clinica Dorobanți",
  "key_name": "Site",
  "key_prefix": "cxk_7Qp2mX9a",
  "scopes": ["calls:read"],
  "api_version": 1
}

Câmp	Tip	Descriere
`account_id`	string	Id-ul contului în CrioX. Are aceeași valoare ca `account_id` din evenimente.
`account_name`	string	Numele contului, așa cum apare în aplicație.
`key_name`	string	Numele dat cheii la creare. Poate fi gol.
`key_prefix`	string	Primele 12 caractere ale cheii, ca în lista din Integrări.
`scopes`	string[]	Permisiunile cheii.
`api_version`	integer	Versiunea majoră a API-ului care a răspuns. În prezent, 1.

Adresa și formatul

Toate rutele au aceeași adresă de bază:

https://api.criox.ro/v1

Răspunsurile sunt JSON, codificate UTF-8. Cererile de citire nu au corp; filtrele se trimit ca parametri în adresă. Convențiile de mai jos sunt aceleași pe toate rutele.

Momentele (tipul moment din tabele) sunt în format ISO 8601, în UTC, cu sufixul Z: 2026-10-17T08:12:41.000Z. Conversia în ora locală se face în aplicația ta. În filtre poți trimite și un moment cu fus orar (2026-10-17T11:12:41+03:00) sau un timestamp Unix, în secunde.
Numerele de telefon apar în două forme: internațională (+40743755549) și națională (0743755549). Folosește forma pe care o are deja sistemul tău. Pentru numerele din străinătate, cele două valori sunt identice.
null înseamnă că valoarea nu este cunoscută sau nu se aplică; API-ul nu completează câmpuri cu valori estimate. Toate cheile sunt prezente în fiecare obiect, inclusiv cele cu valoarea null, deci o mapare configurată pe un apel funcționează pentru toate.
Id-urile sunt UUID-uri și nu se modifică. Un apel are același id în listă, în GET /v1/calls/{id} și în evenimente, unde câmpul se numește call_id, pentru că id identifică acolo evenimentul.
Duratele sunt numere întregi, în secunde.
Listele sunt paginate: data conține rândurile, has_more arată dacă mai urmează pagini, iar next_cursor este valoarea pentru pagina următoare. Cursorul este un șir opac: trimite-l înapoi exact cum l-ai primit, fără să-l modifici sau să-l construiești.

Erori

Erorile folosesc codurile de stare HTTP. Corpul răspunsului are două câmpuri: error, un cod stabil pe care aplicația ta îl poate compara, și message, o explicație pentru jurnale. Codurile din error nu se schimbă; textul din message poate fi reformulat, deci nu îl folosi în logica aplicației.

{
  "error": "invalid_parameter",
  "message": "„direction” poate fi doar: inbound, outbound."
}

Cod	HTTP	Descriere
`missing_key`	401	Lipsește antetul `Authorization`.
`invalid_key`	401	Cheia are un format greșit sau nu există. Cauza obișnuită este o cheie copiată incomplet.
`key_revoked`	401	Cheia a fost revocată. Creează o cheie nouă din Integrări.
`account_suspended`	403	Contul este suspendat. Cererile sunt acceptate din nou după reactivarea contului.
`account_closed`	403	Contul este reziliat.
`account_not_ready`	409	Contul nu are încă o centrală configurată, deci nu are apeluri.
`invalid_parameter`	400	Un parametru are o valoare invalidă. `message` indică parametrul și forma corectă.
`not_found`	404	Ruta nu există. Verifică adresa și versiunea.
`call_not_found`	404	Contul tău nu are un apel cu acest id, sau apelul a depășit perioada de retenție.
`method_not_allowed`	405	Ruta există, dar nu acceptă această metodă HTTP.
`rate_limited`	429	Limita de cereri pe minut a fost depășită. Antetul `Retry-After` indică după câte secunde poți reîncerca.
`unavailable`	503	Centrala nu răspunde momentan. Reîncearcă după câteva secunde.
`internal_error`	500	Eroare internă CrioX. Reîncearcă; dacă eroarea persistă, scrie-ne la suport@criox.ro.

Erorile 429, 500 și 503 sunt temporare: reîncearcă cererea cu pauze din ce în ce mai lungi. Celelalte erori 4xx nu dispar la reîncercare; corectează cererea înainte să o trimiți din nou.

Limite

60 de cereri pe minut pentru fiecare cheie. Peste această limită, API-ul răspunde cu 429 și antetul Retry-After. Fiecare răspuns include antetele X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset (momentul resetării ferestrei, ca timestamp Unix în secunde).
Cel mult 200 de apeluri pe pagină; implicit 50.
Fără from, lista acoperă ultimele 30 de zile. Pentru apeluri mai vechi, trimite from explicit; istoricul este disponibil pe toată perioada de retenție a contului, afișată în Setări.
Cel mult 5 chei active pe cont. Pentru mai multe, scrie-ne la suport@criox.ro.

Pentru apelurile noi, folosește evenimentele. Interogarea repetată a listei consumă din limita de cereri și aduce apelurile mai târziu. Evenimentele sunt trimise automat după fiecare apel; lista este potrivită pentru sincronizări și rapoarte.

Versiuni

Versiunea majoră face parte din adresă: /v1. În aceeași versiune, modificările sunt doar adăugiri: câmpuri noi în răspunsuri, parametri noi opționali, rute noi. Aplicația ta trebuie să ignore câmpurile pe care nu le recunoaște.

În v1 nu se redenumesc și nu se elimină câmpuri, nu se schimbă semnificația valorilor și nu se modifică codurile de eroare. O modificare incompatibilă va fi publicată ca /v2, iar /v1 va funcționa în continuare cel puțin șase luni de la anunț.

Fiecare modificare este publicată, cu data ei, în Noutăți. Specificația completă, în format OpenAPI 3.1, este la openapi.json. O poți importa în Postman sau Insomnia, sau o poți folosi pentru a genera un client în limbajul tău.

În pregătire

Funcțiile de mai jos sunt planificate și nu sunt încă disponibile. Fiecare va fi anunțată în Noutăți la lansare.

Agenda: sincronizarea contactelor din sistemul tău, astfel încât telefoanele să afișeze numele apelantului, indiferent de CRM.
Starea în timp real: colegii aflați în apel și apelurile în așteptare, pentru un panou de monitorizare sau pentru afișarea disponibilității în aplicația ta.
Interioarele: lista interioarelor și a colegilor asociați.
Click-to-call: apeluri inițiate din aplicația ta; centrala sună întâi telefonul colegului, apoi numărul extern.
Cereri de apel: apeluri programate către clienți la ora aleasă, de exemplu un formular „Vă sunăm noi” pe site sau o confirmare de comandă făcută de asistentul AI.

Dacă una dintre aceste funcții este importantă pentru integrarea ta, scrie-ne la suport@criox.ro. Ordinea lansărilor ține cont de cererile clienților.

CrioX · suport@criox.ro · live.criox.ro