Komunikačním protokolem je HTTP, proto je možné použít libovolnou aplikaci nebo knihovnu, která tento protokol podporuje. Pro demonstraci bude využita aplikace curl. Alternativou je například add-on Talend API Tester do prohlížeče Google Chrome. Přístup je zabezpečen pomocí basic authentication (uživatelským jménem a API klíčem) a šifrován protokolem TLSv1.2 a vyšším (HTTPS) pro zajištění maximální bezpečnosti. V hlavičce požadavku je nutné zaslat název Vaší instance (např. moje-crm).

  curl -X GET -u 'uzivatel:api-klic' -H 'X-Instance-Name: moje-crm' 'https://app.raynet.cz/api/v2/company/'

Hodnoty jednotlivých atributů v systému RAYNET CRM jsou tvořeny několika základními datovými typy:

• Řetězec - Textová hodnota.

• Číslo - Číselná hodnota. V závislosti na kontextu se může jednat buď o číslo celé nebo o číslo desetinné. V desetinných číslech se používá desetinná tečka.

• Pravdivostní hodnota - Hodnota ANO/NE. Pro hodnotu ANO lze využít true, on, yes a 1; pro hodnotu NE pak false, off, no a 0.

• Datum - Datum jako řetězec ve formátu yyyy-MM-dd.

• Datum a čas - Datum a čas jako řetězec ve formátu yyyy-MM-dd HH:mm. Akceptovány jsou také datum a čas ve formátu ISO8601 (např. 2022-01-01T12:00:00.000+01:00).

• Reference - Datový typ reference odkazuje na jiný záznam v systému RAYNET CRM. V příchozích datech je reference mapou (JavaScriptový objektem), která obsahuje klíče:

  • id - Identifikátor referencovaného záznamu.

Datum a čas

Datum a čas jako řetězec ve formátu yyyy-MM-dd HH:mm je v časové zóně uživatele, přes kterého jsou API požadavky realizovány. Pro filtrování a zápis (PUT, POST) je možné využít oba formáty (yyyy-MM-dd HH:mm, ISO8601).

V response je ve výchozím stavu datum a čas formátován jako yyyy-MM-dd HH:mm v časové zóně uživatele. Přidáním parametru dateFormat=ISO8601 lze ovlivnit výstupní formát, kdy bude hodnota formátována do tvaru 2022-01-01T12:00:00.000+01:00. např. https://ww....company/?dateFormat=ISO8601

Operátory pracující nad atributy a hodnotami jsou následující:

• EQ - Test na rovnost hodnot.

• EQ_OR_NULL - Test na rovnost nebo prázdnou hodnotu.

• NE - Test na nerovnost hodnot.

• NE_OR_NULL - Test na nerovnost nebo prázdnou hodnotu.

• LT - Hodnota v databázi je menší než zadaná.

• LE - Hodnota v databázi je menší nebo rovna než zadaná.

• GT - Hodnota v databázi je větší než zadaná.

• GE - Hodnota v databázi je větší nebo rovna než zadaná.

• LIKE - Test na hodnotu odpovídající výrazu (např. hodnota filtru ABC% nalezne všechny záznamy, které začínají znaky ABC).

• LIKE_NOCASE - Obdoba LIKE, ale bez ohledu na malá a velká písmena.

• IN - Test na rovnost (více) hodnot oddělených čárkou. Správný formát vstupu je např.: 1,2,3,4.

• NOT_IN - Test na nerovnost (více) hodnot oddělených čárkou. Správný formát vstupu je např.: 1,2,3,4.

• CUSTOM - Speciální operátor - chování testu je popsáno dále v dokumentaci.

Výchozím operátorem je rovnost EQ. Operátor se zapisuje do hranatých závorek za název atributu. Je tak možné zadat více filtrovacích kritérií nad stejným atributem. https://app..../?validFrom[GT]="2014-06-01"&validTill[LT]="2014-06-10" Častým scénářem je vyfiltrování všech záznamů, které mají daný atribut prázdný nebo naopak neprázdný. Pro tyto účely lze použít hodnotu prázdný řetězec v kombinaci s operátorem EQ nebo NE.

Uspořádání seznamu je kontrolováno parametrem sortColumn a sortDirection. U každého API je výčet hodnot, pomocí kterých lze seznam řadit. Parametr sortDirection může nabývat hodnot:

• ASC - Hodnoty jsou řazeny vzestupně

• DESC - Hodnoty jsou řazeny sestupně

Seznam je možné stránkovat nastavením parametrů offset a limit. Offset udává první záznam, který bude zobrazen, limit pak počet záznamů. Maximální velikost stránky je 1 000 položek. Například https://app..../?offset=0&limit=2

Ve většině seznamů je možné využít fulltextové vyhledání podle zadaného textového řetězce. Slouží k tomu parametr fulltext, který se aplikuje např. takto: https://app..../?fulltext=nejakytext

Každá API odpověď obsahuje hlavičky, které popisují stav využití API pro danou instanci.

curl -X GET -u 'uzivatel:api-klic' -H 'X-Instance-Name: moje-crm' 'https://app.raynet.cz/api/v2/company/'

HTTP/1.1 200 OK
Status: 200 OK
X-Ratelimit-Limit: 24000
X-Ratelimit-Remaining: 23999
X-Ratelimit-Reset: 1508889600

Význam jednotlivých hlaviček je následující:

Pokud je limit překročen, je navrácena chybová hláška s HTTP kódem 429 Too Many Requests:

{
  "type": "RequestLimitReached",
  "message": "API request limit reached. See the X-RateLimit-* headers and check out the API documentation for more details."
}

Co když mi limity nestačí

Ve výchozím stavu je přístup limitován na 24 000 požadavků za den (uvažováno od půlnoci do další půlnoci v časové zóně UTC). V případě, že limit pro vaši integraci nestačí, kontaktujte naší zákaznickou podporu na e-mailu podpora@raynet.cz a spolu se určitě dobereme vhodného řešení.

Špatné přihlášení

V případě zaslaní více než 20 požadavků se špatnými přihlašovacími údaji, bude tento přístup na 60 minut zablokován. Toto omezení platí pro konkrétní IP adresu.

API pro práci s klienty.