Speciální služby CRM systému

POST /api/services/mailer

Zprostředkování odeslání e-mailu. Internetové aplikace typicky implementují odeslání e-mailu pomocí přímého přístupu k SMTP serveru. Zde popsaná služba je substitucí za SMTP server, přičemž výhodou využití tohoto API je:

• E-mail je okamžitě k dispozici v databázi CRM.
• E-mail může být napárován na záznamy (kontakt, příležitost, kampaň, objednávka, ...).
• E-mail může obsahovat slučovací pole, která jsou vyhodnocena před odesláním a text e-mailu může být personalizovaný (např. obsahovat oslovení).
• CRM umí založit nový kontakt v dababázi, podle zaslaných údajů (pokud už tam není).
• CRM ověřuje existenci GDPR souhlasů.
• Služba může poslat jen zjednodušené HTML tělo a CRM je "obalí" centrálně spravovanou šablonou (aplikuje jednotný styl).

Službu můžete chápat jako jakousi proxy k SMTP server s tou výhodou, že odeslaný e-mail bude řádně umístěn ve firemním CRM. Funguje takto:

1. Proběhne validace přijatých parametrů (povinné to, subject, body-html).
2. Pokud jsou v parametrech reference na kontakt (org, branch, individual), je tento nalezen v databázi. Pokud ne, tak se CRM pokouší najít kontakt podle e-mail a když i to selže, tak podle telefonu. Když ani telefon "nezabere", je v databázi CRM vytvořen nový kontakt (firma nebo osoba) ze zaslaných údajů (company, firstname, surname). Pokud je znám jen e-mail, založí se nový kontakt, jako "anonymní".
3. Pokud jste zaslali parametr consents, CRM ověří, jestli kontakt nalezený v předchozím bodě má GDPR souhlasy požadované parametrem.
4. CRM zvolí vhodný e-mailový účet podle parametru from (musí být korektně nastaven před prvním voláním tohoto API).
5. Pokud jste zaslali parametr template s kódem šablony, systém použije tuto šablonu k zkompletování HTML těla zprávy. (viz dále)
6. CRM nahradí všechny slučovací značky, jako např. [[[salutation]]] pro vložení oslovení.
7. Je vytvořen záznam v outboxu poštovního účtu a CRM se pokusí e-mail co nejdřív odeslat. Pokud jste poslali parametry campaign, opportunity, busCase nebo problem, je e-mail napárován na příslušné existující záznamy.

Použití předlohy

Volitelný parametr template umožňuje "stylovat" tělo zprávy pomocí předlohy (předlohy se spravují v nastavení CRM). Předloha musí být ve formátu HTML a musí obsahovat slučovací pole [[[html]]]. V místě, kde je v kódu umístěno toto slučovací pole, bude při odesílání vložen text, který přišel v parametru body-html požadavku.

CRM akceptuje požadavek ve dvou dostupných formátech. JSON a formulářová data.

Požadavek (application/x-www-form-urlencoded)

Požadavek (application/json)

V následujícím příkladu JSON požadavku jsou všechny dostupné parametry, ale v praxi nejspíš nebudete všechny zasílat. Povinné parametry jsou označeny.

{
  "app" : "Kafco",
  "from" : "info@kafco.cz",
  "to" : "jan.novak@ruzicka.cz", /* povinné */
  "cc" : "petra.ruzickova@ruzicka.cz",
  "company" : "Růžička s.r.o.",
  "firstname" : "Jan",
  "surname" : "Novák",
  "phone" : "+420606123456",
  "subject" : "Potvrzení objednávky", /* povinné */
  "body-html" : "<p>[[[Potvrzení objednávky]]],</p> <p>děkujeme za Vaši ...", /* povinné */
  "body-plain" : "[[[Potvrzení objednávky]]],\nděkujeme za Vaši ...",
  "consents" : "1,10",
  "template" : 152,
  "org" : 124,
  "branch" : 1204,
  "individual" : 652,
  "campaign" : 12,
  "opportunity" : 356,
  "busCase" : 421,
  "problem" : 3121
}

Odpověď (application/json)

200 OK

CRM přijalo váš požadavek a e-mail byl umístěn do outboxu. Nemusí nutně znamenat, že e-mail byl doručen příjemci (ten může mít plný mailbox nebo SMTP server mohl zkolabovat).

{
  "ok" : true,
  "id" : "25636"  /* Kód e-mailu v CRM */
}

POST /api/services/search

Fulltextové vyhledávání záznamů v CRM.

Požadavek (application/json)

Pomocí JSONu v požadavku specifikujete, co hledáte.

{
  "query": "bitcoin", /* Dotaz */
  "position": 0,  /* Pozice vrácené stránky záznamů - při prvním dotazu neposílejte */
  "all": true,  /* Rozsah hledání - všude */
  "scope": [  /* Pokud potřebujete omezit hledání jen na určité typy záznamů. Vynechejte parametr "all" a použijte "scope" s výčtem */
    "CU", "MA", "OP" 
  ],
}

Platné hodnoty v poli "scope"

Rozšiřující pluginy mohou definovat další hledatelné záznamy.

Odpověď (application/json)

200 OK

Tělo odpovědi bude seznam nalezených záznamů:

{
  "items" : [
    {
      "title" : "Potvrzení nákupu Bitcoinu",  /* Název nalezeného záznamu */
      "icon" : "i/case.jsp",  /* Relativní URL ikony 18x18 px */
      "url" : "editBusCaseLow.do?id=124", /* URL pro otevření editoru záznamu */
      "type" : "BC",  /* Typ záznamu, který byl nalezen */
      "id" : "124",   /* Kód záznamu */
      "description" : "Toto je stručný popis záznamu, který může chybět"
    },
    /* ... */
  ]
}

POST /api/services/search/suggest

Našeptávač pro fulltextové vyhledávání záznamů v CRM. Toto volání neprování plné hledání, ale snaží se našeptávat možné výsledky podle (nedopsaného) dotazu. Formát JSONu požadavku i odpovědi je stejný, jako u koncového bodu /api/services/search. Liší se pouze způsob interpretování dotazu v query parametru (našeptávač předpokládá, že dotaz není kompletní slovo) a tento "našeptávací" koncový bod neposílá description v odpovědi.