API-ul CrioX PBX

Istoricul apelurilor centralei tale, în aplicația ta. Fără export, fără un Make între voi.

CrioX e centrala telefonică pe care o folosești deja în cabinet sau în firmă. API-ul e felul în care programul tău, fie el site-ul, sistemul de comenzi sau un CRM făcut în casă, vorbește cu ea. Are două jumătăți, care se completează:

Cererile le faci tu, când ai nevoie: „dă-mi apelurile de ieri”, „ce s-a întâmplat cu apelul cu id-ul cutare”. Despre ele e pagina de față și referința.
Evenimentele le trimitem noi, când se întâmplă ceva: un apel preluat, unul pierdut, unul încheiat. Tu nu întrebi nimic; primești. Sunt webhook-urile, descrise în pagina lor.

Un sistem bine legat le folosește pe amândouă: evenimentul îți spune că s-a încheiat un apel, iar cererea îți aduce, când vrei, tot ce știm despre el. Obiectul „apel” e același în ambele locuri, cu aceleași chei.

ApeluriLista, cu filtre și paginare, și un apel după id. Toate câmpurile, explicate. EvenimenteCe trimitem, când, cum verifici semnătura și ce facem când serverul tău nu răspunde. Ce e nouFiecare schimbare, cu data ei. Ce e publicat nu se mai schimbă decât prin adăugare.

Cheia API

Orice cerere se face cu o cheie. O faci din CrioX, de pe pagina Integrări, în panoul API: apeși „Cheie nouă”, îi dai un nume ca să știi unde o folosești, și o primești o singură dată, pe ecran. Copiaz-o atunci. După ce închizi fereastra nu se mai poate afișa de nicăieri; nici tu, nici noi nu o mai vedem. Dacă o pierzi, faci alta și o revoci pe cea veche.

Cheia începe cu cxk_ și se trimite la fiecare cerere, în antetul Authorization:

Authorization: Bearer cxk_7Qp2mX9aK3vT8nL1wB4cR6dF0gH2jM5pQ9sU7xZ1aC

Câteva lucruri de știut despre ea:

Ține-o pe server. Cheia deschide istoricul apelurilor, cu numerele și numele celor care au sunat. Pusă într-o pagină de site, oricine o poate citi din sursă. Dacă ai nevoie de un formular pe site, formularul trimite la serverul tău, iar serverul tău vorbește cu noi.
Are drepturi precise. Azi, unul singur: citirea apelurilor (calls:read). O cheie nu poate schimba nimic pe centrală.
Revocarea e imediată și definitivă. Din clipa în care apeși „Revocă”, cererile cu acea cheie primesc 401.
Poți avea mai multe chei, câte una pentru fiecare aplicație. Așa le revoci separat, fără să oprești și celelalte integrări.
Doar administratorii contului le pot crea și revoca. Lista arată numele, primele caractere, când a fost creată fiecare și când a fost folosită ultima dată.

Prima cerere

Cel mai simplu test e să întrebi cine ești. Ruta nu cere nimic de la centrală, deci răspunde pe loc și îți spune dacă cheia merge.

GET/v1/account

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

Răspunsul:

{
  "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	Ce înseamnă
`account_id`	string	Id-ul contului tău în CrioX. Același cu `account_id` din evenimente.
`account_name`	string	Numele contului, cum apare în aplicație.
`key_name`	string	Numele pe care l-ai dat cheii. Poate fi gol.
`key_prefix`	string	Primele 12 caractere ale cheii, cum apar în lista din Integrări.
`scopes`	string[]	Ce are voie cheia.
`api_version`	integer	Versiunea API-ului care a răspuns. Azi, 1.

Adresa și formatul

Toate rutele stau sub o singură adresă:

https://api.criox.ro/v1

Răspunsurile sunt JSON, UTF-8. Cererile de citire nu au corp; filtrele merg în adresă, ca parametri. Câteva convenții, aceleași peste tot:

Momentele sunt ISO 8601, în UTC, cu Z la sfârșit: 2026-10-17T08:12:41.000Z. Programul tău le trece în ora locală. Când trimiți tu un moment, într-un filtru, poți scrie și cu fus orar (2026-10-17T11:12:41+03:00) sau ca secunde Unix.
Numerele de telefon vin în două forme, una lângă alta: internațională (+40743755549) și națională (0743755549). Folosești pe care o are deja sistemul tău. Pentru un număr străin cele două sunt identice.
null înseamnă „nu se știe” sau „nu se aplică”, niciodată o valoare ghicită. Cheia e mereu prezentă, chiar când valoarea e null; o mapare făcută pe un apel merge pe toate.
Id-urile sunt UUID-uri și nu se schimbă. Id-ul unui apel e același în listă, în apelul luat după id și în evenimente (acolo se numește call_id, pentru că evenimentul are id-ul lui).
Duratele sunt numere întregi, în secunde.
Listele vin pe pagini: data (rândurile), has_more (mai e ceva după) și next_cursor (cu ce ceri pagina următoare). Cursorul e un șir opac: îl trimiți înapoi neschimbat, nu îl construiești tu.

Erori

Când ceva nu merge, răspunsul are codul HTTP potrivit și un corp cu două câmpuri: error, un cod stabil pe care îl compari în program, și message, o propoziție pentru cine citește jurnalul. Codurile nu se schimbă; propozițiile pot fi corectate.

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

Cod	HTTP	Când
`missing_key`	401	Lipsește antetul `Authorization`.
`invalid_key`	401	Cheia nu are forma potrivită sau nu există. De obicei a fost copiată pe jumătate.
`key_revoked`	401	Cheia a fost revocată din Integrări. Fă alta.
`account_suspended`	403	Contul e suspendat. API-ul răspunde din nou când contul e activ.
`account_closed`	403	Contul e reziliat.
`account_not_ready`	409	Contul nu are încă o centrală, deci nu are apeluri.
`invalid_parameter`	400	Un parametru e scris greșit. `message` spune care și cum trebuia.
`not_found`	404	Ruta nu există. Verifică adresa și versiunea.
`call_not_found`	404	Nu există un apel cu acest id în contul tău, sau a ieșit din retenție.
`method_not_allowed`	405	Ruta există, dar nu cu această metodă.
`rate_limited`	429	Prea multe cereri pe minut. Antetul `Retry-After` spune câte secunde să aștepți.
`unavailable`	503	Centrala nu răspunde acum. Reîncearcă peste câteva secunde.
`internal_error`	500	O eroare la noi. Reîncearcă; dacă persistă, scrie-ne.

Pe 429 și 503 reîncearcă după o pauză, cu pauze din ce în ce mai lungi. Pe un 4xx nu reîncerca aceeași cerere neschimbată: nu va merge nici a doua oară.

Limite

60 de cereri pe minut cu o cheie. Peste, primești 429 și Retry-After. Fiecare răspuns poartă antetele X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset (secunde Unix, când se resetează fereastra).
Cel mult 200 de apeluri pe pagină; implicit 50.
Fără from, lista acoperă ultimele 30 de zile. Istoricul mai vechi se cere explicit, cu from, cât îl ține retenția contului tău (o vezi în Setări).
Cel mult 5 chei active pe cont. Dacă ai nevoie de mai multe, scrie-ne.

Nu interoga lista ca să afli de apeluri noi. Pentru asta sunt evenimentele: îți spun în câteva secunde că s-a întâmplat ceva, fără nicio cerere din partea ta. Lista e pentru sincronizări și rapoarte.

Versiuni

Versiunea e în adresă: /v1. În interiorul ei, schimbările sunt doar prin adăugare: un câmp nou într-un răspuns, un parametru nou și opțional, o rută nouă. Programul tău trebuie să ignore câmpurile pe care nu le cunoaște; atât.

Ce nu facem în v1: nu redenumim și nu scoatem câmpuri, nu schimbăm sensul valorilor, nu schimbăm codurile de eroare. Dacă vreodată e nevoie de o schimbare care rupe ceva, ea vine ca /v2, iar /v1 continuă să meargă cel puțin șase luni de la anunț.

Fiecare schimbare e scrisă în Ce e nou, cu data. Specificația completă, în format OpenAPI, e la openapi.json: o poți importa în Postman sau Insomnia, sau o dai unui generator de client pentru limbajul tău.

Ce urmează

Nu sunt disponibile încă. Le scriem aici ca să știi încotro merge API-ul; când apare una, o vezi în „Ce e nou”.

Agenda: îți împingi contactele din sistemul tău, ca telefonul să arate numele celui care sună, oricare ar fi CRM-ul tău.
Starea live: cine e la telefon și cine așteaptă, pentru un tablou pe perete sau pentru prezența în aplicația ta.
Telefoanele: interioarele și oamenii din spatele lor.
Click-to-call din aplicația ta: sună întâi telefonul colegului, apoi numărul.
Cereri de apel: „te sunăm noi” de pe site, sau o confirmare de comandă făcută de asistentul AI, la ora pe care o alegi.

Dacă ai nevoie de una dintre ele înaintea celorlalte, scrie-ne la suport@criox.ro. Ordinea o dau cererile clienților.

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