API Zoho CRM, OAuth si limite: raspunsul pe scurt
API-ul Zoho CRM accepta numai OAuth 2.0 pentru autentificare, fara varianta de cheie API. Pentru API Zoho CRM: OAuth si limite, regula practica are doua parti. Reutilizati tokenul de acces cat timp este valid. Grupati apelurile, pentru ca toate integrarile unei organizatii impart acelasi bazin zilnic de credite si aceeasi limita de concurenta.
Acest ghid explica cele trei tokenuri OAuth, limitele lor si erorile pe care le produc. Arata cum alegeti scope-urile si cum arata un flux complet de reinnoire a tokenului. Arata si cum alegeti tipul de apel dupa volumul de date. La final gasiti ce inseamna toate acestea pentru o companie din Romania care leaga CRM-ul de ANAF, SmartBill si cursul BNR.
Cifrele vin din documentatia Zoho pentru versiunea V8 a API-ului si din doua ghiduri tehnice publicate de ZoomInfo si Knit. Pretul exact al creditelor suplimentare nu este publicat de Zoho. Din acest motiv nu il veti gasi in acest ghid.
OAuth 2.0 in Zoho CRM: ce este si de ce nu exista cheie API
OAuth 2.0 este un protocol standard care permite unei aplicatii terte, numita client, sa primeasca acces delegat la resursele protejate din Zoho printr-un API. Acces delegat inseamna ca aplicatia vede doar resursele pe care utilizatorul le-a autorizat. Clientul nu stocheaza parola utilizatorului si nu trebuie sa suporte autentificare cu parola.
Conform documentatiei OAuth 2.0 pentru Zoho CRM API V8, utilizatorul poate revoca oricand accesul delegat al clientului. Daca aplicatia sufera o bresa de securitate, datele sunt expuse doar cat timp tokenul de acces este valid. De aceea conteaza ca tokenul de acces expira dupa o ora.
ZoomInfo noteaza ca Zoho CRM foloseste exclusiv OAuth 2.0 si nu ofera nicio optiune de cheie API. Multe discutii din forumul Zoho pleaca de la aceasta confuzie. Un utilizator voia sa importe lead-uri doar cu cereri cURL simple. El scria ca a petrecut trei ore mergand in cerc cu OAuth, aplicatii si clienti.
Un alt utilizator din forum raporta ca autorizarea veche Zoho-Authtoken esua pe API-ul V2. Intre timp, API-ul a ajuns la a opta versiune majora, V8. Daca urmati un tutorial vechi, verificati intai versiunea de API si metoda de autentificare pe care o descrie.
Cele trei tokenuri OAuth din Zoho CRM: grant, access si refresh
Fluxul OAuth din Zoho CRM foloseste trei tokenuri, fiecare cu alt rol si alta durata de viata. Tokenul de grant, numit si cod de autorizare, este un token temporar de unica folosinta. Clientul il trimite serverului de autorizare si primeste in schimb un token de acces si un token de refresh.
Tabelul de mai jos compara cele trei tokenuri dupa rol, valabilitate si limita principala.
| Token | Rol | Valabilitate | Limita principala |
|---|---|---|---|
| Grant (cod de autorizare) | Se schimba o singura data pe tokenurile de acces si refresh | 3 minute implicit; la self-client se poate alege mai mult din consola API | Cel mult 10 in 10 minute pentru acelasi client ID |
| Acces | Insoteste fiecare apel API, doar pentru operatiile din scope | O ora (3600 de secunde) | Cel mult 15 active per token de refresh; cel mult 10 generate in 10 minute |
| Refresh | Obtine tokenuri de acces noi | Nelimitata, pana la revocare de catre utilizator | Cel mult 20 per utilizator |
Tokenul de acces se trimite la fiecare apel catre API. Tokenul de refresh este cel valoros pe termen lung, pentru ca nu expira pana cand utilizatorul nu il revoca. Tratati tokenul de refresh ca pe o parola a integrarii.
Limitele tokenurilor OAuth si erorile access_denied si INVALID_OAUTHTOKEN
Limitele tokenurilor sunt o cauza frecventa a erorilor intermitente intr-o integrare Zoho CRM. Pagina Zoho despre valabilitatea tokenurilor OAuth in API V8 fixeaza patru praguri:
- Cel mult 10 tokenuri de grant in 10 minute pentru acelasi client ID; peste prag primiti "access_denied" pana la finalul intervalului.
- Cel mult 10 tokenuri de acces generate dintr-un token de refresh in 10 minute; peste prag primiti eroarea "Access Denied".
- Cel mult 15 tokenuri de acces active per token de refresh; al 16-lea il invalideaza pe cel mai vechi.
- Cel mult 20 de tokenuri de refresh per utilizator; al 21-lea il invalideaza pe primul creat.
Ultimele doua praguri produc erorile cel mai greu de urmarit. Daca mai multe procese cer fiecare propriul token, unul dintre ele poate invalida tokenul altuia. Apelul urmator primeste atunci exceptia "INVALID_OAUTHTOKEN". Zoho o returneaza pentru orice token de acces invalid.
Recomandarea Zoho este directa: reutilizati tokenurile valide. Un token de acces traieste o ora, deci un singur token acopera toate apelurile din acel interval. Aceeasi logica se aplica tokenurilor de refresh. Generati unul pentru fiecare integrare si pastrati-l, in loc sa refaceti autorizarea la fiecare implementare.
Scope-urile OAuth: cum le alegeti si ce inseamna OAUTH_SCOPE_MISMATCH
Scope-ul este lista operatiilor pe care un token de acces le poate face. Tokenul nu poate fi folosit pentru nimic in afara acestei liste. ZoomInfo descrie tokenurile de acces ca fiind legate de permisiunile API definite la inregistrarea aplicatiei.
Fiecare familie de endpoint-uri are scope-ul ei. De exemplu, Users API are patru operatii: citire, adaugare, actualizare si stergere de utilizatori. Ea cere scope-ul ZohoCRM.users.all sau ZohoCRM.users.{operation_type}. Varianta cu tipul operatiei permite un acces mai ingust decat varianta .all.
Eroarea OAUTH_SCOPE_MISMATCH, cu mesajul "invalid oauth scope to access this URL", arata ca tokenul nu acopera adresa apelata. Un caz din forumul Zoho arata cat de greu se diagnosticheaza. Un administrator cu abonament Zoho One cerea prin API-ul v4 tipurile de utilizatori ale unui portal.
Tokenul acelui administrator continea ZohoCRM.settings.ALL, ZohoCRM.modules.ALL, ZohoCRM.settings.clientportal.ALL si ZohoCRM.org.ALL. Totusi, fiecare raspuns intorcea aceeasi eroare, atat din functia Deluge, cat si din curl. Autorul spunea ca incercase toate scope-urile din documentatia v4.
Concluzia practica este urmatoarea. Cand apare eroarea, comparati scope-ul din raspunsul de token cu pagina de documentatie a endpoint-ului, pentru versiunea exacta de API apelata. Scope-urile largi de tip .ALL nu garanteaza accesul la orice adresa. In plus, un scope prea larg expune mai multe date daca tokenul se scurge.
Exemplu lucrat: o integrare pe server care reinnoieste tokenul de acces
Exemplul de mai jos descrie o aplicatie de pe serverul dumneavoastra care scrie lead-uri in Zoho CRM. Pasii folosesc numele si parametrii din documentatia Zoho si din cazul publicat in forumul Zoho.
- Inregistrati clientul in consola API Zoho si notati client ID si client secret.
- Generati tokenul de grant doar cu scope-urile necesare, de exemplu ZohoCRM.modules.ALL pentru inregistrari.
- Schimbati tokenul de grant in cel mult trei minute, daca ati pastrat valabilitatea implicita; la self-client puteti alege din lista o durata mai lunga.
- Salvati tokenul de refresh primit numai pe server, criptat.
- Cereti tokenul de acces cu grant_type=refresh_token si parametrii refresh_token, client_id si client_secret; in cazul din forum, adresa era
https://accounts.zoho.com/oauth/v2/token. - Pastrati tokenul primit impreuna cu valoarea expires_in, care in raspuns era 3600 de secunde.
- Trimiteti fiecare apel cu antetul
Authorization: Zoho-oauthtokenurmat de token. - Cereti un token nou doar cand cel curent expira sau cand primiti INVALID_OAUTHTOKEN.
Zoho cere explicit sa nu expuneti tokenul de acces pe forumuri publice sau in depozite de cod publice. Tokenul nu are loc nici in codul din browser, cum ar fi HTML sau JavaScript. Pentru teste fara risc, Developer Edition este o instanta Zoho CRM gratuita, separata de datele de productie.
La Svennis, in integrarile pe care le construim, tinem tokenul de acces intr-un singur loc pe server, iar toate procesele il citesc de acolo pana expira. Asa evitam erorile Access Denied si invalidarile reciproce de tokenuri intre procese.
Limitele de apeluri API Zoho CRM: credite zilnice si concurenta pe organizatie
Limitele de apeluri din Zoho CRM nu sunt calculate pe minut sau pe secunda. Potrivit analizei ZoomInfo despre API-ul Zoho CRM, ele se bazeaza pe doua masuri. Prima este numarul de cereri simultane. A doua este un bazin zilnic de credite, calculat glisant.
Accesul la API este inclus in toate planurile, inclusiv Free Edition, fara un modul separat. Planul gratuit are 5.000 de credite pe zi, pentru 3 utilizatori. Planurile platite pornesc de la 50.000 de credite de baza. La Standard se adauga 250 de credite pe utilizator, iar la Professional 500, cu plafon de 3.000.000.
Concurenta este numarul de apeluri care ruleaza in acelasi timp. Plafonul ei variaza intre 5 si 25, in functie de editie. Operatiile grele au un plafon separat de 10 pe toate editiile. Aici intra COQL, Convert Lead, Send Mail si insert, update sau upsert in masa cu peste 10 inregistrari.
Doua detalii schimba planificarea. Plafonul de concurenta este pe organizatie, nu pe cheie, deci trei integrari pe acelasi CRM impart acelasi plafon. Functiile Deluge, limbajul de scripting Zoho din automatizarile CRM, consuma si ele din acelasi bazin de credite.
Consumul si creditele ramase se vad in Zoho CRM la Settings > Developer Hub > APIs & SDKs. Verificati acest ecran inainte de a porni o integrare noua si dupa prima zi de functionare.
Alegerea tipului de apel dupa volumul de date: insert, Composite, COQL si Bulk
Tipul de apel ales decide cate credite si cate sloturi de concurenta consuma o integrare. Cifrele din tabel vin din analiza ZoomInfo si din ghidul Knit despre endpoint-urile API Zoho CRM.
| Apel | Volum per apel | Cand il folositi |
|---|---|---|
| Insert records | Pana la 100 de inregistrari | Scrieri curente, de exemplu lead-uri noi |
| Composite API | Pana la 5 sub-cereri, cu rollback optional | Operatii legate care trebuie sa reuseasca impreuna |
| COQL | Pana la 2.000 de inregistrari | Citiri filtrate, cu join-uri si functii de agregare |
| Search Records | Pana la 2.000 de inregistrari | Cautari dupa criterii |
| Mass Convert Lead | Pana la 50 de lead-uri | Conversii in lot |
| Bulk Read | Pana la 200.000 de inregistrari pe job, CSV sau ICS | Exporturi mari |
| Bulk Write | Fisier ZIP de cel mult 25 MB; initializarea costa 500 de credite | Importuri mari, nu scrieri mici |
Un singur apel de insert pentru 100 de inregistrari inlocuieste 100 de apeluri separate. Bulk Write merita doar cand volumul justifica cele 500 de credite de initializare. COQL si scrierile in masa intra sub plafonul separat de 10 cereri simultane.
Notificari in loc de interogari repetate
Notification API trimite cereri POST catre o adresa de callback la crearea, actualizarea sau stergerea unei inregistrari. Abonamentele au obligatoriu o data de expirare, deci integrarea trebuie sa le reinnoiasca. Documentatia nu descrie reincercari sau garantii de livrare. Pentru cod, Zoho publica cinci SDK-uri oficiale de server: Java, Python, Node.js, PHP si C#.
Ce inseamna limitele API pentru o companie din Romania cu ANAF, SmartBill si curs BNR
O companie din Romania leaga de obicei Zoho CRM de mai multe servicii locale in acelasi timp. Combinatiile frecvente sunt verificarea CUI la ANAF direct din Zoho CRM si facturarea prin SmartBill conectata la CRM, inclusiv pentru e-Factura. La acestea se adauga preluarea cursului BNR. Fiecare este o integrare separata, dar toate consuma din aceleasi credite zilnice si din acelasi plafon de concurenta.
Planificarea practica porneste de la ritmul real al fiecarui proces:
- Cursul valutar se preia printr-o functie programata si se scrie grupat, nu se cere la fiecare oferta.
- Verificarea CUI ruleaza la crearea sau editarea unei companii, nu ca reverificare in masa in timpul programului.
- Sincronizarea facturilor foloseste apeluri grupate, cu pana la 100 de inregistrari per insert.
- Importurile mari ruleaza in afara orelor de lucru, cand utilizatorii nu ocupa plafonul de concurenta.
Datele clientilor cer o atentie separata. Fiecare integrare ar trebui sa aiba propriul client OAuth, cu scope minim, ca sa poata fi revocata independent. Pentru companiile atente la GDPR, accesul limitat si revocarea rapida simplifica raspunsul la intrebarea cine poate citi ce date.
Pasii urmatori pentru o integrare Zoho CRM stabila
Inainte de a scrie cod, faceti un inventar al tuturor integrarilor care vor folosi acelasi CRM. Apoi parcurgeti lista de mai jos, in ordine:
- Notati pentru fiecare integrare endpoint-urile, scope-ul minim si volumul zilnic estimat de apeluri.
- Verificati la Settings > Developer Hub > APIs & SDKs cate credite are editia dumneavoastra si cat consuma deja functiile Deluge.
- Testati fluxul OAuth si scrierile in Developer Edition, nu pe datele de productie.
- Implementati un singur depozit de tokenuri pe server, cu reinnoire doar la expirare sau la INVALID_OAUTHTOKEN.
- Grupati scrierile si mutati importurile mari pe Bulk Write sau in afara programului.
Unele integrari de care aveti nevoie pot exista deja, de exemplu pentru ANAF, SmartBill sau magazinul online WooCommerce. Verificati intai lista de integrari Zoho CRM disponibile in Romania. Pentru contextul general al platformei, pagina despre implementarea Zoho CRM in Romania descrie ce acopera sistemul.
Surse
- OAuth 2.0 Authentication, Zoho CRM API V8
- Token Validity, OAuth 2.0, Zoho CRM API V8
- Zoho CRM API: Features, Limits (ZoomInfo)
- Zoho CRM API Directory: Endpoints, Auth and Limits (Knit)
- Setting up the API key (Zoho Community)
- CRM API V4 Oauth Issue (Zoho Community)
- Kaizen #51, Handling Users with ZohoCRM API
- Inquiry Regarding Monitoring Zoho CRM API Credit Usage
- CRM API Version 1 vs. Version 2 (Zoho Community)
