Web API

Modified on 03.04.2023. 03:17:PM by htz.ibegovic — Categorized as: WEB API


Korištenje e-Visitor Web API funkcionalnosti

Sučelje je izvedeno kao REST service (root URI: https://www.evisitor.hr/eVisitorRhetos_API/Rest/). Kroz eVisitor Web API sučelje moguće je izvršiti sve operacije koje su dostupne kroz web sučelje same eVisitor aplikacije, pri čemu vrijede ista sigurnosna i poslovna pravila. Primjeri korištenja biti će prikazani u C# programskom jeziku koristeći RestSharp REST klijent. Dozvoljene vrijednosti šifrarnika korištenih u pozivima metoda dostupne su na wiki stranici e-Visitora - Web API - Lista šifrarnika

Svi parametri za rest pozive se šalju u JSON formatu. Datumi se šalju u .NET json Date formatu ("\/Date(1426028400000+0100)\/"), osim ako nije drugačije specificirano za određeni resurs.

Za pregled novosti u pojedinim verzijama REST-a posjetite stranicu WEB API - Novosti

Prijava (login) na e-Visitor Web API

Da bi pristup API-ju bio dozvoljen potrebno se prijaviti (login) u sustav koristeći Authentication service API (URI: https://www.evisitor.hr/eVisitorRhetos_API/Resources/AspNetFormsAuth/Authentication/), koji implementira slijedeće metode:




Primjer prijave na sustav se nalazi u datoteci Authentication.cs, u prilogu Htz.eVisitor.WebApi.Test.zip. Primjer za PHP nalazi se u prilogu eVisitor.PHP.zip.

Pristupni podaci u primjeru su samo ogledni. Ukoliko želite pristupiti sustavu eVisitor, obratite se korisniku za kojeg programirate informacijski sustav.

Pristup testnoj okolini

  1. Aplikacija - https://www.evisitor.hr/test
  2. API ROOT URL - https://www.evisitor.hr/testApi - za login se poziva metoda https://www.evisitor.hr/testApi/Resources/AspNetFormsAuth/Authentication/Login a za ostale resurse sukladno tome npr. https://www.evisitor.hr/testApi/Rest/Htz/Country/

Podaci u testnoj okolini su snapshot podataka iz produkcije od 09.12 - nikakve promjene u produkciji nakon 09.12 se ne vide u testu i obrnuto. To znači da za testnu okolinu treba tražiti zasebne pristupne podatke. Također ne preporuča se koristiti istu kombinaciju korisničkog imena i lozinke za obje okoline.

Vrste REST resursa

U ovom poglavlju biti će objašnjene sve dostupne vrste REST resursa. Svi konkretni resursi biti će definirani vrstom i specifičnim informacijama za pojedinu vrstu resursa.

Entity

Ovaj resurs podržava čitanje, unos, izmjenu i brisanje podataka. Neki od entity resursa ne podržavaju direktnu izmjenu podataka zbog svoje složenosti i ovisnosti o drugim resursima. Njihova izmjena je podržana posebnim metodama(Action-ima). Entity resurs biti će opisan relativnim path-om, popisom atributa, http metoda, te parametrima metoda. Primjer opisa jednog entiteta:

County


Entity resurs podržava slijedeće metode:

GET - dohvat podataka
POST - unos novog zapisa
PUT - izmjena zapisa
DELETE - brisanje zapisa


Browse

Ovaj resurs podržava čitanje podataka iz entiteta u specifičnom obliku. Metoda koju podržava je GET čiji interface je identičan interface-u GET metode opisanom u Entity resursu.

Action

Ovaj resurs podržava izvršavanje serverske akcije. Metoda koju podržava je POST. Parametar se šalje serijaliziran u JSON i specifičan je za konkretnu akciju. Rezultat je prazan u slučaju uspješnog izvršavanja, inače sadrži grešku zbog kojeg izvršavanje nije uspjelo.

Često korišteni procesi

Prijava turista

Da bi prijavili turista potrebno je pozvati akciju CheckInTourist. Akcija ImportTourists još je uvijek dostupna. U prilogu stranice se nalazi testni projekt u kojem su i primjeri korištenja akcija CheckInTourist, CheckOutTourist i CancelTouristCheckIn.

Odjava turista

Da bi odjavili turista potrebno je pozvati akciju CheckOutTourist. Akcija ImportTouristCheckOut još je uvijek dostupna. U prilogu stranice se nalazi testni projekt u kojem su i primjeri korištenja akcija CheckInTourist, CheckOutTourist i CancelTouristCheckIn.

Izmjena prijave turista

Da bi izmjenili prijavu turista potrebno je pozvati akciju CheckInTourist s parametrom ID koji je proslijeđen prilikom prijave turista. Moguće je izmjeniti samo aktivne prijave. Potrebno je slati sve podatke, a ne samo one koje želite izmjeniti. U prilogu stranice se nalazi testni projekt u kojem su i primjeri korištenja akcija CheckInTourist, CheckOutTourist i CancelTouristCheckIn.

Poništanje prijave turista

Da bi poništili prijavu turista potrebno je pozvati akciju CancelTouristCheckIn s parametrom ID koji je proslijeđen prilikom prijave turista. U prilogu stranice se nalazi testni projekt u kojem su i primjeri korištenja akcija CheckInTourist, CheckOutTourist i CancelTouristCheckIn

Otvaranje novog obveznika

Da bi otvorili novog obveznika potrebno je pozvati slijedeće akcije:


Pregled postojećih obveznika

Za pregled postojećih obveznika koristite browse TTPayerUnion.

Aktivacija postojećeg obveznika u "svojoj" turističkoj zajednici

Da bi aktivirali obveznika u svojoj turističkoj zajednici potrebno je pozvati akciju AddRightsToTTPayer. Ova akcija dopuštena je samo roli "turistička zajednica". Da bi saznali da li je obveznik zaveden u sustav pozovite resurs
https://www.evisitor.hr/eVisitorRhetos_API/Rest/Htz/TTPayerExists/?filter=Htz.TTPayerExistsParam&fparam={Pin:"01234567890"}

Otvaranje novog objekta

Da bi otvorili novi objekt potrebno je pozvati slijedeće akcije:


Sve tri akcije obvezno se moraju pozvati kako bi se ispravno otvorio objekt.

Deaktivacija objekta

Da bi deaktivirali objekt potrebno je pozvati slijedeće akcije:


Kreiranje datoteke za MUP

Da bi kreirali datoteku za MUP potrebno je pozvati slijedeće akcije:


Unos gotovinske uplate

Da bi unijeli gotovinsku uplatu (ručno zaduženje/odobrenje potrebno je pozvati akciju SaveCashDiaryPayment.

Dohvat podataka za ispis 3 uplatnice za paušaliste

Da bi dohvatili podatke potrebne za ispis 3 uplatnice za paušaliste koristite Browse PaymentFlatRateSlipSample.

Pokretanje okvirnog obračuna

Pokretanje okvirnog obračuna i dohvat podataka obračuna sastoji se od slijedećih koraka:

Unos DZS podataka za objekt

Da bi unijeli podatke potrebne za DZS koristite POST metodu entiteta FacilityNsoData.

Dohvat ID podatka za objekt

Da bi dohvatili ID objekta potrebno je pozvati GET metodu browse-a FacilityBrowse sa filterom po Code atributu. Primjer poziva metode:
https://www.evisitor.hr/eVisitorRhetos_API/Rest/Htz/FacilityBrowse/?filters=[{"Property":"Code","Operation":"equal","Value":"123456"}]

Resursi

Akcije

AddRightsToTTPayer
CancelTouristCheckIn
CancelTouristCheckOut
CalculateTTTemp
CheckInTourist
CheckOutTourist
CreateFileForMI
CreateFinalCalculation
DeactivateFacility
ImportTouristCheckOut
ImportTourists
NAPOMENA: Od 01.06.2017. atribut ID identifikator turista je obvezan, svi pozivi ove metode trebaju imati ID.
SaveCashDiaryPayment
SaveFacility
SaveFacilityCharacteristics
SaveTTPayer
SaveTTPayerAdditionalData
SaveTuristiZaObracunBoravisnePristojbeTemp
UploadDocument




Entiteti

Svi resursi u ovom poglavlju podržavaju metode opisane u poglavlju Entity

AccommodationUnit
AccommodationUnitCharacteristics
CashDiaryPayment
ContactPerson
Facility
FacilityAdditionalCategory
FacilityDistance
FacilityFacilityCode
FacilityNsoData
FacilityService
FacilityYearPaysTTFlatAmount
FRFOwner
MITTPayerFiles
OpenFacilityPeriod
TouristAcceptancePeriod
TouristAgency
TradeOwner
TTCalculationTouristTemp

Browse

Svi resursi u ovom poglavlju podržavaju metode opisane u poglavlju Browse

AccommodationUnitFacilityType
AccommodationUnitForEdit
AccommodationUnitTypePerSubtype
ArrivalOrganisationLookup
CashDeskLookup
CountryLookup
DistanceLookup
DistanceTypeLookup
FacilityBrowse
FacilityCategoryLookup
FacilityCodeLookup
FacilityLinkToNaturalPersonPerTTPayer
FacilitySubcategoryLookup
FacilityTouristCheckInLookup
LegalPersonTypeLookup
ListOfTourists
ListOfTouristsExtended


ManualApprovalDebitBrowse
OpeningBasisLookup
PaymentFlatRateSlipSample
PaymentPayoutTypeLookup
ServiceTypeLookup
SettlementLookup
SettlementZoneLookup
TouristAgencyBrowse
TouristCheckOut
TTCalculationItemSourceByTourist
TTCalculationItemSourceTempBrowse
TTCalculationItemSourceByFacility
TTPayerDeactivationBasisLookup
TTPayerFinancialRecord
TTPayerLookup
TTPayerUnion
TTPaymentCategoryLookup2
TypeOfInterestCalculation

!!! NOVO !!! Upute za dodijelu pristupnih podataka

Dodatna objašnjenja i upute za obveznike i turističke zajednice u vezi dodijelu pristupnih podataka nalaze se ovdje: Testna okolina - pristupni podaci.docx

!!! NOVO !!!

Upute za provjeru API integracije sa sustavom eVisitor Dodatna objašnjenja i upute za provjeru integracije se nalaze ovdje: Upute za provjeru API integracije sa sustavom eVisitor.pdf

!!! NOVO 2022 !!!

Krivo implementirani API pozivi

Trenutačno eVisitor ima veće sigurnosne provjere nego prijašnje verzije sustava i neće više prihvatiti krivo implementirane API pozive. Molimo da API vendori provjere upute na postojećim Wiki stranicama i naprave reviziju svojih poziva prema eVisitoru te jesu li uredno implementirani prema uputi.

Najčešće greške koje se javljaju API vendorima:


Ukoliko ste potvrdili da nemate krivo implementiran API poziv i rade sve uredno prema napisanim točkama, a zbog nekog razloga imate i dalje grešku molimo da nam proslijede sljedeće informacije:




Povezane stranice