Webhooki umożliwiają integrację systemu Taxxo z innymi systemami (CRM,ERP, itp.) poprzez automatyczne powiadamianie ich o wystąpieniu zdarzenia w Platformie Taxxo. Więcej o webhookach (tu link do https://en.wikipedia.org/wiki/Webhook )
Poniżej kroki należy wykonać aby wykonać integrację wykonać integracje przy użyciu Webhook’ów.
Krok 1. Potrzebujesz konta klienta Taxxo na poziomie Power lub wyższym Możesz aktywować ten poziom bezpłatnie na 30 dni.
Krok 2. Wejdź na stronę konfiguracji Webhook’ów pod adresem
https://platforma2.taxxo.pl/TX20/IntegracjaAPI.aspx?Tab=Webhook
lub za pośrednictwem prawego górnego menu Integracje/API zakładka Webhook
Krok 3. Naciśnij w menu „Dodaj webhook”
Określ:
- Nazwę własną webhooka – np. „Utworzenie nowej faktury”
- Jakie zdarzenie w Taxxo ma uruchamiać wywołanie TEGO webhooka (np. InvoiceCreated określa utworzenie nowej faktury w Taxxo)
- Gdzie ma zostać wysłana informacja o wystąpieniu zdarzenia
- Metoda (POST/PUT/DELETE) – zazwyczaj POST
- Adres URL (wymagane bezpieczne połączenie – rozpoczynające się od https://)
- Możliwy jest opcjonalne określenie typu autoryzacji – np. wysłanie w żądaniu nagłówka (header) klucza x-api-key – z wpisaną tutaj Twoją poufną zawartością – aby wiadomo było że informacja pochodzi od Taxxo a nie od innego nadawcy.
Jeżeli potrzeba przetestować działanie funkcji webhook przed implementacją - polecamy użyć jednej z dostępnych usług online np. https://webhook.site/ - wygeneruje ona indywidualny URL i zapamięta ze szczegółami wszystkie wysłane pod niego informacje i pozwoli je obejrzeć w przyjazny sposób
Zakładka Dokumentacja zawiera informacje o wybranym zdarzeniu, które ma generować komunikat. Dostępny jest krótki opis zdarzenia oraz przykładowe dane które zostaną wysłane na wskazany URL w przypadku wystąpienia zdarzenia.
Dla zdarzenia InvoiceCreated będzie to:
{
"Info":{
"UID":"SAMPLE_e481c136-9324-4632-8f6c-d36f5beed398",
"TimeStamp":"2021-03-30T22:57:03.606771+02:00",
"TypeCode":109,
"Type":"InvoiceCreated"
},
"Context":{
"CustomerId":12345,
"CustomerName":"Firma Testowa SA",
"CustomerNIP":"1234567890",
"AccountingOfficeId":999,
"AccountingOfficeName":"Biuro Rachunkowe ",
"UserId":123,
"UserLogin":"Testowy"
},
"Data":{
"InvoiceId":"53",
"InvoiceNumber":"FV 232/2020",
"BuyerName":"Top Company",
"Amount":"100 EUR"
}
}
Krok 4. Testowanie wysyłki webhook – oznacz dodany webhook I wybierz opcję „Wygeneruj i wyślij przykładowe dane”
Przykładowy podgląd danych na stronie webhook.site
Krok 5. Zintegruj swoją aplikację z realnymi danymi wysyłanymi przez aplikację
Co zrobić po odebraniu danych wygenerowanych przez webhook w integrowanej aplikacji?
Jeżeli zdarzenie nie prześlę wszystkich niezbędnych informacji – a zawarty w nim jest ID (np. InvoiceID) – można wykorzystać „klasyczne” API do pobrania niezbędnych informacji - przeczytaj artykuł API - Jak rozpocząć integrację z Taxxo wykorzystując API?
Krok 6. Monitoruj wysyłkę Webhooków
Na zakładce Webhook z listą zdefiniowanych zdarzeń wybierz opcję „Log ostatnich zdarzeń”.
Jest tu informacja o ostatnich wygenerowanych zdarzeniach i podjętych próbach ich wysyłki.
W kolumnie „Status doręczenia” – mamy odpowiedź serwera HTTP – (200 zwyczajowo oznacza prawidłowy odbiór).
Mamy ewentualny komunikat o błędzie, liczbę podjętych prób przy wysyłce oraz możliwość podejrzenia danych przesłanych w zdarzeniu („tooltip” na ikonie w kolumnie „Dane”)
Webhook zostanie wysłany w ciągu kilku minut na wskazany URL. W przypadku problemu z dostarczeniem Taxxo ponawia 4 krotnie próbę wysyłki z coraz większym czasem opóźnienia.
Uwaga! Jeżeli przez okres kilku dni adres URL podany dla webhooka nie będzie odpowiadał – Taxxo automatycznie zablokuje webhook i będzie potrzeba jego ręcznego odblokowania po usunięciu problemu z serwerem docelowym.
W razie pytań odnośnie Webhooków w Taxxo zapraszamy do kontaktu: api@taxxo.pl