API ir MCP nustatymai bei dokumentacija

API ir MCP leidžia saugiai prijungti kitas sistemas bei dirbtinio intelekto įrankius prie jūsų „Hanna“ paskyros. Ši sritis skirta administratoriams ir darbuotojams, kuriems suteikta API bei MCP prieiga.

Kaip atidaryti API ir MCP nustatymus

Atidarykite Sistemos nustatymai.
Kairiajame meniu pasirinkite API ir MCP.
Atsidariusiame puslapyje matysite aktyvius raktus ir prijungimus, jų naudotojus, teises, būseną, galiojimo laiką bei paskutinį naudojimą.

Jeigu skilties nematote, kreipkitės į administratorių. Darbuotojo kortelėje jam turi būti suteikta API ir MCP prieiga. Prieiga prie šios skilties nepakeičia darbuotojo rolės ir nesuteikia papildomų CRM duomenų teisių.

Kur rasti API dokumentaciją

Puslapio viršuje paspauskite API Dokumentacija. Atsidarys jūsų paskyrai pritaikytas API v4 aprašas. Jame galite:

pasirinkti CRM modulį;
peržiūrėti galimas paieškos, gavimo, kūrimo, redagavimo ir trynimo operacijas;
patikrinti užklausų parametrus ir laukų formatus;
pamatyti atsakymų schemas ir pavyzdžius;
atsisiųsti OpenAPI aprašą.

Tiesioginis dokumentacijos adresas sudaromas pagal jūsų paskyrą:

https://{jūsų-paskyra}.hannacrm.app/api/docs

API v4 bazinis adresas:

https://{jūsų-paskyra}.hannacrm.app/api/v4

OpenAPI YAML aprašas:

https://{jūsų-paskyra}.hannacrm.app/api/openapi.yaml

Dokumentaciją visada atidarykite savo paskyros domene. Tuomet matysite tai paskyrai aktualius modulius, laukus ir serverio adresą.

Viešame „Hanna“ pagalbos centre taip pat galite naudoti centralizuotą „Hanna CRM API v4“ techninį žinyną. Jame patogu ieškoti endpointų, parametrų, autentifikavimo ir užklausų pavyzdžių. Šiame žinyne pateikiamas default.hannacrm.app bazinis adresas, todėl prieš vykdydami užklausą default pakeiskite savo „Hanna“ paskyros subdomenu. Jei reikia tiksliai matyti konkrečioje paskyroje įjungtus modulius ir laukus, naudokite tos paskyros /api/docs dokumentaciją.

Kur rasti MCP dokumentaciją

Tame pačiame puslapyje paspauskite MCP Dokumentacija. Joje pateikiami MCP klientams skirti įrankiai, jų paskirtis ir parametrai. Tiesioginis adresas:

https://{jūsų-paskyra}.hannacrm.app/mcp/docs

MCP dokumentacijoje aprašomi įrankiai, pavyzdžiui, įrašų paieška, vieno įrašo gavimas, kūrimas ar atnaujinimas. Tai nėra įprasti REST adresai – šiuos veiksmus kviečia MCP klientas.

MCP įrankių YAML aprašas:

https://{jūsų-paskyra}.hannacrm.app/mcp/openapi.yaml

MCP dokumentacija yra atskira nuo pagalbos centro API dokumentacijos skilties. Pastarojoje pateikiamas REST API v4 žinynas, o MCP įrankius visada tikrinkite savo paskyros /mcp/docs puslapyje.

Kuo skiriasi API ir MCP

API v4 naudoja jūsų sukurtą raktą ir tinka sistemų integracijoms, duomenų apsikeitimui bei automatizuotiems procesams.

MCP naudoja OAuth prisijungimą ir leidžia suderinamam MCP klientui matyti bei kviesti „Hanna“ įrankius pagal suteiktas teises.

Abiem atvejais galioja CRM modulių, darbuotojo, rolės ir laukų matomumo taisyklės. Jei laukas ar modulis paskyroje išjungtas, integracija jo taip pat gali nematyti.

API v4: potencialaus kliento dublikatas nebegrąžina klaidos

Kuriant potencialų klientą per API v4, atpažintas dublikatas grąžinamas kaip HTTP 200 atsakymas su duplicate: true, o ne kaip naujas įrašas. Jei esamas potencialus klientas prieinamas raktui, atsakyme pateikiamas jo record. Jei sutapęs įrašas nėra prieinamas potencialus klientas, gali būti grąžintas duplicate_of su įrašo tipu; identifikatorius pateikiamas tik turint peržiūros teisę. Tikrinkite šį požymį prieš laikydami atsakymą naujo potencialaus kliento sukūrimu.

Skambučiai API v4 ir MCP

Per API v4 dabar galima gauti skambučių istoriją (GET /api/v4/calls, GET /api/v4/calls/{uuid}) ir atsisiųsti CRM saugomus pokalbių įrašus (GET /api/v4/calls/{uuid}/recording). Pakeistus skambučius galima sinchronizuoti dalimis per updated_since. AI agentai per MCP gali skaityti skambučius, jų transkripcijas ir santraukas. Prieiga ribojama skambučių istorijos ir įrašų teisėmis.

API v4 ir MCP: užklausų susirašinėjimas, priedai ir užsakymai

Nauji skaitymo adresai GET /api/v4/ticket_replies, /api/v4/ticket_notes ir /api/v4/ticket_history (su filter[ticket] ir filter[created_since]). Taip pat GET /api/v4/tickets/{uuid}/files užklausų priedams ir GET /api/v4/supplier_orders su eilutėmis. Pirkimo kainos grąžinamos tik turint teisę „Užsakymų kainos“. Tie patys skaitymo įrankiai prieinami ir Hanna MCP.

Hanna MCP kvietimų ribojimas

Numatytosios Hanna MCP įrankių kvietimų ribos: 100 kvietimų per minutę vienam naudotojui ir 500 visai paskyrai; vienu metu – iki 5 naudotojui ir 20 paskyrai. Sistemos konfigūracijoje ribos gali būti pakeistos. Viršijus taikomą ribą grąžinamas HTTP 429 ir laukimo laikas. Prieš kartodami palaukite nurodytą laiką.

Prekių papildomi laukai API v4

Per API v4 ir MCP kuriant ar redaguojant prekę galima perduoti papildomus laukus, o papildomų laukų žinyne atsirado modulis „items“.

Projektų dalyviai API v4

API v4 papildytas projektų dalyvių (skirtukas „Dalyviai“) sąrašu ir įrašo peržiūra su filtru pagal projektą. Veikia, kai įjungtas renginių valdymas; dalyvis matomas, jei matomas jo projektas.

Užsakymų tiekėjams kūrimas ir redagavimas per API v4

API v4 ir MCP leidžia kurti ir redaguoti užsakymus tiekėjams kartu su eilutėmis ir papildomais laukais. Pakeitus būseną vykdoma tas pats kaip CRM: kuriamos užduotys iš šablonų ir, jei įjungta, pradedamas eksportas į apskaitą.