Versionet e API-t
Versioni është pjesë e rrugës: https://fature.al/api/v1/... ose https://fature.al/api/v2/....
Nuk ka negocim me header dhe nuk ka version të nënkuptuar; një thirrje pa /v1 ose /v2 në rrugë
nuk shkon askund.
v1 është versioni për të ndërtuar#
v1 mban të gjithë API-në: faturat, e-faturat, fletët shoqëruese, faturat e blerjes, klientët,
produktet, arkën fiskale, llogaritë bankare, monedhat, raportet dhe regjistrimin e kompanive. Nëse
nuk keni një arsye nga tabela më poshtë, ndërtoni mbi v1.
v2 ekziston për tri gjëra#
v2 nuk është pasardhësi i v1. Ai mban tre grupe, faturat, klientët dhe fletët
shoqëruese, sepse vetëm këto ndryshojnë formë. Gjithçka tjetër (faturat e blerjes, produktet, arka
fiskale, raportet, regjistrimi) mbetet te v1 dhe thirret prej andej edhe nga një integrim që
faturat i dërgon me v2.
| Grupi | Çfarë ndryshon në v2 |
|---|---|
| Faturat | Pagesa dërgohet si listë payment_methods, me një element për çdo mënyrë, deri në 10. Një faturë e paguar pjesërisht me para në dorë dhe pjesërisht me kartë lëshohet vetëm këtu. Fushat payment_method, company_card dhe vouchers mbi faturën nuk pranohen; karta e kompanisë dhe tollonat shkojnë brenda elementit të payment_methods |
| Klientët | Të dhënat vijnë në objekte (company, person, address, contact) me type company ose person; identifikuesi është objekt id me type dhe value; vlerat janë me shkronja të vogla; përditësimi bëhet me PATCH |
| Fletët shoqëruese | internalId është i detyrueshëm në lëshim, ndërsa te v1 është opsional. Pjesa tjetër e fletës është fjalë për fjalë ajo e v1 |
GET /api/v2/clients kthen ende formatin e sheshtë të v1. Detajet, krijimi dhe përditësimi i
klientit janë në formatin e ri.
Të dy versionet shkruajnë mbi të njëjtat të dhëna. Një klient i krijuar me v1 lexohet me v2 pa
asnjë hap tjetër. Përdorimi i të dyve njëherësh është i zakonshëm: v2 për faturat me pagesë të
ndarë ose për klientët, v1 për gjithçka tjetër.
Të dy versionet ndajnë token-in, kredencialet e aplikacionit, formatin e përgjigjes dhe kufijtë e
kërkesave. Dokumenti i v2 është te /docs/api/v2.
Një ndryshim në 422#
Në v1, përgjigja e validimit (422) përdor fushën success në vend të status. Në v2,
endpoint-et e klientëve kthejnë status edhe në 422, ndërsa endpoint-et e faturave të v2
kthejnë success, si në v1:
{"success": false, "message": "...", "errors": {"lines.0.quantity": ["..."]}}
{"status": false, "message": "...", "errors": {"company.name": ["..."]}}
Në çdo përgjigje tjetër të dy versionet përdorin status. Lexoni gjithmonë së pari kodin HTTP dhe
pastaj fushat. Shihni Gabimet.
Partner API nuk është version i tretë#
/api/partner/v1 shërben integrimin me Wolt dhe ka publikun e vet: një njësi e vetme, porositë e
saj, pranimi, refuzimi dhe fiskalizimi i tyre. Nuk është version i v1 dhe nuk e zëvendëson atë.
Nëse nuk po integroni Wolt, ai grup nuk ju përket.
Dokumentet#
| Dokumenti | Çfarë mbulon | Adresa |
|---|---|---|
| v1 | E gjithë API-ja e faturimit dhe e regjistrimit | /docs/api |
| v2 | Faturat me pagesë të ndarë dhe klientët në formatin e ri | /docs/api/v2 |
| Partner | Porositë e Wolt për një njësi të vetme | /docs/api/partner |
Secili dokument botohet edhe si OpenAPI JSON (/docs/api.json, /docs/api/v2.json,
/docs/api/partner.json) dhe si Markdown për asistentët AI (/docs/api.md).
Asgjë nuk është në dalje#
Asnjë version nuk ka datë përfundimi dhe asnjë nuk është shpallur i vjetëruar. Brenda një versioni
ndryshimet janë vetëm shtesa: një fushë ekzistuese nuk ndryshon kuptim dhe nuk hiqet. Një integrim i
shkruar sot mbi v1 nuk ka afat që duhet ndjekur.
Regjistrimi është falas.
Regjistrohu në fature.al