Integracja danych z Fakturowni za pomocą webhooków

Utworzono: 2015-07-15
Ostatnia aktualizacja: 2022-10-04
Liczba odwiedzin posta: 4927

Webhooki to - obok interfejsu programistycznego API - mechanizm pozwalający na komunikację pomiędzy serwerami. Przeznaczony jest głównie dla deweloperów i zaawansowanych Użytkowników.

Zastosowanie webhooków zmniejsza obciążenie serwera aplikacji, ponieważ potrzebne informacje są automatycznie wysyłane w chwili, kiedy wystąpi określone zdarzenie, więc nie trzeba odpytywać intefejsu API, czy zaszły jakiekolwiek zmiany. Powiadomienia o zdarzeniach są otrzymywane dokładnie w momencie ich zaistnienia, bez konieczności zbyt częstego odpytywania aplikacji.

Webhook posiada:

  • typ, który określa, kiedy webhook ma zostać wysłany (po stworzeniu/zaktualizowaniu/usunięciu klienta)

  • URL, czyli adres URL, pod który wysyłany jest webhook

  • API token, czyli token uwierzytelniający, który użytkownik może dodać do webhooka i który będzie widoczny pod kluczem 'api_token'

Webhook to POST wysyłany na wskazany URL. Struktura musi odpowiadać danym, które mają być przekazywane.

Aby komunikować zmiany w zakresie klientów prześlij odpowiedni POST, np: 

{
client_id: <unikalne ID reprezentujące klienta w bazie Fakturowni>,
client: { <słownik reprezentujący klienta w Fakturowni> },
app_name: 'fakturownia',
api_token: <api_token wpisany w webhooku przez uzytkownika>,
locale: I18n.locale (np. 'pl')
}

 

Faktury


Przykładowy request wysyłany przy utworzeniu faktury:

{
  "id": 111,
  "deal": {
    "name": "Chleb",
    "description": "razowy",
    "price": "12.3",
    "paid": false,
    "url": "https://test.fakturownia.net/f/06-2022/123,
    "date": "2022-07-26",
    "invoice_no": "61/2022",
    "kind": "vat",
    "status": "issued",
    "currency": "PLN",
    "external_ids": {
      "fakturownia": 111
    },
    "client": {
      "name": "Edward",
      "tax_no": "",
      "first_name": "",
      "last_name": "",
      "bank_account": "",
      "bank_account_id": null,
      "register_number": "",
      "skip_webhooks": true,
      "external_ids": {
        "fakturownia": 111
      }
    },
    "skip_webhooks": true
  },
  "app_name": "fakturownia",
  "api_token": "",
  "locale": "pl"
}

 

Klienci 

Przykładowy request wysyłany przy utworzeniu klienta:


{
  "client": {
    "id": 111,
    "name": "Edward",
    "tax_no": "",
    "post_code": "",
    "city": "",
    "street": "",
    "first_name": "",
    "country": "",
    "email": "",
    "phone": "",
    "www": "",
    "fax": "",
    "street_no": null,
    "kind": "buyer",
    "bank": "",
    "bank_account": "",
    "bank_account_id": null,
    "shortcut": "Edek",
    "note": "",
    "last_name": "",
    "deleted": false,
    "discount": null,
    "payment_to_kind": "",
    "use_delivery_address": false,
    "delivery_address": "",
    "company": true,
    "mobile_phone": "",
    "register_number": "",
    "external_id": "",
    "external_ids": {
      "fakturownia": 111
    },
    "buyer": {},
    "skip_webhooks": true
  },
  "app_name": "fakturownia",
  "api_token": "",
  "locale": "pl"
}

Produkty


Przykładowy request wysyłany przy utworzeniu produktu:
{
  "product": {
    "id": 111,
    "name": "Chleb",
    "code": "",
    "price_net": "10.0",
    "tax": "5",
    "price_gross": "10.5",
    "currency": "PLN",
    "description": "",
    "stock_level": "0.0",
    "disabled": false,
    "external_ids": {
      "fakturownia": 111
    },
    "category_name": null,
    "skip_webhooks": true
  },
  "app_name": "fakturownia",
  "api_token": "",
  "locale": "pl"
}


Powrót


Komentarze

Avatar sugester medium
wmajchrzak
Dzień dobry.

Czy po wywołaniu Requestu fakturownia oczekuje jakiejś konkretnej odpowiedzi np. Header 200 OK? Zastanawiam się co w przypadku gdy na naszym serwerze pojawi się np. błąd lub zabraknie komunikacji. Czy fakturownia będzie ponawiać ten request do czasu aż dostanie prawidłową odpowiedź?

2019-06-28 09:36

Zgłoś naruszenie zasad

piotr.wajs
piotr.wajs
Odpowiedź główna   Dzień dobry,

dziękuję za zgłoszenie.
Skieruje Pana zapytanie do programistów. Jak tylko otrzymam odpowiedź przekażę ją niezwłocznie.
Pozdrawiam,
Piotr

2019-08-21 16:57

Zgłoś naruszenie zasad

Avatar sugester medium
anonim
czy oznacanie fv jako opłacona, powoduje wysłanie webhook?

2022-08-03 17:22

Zgłoś naruszenie zasad

piotr.wajs
piotr.wajs
Odpowiedź główna   Dzień dobry, 
jak tylko otrzymam informacje od programistów, przekażę ją Państwu. 

2022-08-04 11:06

Zgłoś naruszenie zasad

Avatar sugester medium
anonim
czy można dodac kwotę netto tam?

2022-09-30 14:07

Zgłoś naruszenie zasad

piotr.wajs
piotr.wajs
Odpowiedź główna   Dzień dobry,
wracam z odpowiedzią.
zmiana statusu na "opłacona" powoduje update na istniejącej fakturce, więc jeśli ma Pan wybrany webhook invoice:update to jak najbardziej zostaną przesłane zaktualizowane dane pod wskazany adres.
Kwota netto również jest możliwa do dodania.
Wystarczy dodać klucz "price_net" do "attributes_for_api", tzn.:

module InvoiceWebhooks

def invoice_client_attributes(client)
...
end

def attributes_for_api
ret = {
name: self.try(:positions).try(:first).try(:name),
description: self.description,
# client_id: self.client_id,
price: self.price_gross,
price_net: self.price_net,
... }
}
Pozdrawiam,
Piotr

2022-10-04 08:59

Zgłoś naruszenie zasad

Dodaj komentarz