# API pentru Analize și Rapoarte Aceste endpoint-uri de tip read-only vă permit să extrageți activitatea contului dvs. în propriile tablouri de bord și rapoarte: numărul de evenimente de mesagerie, consumul de credite, cheltuielile AI și aceleași diagrame și perspective pe care le afișează tabloul de bord din aplicație. Acest ghid acoperă: - **Rezumat** — contoare de volum de mesaje (trimise, livrate, citite, răspunsuri, rezervări, contacte create, credite). - **Credite** — un registru detaliat, paginat, al utilizării creditelor, cu totaluri și defalcări. - **Cost AI** — un total zilnic al cheltuielilor AI. - **Serie de metrici** — o serie temporală pregătită pentru diagrame pentru una sau mai multe metrici, grupate pe campanie, canal, Agent AI sau număr. - **Rezultatele conversațiilor** — modul în care s-au încheiat conversațiile, după eticheta de rezultat atribuită de AI. - **Perspectivele tabloului de bord** și **Perspectivele AI ale tabloului de bord** — datele complete din spatele tabloului de bord din aplicație, inclusiv rezumatele scrise de AI. - **Activitatea entității** — cronologia unui singur contact, oportunități sau sarcini. - **Numărul agregat de evenimente** — o formă legacy, camelCase, a Rezumatului, păstrată pentru integrările existente. Fiecare endpoint de pe această pagină necesită un domeniu exact, nu ambele: transmiteți cel mult unul dintre `campaign_id` (legacy) sau `agent_id` acolo unde endpoint-ul îl acceptă. Trimiterea ambelor returnează `400`, iar un id care nu se află în contul dvs. returnează `404` în loc de `403`, astfel încât id-urile altor conturi să rămână imposibil de ghicit. Toate căile de mai jos sunt relative la URL-ul de bază al API-ului: ``` https://api.youraiconnector.com/v1 ``` Fiecare cerere trebuie autentificată. Consultați [Autentificare](authentication.md) pentru cele patru metode acceptate. Exemplele de aici utilizează antetul `X-API-Key` (și o formă de parametru de interogare pentru cURL). --- ## Interval de date Toate cele trei endpoint-uri acceptă aceleași filtre opționale de dată: | Parametru | Descriere | |---|---| | `from` | Începutul intervalului, `YYYY-MM-DD`, inclusiv. Implicit este acum 30 de zile. | | `to` | Sfârșitul intervalului, `YYYY-MM-DD`, inclusiv. Implicit este ziua de azi. | Datele sunt interpretate în UTC. Intervalul implicit este de **ultimele 30 de zile** și este limitat la **366 de zile** — un interval mai mare va returna `400`. `from` nu trebuie să fie după `to`. ### Indicatorul `truncated` Endpoint-urile **Rezumat** și **Credite** limitează numărul de înregistrări pe care o singură cerere le scanează. Dacă intervalul dvs. este suficient de încărcat pentru a atinge acea limită, răspunsul include `"truncated": true`. Când îl vedeți, cifrele se bazează pe o scanare parțială — restrângeți intervalul de date (sau navigați prin pagini cu o fereastră mai mică) pentru a obține cifre complete. ::: note **Notă:** Cifrele privind costurile și tokenurile sunt incluse doar pentru apelurile AI facturate prin propriile chei API ale furnizorului. Atunci când cifrele de cost sunt ascunse pentru contul dvs., răspunsul setează `"costs_redacted": true`, iar câmpurile de cost sunt returnate ca zero. ::: --- ## Rezumat volum mesaje Returnează contoare agregate pentru evenimentele de mesagerie din contul dvs., atât ca totaluri pe interval, cât și ca serie zilnică. Fiecare zi din interval apare în `by_date` — zilele fără activitate sunt completate cu zero. Filtrați opțional pentru o singură campanie cu `campaign_id`. `GET /analytics/summary` | Parametru | Obligatoriu | Descriere | |---|---|---| | `from` | Nu | Începutul intervalului, `YYYY-MM-DD`. | | `to` | Nu | Sfârșitul intervalului, `YYYY-MM-DD`. | | `campaign_id` | Nu | Numără doar evenimentele care aparțin acestei campanii. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/summary", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Răspuns** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "total": 1240, "sent": 800, "delivered": 760, "read": 540, "replied": 210, "booked": 35, "contact_created": 120, "credits_spent": 412.5, "credits_recharged": 500 }, "by_date": [ { "date": "2026-05-01", "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contact_created": 4, "credits_spent": 13.5, "credits_recharged": 0 } ], "truncated": false } ``` Fiecare intrare din `by_date` are aceleași câmpuri de contorizare ca `totals`, plus un `date`. Dacă transmiți un `campaign_id` care nu aparține contului tău, răspunsul va fi `404` cu `{ "success": false, "error": "Campaign not found" }`. --- ## Utilizarea creditelor Returnează utilizarea creditelor pe intervalul specificat: o listă paginată de înregistrări individuale, plus totalurile pe interval și defalcări pe motiv și pe campanie. `GET /analytics/credits` | Parametru | Obligatoriu | Descriere | |---|---|---| | `from` | Nu | Începutul intervalului, `YYYY-MM-DD`. | | `to` | Nu | Sfârșitul intervalului, `YYYY-MM-DD`. | | `campaign_id` | Nu | Include doar utilizarea atribuită acestei campanii. | | `limit` | Nu | Dimensiunea paginii pentru `records`, 1–100. Valoarea implicită este 50. | | `cursor` | Nu | Transmite `next_cursor` din pagina anterioară pentru a prelua pagina următoare. | > **Ajustări vs. consum:** Modificările de sold, cum ar fi bonusurile, reînnoirile de plan și corecțiile, sunt **excluse** din `totals` și din defalcări — acestea nu reprezintă un consum real. Ele apar în continuare în lista `records`, marcate cu `"is_adjustment": true`. **Totalurile și defalcările apar doar pe prima pagină** (când nu este furnizat niciun `cursor`). Pe paginile ulterioare, `totals`, `by_reason`, `by_reason_cost` și `by_campaign` sunt returnate ca `null` — doar matricea `records` continuă. Acest lucru evită scanarea întregului interval pentru fiecare pagină. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31", limit: "50", }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // To page: pass data.next_cursor as ?cursor on the next request, until it is null. ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/credits", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50}, ) data = res.json() # To page: pass data["next_cursor"] as cursor on the next request, until it is None. ``` **Răspuns** (prima pagină) ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "credits_used": 412.5, "cost_usd": 1.284512, "records": 318 }, "by_reason": { "AI Message": 380.0, "Campaign Message": 32.5 }, "by_reason_cost": { "AI Message": 1.284512, "Campaign Message": 0 }, "by_campaign": { "Spring Promo": 250.0, "Reactivation": 162.5 }, "records": [ { "id": "rec_abc123", "amount": 1, "timestamp": "2026-05-31T14:02:11.000Z", "reason": "AI Message", "is_adjustment": false, "campaign_id": "campaign123", "campaign_name": "Spring Promo", "contact_id": "contact456", "contact_name": "Jane Smith", "credit_type": "ai", "custom_keys_used": false, "description": null, "cost_usd": 0, "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_creation_tokens": 0, "ai_model": null, "request_id": null, "is_test": false } ], "next_cursor": "rec_abc123", "costs_redacted": false, "truncated": false } ``` **Note de teren:** - `amount` — credite taxate pentru înregistrare. Zero pentru înregistrările facturate către propria cheie API de furnizor. - `is_adjustment` — `true` pentru modificările de sold (excluse din totaluri/defalcări). - `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `ai_model`, `request_id` — completate doar pentru înregistrările facturate către propria cheie API de furnizor; zero sau `null` în caz contrar. - `is_test` — `true` pentru rulările de test/playground, care nu sunt niciodată facturate. - `next_cursor` — cursorul pentru pagina următoare sau `null` când nu mai există înregistrări. --- ## Centralizator costuri AI Returnează centralizatorul cheltuielilor AI pe zi pentru contul tău. Această funcție citește totalurile zilnice pre-agregate, deci este rapidă chiar și pe intervale lungi. Fiecare zi din interval apare în `days` — zilele fără activitate sunt completate cu zero. `GET /analytics/ai-cost` | Parametru | Obligatoriu | Descriere | |---|---|---| | `from` | Nu | Începutul intervalului, `YYYY-MM-DD`. | | `to` | Nu | Sfârșitul intervalului, `YYYY-MM-DD`. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/ai-cost", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Răspuns** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "total_usd": 12.4821, "byok_usd": 12.4821, "platform_usd": 0, "calls": 4210 }, "days": [ { "date": "2026-05-01", "total_usd": 0.4012, "byok_usd": 0.4012, "platform_usd": 0, "input_usd": 0.18, "output_usd": 0.19, "cache_creation_usd": 0.02, "cache_read_usd": 0.0112, "calls": 140, "by_provider": { "anthropic": 0.4012 } } ], "costs_redacted": false } ``` **Note de teren:** - `byok_usd` — cheltuieli facturate către propriile chei API ale furnizorului tău. - `platform_usd` — partea din cheltuieli care a fost rulată pe platformă în loc de propria cheie. - `input_usd`, `output_usd`, `cache_creation_usd`, `cache_read_usd` — componentele de cost care alcătuiesc `total_usd`. - `by_provider` — cheltuieli în USD grupate după numele furnizorului AI. - Cifrele în USD sunt returnate doar conturilor care își folosesc propria cheie de furnizor. Pentru conturile care plătesc prin credite, fiecare câmp USD este zero, iar `costs_redacted` este `true` (numărul de apeluri rămâne vizibil). --- ## Serie de metrici Returnează una sau mai multe serii temporale de metrici într-un singur apel, grupate opțional pe până la două dimensiuni — endpoint-ul pentru a lega o diagramă. O singură cerere poate răspunde la „trimise și răspunsuri pe zi, pe canal, pentru această campanie” fără a face un apel per campanie. `GET /analytics/series` Fiecare răspuns conține o matrice `labels` (axa timpului, completată cu zero pe tot intervalul) și o intrare în `series` per grup, fiecare conținând o matrice per metrică solicitată aliniată la `labels`. Seriile de după `limit` nu sunt eliminate — ele se comprimă în `other_bucket`, calculat ca totalul intervalului minus seria returnată, astfel încât o diagramă redată să însumeze întotdeauna cifrele dvs. reale; `truncated` este `true` ori de câte ori se întâmplă acest lucru. De unde provin cifrele: `sent`, `delivered`, `read` și `replied` provin din înregistrările mesajelor, care conțin canalul și numărul de trimitere. `booked`, `contact_created` și `credits_spent` provin din fluxul de evenimente, care nu conține niciun număr de trimitere, deci acele metrici ajung în bucket-ul `null`-number atunci când grupați după `number`. | Parametru | Obligatoriu | Descriere | |---|---|---| | `from` | Nu | Începutul intervalului, `YYYY-MM-DD`. Implicit: acum 30 de zile. | | `to` | Nu | Sfârșitul intervalului, `YYYY-MM-DD`. Implicit: astăzi. | | `metrics` | Nu | Listă separată prin virgulă din `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. Implicit: `sent,replied`. O metrică necunoscută returnează `400`. | | `group_by` | Nu | Listă separată prin virgulă de până la două dimensiuni din `date`, `campaign`, `channel`, `agent`, `number`. `date` este acceptat, dar nu are niciun efect — fiecare răspuns conține deja axa timpului. Omiteți pentru o singură serie la nivel de cont. | | `granularity` | Nu | `day` (implicit), `week` sau `month`. Bucket-urile săptămânale încep luni, cele lunare pe data de 1. | | `limit` | Nu | Câte serii să returneze înainte ca restul să se comprime în `other_bucket`, 1–50. Implicit: 12. | | `campaign_id` | Nu | Numărați doar activitatea aparținând acestei campanii. Legacy; preferați `agent_id`. | | `agent_id` | Nu | Numărați doar activitatea aparținând acestui Agent AI. | | `channel` | Nu | Numărați doar activitatea pe acest canal, de exemplu `whatsapp`. | Intervalul de date al acestui endpoint este limitat la **92 de zile** (mai strict decât limita de 366 de zile utilizată în altă parte pe această pagină). **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31", metrics: "sent,replied,booked", group_by: "campaign,channel", limit: "10", }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/series", headers={"X-API-Key": "YOUR_API_KEY"}, params={ "from": "2026-05-01", "to": "2026-05-31", "metrics": "sent,replied,booked", "group_by": "campaign,channel", "limit": 10, }, ) data = res.json() ``` **Răspuns** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "granularity": "day", "labels": ["2026-05-01", "2026-05-02"], "group_by": ["campaign", "channel"], "metrics": ["sent", "replied", "booked"], "series": [ { "key": { "campaign_id": "campaign123", "campaign_name": "Spring Promo", "channel": "whatsapp" }, "total": 812, "metrics": { "sent": [40, 35], "replied": [12, 9], "booked": [2, 1] } } ], "other_bucket": { "series_count": 6, "total": 340, "metrics": { "sent": [18, 20], "replied": [5, 6], "booked": [0, 1] } }, "truncated": true } ``` **Note de teren:** - `key` — identitatea unei serii. Sunt prezente doar cheile pentru dimensiunile `group_by` solicitate; o dimensiune a cărei valoare este necunoscută pentru un rând (un mesaj fără campanie, un eveniment fără canal) revine ca `null` în loc să fie eliminată, astfel încât seriile să însumeze în continuare totalurile. - `other_bucket` — `null` când nimic nu a fost comprimat. - Acest endpoint returnează `503` cu `"error_code": "analytics_unavailable"` atunci când baza de date de raportare nu poate oferi un răspuns pentru contul dvs., în loc de un `200` plin de zerouri — o diagramă cu zerouri ar fi interpretată ca fapt. --- ## Rezultatele conversațiilor Returnează modul în care s-au încheiat conversațiile pe un interval de date: un număr zilnic pentru fiecare etichetă de rezultat atribuită de AI, plus totalurile pe interval pentru răspunsuri, rezervări, transferuri către un operator uman și conversații pe care AI-ul nu le-a clasificat niciodată. `GET /analytics/outcomes` Transmiteți `group_by=tag` pentru a comprima axa timpului și a obține doar totalurile pe interval per etichetă — în acel mod `labels` este gol și matricea `counts` a fiecărei etichete este goală, în timp ce `total` este încă populat. | Parametru | Obligatoriu | Descriere | |---|---|---| | `from` | Nu | Începutul intervalului, `YYYY-MM-DD`. Implicit: acum 30 de zile. | | `to` | Nu | Sfârșitul intervalului, `YYYY-MM-DD`. Implicit: astăzi. | | `campaign_id` | Nu | Numără doar conversațiile cu contactele aflate în prezent în această campanie. Depășit; preferați `agent_id`. | | `agent_id` | Nu | Numără doar rezultatele care aparțin acestui Agent AI. | | `group_by` | Nu | `date` (implicit) păstrează numărătorile pe zi; `tag` restrânge la totalurile pe interval. | Intervalul de date al acestui endpoint este limitat la **92 de zile**. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/outcomes", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Răspuns** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "group_by": "date", "labels": ["2026-05-01", "2026-05-02"], "by_tag": [ { "tag": "interested", "total": 84, "counts": [3, 5] }, { "tag": "not_interested", "total": 40, "counts": [1, 2] }, { "tag": null, "total": 12, "counts": [0, 1] } ], "totals": { "sessions": 260, "replied": 210, "booked": 35, "human_alerted": 18, "unresolved": 12 } } ``` **Note de teren:** - `by_tag[].tag` — `null` pentru conversațiile cărora AI-ul nu le-a atribuit niciodată o etichetă de rezultat. - `totals.human_alerted` — conversații transferate către un operator uman; acest lucru este înregistrat la fiecare transfer și nu a fost afișat anterior de niciun endpoint. - Aceeași postură `503`/`analytics_unavailable` ca seria Metric atunci când baza de date de raportare nu poate oferi un răspuns. --- ## Informații din tablou de bord Returnează întregul payload al tabloului de bord pentru un interval de date într-un singur apel: o hartă termică a ratei de răspuns pe zi a săptămânii și oră, clasamentul campaniilor, volumul pe canal, totaluri exacte pe conexiune, defalcări ale metricilor pe zi (la nivel de cont, pe canal și pe număr), proveniența contactelor, timpul de răspuns în inbox și un flux de activitate recentă. Acesta este cel mai bogat payload de raportare din API — alimentează direct tabloul de bord din aplicație. `GET /analytics/dashboard-insights` | Parametru | Obligatoriu | Descriere | |---|---|---| | `startDate` | Da | Începutul intervalului, `YYYY-MM-DD`. | | `endDate` | Da | Sfârșitul intervalului, `YYYY-MM-DD`. | | `campaignId` | Nu | Include doar activitatea care aparține acestei campanii (se acceptă și `campaign_id`). Depășit; preferați `agent_id`. | | `agent_id` | Nu | Include doar activitatea care aparține acestui Agent AI (se acceptă și `agentId`). În cadrul domeniului de aplicare al unui agent, clasamentul campaniilor este construit doar din activitatea acelui agent. | Acest endpoint utilizează `startDate`/`endDate` (nu `from`/`to`) deoarece își împarte implementarea cu tabloul de bord din aplicație. Intervalul este limitat la 92 de zile și este **ajustat, nu respins**, atunci când este mai mare. > **Null înseamnă indisponibil, nu zero.** Mai multe blocuri (`numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`) sunt calculate din baza de date de raportare și returnează `null` atunci când aceasta nu poate oferi un răspuns pentru contul dumneavoastră. Nu redați un bloc `null` ca pe un grafic gol. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/dashboard-insights", headers={"X-API-Key": "YOUR_API_KEY"}, params={"startDate": "2026-05-01", "endDate": "2026-05-31"}, ) data = res.json() ``` **Răspuns** (prescurtat — acest payload este mare; consultați [Referința API](reference.md) pentru schema completă) ```json { "success": true, "data": { "heatmap": { "buckets": [ { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 } ] }, "topCampaigns": [ { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 } ], "channelVolume": [ { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" } ], "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 }, "activityFeed": [ { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" } ], "numberStats": null, "channelDailySeries": null, "metricDailyBreakdown": null, "contactsByCountry": null, "ai_human_split": null } } ``` **Note de teren:** - `heatmap.buckets[].weekday` — `0` este duminică până la `6` care este sâmbătă. - `numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`, `ai_human_split` — fiecare este în mod independent `null` atunci când baza de date de raportare este indisponibilă pentru contul dumneavoastră; toate celelalte blocuri returnează în continuare date. --- ## Informații AI din tablou de bord Returnează trei scurte informații scrise de AI despre mesajele contului pe un interval de date: un succes, un aspect de urmărit și un sfat — propoziții pe care le puteți insera direct într-un raport, în loc de cifre pe care trebuie să le interpretați. Generate exclusiv din metricile de mesagerie ale contului. `GET /analytics/dashboard-ai-insights` | Parametru | Obligatoriu | Descriere | |---|---|---| | `startDate` | Da | Începutul intervalului, `YYYY-MM-DD`. | | `endDate` | Da | Sfârșitul intervalului, `YYYY-MM-DD`. | Acest endpoint este la nivel de cont — nu necesită un domeniu de campanie sau agent. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights", headers={"X-API-Key": "YOUR_API_KEY"}, params={"startDate": "2026-05-01", "endDate": "2026-05-31"}, ) data = res.json() ``` **Răspuns** ```json { "success": true, "data": { "insights": [ { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." }, { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." }, { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." } ] } } ``` Lipsa `startDate` sau `endDate` returnează `400`. --- ## Cronologia activității entității Returnează activitatea unui singur contact, unei tranzacții sau a unei sarcini sub forma unei cronologii, cu cele mai recente elemente primele: ce s-a întâmplat și când, incluzând mesaje, programări, notițe și schimbări de stare. Folosiți-l pentru a răspunde la întrebarea „ce s-a întâmplat cu această persoană” fără a combina mai multe endpoint-uri de listare. `GET /analytics/entity-activity` | Parametru | Obligatoriu | Descriere | |---|---|---| | `entityType` | Da | `contact`, `deal` sau `task`. | | `entityId` | Da | ID-ul înregistrării a cărei cronologie trebuie returnată. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/entity-activity", headers={"X-API-Key": "YOUR_API_KEY"}, params={"entityType": "contact", "entityId": "contact456"}, ) data = res.json() ``` **Răspuns** ```json { "success": true, "data": { "items": [ { "id": "evt_9", "kind": "appointment_booked", "at": "2026-05-31T14:02:11.000Z", "label": "Booked an appointment for June 3", "detail": "Consultation call, 30 minutes" }, { "id": "evt_8", "kind": "message_replied", "at": "2026-05-31T13:58:02.000Z", "label": "Replied: \"Yes, that time works\"" } ] } } ``` Un `entityType`/`entityId` lipsă sau invalid returnează `400`. O entitate care nu există în contul dumneavoastră returnează `404`, astfel încât ID-urile altor conturi rămân imposibil de ghicit. --- ## Număr total de evenimente agregate (legacy) Returnează aceleași numărători agregate de evenimente ca [Rezumatul volumului de mesaje](#message-volume-summary), dar în formatul camelCase (`contactCreated` în loc de `contact_created`, `byDate` în loc de `by_date`) pe care au fost construite unele integrări mai vechi. Preferați `/analytics/summary` pentru integrări noi — acest endpoint există doar pentru ca tabloul de bord din aplicație și API-ul să partajeze aceeași implementare. `GET /analytics/aggregate` | Parametru | Obligatoriu | Descriere | |---|---|---| | `startDate` | Nu | Începutul intervalului, dată sau dată-timp ISO. Implicit este aceeași fereastră pe care o folosește `/analytics/summary`. | | `endDate` | Nu | Sfârșitul intervalului, dată sau dată-timp ISO. | | `campaignId` | Nu | Numără doar evenimentele care aparțin acestei campanii (este acceptat și `campaign_id`). Legacy; preferați `agent_id`. | | `agent_id` | Nu | Numără doar evenimentele care aparțin acestui Agent AI (este acceptat și `agentId`). | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **Răspuns** ```json { "success": true, "data": { "from": "2026-05-01", "to": "2026-05-31", "total": 1240, "byAnalyticType": { "total": 1240, "sent": 800, "delivered": 760, "read": 540, "replied": 210, "booked": 35, "contactCreated": 120, "creditsSpent": 412.5, "creditsRecharged": 500 }, "byDate": [ { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } } ] } } ``` --- ## Rollup pentru sub-conturi de agenție --- ## Erori API Analytics Endpoint-urile Analytics returnează plicul de eroare standard: ```json { "success": false, "error": "Date range too large. Maximum is 366 days." } ``` Pe un endpoint de analiză, un format de dată invalid sau o fereastră în afara intervalului returnează `400`, iar un `campaign_id` sau `agent_id` necunoscut returnează `404`. Trimiterea ambelor `campaign_id` și `agent_id` pe un endpoint care acceptă oricare dintre ele este, de asemenea, o eroare `400` — transmiteți cel mult unul. Endpoint-urile de raportare doar pentru PG (Serii de metrici, Rezultate conversații, Rollup agenție) returnează `503` cu `"error_code": "analytics_unavailable"` în loc de un `200` plin de zerouri atunci când baza de date de raportare nu poate oferi un răspuns pentru contul dumneavoastră — reîncercați în scurt timp. Codurile partajate pe care le poate returna orice endpoint — `401`, `403` (planul dumneavoastră nu include acces API sau, în cazul rollup-ului de agenție, contul dumneavoastră nu este de tip Agenție/Dev), `429` (limită de rată) și `500` — sunt listate cu instrucțiuni de reîncercare în [Erori și Paginare](errors-and-pagination.md). --- ## Pașii următori - [Autentificare](authentication.md) — cele patru modalități de autentificare a unei cereri. - [Erori și limite de rată](errors-and-pagination.md) — coduri de stare și limita de 300 cereri/min. - [API Campanii](campaigns.md) — campaniile după care pot fi filtrate aceste cifre.