API
Dokumentacja API DLA APLIKACJI FARA E-INTENCJE 3.0
E-Intencje 3.0 dostępne są w programie FARA od wersji 5.0.80.34
URL: https://signum-net.pl
Ostatnia aktualizacja: 8.06.2025
Aby korzystać z API do pobierania danych z księgi intencji programu FARA należy najpierw aktywować udostępnianie u konkretnego klienta. W tym celu należy w programie FARA danego klienta przejść do funkcji udostępniania:
Okno główne programu FARA -> Intencje -> E-intencje -> Dostosuj
W oknie Dostosuj trzeba przejść na zakładkę API i integracje i wybrać z listy dostawcę usługi i kliknąć w przycisk Włącz udostępnianie.
Jeśli usługodawcy nie ma na liście można wybrać ostatnia opcję „Inny dostawca usług”
Przy takim wyborze należy kliknąć w przycisk Włącz udostępnianie – wówczas system wygeneruje dla dostawcy klucz API i umieści go w polach w oknie.
Do autoryzacji w systemie niezbędne są 2 parametry:
POST
| { |
| "uid" : NN, |
| "apiKey" : "XXX" |
| } |
| { |
| "token" : "XXX", |
| "error" : "error message" |
| } |
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| } |
| { |
| "success" : true, |
| "message" : "Logged out successfully" |
| } |
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| "church" : N |
| } |
| { |
| "error" : "error message" |
| "data" : [ |
| {"church": 99, "faraid": 99999, "id": 999999, "mass": ""O dary Ducha Świętego, wszelkie potrzebne łaski", "massdate": "2025-05-04","masshour": 700, "reservation": false}, |
| {"church": 99, ........} |
| ] |
| } |
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| "church" : N |
| } |
| { |
| "error" : "error message" |
| "data" : [ |
| {"church": 99, "faraid": 99999, "id": 999999, "massdate": "2025-05-04","masshour": 700, "reservation": false, "stage": 1}, |
| {"church": 99, ........} |
| ] |
| } |
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| } |
| { |
| "error" : "error message" |
| "data" : [ |
| {"id": 1, "type": 1, "symbol": "XXX", "data": "Kościół parafialny", "allow_order_from_calendar": 1,"allow_order_with_no_date": 0, collective_limit:0}, |
| {"id": 1, ........} |
| ] |
| } |
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| } |
{„error” : „opis błędu”} lub json z ustawieniami. Poniżej zamieszczono przykładowy plik ustawień ze wszystkimi sekcjami i przykładowymi wartościami w formacie jsonc. Jsonc jest plikiem json z komentarzami – ten plik nie zostanie prawidłowo sparsowany – jego celem jest jedynie wyjaśnienie poszczególnych sekcji.
🚨 WAŻNE!
Ten endpoint pozwala na rejestrowanie w systemie zamówień intencji. Przed jego wykorzystaniem należy upewnić się, że w programie FARA została dodatkowo włączona usługa przyjmowania zgłoszeń. Jeśli usługa ta nie będzie włączona to zamówienia będą rejestrowane w systemie, ale nie zostaną odczytane !!!
W programie FARA są 2 tryby przyjmowania zdalnych intencji definiowane w panelu użytkownika programu FARA:
Tryb Wpisz do rejestru zgłoszeń i nie publikuj przed akceptacją powoduje, że złożona intencja nie zostaje natychmiast opublikowana i nie zostaje wpisana do księgi intencji FARY. Intencja zostaje zapisana do odrębnego rejestru zgłoszeń i widnieje jako „w trakcie rezerwacji”. Dopiero po ręcznej moderacji przez użytkownika po stronie FARY intencja taka zostaje albo odrzucona (i termin ponownie staje się wolny), albo zaakceptowana, co powoduje jej wpisanie do księgi i automatyczną publikację.
Tryb Automatycznie wpisz do księgi intencji i opublikuj powoduje, że złożona intencja zostaje natychmiast opublikowana i wpisana do księgi.
W komentarz używany jest zwrot logiczny mustAcceptMass określający aktywny tryb przyjmowania zdalnych intencji.
POST
| { |
| "uid" : NN, |
| "token" : "XXX", |
| "church" : N, |
| "massid" : 99999, |
| "faraid" : 55555, |
| "massdate" : "2028-12-20", |
| "masshour" : 1800, |
| "nazwisko" : "Jan Kowalski", |
| "adres" : "Przykładowice", |
| "telefon" : 999 999 999, |
| "email" : "something@somewhere.eu", |
| "ofiara" : 0, |
| "uwagi" : "Zażółć żółtą jaźń", |
| "intencja" : "treść intencji" |
| } |
| { |
| "error": numer błędu, |
| "description": opis błędu, |
| "success": 1 |
| "order": { |
| "resvid" : NNNNN, |
| "ip" : "NNN.NNN.NNN.NNN", |
| "server": "....". |
| "uid": NNNN, |
| "massid" : 99999, |
| "faraid" : 55555, |
| "content": "W intencji udanego kodowania", |
| "massdate" : "2028-12-20", |
| "masshour" : 1800, |
| "church" : N, |
| "orderName" : "Jan Kowalski", |
| "orderAddress" : "Przykładowice", |
| "orderPhone" : 999 999 999, |
| "orderEmail" : "something@somewhere.eu", |
| "donation" : 0, |
| "notes" : "Zażółć żółtą jaźń" |
| } |
| } |
Funkcja zapisu intencji (wm_order_mass) zapisuje intencje w zależności od wartości mustAcceptMass (Tryby przyjmowania zdalnych intencji opisane w wm_order_mass). Nie ma potrzeby samodzielnego odnoszenia się do tej wartości. Dla zasady mona ją odczytać przy pomocy tego endpointa.
POST
| { |
| "uid" : NN, |
| "token" : "XXX" |
| } |
| { |
| "error" : "error message" |
| "mode" : 1 (mustAcceptMass - intencja została zarejestrowana w rejestrze zgłoszeń), 0 (intencja została automatycznie opublikowana) |
| } |
Wyjaśnienia dodatkowe
W programie FARA są 2 klasy księgi intencji:
Klasę księgi definiuje użytkownik po stronie programu FARA:
W przypadku klasy Ogromna liczba intencji (niezwykle rzadko) każda wewnętrzna księga programu (każdy kościół) ma swój typ opisany w funkcji wm_fetch_church_data (normalny, same zbiorówki, wieczyste).
W bazie danych znajduję się wpisy na konkretne terminy, lecz z pustą treścią intencji. FARA traktuje je jako wolne i wyszukuje terminy na podstawie takich wpisów, o ile nie są już zarezerwowane.
Wolne terminy wyznaczane są na podstawie zapisanego w Farze harmonogramu i dziennego limitu
Jeśli klasa księgi to Ogromna liczba intencji i typ kościoła ma wartość 2 – same zbiorówki.
W takiej sytuacji wolnych terminów nie zapisuje się w Farze jako pustych intencji – wolny termin wyznaczany jest na podstawie harmonogramu i limitów. Wówczas identyfikatory massid oraz faraid są zerowe i zostają nadane automatycznie po zarejestrowaniu intencji.