top_pl
Logowanie

Bitrix24Care

Webhook

Usługa Bitrix24 oferuje rozbudowany interfejs REST API, który może być używany do rozszerzenia funkcjonalności i integracji z systemami innych firm. Metody REST mogą tworzyć i edytować elementy i zadania CRM, publikować wiadomości na Tablicy i realizować wiele innych funkcji. 

Jednak do niedawna życie pozornie nonszalanckiego dewelopera REST było utrudnione wizją nadchodzącego protokołu OAuth 2.0, który był niezbędny, a był trudny do wdrożenia. Mimo że minęło już sporo czasu, odkąd został wprowadzony, a obecnie jest używany przez największych producentów oprogramowania, wielu programistów wciąż niepokoi konieczność wdrażania go od podstaw. Inną wadą jest konieczność okazjonalnej aktualizacji tokenów uwierzytelniających, jeśli wymaganiem jest automatyczna, nienadzorowana, ciągła wymiana danych z Bitrix24. 

Czasami wszystko, czego programista potrzebuje, to połączenie instancji Bitrix24 do systemu innej firmy lub po prostu do prostego formularza internetowego. Powiedzmy, że szef cierpiący po wczorajszej imprezie na straszny ból głowy nagle chce opublikować raporty magazynowe na Tablicy. Co z tym zrobisz? 

Spokojnie, proszę Państwa. Ułatwiliśmy Wam życie: opracowaliśmy nowy system integracji Bitrix24, który idealnie pasuje do rozwiązań wewnętrznych. Mówię o „głośnych” webhookach. Cóż, „głośne” może być złym słowem: słyną one z tego, że uszczęśliwiają programistów.

Dzięki webhookom można skorzystać z metod API REST, oszczędzając przy tym konieczności wdrożenia OAuth 2.0. 

Webhooki przychodzące

Zobaczmy, jak z nich skorzystać. Załóżmy, że mamy formularz zwrotny na naszej stronie internetowej, który z jakiegoś powodu nadal nie wykorzystuje formularzy CRM Bitrix24. Jesteśmy przy tym na tyle uparci, aby zostawić formularz taki, w jakiej jest, dodając jakieś drobiazgi, które pozwolą na przetworzenie nowego leada po przesłaniu formularza.

Wystarczy otworzyć opcję Aplikacje > Webhooki i kliknąć polecenie Dodaj webhook: 

Wybierz opcje Webhook przychodzący (naszym zamiarem jest zewnętrzne połączenie z systemem Bitrix24, prawda?) i... oto nadchodzi formularz parametrów webhook.

Wprowadź nazwę i opis webhooka i wybierz moduł, do którego potrzebujesz dostępu. W tym przypadku, ponieważ chcemy dodać leadów, potrzebujemy dostępu do modułu CRM.

Kliknij pozycję Zapisz. Formularz pokaże pewne nowe informacje: 

Zobaczmy teraz, co zawiera ten adres URL. 

1. Jest to identyfikator użytkownika, którego uprawnienia dostępu będą dotyczyć danego webhooka. Oczywiście adres URL określa identyfikator użytkownika, który właśnie utworzył plik webhook. 
2. Kod webhooka. Dbaj o jego ochronę. Nie publikuj selfie z tym kodem na Instagramie. 3A. Metoda REST do wykonania. Metoda „profil” to tylko przykład; zamiast tego użyjemy crm.lead.add
3. Wszystko, co jeszcze musimy zrobić, to wywołać odpowiedni adres URL, który stworzyła dla nas sprytna maszyna, podając wymaganą nazwę metody. To wszystko.

Oto jak można to zrobić: 

<?
/**
 * Zapis danych do pliku dziennika.
 *
 * @param mixed $data
 * @param string $title
 *
 * @return bool
 */
function writeToLog($data, $title = '') {
 $log = "\n------------------------\n";
 $log .= date("Y.m.d G:i:s") . "\n";
 $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
 $log .= print_r($data, 1);
 $log .= "\n------------------------\n";
 file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
 return true;
}

$defaults = array('first_name' => '', 'last_name' => '', 'phone' => '', 'email' => '');

if (array_key_exists('saved', $_REQUEST)) {
 $defaults = $_REQUEST;
 writeToLog($_REQUEST, 'webform');

 $queryUrl = 'https://restapi.bitrix24.ru/rest/1/31uhq2q855fk1foj/crm.lead.add.json';
 $queryData = http_build_query(array(
 'fields' => array(
 "TITLE" => $_REQUEST['first_name'].' '.$_REQUEST['last_name'],
 "NAME" => $_REQUEST['first_name'],
 "LAST_NAME" => $_REQUEST['last_name'],
 "STATUS_ID" => "NEW",
 "OPENED" => "Y",
 "ASSIGNED_BY_ID" => 1,
 "PHONE" => array(array("VALUE" => $_REQUEST['phone'], "VALUE_TYPE" => "WORK" )),
 "EMAIL" => array(array("VALUE" => $_REQUEST['email'], "VALUE_TYPE" => "WORK" )),
 ),
 'params' => array("REGISTER_SONET_EVENT" => "Y")
 ));

 $curl = curl_init();
 curl_setopt_array($curl, array(
 CURLOPT_SSL_VERIFYPEER => 0,
 CURLOPT_POST => 1,
 CURLOPT_HEADER => 0,
 CURLOPT_RETURNTRANSFER => 1,
 CURLOPT_URL => $queryUrl,
 CURLOPT_POSTFIELDS => $queryData,
 ));

 $result = curl_exec($curl);
 curl_close($curl);

 $result = json_decode($result, 1);
 writeToLog($result, 'webform result');

 if (array_key_exists('error', $result)) echo "Error saving lead: ".$result['error_description']."<br/>";
}

?>
<fo rm method="post" action="">
    Name: <input type="text" name="first_name" size="15" value="<?=$defaults['first_name']?>"><br/>
    Last name: <input type="text" name="last_name" size="15" value="<?=$defaults['last_name']?>"><br/>
    Phone: <input type="phone" name="phone" value="<?=$defaults['phone']?>"><br/>
    E-mail: <input type="email" name="email" value="<?=$defaults['email']?>"><br/>
    <input type="hidden" name="saved" value="yes">
    <input type="submit" value="send">
</form>  


Kilka istotnych uwag. Przede wszystkim: nigdy nie twórz formularzy internetowych tak brzydkich i niezabezpieczonych, jak w przykładzie. Następnie: prawie wszystkie podejścia do integracji systemu Bitrix24 sprowadzają się do tych prostych kroków: utwórz adres URL; wypełnij zmienną $queryData (więcej informacji tutaj); zainicjuj metodę curl i wywołaj system Bitrix24 za pomocą wywołania curl_exec. Przetwórz odpowiedź JSON — i wszyscy są szczęśliwi. Nawet kac szefa się skończył. 

Podsumujmy trzy proste kroki: 

1. Dodanie webhooka i użycie parametrów webhook, aby uzyskać nowy, gorący URL w Bitrix24. 
2. Zastąpienie domyślnej nazwy metody REST taką, której potrzebujesz. Utworzenie tablicy danych zapytania. 
3. Wywołanie Bitrix24 za pomocą adresu URL. 

Jeśli chcesz przetestować swój nowy mały pomysł, otwórz formularz, wypełnij pola i prześlij go.вАУ Teraz przejdź do Bitrix24 i zobacz, czy dodano nowego leada. To wszystko — otwórz piwo i zrelaksuj się. 

Webhooki wychodzące

To nie wszystko, co możesz osiągnąć! Integracja może być realizowana obustronnie. Czasami od razu trzeba wysłać pewne informacje do systemu zewnętrznego, gdy tylko nastąpi zmiana w Bitrix24. Na przykład musisz zamówienie w niestandardowym systemie ERP musi być utworzone od razu, gdy przedstawiciel handlowy wprowadzi określony status umowy Bitrix24. 

Ponownie otwórz obszar Aplikacje > Webhooki, ale tym razem kliknij opcję Webhook wychodzący. Spowoduje to wyświetlenie innego formularza, ponieważ nie musimy tworzyć klucza przychodzącego. Musimy jednak wybrać zdarzenie, które po aktywacji wywoła nasz uchwyt.


Podaj adres URL uchwytu, nadaj nowemu webhookowi ładną i przejrzystą nazwę, a co najważniejsze wybierz zdarzenie ONCRMDEALUPDATE. Prześlij formularz, aby utworzyć klucz uwierzytelniający, którego będziemy używać w naszym uchwycie, aby sprawdzić, czy wywołanie pochodzi z Bitrix24, a połączenie jest wiarygodne. Może to nie być najmocniejszy środek bezpieczeństwa, ale w większości przypadków wystarczy. 


Uchwyt z tego przykładu wykonuje najprostsze zadanie: rejestruje wszystko, co zostało mu przekazane. 

<?

print_r($_REQUEST);
writeToLog($_REQUEST, 'incoming');

/**
 * Zapis danych do pliku dziennika.
 *
 * @param mixed $data
 * @param string $title
 *
 * @return bool
 */
function writeToLog($data, $title = '') {
 $log = "\n------------------------\n";
 $log .= date("Y.m.d G:i:s") . "\n";
 $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
 $log .= print_r($data, 1);
 $log .= "\n------------------------\n";
 file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
 return true;
}  


Jeśli teraz otworzymy deal do edycji zapiszemy zmiany, w dzienniku pojawi się wpis: 

2017.01.17 12:58:29
incoming
Array
(
    [event] => ONCRMDEALUPDATE
    [data] => Array
     (
      [FIELDS] => Array
          (
           [ID] => 662
          )

     )

    [ts] => —Е—Е—Е
    [auth] => Array
     (
      [domain] => —Е—Е—Е.bitrix24.com
      [client_endpoint] => https://—Е—Е—Е.bitrix24.com/rest/
      [server_endpoint] => https://oauth.bitrix.info/rest/
      [member_id] => —Е—Е—Е
      [application_token] => —Е—Е—Е
     )

)
  

Widzisz, jak proste było uzyskanie informacji o zmianie umowy? Teraz możemy użyć omówionego wcześniej webhooka przychodzącego, aby uzyskać szczegóły dealu. Wywołaj w tym celu metodę crm.deal.get.

Wsparcie automatyzacji CRM

Jak widać, webhooki są tak proste i użyteczne, że zrobiliśmy jeszcze jeden krok w stronę automatyzacji CRM. 

Otwórz formularz preferencji CRM i wybierz w menu polecenie Automatyzacja i kliknij polecenie Deale. 

Aby zachować prostotę rozwiązania, użyjemy tego samego programu obsługi ruchu wychodzącego, który już utworzyliśmy. Tym razem jednak bezpośrednio go wywołamy. 

Kliknij polecenie Konfiguruj reguły automatyzacji i dodaj regułę do dowolnego etapu transakcji, wybierając jako jej typ ustawienie Webhook. Po wybraniu typu reguły pojawi się nowy formularz, w którym określimy adres URL i parametry, które zostaną mu przekazane. 

Jako przykład przekażmy do uchwytu etap dealu: 

Zapisz wszystko (nie cały świat, po prostu kliknij w formularzach opcję Zapisz). Otwórz dowolny deal i zmień jego etap na ten, dla którego stworzyliśmy regułę. Spowoduje to uruchomienie webhooka wychodzącego, a uchwyt doda do dziennika dane dealu:

2017.01.17 12:58:27
incoming
Array
(
    [status] => New
    [document_id] => Array
     (
      [0] => crm
      [1] => CCrmDocumentDeal
      [2] => DEAL_662
     )

    [auth] => Array
     (
      [domain] => xxx.bitrix24.com
      [client_endpoint] => https://xxx.bitrix24.com/rest/
      [server_endpoint] => https://oauth.bitrix.info/rest/
      [member_id] => xxx
     )

) 

To pomogło Dzięki :) To nie pomogło Przykro nam :( Komentarz
Czy możesz nam powiedzieć, dlaczego:
Nie tego szukam
To zbyt skomplikowane