Vitajte v špecifikácii REST API rozhrania pre Gram CRM.

Základy

API rozhranie používa na komunikáciu HTTPS protokol. Základné API URL je: https://api.gramcrm.com/organizacia/api/v1/. Kde organizacia je vždy názov Vašej organizácie. Formát komunikácie je vždy JSON.

V príkladoch použitia API rozhrania budeme používať aplikáciu curl. Pre pohodlnú prácu pri vývoji a testovaní odporúčame použiť nástroj Postman.

API vždy vracia v odpovedi okrem stavových http kódov (200,400,500 atď.) aj úspešnosť vykonaného príkazu v hodnote Result.

API zohľadňuje oprávnenia užívateľa a k nemu prislúchajúci Token.

Autorizácia

Každá požiadavka na API rozhranie musí byť autorizovaná pomocou platného Token-u. Token musí byť prítomný v hlavičke požiadavky (Headers). Token môže byť trvalý (štandardne napríklad pre prepojenie s externým systémom, web lead a pod.) alebo Token pre konkrétneho užívateľa.

Získať Token pre existujúceho užívateľa je možné pomocou funkcie: /Login.

Príklad prihlásenia
curl -H "Content-Type: application/json" -X POST -d '{"Username":"ondrej@mojafirma.sk","Password":"3bb984343e0469083fa53851f1ccbdb8"}' https://api.gramcrm.com/demo/api/v1/Login/
{
    "UserName": "ondrej@mojafirma.sk",
    "Password": "3bb984343e0469083fa53851f1ccbdb8"
}

V prípade úspešného prihlásenia dostaneme odpoveď a nový Token spolu s informáciou o dĺžke jeho platnosti:

{
    "Result": true,
    "ResultText": "User loged in.",
    "Token": {
        "NewToken": "3e99f8dda9ad4444bed1c6f44459ae06",
        "ValidTo": "2021-01-25 12:28:17"
    }
}

Token platí vždy 2 týždne od poslednej operácie ak nie je v systéme nastavené inak. Pre napojenie na externé aplikácie je vhodné použiť Token bez obmedzenia platnosti, prosím kontaktujte našu podporu. Príklad takéhoto prepojenia nájdete v tomto článku.

Ping

Overiť dostupnosť API rozhrania a platného Tokenu je možné prostredníctvom funkcie/Ping . Ak je všetko v poriadku funkcia vráti hodnotu Result: true;

curl https://api.gramcrm.com/demo/api/v1/Ping -H "Token: 3e9968dda98d4444bed1c6f44459ae06"
{"Result":true}

Entity

Prehľad

Gram CRM pracuje s údajmi, ktoré sú uložené v tzv Entitách. Štandardné Entity sú Klienti, Kontakty, Leady, Obchodné prípady, Aktivity atď. Pomocou API môžete pristupovať ku všetkým Entitám ku ktorým máte oprávnenie vrátane vlastných Entít. Taktiež je možné prostredníctvom API vytvárať vlastné Entity (ak je užívateľ Administrátor).

Údaje jednotlivých Entít je možné čítať, pridávať, modifikovať a taktiež mazať.

Systémové Entity

Vaša organizácia obsahuje Entity podľa riešenia, ktoré používate. Zoznam štandardne inštalovaných Entít pre obchodné riešenie:

  • Account
  • Activity
  • Asset
  • BankAccount
  • Call
  • Campaign
  • Case
  • CaseWork
  • Contact
  • ContactRelation
  • Contract
  • ContractItem
  • CreditInvoice
  • Deal
  • DealItem
  • Email
  • Event
  • Fueling
  • Invoice
  • InvoiceItem
  • InvoicePayment
  • Lead
  • Note
  • Order
  • OrderItem
  • Product
  • ProformaInvoice
  • ProformaInvoiceItem
  • ProformaInvoicePayment
  • Project
  • Proposal
  • ProposalItem
  • ProposalItemProduct
  • ProposalItemSection
  • ProposalText
  • PurchaseInvoice
  • PurchaseInvoiceItem
  • PurchaseOrder
  • PurchaseOrderItem
  • Route
  • StandardInvoice
  • SupplyContract
  • SupplyContractItem
  • Task
  • Vehicle

Čítanie záznamov

Pre prístup k údajom v Entitách použijeme funkciu podľa príslušného názvu danej Entity v jednotnom čísle.

Príklad načítania údajov pre Entitu Account:

curl https://api.gramcrm.com/demo/api/v1/Account -H "Token: 3e9968dda98d4444bed1c6f44459ae06"
{ "TotalResults": 19,
    "HasMore": false,
    "Data": [
        {
            "Id": "069719ba-aeca-47fc-bd92-0ff774bbc028",
            "CreatedDate": "2020-12-28 15:53:34",
            "CreatedUser": "6c94ab06-91d4-432c-a9ad-f1a746147178",
            "CreatedUser:FullName": "System",
            "CreatedUser:Email": "podpora@arterio.sk",
            "CreatedUser:Phone": "+421 2 4333 4333",
            "CreatedUser:Shortcut": "ZZZ",
            "CreatedUser:Position": null,
            "ModifiedDate": "2021-02-11 09:51:14",
            "ModifiedUser": "6c94ab06-91d4-432c-a9ad-f1a746147178",
            "ModifiedUser:FullName": "System",
            "ModifiedUser:Email": "podpora@gramcrm.sk",
            "ModifiedUser:Phone": "+421 2 4333 4333",
            "ModifiedUser:Shortcut": "ZZZ",
            "ModifiedUser:Position": null,
            "RecordType": "Account",
            "Ext": null,
            "ExtDate": null,
            "Number": "C0009",
            "Name": "Demonte s.r.o.",
            "Street": "Školská",
            "City": "Zbehy",
            "Zip": "951 42",
            "Country": 202,
            "Country:Label": "Slovensko",
            "Country:Color": null,
            "Country:Order": 1,
            "Country:CustomValue": 0,
            "Country:GroupValue": 0,
            "ShippingName": null,
            "ShippingStreet": null,
            "ShippingCity": null,
            "ShippingZip": null,
            "ShippingCountry": null,
            "ShippingCountry:Label": null,
            "ShippingCountry:Color": null,
            "ShippingCountry:Order": null,
            "ShippingCountry:CustomValue": null,
            "ShippingCountry:GroupValue": null,
            "Owner": "40d545b6-eebe-4f6d-a5e0-9f708a2d78d9",
            "Owner:FullName": "Juraj Lackovič",
            "Owner:Email": "juraj.lahky@gramcrm.sk",
            "Owner:Phone": "+421 2 4333 4333",
            "Owner:Shortcut": "JURla",
            "Owner:Position": "Obchodný manažér",
            "Phone": "+421 948 222 999",
            "Email": "info@demonte.sk",
            "Web": "www.demonte.sk",
            "Note": null,
            "RegNo": "47192777",
            "Vat": "2016722167",
            "VatNo": "SK2016722167",
            "Registration": null,
            "InvoiceLife": 14,
            "Region": 2,
            "Region:Label": "Západ",
            "Region:Color": "",
            "Region:Order": 2,
            "Region:CustomValue": 0,
            "Region:GroupValue": 0,
            "Rating": 3,
            "Rating:Label": "B",
            "Rating:Color": "#8bc34a",
            "Rating:Order": 20,
            "Rating:CustomValue": 0,
            "Rating:GroupValue": 0,
            "Relationship": 1,
            "Relationship:Label": "Odberateľ",
            "Relationship:Color": null,
            "Relationship:Order": 4,
            "Relationship:CustomValue": 0,
            "Relationship:GroupValue": 0,
            "IncomeThis": null,
            "IncomeLast": null,
            "IncomeTotal": null,
            "LastActivity": "cf4a7fad-99a2-42ad-b0fe-b60f33036d69",
            "LastActivity:CreatedDate": "2020-12-28 15:53:47",
            "LastActivity:CreatedUser": "6c94ab06-91d4-432c-a9ad-f1a746147178",
            "LastActivity:ModifiedDate": null,
            "LastActivity:ModifiedUser": null,
            "LastActivity:RecordType": "Event",
            "LastActivity:Ext": null,
            "LastActivity:ExtDate": null,
            "LastActivity:Subject": "Zápis zo stretnutia",
            "LastActivity:RelatedTo": "7b410875-0a7c-4b42-9973-c1893e80430e",
            "LastActivity:ActivityDate": "2020-04-01 13:00:00",
            "LastActivity:StartDate": "2020-04-01 13:00:00",
            "LastActivity:EndDate": "2020-04-01 15:00:00",
            "LastActivity:Done": 1,
            "LastActivity:AssignedTo": "40d545b6-eebe-4f6d-a5e0-9f708a2d78d9",
            "LastActivity:Category": 2,
            "LastActivity:Description": "Preberali sme požiadavky zákazníka",
            "LastActivity:Priority": null,
            "LastActivity:Account": "069719ba-aeca-47fc-bd92-0ff774bbc028",
            "LastActivity:Contact": "3692565f-00f0-4e1a-b138-faca060802e1",
            "PlannedActivity": null,
            "PlannedActivity:CreatedDate": null,
            "PlannedActivity:CreatedUser": null,
            "PlannedActivity:ModifiedDate": null,
            "PlannedActivity:ModifiedUser": null,
            "PlannedActivity:RecordType": null,
            "PlannedActivity:Ext": null,
            "PlannedActivity:ExtDate": null,
            "PlannedActivity:Subject": null,
            "PlannedActivity:RelatedTo": null,
            "PlannedActivity:ActivityDate": null,
            "PlannedActivity:StartDate": null,
            "PlannedActivity:EndDate": null,
            "PlannedActivity:Done": null,
            "PlannedActivity:AssignedTo": null,
            "PlannedActivity:Category": null,
            "PlannedActivity:Description": null,
            "PlannedActivity:Priority": null,
            "PlannedActivity:Account": null,
            "PlannedActivity:Contact": null,
            "WonDeals": null,
            "PotentialDeals": null,
            "WonProposals": null,
            "PotentialProposals": null,
            "Phone2": null,
            "Iban": null,
            "InvoiceEmail": null,
            "InvoiceName": null,
            "Status": 1,
            "Status:Label": "Potenciálny",
            "Status:Color": "",
            "Status:Order": 4,
            "Status:CustomValue": 0,
            "Status:GroupValue": 0
        }
]
}

Hodnota "TotalResults": 19 určuje počet záznamov zodpovedajúcich požiadavke. Pole "Data“ obsahuje požadované dáta z požiadavky pričom ak neboli špecifikované stĺpce, systém vráti základné stĺpce pre danú Entitu a „druhý level“ pre stĺpce typu Lookup, Option.

Načítanie konkrétneho záznamu

Ak potrebujeme prístup ku konkrétnemu záznamu môžeme Id požadovanej položky uviesť priamo v URL požiadavky. Príklad:

curl https://api.gramcrm.com/demo/api/v1/Account/069719ba-aeca-47fc-bd92-0ff774bbc028 -H "Token: 3e9968dda98d4444bed1c6f44459ae06"

Stránkovanie

Ak potrebujeme obmedziť počet vrátených záznamov pridáme parameter: "Limit":100. Pre preskočenie počtu záznamov môžeme definovať parameter "Skip":10. Ak máme takto obmedzený záznam potom vo výsledku sa nám vráti hodnota "HasMore": true

Výber stĺpcov

Pri čítaní údajov si môžeme špecifikovať, ktoré stĺpce chceme načítať. Obmedziť výstup môžeme pomocou parametru {"Select": ["Name", "Street", "Status:Label"]}. Pri stĺpcoch môžeme využiť aj alias napr.: {"Select": ["Name MyName", "Street", "Status:Label"]}. Toto je vhodné hlavne pre agregované funkcie. Pokiaľ požadujeme neexistujúci stĺpec, alebo stĺpec na ktorý nemáme právo tak tento bude ignorovaný a API ho odstráni z požiadavky (nezobrazí chybu).

Príklad načítania iba zvolených stĺpcov pre Entitu Account:

POST https://api.gramcrm.com/demo/api/v1/Account/

Body:

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

Odpoveď:

{
    "TotalResults": 19,
    "HasMore": false,
    "Data": [
        {
            "MyNewName": "Demonte s.r.o.",
            "Street": "Školská",
            "Status:Label": "Potenciálny"
        },
        {
            "MyName": "GBF Telekom, a.s.",
            "Street": "Majská 10",
            "Status:Label": "Potenciálny"
        }]
}

Zoradenie

Výstup môžeme zoradiť podľa jednotlivých stĺpcov pomocou parametru OrderBy. Doplníme náš príklad o zoradenia podľa Názvu a Ulice:

{
    "Select": ["Name MyNewName", "Street", "Status:Label"],
    "OrderBy": [
        {
            "Field": "Name",
            "Order": "asc"
        },
        {
            "Field": "Street",
            "Order": "desc"
        }
    ]
}

Možné typy zoradenia: asc, desc. Pričom „Order“ je voliteľný parameter, ak sa neuvedie je vždy asc. Zoradiť je možné aj podľa čísla stĺpca rovnako ako v SQL. Teda namiesto názvu pola zadáme číslo. Prvý stĺpec je číslo 1.

{
    "Select": ["Name MyNewName", "Street", "Status:Label"],
    "OrderBy": [
        {
            "Field": "1"
        },
        {
            "Field": "Street",
            "Order": "desc"
        }
    ]
}

Filtrovanie

Ak potrebujeme zobraziť len záznamy vyhovujúce podmienke toto definujeme pomocou parametru Where. Pričom je možné doplniť parametrom WhereLogic, ktorý určí vzťah medzi jednotlivými podmienkami. Pričom prvá podmienka má číslo 1. Pri WhereLogic je možné používať aj zátvorky. Napríklad: (1 AND 2) OR (3 AND 4).

Príklad ktorý zobrazí Klientov, ktorí majú v názve text „europe“ alebo „tele“:

{
    "Select": ["Name MyNewName", "Street", "Status:Label"],
    "OrderBy": [
        {
            "Field": "1"
        },
        {
            "Field": "Street",
            "Order": "desc"
        }
    ],
    "Where": [
        {
            "Field": "Name",
            "Operator": "c",
            "Value": "europe"
        },
        {
            "Field": "Name",
            "Operator": "c",
            "Value": "tele"
        }
    ],
    "WhereLogic": "1 OR 2"
}
Dostupné operátory
  • e = equals
  • ne = not equal to
  • l = less than
  • g = greater than
  • le = less or equal
  • ge = greater or equal
  • c = contains
  • nc = does not contain
  • s = starts with
  • empty = value is not set
  • nempty = value is set

Systémové hodnoty vo filtrovaní

Existujú systémové hodnoty, ktoré môžeme použiť vo filtrovaní a majú nasledovný význam.

Hodnoty aktuálneho obdobia
  • $DATE_TODAY$ – Aktuálny dátum
  • $DATE_YESTERDAY$ – Včerajší dátum
  • $DATE_THIS_WEEK_START$ – Prvý deň aktuálneho týždňa (Pondelok)
  • $DATE_THIS_WEEK_END$ – Posledný deň aktuálneho týždňa (Nedeľa)
  • $DATE_THIS_MONTH_START$ – Prvý deň aktuálneho mesiaca
  • $DATE_THIS_MONTH_END$ – Posledný deň aktuálneho mesiaca
  • $DATE_Q1_START$ – Prvý deň, prvého kvartálu v aktuálnom roku (1.1.)
  • $DATE_Q1_END$ – Posledný deň, prvého kvartálu v aktuálnom roku (31.3.)
  • $DATE_Q2_START$ – Prvý deň, druhého kvartálu v aktuálnom roku (1.4.)
  • $DATE_Q2_END$ – Posledný deň, druhého kvartálu v aktuálnom roku (30.6.)
  • $DATE_Q3_START$ – Prvý deň, tretieho kvartálu v aktuálnom roku (1.7.)
  • $DATE_Q3_END$ – Posledný deň, tretieho kvartálu v aktuálnom roku (30.9.)
  • $DATE_Q4_START$ – Prvý deň, štvrtého kvartálu v aktuálnom roku (1.10.)
  • $DATE_Q4_END$ – Posledný deň, štvrtého kvartálu v aktuálnom roku (31.12.)
  • $DATE_THIS_QUARTER_START$ – Prvý deň v aktuálnom kvartáli
  • $DATE_THIS_QUARTER_END$ – Posledný deň v aktuálnom kvartáli
  • $DATE_THIS_YEAR_START$ – Prvý deň v aktuálnom roku (1.1.)
  • $DATE_THIS_YEAR_END$ – Posledný deň v aktuálnom roku (31.12.)
Príklad použitia

Uvedený príklad vráti všetky hodnoty, kde pole TaxDate je rovné "Operator": "e" aktuálnemu dňu.

{
    "Where": [
        {
            "Field": "TaxDate",
            "Operator": "e",
            "Value": "$DATE_TODAY$"
        }
    ]
}
Hodnoty predchádzajúceho obdobia
  • $DATE_LAST_WEEK_START$ – Prvý deň predchádzajúceho týždňa (Pondelok)
  • $DATE_LAST_WEEK_END$ – Posledný deň predchádzajúceho týždňa (Nedeľa)
  • $DATE_LAST_MONTH_START$ – Prvý deň predchádzajúceho mesiaca
  • $DATE_LAST_MONTH_END$ – Posledný deň predchádzajúceho mesiaca
  • $DATE_LAST_QUARTER_START$ – Prvý deň predchádzajúceho kvartálu
  • $DATE_LAST_QUARTER_END$ – Posledný deň predchádzajúceho kvartálu
  • $DATE_LAST_YEAR_START$ – Prvý deň predchádzajúceho roku (1.1.)
  • $DATE_LAST_YEAR_END$ – Posledný deň predchádzajúceho roku (31.12.)
Hodnoty intervalov (prvý a posledný deň intervalu je započítaný)
  • $DATE_INTERVAL_THIS_WEEK$ – Rozsah hodnôt aktuálneho týždňa $DATE_THIS_WEEK_START$ a $DATE_THIS_WEEK_END$.
  • $DATE_INTERVAL_THIS_MONTH$ – Rozsah hodnôt aktuálneho mesiaca $DATE_THIS_MONTH_START$ a $DATE_THIS_MONTH_END$.
  • $DATE_INTERVAL_THIS_QUARTER$ – Rozsah hodnôt aktuálneho kvartálu $DATE_THIS_QUARTER_START$ a $DATE_THIS_QUARTER_END$.
  • $DATE_INTERVAL_THIS_YEAR$ – Rozsah hodnôt aktuálneho roka $DATE_THIS_YEAR_START$ a $DATE_THIS_YEAR_END$.
  • $DATE_INTERVAL_LAST_WEEK$ – Rozsah hodnôt predchádzajúceho týždňa $DATE_LAST_WEEK_START$ a $DATE_LAST_WEEK_END$.
  • $DATE_INTERVAL_LAST_MONTH$ – Rozsah hodnôt predchádzajúceho týždňa $DATE_LAST_MONTH_START$ a $DATE_LAST_MONTH_END$.
  • $DATE_INTERVAL_LAST_QUARTER$ – Rozsah hodnôt predchádzajúceho týždňa $DATE_LAST_QUARTER_START$ a $DATE_LAST_QUARTER_END$.
  • $DATE_INTERVAL_LAST_YEAR$ – Rozsah hodnôt predchádzajúceho týždňa $DATE_LAST_YEAR_START$ a $DATE_LAST_YEAR_END$.
Príklad použitia

Uvedený príklad vráti všetky hodnoty, kde pole TaxDate je v intervale aktuálneho roka 1.1.YYYY medzi 31.12.YYYY. V tomto prípade podmienka Operator je ignorovaná nakoľko sa jedná o interval dátumov.

{
    "Where": [
        {
            "Field": "TaxDate",
            "Operator": "e",
            "Value": "$DATE_INTERVAL_THIS_YEAR$"
        }
    ]
}
Hodnoty rozdielu v dátume
  • DATE_DIFF([+/-]N) – Rozdiel +/-N dní od dnešného dátumu.
Príklad použitia

Uvedený príklad vráti všetky hodnoty, kde pole DueDate má hodnotu o 12 dní nižšiu, ako dnešný deň, t.j. zoznam faktúr 12 dní po splatnosti.

{
    "Where": [
        {
            "Field": "Payed",
            "Operator": "e",
            "Value": 0
        },
        {
            "Field": "DueDate",
            "Operator": "e",
            "Value": "DATE_DIFF(-12)"
        }
    ],
    "WhereLogic": "1 AND 2"
}

Kanban view

V prípade ak potrebujeme načítať dáta pre tzv. Kanban pohľad je možné použiť parameter KanbanField . ktorým určíme podľa, ktorého stĺpca sa má výpis zúžiť. Podporované sú len stĺpce typu Option. Pri tomto filtrovaní sú zobrazené len aktívne stavy Optionu. Teda „Won“ a „Lost“ sa nepočítajú. Ak tento stĺpec nebol vyžiadaný tak sa automaticky doplní do zoznamu požadovaných stĺpcov. Parameter rozširuje podmienku „Where“ a sú navzájom kombinovateľné. Teda je možné použiť aj parameter Where a KanbanField pričom vzťah medzi nimi je vždy AND.

Príklad (načítajú sa záznamy ktoré sú uhradené (Payed) a zároveň v aktívnom stave (Status)):

{
    "Select": [
        "Name"
    ],
    "Where": [
        {
            "Field": "Payed",
            "Operator": "e",
            "Value": 0
    },
    "KanbanField":"Status"
}

Agregované funkcie

Ak potrebujeme vrátiť agregovanú funkciu SUM, COUNT, MIN, MAX, AVG môžeme zapísať v parametre Select. Spolu s agregovanou funkciou potrebujeme zadefinovať aj GroupBy, napríklad:

{
    "Select": [
        "SUM(Price) MyTotalPrice",
        "AVG(Vat) AvgVat"
    ],
    "GroupBy": [
        "Id"
    ]
}

Sumárne hodnoty

Ak potrebujeme, aby sa okrem vrátených údajov zrealizoval aj výpočet sumárov použijeme parameter "Summary": true. Výsledné hodnoty budú potom spočítané bez ovplyvnenia parametrom Limit a Skip pre stĺpce, ktoré podporujú výpočet hodnôt. Pričom pre typ currency a number sa použije agregovaná funkcia SUM a pre percentage sa použije AVG.

Rovnako je možné presne definovať stĺpce, ktoré potrebujeme vrátiť vo výsledku.

Príklad použitia automatického vygenerovania sumárnych hodnôt
https://api.gramcrm.sk/demo/api/v1/Invoice/
{
    "Select": [
        "Number", "Name", "Price", "Profit", "ProfitPercentage"
    ],
    "Summary": true,
    "Limit": 10
}
Príklad špecifikovania vlastných sumárnych hodnôt
{
    "Summary": [
        {
            "Field": "Price",
            "Function":  "avg"
        },
        {
            "Field": "Price",
            "Function":  "min",
            "Alias": "MaxPrice"
        }
}

Údaje vo výstupe potom okrem štandardných hodnôt obsahujú aj hodnoty SummaryData:

{
    "SummaryData": [
        {
            "Field": "Price",
            "Function": "avg",
            "Alias": "Price",
            "Value": 10591.666666667
        }
}

Naposledy otvorené

Pomocou API môžeme ovplyvniť aj zoznam naposledy otvorených položiek, ktoré potom UI rozhranie Gram CRM uprednostňuje. Stačí uviesť do požiadavky parameter "Reason": "View". Toto je vhodné používať výhradne pri načítavaní jedného záznamu, pretože ak API vráti viac výsledkov tak každý jeden nastaví ako naposledy otvorený.

{
    "Reason": "View"
}

Maximálny počet naposledy otvorených záznamov pre jednu entitu a užívateľa je 30. Teda uchovávame maximálne 30 posledných záznamov pre každú entitu a užívateľa. Teda 30 Account entít, 30 Contact. Ak GET vráti napr. 100 záznamov tak sa kompletne prepíše história danej entity a užívateľa.

Poznámka: ak použijeme Reason:View tak ak vo výsledku si nevyžiadame Id tak nám ho vždy doplní.

Export záznamov

Výsledok dopytu môžeme v rámci API volania exportovať do Excelu. Výsledok bude vo formáte XLSX namiesto pôvodného JSON formátu. V požiadavke je potrebné pridať parameter „Export“. Zároveň môžeme špecifikovať názvy stĺpcov v Exceli pomocou parametra „Columns„. Pokiaľ nepoužijeme tento parameter tak sa použijú systémové názvy polý.

Príklad exportu Klientov:

PUT https://api.gramcrm.com/demo/api/v1/Account/
{
   "Select": ["Name", "Street", "Vat"],
   "Export": {
      "Type": "xlsx",
      "Columns": [
          {"Field": "Name", "Label": "Názov"},
          {"Field": "Street", "Label": "Ulica"},
          {"Field": "Vat", "Label": "IČO"}
      ]
   }
}

Pridávanie záznamov

Pre zmenu údajov v Entitách použijeme opätovne funkciu podľa príslušného názvu danej Entity v jednotnom čísle v anglickom jazyku.

Príklad pridania nového Klienta v Entite Account:

PUT https://api.gramcrm.com/demo/api/v1/Account/
{
   "Name": "New Account, ltd.",
   "Street": "Great platan street 123"
}

V odpovedi potom dostaneme nové Id v hodnote NewId. Ak sme v požiadavke uviedli hodnotu Id a takýto záznam ešte neexistoval NewId a Id hodnota budú identické. Ak takýto záznam už existoval dôjde k zmene údajov namiesto pridania nového. Zároveň dostaneme v hodnote RefreshList aj zoznam všetkých Entít(modulov) v ktorých došlo k zmene (či už pridaniu alebo zmene záznamu). V tomto zozname je vždy Entita len 1x aj keď bolo zmenených viac záznamov daného typu.

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

Zmena záznamov

Zmena existujúcich údajov v Entite je identická ako pri pridávaní. Pokiaľ záznam s požadovaným Id existuje uskutoční sa zmena údajov. V opačnom prípade dôjde k vytvoreniu nového záznamu.

Príklad zmeny názvu Klienta v Entite Account:

PUT https://api.gramcrm.com/demo/api/v1/Account/bb1a1c6e-0e2b-4d1a-8d1e-ead8a8fe6aca
{
    "Name": "My nice new name"
}

Pokiaľ nedôjde k reálnej zmene údajov v rámci záznamu. Napríklad pošleme rovnaký názov ako už bol API vráti textovú informáciu v hodnote "ResultText": "Nothing to do."

{
    "ResultText": "Nothing to do.",
    "Result": true
}

Zmena poradia záznamov

Niektoré Entity podporujú tzv. poradie. Sú to zväčša Entity, ktoré sú položkovité. Teda napríklad položky faktúry, ponuky, obchodného prípadu a podobne. Entita ktorá podporuje zmenu poradia musí obsahovať stĺpec „Row“. K zmene poradia záznamov slúži funkcia „ChangeOrder“, ktorá má nasledovný formát:

PUT https://api.gramcrm.com/demo/api/v1/InvoiceItem/ChangeOrder/
{
     "Data": ["b3834656-cd34-4f8e-b3aa-ac4208cf3b0a", "31c306b3-352f-410b-a63c-56bc8284641d", "d622fb80-9eb0-479b-aab5-13ddce1c0fd9"]
}

Pokiaľ je všetko v poriadku API zmení poradie záznamov a to tak, že prvý záznam bude mať hodnotu 1 a každý ďalší o 1 vyššiu.

Zmazanie záznamov

Zmazanie záznamu príslušnej Entity je možné pomocou metódy DELETE. Pričom pri mazaní sa zohľadňuje vzťah medzi jednotlivými Entitami, ktorý je definovaný pri príslušných stĺpcoch.

Príklad: Ak máme požiadavku na zmazanie Faktúry (StandardInvoice) a existujú pre ňu položky faktúry tak dôjde k zmazaniu aj všetkých položiek patriacich k danej Faktúre rovnako dôjde aj k zmazaniu všetkých Aktivít k Faktúre. Pokiaľ sa však pokúsime zmazať Klienta (Account), ktorý má vytvorený napríklad Obchodný prípad (Deal) tak takéhoto klienta sa nám nepodarí zmazať. Upraviť toto správanie je možné pri danom prepojení v lookup stĺpci povolením hodnoty "AllowDeleteLookup":"1".

Príklad zmazania Klienta (Account):

DELETE https://api.gramcrm.com/demo/api/v1/Account/bb1a1c6e-0e2b-4d1a-8d1e-ead8a8fe6aca
{
    "Info": "Deleted",
    "Result": true
}

V prípade ak existuje prepojenie na ďalšie Entity a nie je povolené ich zmazanie "AllowDeleteLookup":"0".

{
    "Result": false,
    "ResultText": "Deal: 1 rec(s)",
    "ResultCode": "ErrorRelatedExists"
}

ACL

Nastavené ACL (Access Control List) pravidlá užívateľa môžu ovplyvniť výsledok, ktorý dostaneme na výstupe. Ak na požadovaný stĺpec nemá užívateľ právo, nezobrazí sa na výstupe a nie je možné použiť ho ani vo filtrovaní filtrovaní, resp. zoraďovaní. To isté platí aj pre samotné Entity.

Upozornenie: API minimalizuje chybové odpovede pri požiadavkach na neoprávnené údaje. Namiesto vrátenia chyby odstráni neoprávavnené resp. nesprávne uvedené parametre. Príklad: Ak užívateľ nemá oprávnenie meniť IČO Klienta a pošle takúto požiadavku spolu so zmenou názvu Klienta na ktorú ale má oprávnenie API zmení názov klienta avšak nezmení IČO Klienta.

Hromadné operácie/Batch

API volania je možné jednoducho vykonať v jednom volaní. Na to slúži funkcia „batch“. V tejto fukcii môžeme jednoducho definovať jednotlivé API volania. Následne v odpovedi dostaneme výsledok pre jednotlivé riadky. Povinný je parameter „Url“. Pokiaľ nie je definovaný parameter „Method“ použije sa vždy „get“. V prípade potreby je možné definovať aj vlastný identifikátor pre každý riadok.

Príklad ako v jednom API volaní pridáme nový „Account“ a zároveň ho rovno aj zmažeme.

https://api.gramcrm.com/demo/api/v1/batch
{
    "Requests": [
        {
            "Url": "Account/1",
            "Method": "put",
            "Body": {
                "Name": "1476330b-d4f6-43ea-8843-5f457951f4c3"
            }
        },
        {
            "Url": "Account/1476330b-d4f6-43ea-8843-5f457951f4c3",
            "Id": "VlastnyID",
            "Method": "delete"
            }
        }
    ]
}

Workflow

Upozornenie: Pri každej zmene a pridávaní záznamov sa zároveň vykonávajú aj pracovné postupy (Workflow) pre prísušné Entity ak spĺňajú definované pravidlá. Teda aj pri pridaní/zmene Entity prostredníctvom API dôjde k spusteniu pracovných postupov vrátane uživateľsky definovaných. Napríklad notifikácia o vytvorení faktúry, priradení úlohy, upozornenie na nízku ziskovosť atď.

Toto správanie je možné upraviť, prosím kontaktujte našu podporu.

Jazyková podpora

API je možné prepnúť do inej jazykovej verzii pomocou hlavičky Content-Language. Podporované sú jazyky: en, de, sk, cz, hu. Prednastavený je jazyk anglický teda en.

curl -H "Content-Language: sk" -X GET https://api.gramcrm.com/demo/api/v1/Ping/

Volanie vráti výsledok v jazyku Slovenskom. Taktiež vráti príslušný jazyk vo vrátenej hlavičke (Content-Language). Pokiaľ dôjde k zmene jazyka počas platnosti Tokenu. (teda napr. prvé API volanie „prepne“ token na sk tak všetky ďalšie aj keď nebudú definované v hlavičke Content-Language budú v sk jazyku). Ak token pracuje s viacerými jazykovými verziami je teda vhodné pre konzistentnosť posielať jazyk v každom API volaní.

Tlačové zostavy

Vygenerovanú tlačovú zostavu získame pomocou funkcie BuildReport. Pričom všetky hodnoty uvádzame v príslušnom URL.

Formát URL: BuildReport/[EntityName]/[EntityId]?Report=[ReportID]&Format=pdf

Príklad: Získanie konkrétnej tlačovej zostavy pre Entitu Cenová ponuka (Proposal) vo formáte PDF:

https://api.gramcrm.com/demo/api/v1/BuildReport/Proposal/ae751564-a5e1-438b-831f-31db0391b190?Report=23f3aad5-ff97-4805-bd57-f571c514aa42&Format=pdf

Súbory

Pridanie súboru uskutočníme prostredníctvom funkcie /File. Pričom samotný súbor posielame ako binary data.

Príklad: Nahratie súboru súboru c:\Upload\Invoice.pdf súboru:

curl --request PUT --data-binary "@c:\Upload\Invoice.pdf" -H "Token: 9468e366b59e11e78dd0618c6caea75d" https://api.gramcrm.com/demo/api/v1/File?Name=MyFirstInvoice.pdf -k

Odpoveď:

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

Súbor je nahratý do úložíska. Ak je z podporovaných, systém vytvorí náhľad súboru (štandardne PDF). Následne môžeme vytvorený súbor priradiť k požadovanému stĺpcu typu „File“. Štandardne napríklad k poznámke. Ak nedôjde k žiadnemu priradeniu súboru tak systém takýto súbor zo serveru odstráni do 24 hodín.

Príklad: Priradenie nahratého súboru ako príloha k faktúre:

PUT https://api.gramcrm.com/demo/api/v1/Note/
{
    "Title": "Uploaded invoice scan",
    "Parent": "{InvoiceId}",
    "Attachment": "7c693828-c473-4c5c-8487-0e42419e36c9",
}
Prevzatie súboru

Súbor môžeme prevziať pomocou funkcie /File:

curl -H "Token: 9468e366b59e11e78dd0618c6caea75d" https://api.gramcrm.com/demo/api/v1/File/7c693828-c473-4c5c-8487-0e42419e36c9 -k --output c:\Output\Invoice.pdf

Rozšírené API

V rámci API je možné vytvárať a upravovať aj samotné Entity, Polia Entít, Pohľady, Grafy, Nástenky, Pracovné postupy, Tlačové zostavy, Nastavovať oprávnenia, atď. …

Upozornenie: Nesprávnym použitím rozšíreného API môžete zmeniť aj štandardné správanie systému, prípadne znefunkčniť Vašu inštaláciu a taktiež poškodiť existujúce dáta. Preto túto časť odporúčame využívať len po dôkladnom oboznámení sa s fungovaním systému, absolvovaní školenia a konzultácii s našou podporou.

Polia Entít

Zoznam

Zoznam polí je možné získať pomocou funkcie /core/EntityField:

GET https://api.gramcrm.com/demo/api/v1/core/EntityField/

Obmedziť výpis pre konkrétnu Entitu je možné pomocou parametra „Entity“. Napríklad pokiaľ potrebujeme vypísať zoznam Polí pre Entitu „Account“:

GET https://api.gramcrm.com/demo/api/v1/core/EntityField/
{ "Entity": "Account"}

Pridanie nového Poľa

Pri pridávaní sú povinné 3 hodnoty. Názov Entity do ktorého pole pridávame, Názov („Name“) poľa a dátový typ „DataType“. Štandardným typom poľa je „edit“. Ak si prajeme vytvoriť iný typ použujeme aj parameter „Type“.

PUT https://api.gramcrm.com/demo/api/v1/core/EntityField/
{
    "Entity": "Account",
    "Name": "PocetObchodnikov",
    "Label": "Počet obchodníkov",
    "DataType": "number(11)"
}

Pozor! Nový pridané pole sa automaticky nezobrazí v prostredí aplikácie. Stĺpec budeme vedieť vybrať v pohľadoch avšak do Layoutov ho musíme pridať ručne či už cez API alebo v prostedí aplikácie.

Podporavané typy polí:

  • edit – Je štandardné editovateľné pole. Jeho hodnotu môžeme zmeniť prostredníctvom API alebo aplikácie
  • autonumber – Automaticky generovaná hodnota na základe definovaného patternu. Napríklad čísla dokladov a podobne
  • formula – Automaticky počítané údaje. Môžu byť matematického typu, napríklad môžeme spočítať rôzne polia, alebo textová hodnota
  • calculated – Automaticky počítaná hodnota z rôznych Entít. Napríklad suma faktúr, položiek atď.

Podporované dátové typy (DataType):

  • varchar(N) – Jednoriadkový text kde (N) je maximálny počet znakov. Napríklad varchar(100)
  • text – Viacriadkový text
  • date – Dátum
  • datetime – Dátum a čas
  • number(N) – Celé číslo kde N je maximálny počet čísel
  • float(N,D) – Číslo s desatinnou čiarkou kde N je maximálny počet pred desatinným číslom a D je max počet za desatinným číslom
  • currency(N,D) – Mena kde N je maximálny počet čísel pred desatinným číslom, a D – je počet čísel za desatinným číslom
  • percentage(N,D) – Percento, N a D je identické ako pri float a currency
  • lookup(Entita) – Prepojenie na konkrétnu Entitu
  • option(Name) – Zoznam
  • check – Zaškrtávacie políčko
  • related – Relácia na ľubovoľnú Entitu

Zmena pola

Postupujeme rovnako ako pri pridávaní pola k Entite. Treba mať na pamäti, že pri zmene dátového typu v niektorých prípadoch môže dôjsť k zmazaniu hodnôt, ktoré boli predtým uložené.

Pri požiadavke stačí poslať „Id“ a hodnoty, ktoré požadujeme zmeniť:

PUT https://api.gramcrm.com/demo/api/v1/core/EntityField/9dd67252-31aa-4468-8bd1-900aca6295b9
{
    "DataType": "number(5)",
    "Label": "Skutočný počet obchodníkov"
}

AccountInfo

Prostredníctvom tejto funkcie získate informácie o právnych subjektoch v Slovenskej a Českej republike. Môžete tak efektívne rozšíriť napríklad kontaktný formulár na webe a rovno doplniť kontakt do Leadu. Na vstupe je parameter Value.

PUT https://api.gramcrm.com/demo/api/v1/AccountInfo?Value=Arterio
Dátum poslednej aktualizácie 2. novembra 2023