Token PAT în CloudCart: conectează Claude, ChatGPT și Gemini

Pe scurt: tokenul PAT (Personal Access Token) este cheia cu care un agent AI precum Claude Code, ChatGPT Codex sau Gemini CLI intră în magazinul tău din CloudCart. Îl creează doar proprietarul, din Setări → Tokenuri PAT. Tokenul începe cu cc_pat_, se afișează o singură dată și are unul din trei niveluri de acces: Read Only, Full Access sau Custom Permissions.

Ghidul acesta e doar despre cheie: cum o creezi, ce drepturi îi dai, când o legi de o adresă IP și cum oprești accesul. Cum instalezi agentul și ce poate face după aceea găsești în articolul despre Claude Code și magazinul online. Numele ecranelor și ale câmpurilor sunt cele din panoul de administrare CloudCart, unde formularul tokenului apare cu etichetele în engleză (Token Name, Permissions, Generate Token). Detaliile sunt luate din documentația platformei și din paginile integrare AI cu CloudCart și pentru dezvoltatori.

Ce este un token PAT în CloudCart

Tokenul PAT este cheia personală de acces a proprietarului, prin care API-ul de administrare CloudCart (Admin GraphQL API) și CloudCart CLI recunosc cine trimite cererea. Fiecare cerere făcută cu tokenul lucrează în numele proprietarului, dar numai în limitele drepturilor, termenului de valabilitate și adreselor IP pe care le-ai setat.

Tokenul are 71 de caractere: cc_pat_ urmat de 64 de caractere hexazecimale aleatorii. Platforma păstrează doar amprenta lui criptografică (hash SHA-256), de aceea valoarea o vezi o singură dată, în panoul verde „Token Created Successfully!” de după creare. Un token pierdut nu se recuperează: îl ștergi și faci altul.

Token PAT, cheie API sau token SmartBill: care e diferența

Tokenul PAT e pentru agenți AI și Admin GraphQL API, iar cheia API e pentru REST API și integrări permanente. Comercianții din România mai lucrează de obicei și cu tokenul API din SmartBill, iar vitrinele headless Nitrogen au tokenurile lor separate. Tabelul arată la ce folosește fiecare:

Cheia	Unde o creezi	La ce folosește	Drepturi
Token PAT	Setări → Tokenuri PAT	Agenți AI, CloudCart CLI, Admin GraphQL API (/api/gql)	Read Only, Full Access sau resurse alese; termen și adrese IP
Cheie API	Setări → Api keys	REST API (/api/v2) pentru integrări externe: ERP, sisteme de automatizare, scripturi	Tot magazinul, fără împărțire pe resurse; de la Starter Pack în sus, cu limită pe plan
Token API SmartBill	În contul tău SmartBill	Îl introduci în Aplicații → SmartBill, împreună cu e-mailul contului și CIF-ul, ca să se emită facturile	Doar legătura cu SmartBill; nu deschide magazinul pentru agent

Pentru un agent AI ai nevoie de un token PAT. Cheia API e pentru integrări fixe, tokenul SmartBill rămâne în aplicația de facturare (detaliile sunt în ghidul despre facturile SmartBill în CloudCart).

Cine are nevoie de un token PAT și când

Ai nevoie de un token PAT dacă vrei ca un agent AI să citească sau să modifice magazinul ori dacă folosești CloudCart CLI. Funcția nu e limitată pe plan: ecranul Tokenuri PAT e același în Baby Pack, Starter Pack, CC Pro și CC Master.

• Conectezi agentul prima dată. După ce lipești fraza din cardul de conectare cu un agent AI de pe tabloul de bord, agentul instalează singur ce îi trebuie și la final îți cere două lucruri: adresa magazinului și un token PAT.
• Vrei doar rapoarte. Un agent care îți spune dimineața vânzările, stocul și coșurile abandonate se descurcă cu un token Read Only. Un exemplu de astfel de sarcină e în articolul despre raportul de vânzări de la 8:00 cu un agent AI.
• Îi dai agentului de lucru într-o singură parte a magazinului. De exemplu doar produse și stocuri, fără comenzi și clienți: asta se face cu Custom Permissions.
• Lucrezi pe mai multe calculatoare sau cu mai mulți agenți. Un token separat pentru fiecare îți permite să oprești unul fără să-i atingi pe ceilalți.

Tokenul nu e un cont de angajat și nu intră în limita de administratori a planului. Baby Pack include 1 administrator (condițiile planurilor), iar agentul lucrează fără să ocupe un al doilea loc. Prețurile tuturor planurilor sunt pe pagina de prețuri.

Cum creezi un token PAT, pas cu pas

Tokenul PAT se creează din ecranul Setări → Tokenuri PAT (calea din admin este Settings → Account → PAT Tokens) sau din meniul profilului din stânga jos → PAT Tokens. Ai nevoie de un nume și de un nivel de acces, restul e opțional.

1. Intră ca proprietar. Doar proprietarul magazinului creează și administrează tokenurile. Un administrator sau moderator primește refuzul „Only store owners can manage CLI tokens”, iar în drepturile angajaților nu există o bifă prin care să delegi asta.
2. Deschide Tokenuri PAT. Sus vezi contorul „N of 100 tokens”: până la 100 de tokenuri pe proprietar. Dacă nu ai încă niciun token, apasă Create Your First Token, altfel Create Token.
3. Completează Token Details. Token Name e obligatoriu (până la 100 de caractere): scrie pentru cine e, de exemplu „Claude Code, laptopul de la birou”. Description e opțional (până la 500 de caractere).
4. Alege nivelul în Permissions. Ai trei carduri: Read Only (marcat „Recommended” și ales implicit), Full Access și Custom Permissions. Când se potrivește fiecare vezi în secțiunea următoare.
5. Deschide Advanced Settings dacă vrei termen sau IP. Secțiunea e restrânsă. În Token Validity dezactivezi „No expiration” și alegi data de expirare. În IP Restrictions, cu Add IP Address, adaugi până la 20 de adrese sau intervale.
6. Apasă Generate Token. Apare panoul „Token Created Successfully!” cu tokenul întreg și butonul Copy. Copiază-l imediat: după Done valoarea dispare definitiv. Un clic în afara ferestrei nu o închide, ca să nu pierzi tokenul din greșeală.
7. Dă-i tokenul agentului. Lipește-l în conversația cu agentul când ți-l cere, împreună cu adresa magazinului fără https:// (de exemplu magazinulmeu.cloudcart.net sau magazinulmeu.ro). Agentul îl folosește doar în comanda de autentificare și îl păstrează pe calculatorul tău.
8. Verifică cu o întrebare. Pe ecran nu există un buton de test. Scrie-i agentului „Câte comenzi am avut ieri?”. Dacă răspunde, coloana Last used at a tokenului arată ora cererii.

Important: tokenul funcționează de pe orice calculator, pentru oricine îl are, dacă nu ai setat adrese IP. Păstrează-l ca pe o parolă: nu-l trimite pe e-mail sau pe WhatsApp, nu-l fotografia și nu-l pune în documente partajate.

Ce drepturi îi dai tokenului PAT

Începe cu Read Only și treci la un acces mai larg când agentul trebuie să modifice ceva. Este principiul drepturilor minime (least privilege), recomandat și de NIST, și de OWASP: fiecare cheie are exact atât acces cât îi trebuie pentru sarcină.

Nivel	Ce permite	Când îl alegi
Read Only	Citește tot, nu modifică nimic. Orice modificare e refuzată.	Rapoarte, KPI, întrebări despre stoc și comenzi, primele zile cu agentul
Full Access	Citește și modifică tot în magazin	Agentul creează magazinul, scrie descrieri, schimbă prețuri și setări
Custom Permissions	Doar resursele alese, fiecare cu None, Read sau Read & Write	Agentul lucrează într-o singură parte: de exemplu produse și stocuri

În Custom Permissions sunt 8 rânduri: Products, Orders, Customers, Inventory, Discounts, Blog, Settings și Webhooks. Inventory și Discounts nu au variantă doar pentru citire: un agent care trebuie să vadă stocurile primește accesul complet la Inventory. Dacă lași toate rândurile pe None, tokenul se salvează ca Read Only. Jos ai butoanele rapide Select all as Read, Select all as Read & Write și Clear all.

Ce drepturi cere fiecare sarcină

Tabelul acoperă sarcinile pe care comercianții i le dau cel mai des agentului. Frazele sunt exemple pe care le poți lipi direct:

Sarcina	Fraza pentru agent	Drepturi minime
Raportul de dimineață și KPI	„Compară venitul de ieri cu aceeași zi de săptămâna trecută.”	Read Only
Listă nouă de prețuri de la furnizor	„Actualizează prețurile după coduri și arată-mi care lipsesc.”	Products: Read & Write
Comanda către furnizor	„Ce produse au sub 5 bucăți în stoc? Fă un tabel.”	Products: Read + Inventory
Promoție de Black Friday	„Fă o reducere de 15% la categoria Iarnă până duminică.”	Discounts + Products: Read
Articol pe blogul magazinului	„Scrie o ciornă despre îngrijirea pielii iarna.”	Blog: Read & Write
Raport pe categorii	„Arată-mi vânzările pe categorii în octombrie.”	Settings: Read (rapoartele sunt în Settings)

Mai multe fraze gata făcute găsești în promptul potrivit pentru comenzi, stoc, prețuri și SEO, iar ce cifre merită urmărite și cum le calculează agentul e explicat în cei 10 KPI ai magazinului online.

Ce drepturi cere agentul pentru e-mailuri, reclame și cifre

Pentru marketing agentul are nevoie de Settings, pentru că în Admin GraphQL API campaniile, aplicațiile, setările SEO și rapoartele magazinului stau sub această resursă. Abonații și clienții sunt sub Customers. Tokenul PAT îi deschide agentului doar magazinul din CloudCart: rezultatele din Meta Ads Manager, Google Ads, TikTok Ads Manager și Google Search Console se citesc cu un acces separat, pe care îl dai în serviciul respectiv.

Activitatea	Ce face agentul în CloudCart	Drepturi minime ale tokenului	Ce rămâne în afara tokenului
Campanie de e-mail în Marketing Suite	Scrie campania din produsele și prețurile reale, alege segmentul de abonați, pregătește șablonul	Settings: Read & Write, Customers: Read, Products: Read	Nimic: e-mailurile, SMS, Viber și web push sunt în Marketing, în magazin
Meta (Facebook și Instagram)	Verifică Pixel ID și Conversions API în Aplicații → XML Feed → Facebook, scrie texte de reclamă pentru cele mai vândute produse	Settings: Read, Products: Read, Orders: Read	Bugetele și rezultatele reclamelor din Meta Ads Manager
Google Ads și Google Shopping	Îmbunătățește titlurile și descrierile produselor care intră în feed, verifică Google Dynamic Remarketing și Google Tag Manager	Products: Read & Write, Settings: Read	Campaniile și costurile din contul Google Ads
TikTok	Verifică aplicațiile TikTok Pixel și TikTok Shop și produsele care intră în catalogul TikTok	Settings: Read, Products: Read	Campaniile și bugetele din TikTok Ads Manager
Google Search Console	Verifică validarea în Aplicații → Google Search Console, scrie titluri SEO și meta descrieri pentru produse	Products: Read & Write, Settings: Read	Interogările, clicurile și pozițiile din Search Console
Cifrele magazinului	Calculează venitul, numărul de comenzi, valoarea medie a comenzii, ponderea clienților care revin, produsele cele mai vândute și stocurile mici	Read Only	Sesiunile din GA4, dacă le vrei și de acolo

Fiecare canal are ghidul lui: campania de e-mail în CloudCart pas cu pas, reclamele Facebook pentru magazinul online, Google Ads pentru magazinul online, TikTok Shop și TikTok Ads și Google Search Console pentru magazinul online.

Important: pentru texte de reclamă și e-mailuri agentul nu are nevoie să vadă clienții pe nume. Dă-i Customers: Read doar când sarcina e un segment de abonați sau un raport despre clienții care revin. Așa ții și datele personale ale clienților departe de agent, în spiritul GDPR.

Cu restricție IP sau fără și ce termen să aibă tokenul

Pune restricție IP când agentul lucrează de la o adresă care nu se schimbă: birou, server sau CI. Dacă lucrezi de pe laptop de acasă și furnizorul de internet îți dă o adresă dinamică, lasă lista goală și pune un termen scurt.

• Lista goală înseamnă că tokenul funcționează de la orice adresă. Aceasta e valoarea implicită.
• O singură adresă se scrie ca 192.168.1.100, o rețea întreagă ca 192.168.1.0/24 (256 de adrese). Sunt acceptate IPv4, IPv6 și intervale CIDR, până la 20 pe token.
• O cerere de la altă adresă primește refuzul IP_NOT_ALLOWED, iar coloana Last used at nu se schimbă. Astfel, ea arată doar cererile reușite.

Termenul (Token Validity) este implicit „No expiration”: tokenul funcționează până îl ștergi sau îl dezactivezi. Data de expirare trebuie să fie în viitor. Pune-ți un memento în calendar pentru data expirării, ca agentul să nu se oprească pe neașteptate. O practică rezonabilă: 30 până la 90 de zile pentru tokenul de pe laptop și fără termen doar pentru un token legat de IP-ul unui server.

Cum oprești accesul agentului AI

Accesul se oprește imediat, pe toate calculatoarele, când dezactivezi sau ștergi tokenul în Tokenuri PAT. Cele două variante au urmări diferite:

Acțiunea	Unde	Ce se întâmplă	Se poate anula?
Dezactivare (Active)	Comutatorul de pe rând	Orice cerere e refuzată; tokenul rămâne în listă	Da: îl reactivezi și același token funcționează din nou
Ștergere (Delete)	Butonul de pe rând, cu confirmarea „This action cannot be undone.”	Amprenta tokenului se distruge definitiv	Nu: faci un token nou, cu altă valoare
cloudcart auth logout	Terminalul de pe calculatorul cu agentul	Șterge autentificarea doar de pe acel calculator	Da, cu o nouă autentificare

Dezactivarea e comodă pentru o pauză, de exemplu cât ești în concediu. Ștergerea e pasul corect de îndată ce bănuiești că tokenul a ajuns la altcineva. Editarea nu schimbă valoarea: pentru o cheie nouă cu aceleași drepturi ștergi tokenul vechi și creezi altul. Dacă magazinul trece la alt proprietar, tokenurile PAT ale fostului proprietar nu trec la cel nou: el își creează propriile tokenuri.

Ce câștigi cu un token PAT și un agent AI

Cu un token setat corect, o sarcină de zeci de clicuri devine o frază, iar riscul rămâne sub control. Într-un magazin de cosmetice cu 300 de produse, o listă nouă de prețuri de la furnizor înseamnă să verifici 300 de coduri și 300 de prețuri. Un agent cu token Products: Read & Write compară codurile, îți arată diferențele și schimbă prețurile cu o singură operație în masă, care rulează în fundal.

• Viteză. Admin GraphQL API acceptă 300 de cereri pe minut pe adresa magazinului, iar modificările în masă trec ca o singură sarcină în fundal în loc de sute de cereri separate.
• Control. Un token Read Only nu poate schimba nimic, chiar dacă agentul greșește cererea. Refuzul numește exact dreptul care lipsește.
• Trasabilitate. Modificările făcute prin token apar ca făcute de proprietar. Cu un token separat pentru fiecare agent și coloana Last used at vezi ce cheie a lucrat și când.

Câte ore pe săptămână economisește asta într-un magazin obișnuit am calculat în articolul despre agentul AI pentru magazinul online, iar modificările în masă sunt explicate în modificarea în masă a prețurilor și stocurilor dintr-o frază. CloudCart ia 0% comision din vânzări, așa că pentru comenzile pe care agentul te ajută să le câștigi nu plătești niciun procent platformei.

7 reguli bune pentru tokenurile PAT

1. Un token pentru un agent sau un calculator. Numele spune cine și unde („Gemini CLI, server”). Oprești unul fără să le oprești pe celelalte.
2. Read Only la început. În primele zile cere-i agentului rapoarte și stocuri. Full Access îl dai după ce ai văzut cum lucrează.
3. Cere „arată-mi întâi”. Roagă agentul să-ți arate lista de modificări și confirm-o înainte să o aplice. Așa vezi o greșeală din cerere înainte să ajungă în magazin.
4. Pornește copiile zilnice înainte de Full Access. După ce copiezi fraza de pe tabloul de bord, panoul îți propune abonamentul la copii de rezervă zilnice, când magazinul le poate avea. Cu ele readuci tot magazinul sau o parte din el la ultima copie zilnică.
5. Termen pentru laptop, IP pentru server. Tokenul de pe laptop cu 30-90 de zile, tokenul de pe server legat de adresa lui.
6. Verifică Last used at o dată pe lună. Un token nefolosit de câteva săptămâni îl ștergi. Coloana se actualizează doar la o cerere reușită.
7. Gândește-te ce citește furnizorul. Furnizorul agentului (Anthropic, OpenAI, Google) prelucrează ce citește agentul, după condițiile contului tău la el. Dacă agentul nu are nevoie de clienți, nu-i da Customers.

Greșeli de evitat și ce înseamnă refuzurile

Cea mai frecventă greșeală este închiderea ferestrei înainte de a copia tokenul: atunci singura ieșire e un token nou. A doua este Full Access „pentru orice eventualitate” pentru un agent care doar citește rapoarte. A treia este un singur token comun pentru tot, pe care apoi nu-l poți opri fără să oprești toți agenții.

Când agentul nu poate face ceva, Admin GraphQL API întoarce un cod și un mesaj. Tabelul le arată pe cele mai dese:

Mesajul	Cauza	Ce faci
„Invalid or expired token”	Token copiat greșit, dezactivat sau expirat	Reactivează tokenul sau creează unul nou și autentifică din nou agentul
„Token has been revoked”	Tokenul a fost șters în Tokenuri PAT	Creează un token nou și dă-l agentului
„… writes data, which this token's scopes do not allow.”	Read Only sau doar Read pentru resursa respectivă	Un token cu Read & Write pentru resursă
„… needs the `inventory` scope, which this token does not have.”	În Custom Permissions lipsește resursa	Adaug-o din Edit, în fișa tokenului
IP_NOT_ALLOWED	Cererea vine de la o adresă din afara listei	Adaugă adresa sau golește lista
TOO_MANY_REQUESTS (429)	Peste 300 de cereri pe minut pe magazin	Cere-i agentului o operație în masă în locul unei bucle

În Edit (clic pe numele din listă) schimbi numele, nivelul de acces, adresele IP și termenul, iar valoarea tokenului rămâne aceeași. Cele trei API-uri CloudCart și limitele REST API pe plan sunt descrise pe pagina pentru dezvoltatori, iar regulile generale pentru tokenurile personale le găsești și în documentația GitHub. Dacă te blochezi undeva, scrie-ne la support@cloudcart.com.

Întrebări frecvente