README

Cloud CRM REST API je programové rozhraní systému RAYNET CRM, které umožňuje pracovat s daty uvnitř CRM z aplikací třetích stran. Komunikace probíhá standardním protokolem HTTP s ohledem na REST principy.

Připojení k RAYNET CRM

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/'

Datové typy

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

Filtrování seznamu

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

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ě

Stránkování seznamu

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

Fulltext

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

Limity API

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.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/wpify/raynet-api-php-sdk.git"
    }
  ],
  "require": {
    "wpify/raynet-api-php-sdk": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: instanceName
$config = RaynetApiClient\Configuration::getDefaultConfiguration()->setApiKey('X-Instance-Name', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = RaynetApiClient\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-Instance-Name', 'Bearer');

// Configure HTTP basic authorization: basicAuth
$config = RaynetApiClient\Configuration::getDefaultConfiguration()
              ->setUsername('YOUR_USERNAME')
              ->setPassword('YOUR_PASSWORD');


$apiInstance = new RaynetApiClient\Api\AktivityApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$offset = 0; // int | Zobrazeni zaznamu od zacatku
$limit = 100; // int | Maximální počet vrácených událostí je `1000`
$sort_column = id; // string | 
$sort_direction = ASC; // string | 
$fulltext = myText; // string | Fulltextové vyhledání v seznamu. Operátor se v tomto případě nepoužívá.
$id = 3; // int | Filtrování aktivit podle ID. Lze využít operátoru `EQ`, `NE`, `GT`, `GE`, `LT`, `LE`
$title = myTag; // string | Filtrování aktivit podle předmětu. Lze využít operátoru `EQ`, `NE`, `LIKE`, `LIKE_NOCASE`
$scheduled_from = 2022-06-01 10:00; // string | Filtrování aktivit podle data naplánování (\"od\"). Lze využít operátoru `GT`, `GE`, `LT`, `LE`
$scheduled_till = 2022-06-01 10:00; // string | Filtrování aktivit podle data naplánování (\"do\"). Lze využít operátoru `GT`, `GE`, `LT`, `LE`
$completed = 2022-06-01 10:00; // string | Filtrování aktivit podle data realizování. Lze využít operátoru `GT`, `GE`, `LT`, `LE`
$category_id = 3; // int | Filtrování aktivit podle ID kategorie. Lze využít operátoru `EQ`, `NE`, `GT`, `GE`, `LT`, `LE`
$status = SCHEDULED; // string | Filtrování aktivit podle statusu. Lze využít operátoru `EQ`, `NE`, `LIKE`, `LIKE_NOCASE`
$owner_id = 3; // int | Filtrování aktivit podle ID kontaktní osoby, která je vlastníkem aktivity. Lze využít operátoru `EQ`, `NE`, `GT`, `GE`, `LT`, `LE`
$person_filter = 3; // int | Filtrování aktivit podle ID kontaktní osoby, která je participantem. Nelze využít standardních operátorů.
$company_context_filter = 3; // int | Filtrování aktivit podle ID klienta, kterého se aktivity týkají (klient je napojený v kontextu nebo je participantem). Nelze využít standardních operátorů.
$lead_context_filter = 3; // int | Filtrování aktivit podle ID leadu, kterého se aktivity týkají (lead je napojený v kontextu nebo je participantem). Nelze využít standardních operátorů.
$business_case = 3; // int | Filtrování aktivit podle ID obchodního případu, kterého se události týkají. Lze využít operátoru `EQ`, `NE`, `IN`, `NOT_IN`
$row_info_created_at = 2022-06-01 10:00; // string | Filtrování aktivit podle data vytvoření. Lze využít operátoru `GT`, `GE`, `LT`, `LE`
$row_info_updated_at = 2022-06-01 10:00; // string | Filtrování aktivit podle posledního data upravení. Lze využít operátoru `GT`, `GE`, `LT`, `LE`
$row_info_last_modified_at = 2022-06-01 10:00; // string | Filtrování aktivit podle posledního data modifikace (vytvoření nebo upravení). Lze využít operátoru `GT`, `GE`, `LT`, `LE`. Vhodné pro periodickou detekci změn.
$view = rowInfo; // string | Pokud je hodnota rovna `rowInfo`, jsou vráceny pouze stavové informace o záznamu (data vytvoření, upravení, verze, ...). Vhodné pro periodickou detekci změn.
$tags = tags; // string | Filtrování podle štítku. Je možné hledat podle více štítků oddělených čárkou. Záznam potom musí alespoň jeden obsahovat (`tag1,tag2`).

try {
    $apiInstance->activityGet($offset, $limit, $sort_column, $sort_direction, $fulltext, $id, $title, $scheduled_from, $scheduled_till, $completed, $category_id, $status, $owner_id, $person_filter, $company_context_filter, $lead_context_filter, $business_case, $row_info_created_at, $row_info_updated_at, $row_info_last_modified_at, $view, $tags);
} catch (Exception $e) {
    echo 'Exception when calling AktivityApi->activityGet: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://app.raynet.cz/api/v2

Models

Authorization

basicAuth

Type: HTTP basic authentication

instanceName

Type: API key
API key parameter name: X-Instance-Name
Location: HTTP header

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 2.0.0
Build package: org.openapitools.codegen.languages.PhpClientCodegen

wpify / raynet-api-php-sdk

Maintainers

Details