6.2

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:

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)

ParametrTypPopisPříklad
appstringIdentifikátor klientské aplikace. Vkládá se do hlavičky X-Remote-App odesílaného e-mailuKafco
fromstringE-mailová adresa odesilateleinfo@kafco.cz
tostringE-mailová adresa příjemcejan.novak@ruzicka.cz
ccstringE-mailová adresa příjemce kopie
bccstringE-mailová adresa příjemce skryté kopie
companystringNázev společnosti příjemceRůžička s.r.o.
firstnamestringJméno příjemceJan
surnamestringPříjmení příjemceNovák
phonestringTel. číslo příjemce606 123 456
subjectstringNázev (věc) e-mailuPotvrzení objednávky
body-htmlstringText e-mailu ve formátu HTML...
body-plainstringText e-mailu v plain textu...
consentsstringSeznam kódů souhlasů, které budou ověřeny před odesláním (čárkou oddělená celá čísla)1, 10
templateintKód předlohy, který bude použita pro obalení těla HTML e-mailu152
orgintKód existujícího kontaktu (společnost)124
branchintKód existujícího kontaktu (pobočka)1204
individualintKód existujícího kontaktu (osoba)652
campaignintKód existující kampaně12
opportunityintKód existující příležitosti356
busCaseintKód existující objednávky421
problemintKód existujícího problému (helpdesk)3121

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 */
  "scope": [  /* Pokud potřebujete omezit hledání jen na určité typy záznamů. Vynechejte, pokud chcete hledat všude */
    "customers", "mails", "tasks", "events", "opportunities", "buscases", "contacts" /* telefonáty */, 
    "products", "problems", "offers", "files", "invoices", "knowledges"
  ],
}

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.