Gram CRM API

Základy

REST API Gram CRM komunikuje cez HTTPS vo formáte JSON. Adresa API je https://api.gramcrm.com/{organizacia}/api/v1/, kde {organizacia} je názov vašej organizácie, rovnaký ako v adrese aplikácie. V ďalších príkladoch uvádzame pri volaniach len časť adresy za /api/v1/ a organizáciu vasafirma.

Každá odpoveď obsahuje okrem HTTP stavového kódu aj Result (true alebo false). Pri chybe pribudne ResultText s popisom a ResultCode, podľa ktorého chybu spracujete v kóde. Prehľad je vyššie v časti Odpovede a chyby.

API pracuje s oprávneniami používateľa, ktorému patrí token. Vidí a mení len to, čo smie tento používateľ v aplikácii. Na skúšanie volaní sa okrem curl hodí napríklad Postman.

Hlavičky požiadavky

Hlavička	Význam
Authorization: Bearer <token>	Povinná pri každom volaní okrem prihlásenia, pozri Autorizácia.
Content-Type: application/json	Pri požiadavkách s telom.
Content-Language	Jazyk textov v odpovedi: en, de, sk, cz, hu. Pozri Jazyk, dátumy a časové pásmo.
X-Timezone	Časové pásmo len pre túto požiadavku, názov podľa IANA, napríklad Europe/Bratislava. Bez hlavičky platí pásmo používateľa.
X-Date-Format: iso	Dátumy a časy v odpovedi vo formáte ISO 8601 s posunom, napríklad 2026-09-14T10:00:00Z.
If-None-Match	Hodnota hlavičky ETag z predchádzajúcej odpovede. Ak sa výsledok odvtedy nezmenil, API vráti 304 Not Modified bez tela.

Autorizácia

Každá požiadavka musí mať platný token v hlavičke Authorization: Bearer <token>. Staršia hlavička Token: <token> funguje ďalej.

Na prepojenie s iným systémom použite API kľúč: trvalý token bez expirácie, ktorý vytvoríte v aplikácii v časti Nastavenia / API kľúče (návod). Kľúč patrí konkrétnemu používateľovi a má jeho oprávnenia. Pre integráciu odporúčame samostatného používateľa s vlastným profilom, aby ste presne určili, čo smie prepojený systém čítať a meniť.

curl https://api.gramcrm.com/vasafirma/api/v1/core/Me \
  -H "Authorization: Bearer VAS_TOKEN"

Prihlásenie menom a heslom

Token pre konkrétneho používateľa získate volaním Login. Heslo sa posiela ako text, spojenie je vždy šifrované.

curl -X POST https://api.gramcrm.com/vasafirma/api/v1/Login/ \
  -H "Content-Type: application/json" \
  -d '{"UserName": "jana@vasafirma.sk", "Password": "vase-heslo"}'

{
  "Result": true,
  "ResultText": "User loged in.",
  "Token": {
    "NewToken": "3e99f8dda9ad4444bed1c6f44459ae06",
    "Language": 3,
    "ValidTo": "2026-10-16 12:28:17"
  }
}

Token z prihlásenia platí 14 dní. Keď ho používate a do konca platnosti zostáva menej ako 7 dní, platnosť sa sama predĺži o ďalších 14 dní. Po vypršaní vráti API 401 s kódom ErrTokenExpired. Pri používateľovi s trvalým prihlásením token neexpiruje a ValidTo v odpovedi chýba. Nesprávne meno alebo heslo vráti 401 s kódom ErrLoginPassword.

Dvojfaktorové overenie

Ak má používateľ zapnuté dvojfaktorové overenie, Login ešte nevráti token, ale výzvu na kód:

{
  "Result": true,
  "ResultText": "MFA verification required.",
  "ResultCode": "MfaRequired",
  "Mfa": {
    "ChallengeId": "9f1c2a7b5d3e4f60a1b2c3d4e5f60718",
    "ValidTo": "2026-10-02 12:35:00",
    "Method": "TOTP"
  }
}

Do 5 minút pošlite kód z autentifikačnej aplikácie alebo jeden zo záložných kódov. Odpoveď obsahuje Token rovnako ako bežné prihlásenie.

POSTcore/MfaVerifyLogin

{
  "ChallengeId": "9f1c2a7b5d3e4f60a1b2c3d4e5f60718",
  "Code": "123456"
}

Pre integrácie je jednoduchší API kľúč: s ním sa neprihlasujete, takže dvojfaktorové overenie nerieši.

Overenie tokenu a odhlásenie

GET core/Me overí token a vráti prihláseného používateľa (User), organizáciu a entity, ku ktorým má prístup (Entities). Neplatný token vráti 401 s kódom ErrTokenNotValid.

GET core/UserLogout zruší token, s ktorým ho voláte. Používajte ho len pri tokene z prihlásenia: zavolaný s API kľúčom zruší aj kľúč.

Ping

GET Ping overí, či je API dostupné. Požiadavka musí mať hlavičku s tokenom, jeho platnosť však Ping nekontroluje. Na to slúži core/Me.

curl https://api.gramcrm.com/vasafirma/api/v1/Ping \
  -H "Authorization: Bearer VAS_TOKEN"

{"Result": true, "ResultText": "pong", "ResultCode": "OK"}

Entity a záznamy

Prehľad entít

Údaje sú v entitách: firmy, kontakty, leady, obchodné prípady, aktivity a ďalšie, vrátane vlastných entít, ktoré si vytvoríte. Každá entita má v API adresu podľa svojho interného anglického názvu v jednotnom čísle. Najčastejšie sú:

Adresa	Entita
Account/	Firmy (klienti)
Contact/	Kontakty
Lead/	Leady
Deal/	Obchodné prípady
Activity/	Aktivity
Proposal/	Cenové ponuky
Product/	Produkty
Note/	Poznámky

Ktoré entity vaša organizácia má, závisí od riešenia a nastavení. Zoznam s internými názvami vráti GET core/Me v časti Entities.

Polia entity

GET core/EntityFields/{Entita} vráti polia entity, ktoré smie používateľ vidieť: názov, popis, dátový typ, povinnosť a predvolenú hodnotu.

curl https://api.gramcrm.com/vasafirma/api/v1/core/EntityFields/Account \
  -H "Authorization: Bearer VAS_TOKEN"

{
  "Data": [
    {
      "Name": "Rating",
      "Label": "Rating",
      "SimpleDataType": "option",
      "DataType": "option(AccountRating)",
      "Required": "1",
      "ChangeTracking": "0",
      "DefaultValue": "4"
    }
  ],
  "Result": true
}

Dátový typ určuje, akú hodnotu pole očakáva. Pri lookup(Entita) je to Id záznamu inej entity, pri option(Číselník) číselná hodnota z číselníka (pozri Číselníky), pri file Id nahratého súboru.

Čítanie záznamov

Záznamy načítate na adrese entity. Parametre ako stĺpce, filtre, zoradenie a stránkovanie posielate v tele požiadavky. Mnohé nástroje pri GET telo neposielajú, preto rovnako funguje aj POST na tú istú adresu. Aj ten len číta.

curl -X POST https://api.gramcrm.com/vasafirma/api/v1/Account/ \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Select": ["Name", "City", "Owner:FullName", "Status:Label"], "Limit": 2}'

{
  "TotalResults": 19,
  "HasMore": true,
  "Data": [
    {
      "Name": "Horizont Stavby, s.r.o.",
      "City": "Nitra",
      "Owner:FullName": "Jana Malá",
      "Status:Label": "Zákazník"
    },
    {
      "Name": "Demonte s.r.o.",
      "City": "Zbehy",
      "Owner:FullName": "Juraj Lackovič",
      "Status:Label": "Potenciálny"
    }
  ],
  "Result": true
}

TotalResults je počet záznamov, ktoré spĺňajú podmienky, Data obsahuje samotné záznamy. Bez Select vráti API základné stĺpce entity a pri poliach typu lookup a option aj ich druhú úroveň, napríklad Owner:FullName alebo Status:Label.

Jeden záznam

Id záznamu uveďte v adrese. Data je aj vtedy pole, s jedným záznamom. Ak záznam neexistuje alebo ho používateľ nesmie vidieť, Data je prázdne a API vráti 200, nie chybu.

curl https://api.gramcrm.com/vasafirma/api/v1/Account/069719ba-aeca-47fc-bd92-0ff774bbc028 \
  -H "Authorization: Bearer VAS_TOKEN"

Stránkovanie

Limit obmedzí počet vrátených záznamov, Skip ich toľko na začiatku preskočí. Ak sú za vrátenými záznamami ďalšie, odpoveď má "HasMore": true.

{"Limit": 100, "Skip": 200}

Výber stĺpcov

Select určí, ktoré stĺpce sa vrátia. Stĺpec naviazaného záznamu zapíšete cez dvojbodku, napríklad Account:Name pri kontakte. Za medzeru môžete pridať alias, pod ktorým stĺpec príde. Stĺpec, ktorý neexistuje alebo naň používateľ nemá právo, API vynechá bez chyby.

{"Select": ["Name Firma", "Street", "Status:Label"]}

Zoradenie

OrderBy určí poradie. Order je asc (predvolené) alebo desc. Namiesto názvu poľa môžete uviesť poradie stĺpca v Select, prvý stĺpec je "1".

{
  "Select": ["Name", "City"],
  "OrderBy": [
    {"Field": "City"},
    {"Field": "Name", "Order": "desc"}
  ]
}

Filtrovanie

Podmienky sú v poli Where, každá má Field, Operator a Value. Bez WhereLogic musia platiť všetky naraz. WhereLogic ich spojí inak: podmienky sa číslujú od 1 a smiete použiť AND, OR a zátvorky.

Príklad: firmy z Nitry, ktoré majú v názve „stav“ alebo „build“:

{
  "Select": ["Name", "City"],
  "Where": [
    {"Field": "Name", "Operator": "c", "Value": "stav"},
    {"Field": "Name", "Operator": "c", "Value": "build"},
    {"Field": "City", "Operator": "e", "Value": "Nitra"}
  ],
  "WhereLogic": "(1 OR 2) AND 3"
}

Operátor	Význam
e (eq)	rovná sa, predvolený operátor
ne (neq)	nerovná sa
l (lt), le (lte)	menšie, menšie alebo rovné
g (gt), ge (gte)	väčšie, väčšie alebo rovné
c (like), nc (nlike)	obsahuje, neobsahuje. Pri viacerých slovách oddelených medzerou musí text obsahovať všetky.
s (startswith), ns	začína na, nezačína na
ends	končí na
in, nin	je v zozname, nie je v zozname. Hodnota je pole alebo text s hodnotami oddelenými čiarkou.
between	v intervale vrátane oboch hraníc. Hodnota je pole dvoch hraníc.
empty, nempty	prázdne, vyplnené. Hodnota sa neuvádza.

Hviezdička v hodnote zastupuje ľubovoľné znaky. "Value": null s operátorom e funguje ako empty, s ne ako nempty. Neznámy operátor sa vyhodnotí ako e. Podmienka s poľom, ktoré neexistuje alebo naň používateľ nemá právo, sa vynechá bez chyby.

Filter podľa stavu a číselníka

Pri poli typu option sa porovnáva číselná hodnota z číselníka. Operátory e a ne sa pri ňom správajú ako in a nin, takže môžete poslať viac hodnôt naraz. Namiesto konkrétnych hodnôt môžete uviesť aj skupinu stavov: Active (rozpracované), Won (úspešne ukončené) a Lost (neúspešne ukončené).

{"Where": [{"Field": "Status", "Operator": "in", "Value": "Active"}]}

Dátumy vo filtri

Namiesto pevného dátumu môžete použiť hodnoty, ktoré sa vyhodnotia pri každej požiadavke podľa časového pásma používateľa:

Hodnota	Význam
{System.Today}, $DATE_TODAY$	dnes
{System.Yesterday}, $DATE_YESTERDAY$	včera
{System.Tomorrow}, $DATE_TOMORROW$	zajtra
$DATE_THIS_WEEK_START$, $DATE_THIS_WEEK_END$	prvý a posledný deň tohto týždňa (pondelok a nedeľa)
$DATE_THIS_MONTH_START$, $DATE_THIS_MONTH_END$	prvý a posledný deň tohto mesiaca
$DATE_THIS_QUARTER_START$, $DATE_THIS_QUARTER_END$	prvý a posledný deň tohto štvrťroka
$DATE_THIS_YEAR_START$, $DATE_THIS_YEAR_END$	1. 1. a 31. 12. tohto roka
$DATE_LAST_WEEK_START$ … $DATE_LAST_YEAR_END$	to isté pre minulý týždeň, mesiac (LAST_MONTH), štvrťrok (LAST_QUARTER) a rok (LAST_YEAR)
$DATE_NEXT_WEEK_START$ … $DATE_NEXT_YEAR_END$	to isté pre budúci týždeň, mesiac (NEXT_MONTH) a rok (NEXT_YEAR)
$DATE_Q1_START$ … $DATE_Q4_END$	prvý a posledný deň 1. až 4. štvrťroka tohto roka
=DATE_DIFF(n)	dnes posunuté o n dní, napríklad =DATE_DIFF(-30) je pred 30 dňami
=WORKDAY(n)	dnes posunuté o n pracovných dní (pondelok až piatok, bez sviatkov)

Celé obdobie naraz pokryjú intervaly $DATE_INTERVAL_THIS_WEEK$, …_THIS_MONTH$, …_THIS_QUARTER$, …_THIS_YEAR$, …_LAST_WEEK$, …_LAST_MONTH$, …_LAST_QUARTER$, …_LAST_YEAR$, …_NEXT_WEEK$, …_NEXT_MONTH$, …_NEXT_YEAR$ a $DATE_INTERVAL_LAST_3_DAYS$, …_LAST_7_DAYS$, …_LAST_14_DAYS$, …_LAST_30_DAYS$ (vrátane dneška). Používajú sa s operátorom e.

Príklad: obchodné prípady s koncom v tomto mesiaci a firmy založené za posledných 30 dní:

{"Where": [{"Field": "EndDate", "Operator": "e", "Value": "$DATE_INTERVAL_THIS_MONTH$"}]}

{"Where": [{"Field": "CreatedDate", "Operator": "ge", "Value": "=DATE_DIFF(-30)"}]}

Konkrétny interval zadáte operátorom between. Hranicou môže byť dátum aj niektorá z hodnôt vyššie:

{"Where": [{"Field": "EndDate", "Operator": "between", "Value": ["{System.Today}", "$DATE_THIS_MONTH_END$"]}]}

Zoskupenie a agregačné funkcie

V Select môžete použiť funkcie SUM, COUNT, MIN, MAX a AVG. K nim patrí GroupBy s poľami, podľa ktorých sa záznamy zoskupia. Príklad: počet a súčet obchodných prípadov podľa obchodníka:

{
  "Select": ["Owner", "COUNT(Id) Pocet", "SUM(Price) Spolu"],
  "GroupBy": ["Owner"]
}

Súčty

S parametrom "Summary": true vráti API popri záznamoch aj súčty číselných stĺpcov zo Select: pri mene, celých a desatinných číslach súčet, pri percentách priemer. Súčty sa počítajú zo všetkých záznamov, ktoré spĺňajú podmienky, bez ohľadu na Limit a Skip.

{
  "Select": ["Name", "Price", "Profit", "ProfitPercentage"],
  "Summary": true,
  "Limit": 10
}

Vlastné súčty určíte poľom s Field a Aggregate (sum, avg, min, max, count):

{
  "Summary": [
    {"Field": "Price", "Aggregate": "sum"},
    {"Field": "Price", "Aggregate": "max"}
  ]
}

Výsledok je v SummaryData. S "Reason": "Summary" vráti API len súčty, bez záznamov. Súčty sa počítajú najviac zo 100 000 záznamov, pri väčšom počte ich odpoveď nemá a obsahuje SummaryError.

{
  "SummaryData": [
    {"Field": "Price", "Aggregate": "sum", "Value": 127100},
    {"Field": "Price", "Aggregate": "max", "Value": 24800}
  ]
}

Kanban

Pre kanban zoskupí API záznamy do stĺpcov podľa jedného poľa. Stačí "KanbanField": "Status", alebo podrobnejšie Kanban:

{
  "Select": ["Name", "Price", "Owner:FullName"],
  "Where": [{"Field": "Status", "Operator": "in", "Value": "Active"}],
  "Kanban": {"Field": "Status"},
  "Summary": [{"Field": "Price", "Aggregate": "sum"}],
  "Limit": 30
}

Skip a Limit platia pre každý stĺpec zvlášť, prvých 30 kariet sa teda vráti z každého stĺpca. Odpoveď obsahuje Sections so stĺpcami (Key, Label, Count, HasMore, NextSkip a pri Summary aj SummaryData) a každý záznam v Data má _SectionKey svojho stĺpca. Ďalšie karty jedného stĺpca načítate s "OnlySections": ["…Key…"] v objekte Kanban a Skip podľa NextSkip.

Pri číslach a dátumoch môže stĺpce tvoriť interval, objekt Kanban potom má Aggregate: interval_100 (po 100), date, weekyear, monthyear, year, month, week, pri texte firstchar (prvé písmeno).

Naposledy otvorené

S "Reason": "View" zaradí API načítaný záznam medzi naposledy otvorené, ktoré aplikácia ponúka používateľovi. Používajte ho len pri čítaní jedného záznamu: pri viacerých by sa za otvorený považoval každý. Aplikácia si pamätá 30 posledných záznamov z každej entity na používateľa.

Export do Excelu

S parametrom Export vráti čítanie namiesto JSON súbor XLSX (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet). V Columns môžete pomenovať stĺpce, inak majú systémové názvy polí.

curl -X POST https://api.gramcrm.com/vasafirma/api/v1/Account/ \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Select": ["Name", "City", "RegNo"], "Export": {"Type": "xlsx", "Columns": [{"Field": "Name", "Label": "Názov"}, {"Field": "City", "Label": "Mesto"}, {"Field": "RegNo", "Label": "IČO"}]}}' \
  --output firmy.xlsx

Pridanie a zmena záznamu

Nový záznam pridáte cez PUT na adresu entity, existujúci zmeníte cez PUT s jeho Id v adrese. Posielate len polia, ktoré chcete nastaviť.

PUTAccount/

{
  "Name": "Horizont Stavby, s.r.o.",
  "City": "Nitra",
  "RegNo": "47192777"
}

{
  "NewId": "bb1a1c6e-0e2b-4d1a-8d1e-ead8a8fe6aca",
  "Result": true,
  "RefreshList": ["Account"]
}

NewId je Id nového záznamu. RefreshList vymenúva entity, v ktorých sa pri zápise niečo zmenilo, napríklad aj prepočítané súčty na nadradenom zázname. Id môžete vytvoriť aj sami (UUID) a poslať ho v adrese alebo v tele: ak záznam s takým Id neexistuje, vznikne s ním. Tak viete napríklad v hromadnej operácii hneď naviazať ďalší záznam.

PUTAccount/bb1a1c6e-0e2b-4d1a-8d1e-ead8a8fe6aca

{"City": "Bratislava"}

Ak zápis nič nezmení, napríklad pošlete rovnakú hodnotu, odpoveď má "ResultText": "Nothing to do.".

Hodnoty polí

• Lookup (odkaz na záznam inej entity) berie Id záznamu. Môžete poslať aj názov: API nájde záznam podľa hlavného poľa (pri číselníkoch aj podľa kódu alebo symbolu, napríklad mena EUR). Ak sa nenájde, vytvorí nový záznam s týmto názvom. Ďalšie jeho polia môžete poslať cez dvojbodku, napríklad "Account": "Horizont Stavby, s.r.o.", "Account:City": "Nitra".
• Option berie číselnú hodnotu z číselníka, nie text.
• Dátum posielajte ako 2026-10-02, dátum a čas ako 2026-10-02 14:30:00 v časovom pásme používateľa. S hlavičkou X-Date-Format: iso môžete poslať aj čas s posunom, napríklad 2026-10-02T12:30:00Z.
• Zaškrtávacie pole berie 1 alebo 0.
• Súbor berie Id súboru nahratého cez File.

Polia, ktoré používateľ nesmie meniť, API pri zápise vynechá bez chyby. Polia, ktoré počíta systém (vzorce, čísla dokladov, súčty z iných záznamov), sa pri zápise prepočítajú, preto ich neposielajte.

Zmena poradia položiek

Entity s poradím (napríklad položky ponuky alebo faktúry) majú pole Row. Nové poradie nastavíte zoznamom Id: prvý záznam dostane 1, každý ďalší o 1 viac.

PUTProposalItem/ChangeOrder

{
  "Data": {
    "Ids": [
      "b3834656-cd34-4f8e-b3aa-ac4208cf3b0a",
      "31c306b3-352f-410b-a63c-56bc8284641d",
      "d622fb80-9eb0-479b-aab5-13ddce1c0fd9"
    ]
  }
}

Ak sa poradie ukladá do iného poľa, uveďte ho v Data ako "OrderField".

Zmazanie záznamu

curl -X DELETE https://api.gramcrm.com/vasafirma/api/v1/Account/bb1a1c6e-0e2b-4d1a-8d1e-ead8a8fe6aca \
  -H "Authorization: Bearer VAS_TOKEN"

{"Result": true, "ResultText": "Deleted", "RefreshList": ["Account"]}

Zmazaný záznam ide do koša a dá sa obnoviť, pozri Kôš a obnova. Čo sa stane so záznamami, ktoré naň odkazujú, určuje nastavenie poľa, cez ktoré odkazujú (AllowDeleteLookup):

• 0: zmazanie sa odmietne. API vráti 403 s kódom ErrorRelatedExists a v ResultText uvedie, čo bráni, napríklad Deal: 1 rec(s).
• 1: zmažú sa aj naviazané záznamy, napríklad položky faktúry s faktúrou.
• 2: odkaz v naviazaných záznamoch sa vyprázdni.

Neexistujúci záznam vráti 404 s kódom ErrorNotExists.

Kôš a obnova

Jedno mazanie vrátane naviazaných záznamov je v koši jedna položka (dávka) so svojím BatchId.

Volanie	Čo robí
GET core/Trash	zoznam zmazaných, s parametrami Skip, Limit (najviac 200), Search, Entity, From, To
GET core/Trash/{BatchId}	čo všetko dávka obsahuje
PUT core/Trash/{BatchId}/Restore	obnoví dávku; s ?Preview=1 len skontroluje, či obnove niečo nebráni

Zamknuté záznamy

Zamknutý záznam sa nedá zmeniť ani zmazať, ani cez API. Zápis vráti 423 s kódom RecordLocked, meniť sa dajú len polia, ktoré to pri zámku výslovne povoľujú. Zámok platí aj pre podriadené položky, napríklad položky zamknutej objednávky.

Volanie	Čo robí
PUT Lock/{Entita}/{Id}	zamkne záznam, v tele môže byť dôvod: {"Reason": "Odoslané do ERP"}
PUT Unlock/{Entita}/{Id}	odomkne záznam
GET Lock/{Entita}/{Id}	kto, kedy a prečo záznam zamkol

Ak má integrácia zapisovať aj do zamknutých záznamov (napríklad spätný zápis z ekonomického systému), dajte jej používateľovi v profile právo zapisovať do zamknutých záznamov.

Oprávnenia

API používa rovnaké oprávnenia ako aplikácia. Entity, záznamy a polia, ktoré používateľ nesmie vidieť, sa vo výsledkoch nezobrazia a nedajú sa použiť ani vo filtri či zoradení. Pri zápise API vynechá polia, ktoré používateľ nesmie meniť, a zvyšok zapíše. Chybu nevracia, aby integrácia nespadla len preto, že správca obmedzil jedno pole. Celú operáciu, na ktorú používateľ nemá právo, API odmietne s 403 a kódom ErrorNoPermission.

Pracovné postupy

Zápis cez API spúšťa rovnaké pracovné postupy ako zápis v aplikácii, napríklad upozornenia, úlohy alebo výpočty. Postup sa môže spustiť aj pred uložením a zápis zastaviť. API potom vráti 409:

• WorkflowInteractionRequired: chýbajú údaje, ktoré postup vyžaduje. Zoznam polí je v WorkflowInteraction.Requests, pri každom s Requirement (Required, Recommended alebo Optional).
• WorkflowBlocked: postup zápis zakázal, dôvod je vo WorkflowInteraction.Message.

{
  "Result": false,
  "ResultCode": "WorkflowInteractionRequired",
  "WorkflowInteraction": {
    "Version": 1,
    "Outcome": "interaction_required",
    "Entity": "Activity",
    "Operation": "update",
    "Requests": [
      {"Kind": "Fields", "Fields": [
        {"Field": "Result", "Requirement": "Required", "Label": "Výsledok", "DataType": "option(ActivityResult)"}
      ]}
    ]
  }
}

Doplňte chýbajúce polia a pošlite zápis znova. Odporúčané a nepovinné polia môžete pri opakovanom pokuse vynechať tak, že k telu pridáte {"WorkflowInteraction": {"Version": 1, "Skipped": {"Fields": ["Note"]}}}. Povinné pole sa vynechať nedá.

Hromadné operácie

Volanie batch vykoná viac požiadaviek naraz, postupne v uvedenom poradí. Každá požiadavka má Url (časť adresy za /api/v1/), Method (get, post, put, delete, predvolené get), voliteľne Body a vlastné Id, podľa ktorého ju nájdete vo výsledku. Požiadavky nie sú jedna transakcia: chyba jednej nezruší tie, ktoré už prebehli.

Príklad: firma s vlastným Id a kontakt naviazaný na ňu v jednom volaní.

POSTbatch

{
  "Requests": [
    {
      "Id": "firma",
      "Url": "Account/5f0c7d2e-8a41-4c3b-9e6f-2b7d1a9c4e30",
      "Method": "put",
      "Body": {"Name": "Horizont Stavby, s.r.o.", "City": "Nitra"}
    },
    {
      "Id": "kontakt",
      "Url": "Contact/",
      "Method": "put",
      "Body": {
        "Name": "Martina",
        "Surname": "Kováčová",
        "Email": "martina.kovacova@horizontstavby.sk",
        "Account": "5f0c7d2e-8a41-4c3b-9e6f-2b7d1a9c4e30"
      }
    }
  ]
}

{
  "Result": true,
  "Responses": [
    {
      "Id": "firma",
      "Endpoint": "Account/5f0c7d2e-8a41-4c3b-9e6f-2b7d1a9c4e30",
      "Status": 200,
      "Result": true,
      "ResultText": null,
      "Body": {"NewId": "5f0c7d2e-8a41-4c3b-9e6f-2b7d1a9c4e30"},
      "TimeMs": 41.2
    },
    {
      "Id": "kontakt",
      "Endpoint": "Contact/",
      "Status": 200,
      "Result": true,
      "ResultText": null,
      "Body": {"NewId": "8c2e5b14-3f7a-4d9e-a1c6-0e5d7b2f9a83"},
      "TimeMs": 37.9
    }
  ]
}

Každá odpoveď má vlastný Status s HTTP kódom. Požiadavka bez Url má Status 440, s nepodporovanou metódou 441.

Vyhľadávanie

GET GlobalSearch hľadá text naprieč entitami podľa hlavných údajov záznamov (názov, meno, číslo a podobne), rovnako ako vyhľadávanie v hlavičke aplikácie.

curl "https://api.gramcrm.com/vasafirma/api/v1/GlobalSearch?Query=horizont&Entity=Account,Contact&Limit=10" \
  -H "Authorization: Bearer VAS_TOKEN"

{
  "TotalResults": 2,
  "HasMore": false,
  "Data": [
    {
      "Id": "5f0c7d2e-8a41-4c3b-9e6f-2b7d1a9c4e30",
      "RecordType": "Account",
      "Primary": "Horizont Stavby, s.r.o.",
      "Secondary": "Nitra"
    },
    {
      "Id": "8c2e5b14-3f7a-4d9e-a1c6-0e5d7b2f9a83",
      "RecordType": "Contact",
      "Primary": "Martina Kováčová",
      "Secondary": "Horizont Stavby, s.r.o."
    }
  ],
  "Result": true
}

Entity je voliteľný zoznam entít oddelený čiarkou. Výsledok obsahuje len záznamy, ktoré smie používateľ vidieť.

Jazyk, dátumy a časové pásmo

Hlavička Content-Language prepne jazyk textov v odpovedi, napríklad popisov hodnôt (Status:Label) a chybových hlásení. Podporované sú en, de, sk, cz a hu. Zvolený jazyk si token zapamätá a platí aj pre ďalšie volania bez hlavičky. Ak s jedným tokenom pracujete vo viacerých jazykoch, posielajte ju pri každom volaní.

curl https://api.gramcrm.com/vasafirma/api/v1/Deal/ \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Language: sk"

Dátumy a časy vracia API ako 2026-10-02 14:30:00 v časovom pásme používateľa. Pásmo pre jednu požiadavku zmeníte hlavičkou X-Timezone (napríklad Europe/Bratislava). Pre integrácie odporúčame X-Date-Format: iso: časy potom prídu vo formáte ISO 8601 s posunom (2026-10-02T12:30:00Z) a rovnako ich môžete aj posielať.

Tlačové zostavy

Dokument podľa tlačovej zostavy (ponuku, faktúru, protokol) vygenerujete pre konkrétny záznam. Id zostáv k jednotlivým entitám vráti GET core/Me v časti Reports.

curl "https://api.gramcrm.com/vasafirma/api/v1/BuildReport/Proposal/ae751564-a5e1-438b-831f-31db0391b190?Report=23f3aad5-ff97-4805-bd57-f571c514aa42&Format=pdf" \
  -H "Authorization: Bearer VAS_TOKEN" \
  --output ponuka.pdf

S Format=pdf príde PDF, bez neho dokument vo formáte šablóny (napríklad DOCX alebo XLSX).

Súbory

Súbor nahráte cez PUT File?Name={názov}, v tele sú samotné dáta súboru.

curl -X PUT "https://api.gramcrm.com/vasafirma/api/v1/File?Name=Faktura-2026-0153.pdf" \
  -H "Authorization: Bearer VAS_TOKEN" \
  --data-binary "@Faktura-2026-0153.pdf"

{
  "Status": "New file uploaded",
  "Id": "7c693828-c473-4c5c-8487-0e42419e36c9",
  "Location": "Files",
  "Result": true
}

Nahratý súbor priraďte do poľa typu súbor, napríklad ako prílohu poznámky k faktúre. Súbor, ktorý nepriradíte žiadnemu záznamu, sa môže časom automaticky zmazať.

PUTNote/

{
  "Title": "Faktúra od dodávateľa",
  "Parent": "{Id faktúry}",
  "Attachment": "7c693828-c473-4c5c-8487-0e42419e36c9"
}

Súbor stiahnete cez GET File/{Id}:

curl https://api.gramcrm.com/vasafirma/api/v1/File/7c693828-c473-4c5c-8487-0e42419e36c9 \
  -H "Authorization: Bearer VAS_TOKEN" \
  --output faktura.pdf

Webhooky

Webhook pošle do vášho systému správu hneď, keď sa v Gram CRM vytvorí, zmení alebo zmaže záznam. Nastavíte ho v aplikácii v nastaveniach alebo cez API (návod). Správa obsahuje entitu, Id záznamu a udalosť. Aktuálne údaje si potom načítate cez API.

Nastavenie webhooku

PUTcore/Webhook/{Id}

{
  "Name": "Zmeny produktov pre e-shop",
  "Url": "https://eshop.vasafirma.sk/gramcrm/webhook",
  "Events": ["create", "edit", "delete"],
  "Entities": ["Product"],
  "Email": "it@vasafirma.sk",
  "Auth": {"Type": "bearer", "Token": "tajny-token-eshopu"}
}

Pole	Význam
Url	adresa, na ktorú Gram CRM pošle správu
Events	udalosti create, edit, delete, alebo ["*"] pre všetky. Bez Events sa webhook nespustí.
Entities	entity, pri ktorých sa má volať. Bez nich alebo s ["*"] pri všetkých.
Name, Description	názov a popis pre prehľad v nastaveniach
Email	kam poslať upozornenie, keď webhook nefunguje
Auth	overenie voči vášmu systému: {"Type": "none"}, basic s User a Password, bearer s Token, alebo header s vlastnou hlavičkou Header a hodnotou Token
Mode	system (predvolené) sa spúšťa pri udalostiach, manual len z kroku pracovného postupu

Webhooky smie spravovať len používateľ s právom upravovať nastavenia systému. GET core/Webhook vráti zoznam, heslá a tokeny v ňom sú skryté ako ********. Pri zmene môžete ******** poslať späť a uložená hodnota sa zachová. Webhook zmažete cez DELETE core/Webhook/{Id}.

Správa z webhooku

Gram CRM pošle na Url požiadavku POST s telom application/json:

{
  "Data": {
    "Entity": "Product",
    "Id": "b48399a2-f8b9-4216-9543-b8c1f5b7197a",
    "Event": "create"
  }
}

Váš systém musí odpovedať kódom 2xx do 10 sekúnd (na pripojenie má 5 sekúnd). Inak sa doručenie opakuje: prvé štyri pokusy po 1 minúte, ďalších päť po 5 minútach, potom každú hodinu. Správy jedného webhooku prichádzajú v poradí, v akom vznikli: kým sa nepodarí doručiť staršiu, novšie čakajú.

Keď je adresa nedostupná 2 hodiny, príde upozornenie na Email a po obnovení správa, že webhook opäť funguje. Po 3 dňoch nedostupnosti sa webhook zruší a pošle sa o tom e-mail. Doručovanie znova zapnete opätovným uložením webhooku.

Údaje o firmách z registra

GET AccountInfo?Value={text} vyhľadá firmy v registri firiem Slovenska a Česka. Každá nájdená firma má názov, IČO, DIČ, IČ DPH, adresu a krajinu (Name, RegNo, Vat, VatNo, Street, City, Zip, Country). Hodí sa napríklad do formulára na webe: z názvu firmy doplníte IČO, DIČ a adresu a založíte lead s kompletnými údajmi.

curl "https://api.gramcrm.com/vasafirma/api/v1/AccountInfo?Value=Arterio" \
  -H "Authorization: Bearer VAS_TOKEN"

{
  "AutocompleteProvider": "Business register",
  "Data": [
    {
      "Name": "Arterio, s.r.o.",
      "RegNo": "50182099",
      "Vat": "2120201490",
      "VatNo": "SK2120201490",
      "Street": "M. R. Štefánika 17",
      "City": "Levice",
      "Zip": "934 01"
    }
  ],
  "Result": true
}

Excel, Power BI a ďalšie BI nástroje

Na analýzy v Exceli, Power BI, Tableau alebo Qlik má Gram CRM zdroj OData v4 na adrese https://api.gramcrm.com/{organizacia}/odata/. Je len na čítanie a platia v ňom rovnaké oprávnenia ako v aplikácii.

• Prihlásenie: v BI nástroji zvoľte základné overenie (Basic). Meno je ľubovoľné, heslo je API kľúč. Funguje aj hlavička Authorization: Bearer.
• Entity: /odata/ vráti zoznam entít, /odata/$metadata ich schému, /odata/Deal záznamy.
• Jazyk popisov: pred názov entity pridajte jazyk, napríklad /odata/sk/Deal. Bez neho sú popisy po anglicky.
• Dotazy: podporované sú $select, $filter (eq, ne, gt, ge, lt, le, in, contains, startswith, endswith, and, or), $orderby, $top, $skip, $count a $expand pre naviazané záznamy.

Postup pre Power BI je v návode Power BI a CRM.

Gram CRM sa dá pripojiť aj do ChatGPT a Claude (MCP). Pripojenie používa prihlásenie používateľa a jeho oprávnenia, postup je v návode Pripojenie Gram CRM ku Claude cez MCP.

Rozšírené API

Cez API sa dajú vytvárať a meniť aj samotné entity, polia, pohľady, nástenky, pracovné postupy, tlačové zostavy a oprávnenia. Tieto volania smie len správca.

Upozornenie: nesprávnym použitím rozšíreného API môžete zmeniť správanie systému alebo poškodiť údaje. Používajte ho až po oboznámení sa so systémom a po konzultácii s našou podporou.

Polia entít

GET core/EntityField vráti definície polí so všetkými vlastnosťami. Pre jednu entitu pošlite v tele {"Entity": "Account"}. Na bežné čítanie a zápis stačí prehľadnejšie core/EntityFields/{Entita} (pozri Polia entity).

Pridanie poľa

Povinné sú entita (Entity), názov poľa (Name) a dátový typ (DataType). Typ poľa (Type) je predvolene edit.

PUTcore/EntityField/

{
  "Entity": "Account",
  "Name": "PocetObchodnikov",
  "Label": "Počet obchodníkov",
  "DataType": "number(11)"
}

Nové pole sa dá hneď použiť v pohľadoch, filtroch aj v API. Do formulára záznamu ho pridajte v aplikácii.

Typ poľa (Type)	Význam
edit	bežné pole, hodnotu zadáva používateľ alebo API
autonumber	číslo podľa vzoru, napríklad čísla dokladov INV-{YYYY}-{0000}
formula	vzorec z iných polí záznamu, napríklad {ItemPrice} * {Quantity}
calculated	súhrn z iných záznamov, napríklad súčet položiek faktúry

Dátový typ (DataType)	Význam
varchar(N)	jednoriadkový text s najviac N znakmi. Variant varchar(email), varchar(phone) a varchar(url) je e-mail, telefón a odkaz.
text	viacriadkový text
number(N)	celé číslo
float(N,D)	desatinné číslo, N číslic spolu, D za desatinnou čiarkou
currency(N,D)	suma v mene
percentage(N,D)	percentá
date, datetime, time	dátum, dátum a čas, čas
check	zaškrtávacie pole
option(Číselník)	výber z číselníka
lookup(Entita)	odkaz na záznam konkrétnej entity
related	odkaz na záznam ľubovoľnej entity
file	súbor

Zmena poľa

Pošlite Id poľa v adrese a len vlastnosti, ktoré meníte. Pri zmene dátového typu sa môžu stratiť hodnoty, ktoré do nového typu nepasujú.

PUTcore/EntityField/9dd67252-31aa-4468-8bd1-900aca6295b9

{
  "DataType": "number(5)",
  "Label": "Skutočný počet obchodníkov"
}

Číselníky

Hodnoty polí typu option sú v číselníkoch. Názov číselníka je v dátovom type poľa, napríklad pole Rating s typom option(AccountRating) používa číselník AccountRating. GET core/FieldOption vráti zoznam číselníkov, GET core/FieldOption/{Číselník} jeho hodnoty:

curl https://api.gramcrm.com/vasafirma/api/v1/core/FieldOption/AccountRating \
  -H "Authorization: Bearer VAS_TOKEN"

{
  "Id": "b00195bf-f428-44ce-ab6a-d0777163c2cf",
  "Name": "AccountRating",
  "Global": 0,
  "Items": [
    {"Label": "C", "Value": 4, "Order": 10, "Color": "#5bc8c4", "Stage": 0, "Enabled": 1},
    {"Label": "B", "Value": 3, "Order": 20, "Color": "#8bc34a", "Stage": 0, "Enabled": 1},
    {"Label": "A", "Value": 2, "Order": 30, "Color": "#ff7043", "Stage": 0, "Enabled": 1},
    {"Label": "VIP", "Value": 1, "Order": 40, "Color": "#ff3547", "Stage": 0, "Enabled": 1}
  ],
  "Result": true
}

Pri zápise posielate Value, pri čítaní dostanete hodnotu aj popis (Rating a Rating:Label).