English version: https://helpdesk.fmcgsolutions.dk/hc/da/articles/13492871926556-API-Integration-to-external-systems
Om integration med fmcgProducts og fmcgProductsIntegrator
Metoder.
fmcgProducts understøtter integration af produktdata med andre systemer ved brug af et web services API (JSON/XML), FTP og mail-in.
Filtyper.
Udover JSON/XML kan fmcgProducts behandle tekstfiler (kommasepareret eller kolonneformatteret) og Excel-filer.
Felttyper.
fmcgProducts kan sende og modtage følgende felttyper.
- GDSN 3.1 felter ”Dxxxx” , f.eks. EAN/GTIN (D8165), Varenavn (D8258) etc.
- Egne felter ”Exxxx”, f.eks. sortiments, produktkategorifelter etc, som man ønsker at ”styre på” i fmcgProducts, f.eks. ift. sortimentsoversigter, produktkategorioversigter, Excel udtræk, integration med øvrige systemer etc.
- Systemfelter ”Xxxxx”, f.eks. X9000 ”Klar til GS1” som gør det muligt at styre synkronisering af produktdata med GS1 (skal produktet synkroniseres med GS1 hvis det er ”GS1 validt” eller ej).
- Andre felter som ”mappes” til kendte felter i fmcgProducts.
Historik.
Uanset hvilken metode der anvendes til integration og opdatering af fmcgProducts, vil alle transaktioner og ændringer blive registreret på den enkelte produktenhed. Den specifikke hsitorik for den enkelte produktenhed kan ses ved at vælge ”Vis produkthistorik” fra brugergrænsefladen på det enkelte produkt.
Mail-In.
fmcgProducts kan modtage tekstfiler (kommasepareret eller kolonneformatteret) samt Excel-filer via mail-in. fmcgProducts kan konfigureres så det alene er specifikke afsender-adresser som har lov til at maile filer til fmcgProducts for opdatering.
Integration uden ”mapping”.
fmcgProducts kan indlæse et MS Excel regneark direkte (uden mapping), forudsat at syntaks for Excel-import er overholdt. Korrekt syntaks er felttype/nr i første række samt at GDSN 3.1 standard er anvendt ift. keywords – eksempel:
Såfremt produktenheden findes i forvejen i fmcgProducts (den unikke nøgle er ”EAN/GTIN + target market (landekode)), opdateres produktenheden i fmcgProducts. Hvis ”EAN/GTIN + target market” ikke findes i fmcgProducts, oprettes der en ny produktenhed i fmcgProducts.
Såfremt syntaksen ikke er overholdt, f.eks. ved manglende Ean/GTIN i kolonne A, feltet der er angivet i første række ikke findes fmcgProducts, brug af ugyldigt keyword etc., springes pågældende række over (produkt) og der forsøges indlæsning af næste række (produkt).
Ved enhver indlæsning af produktdata til fmcgProducts genereres der en indlæsningsrapport, som viser præcist hvilke rækker (produkter) der er indlæst korrekt, og hvilke rækker (produkter) der ikke er indlæst pga syntaksfejl. Den præcise årsag til syntaksfejl er angivet i indlæsningsrapporten (felt findes ikke, ugyldigt keyword etc.).
Det er muligt at opsætte fmcgProducts således at indlæsningsrapporten mailes til en eller flere mailadresser i forlængelse af en indlæsning til fmcgProducts.
Integration med ”mapping”.
fmcgProducts indeholder et ”mappingmodul”, som gør det muligt at ind- og udlæse filer (kommasepareret eller kolonneformatteret tekstfil) til/fra fmcgProducts.
Forudsat at ”EAN/GTIN + target market” er angivet korrekt et vilkårligt sted i indlæsningsfilen, er det muligt at mappe alle felter fra importfilen, dvs. position i indlæsningsfilen, til de tilhørende felter i fmcgProducts.
Ifm. mapping kan der samtidig udføres en række funktioner – eksempler:
- Konvertering (f.eks. fra KG til GRAM)
- Default felter (f.eks. måleenheder, landekoder, faste værdier i felter etc)
- ”en til flere enheder” f.eks. kan der indlæses én række fra tekstfil, som efterfølgende danner grundlag for opdatering/oprettelse af flere produktenheder (basis-kasse-palle)
Web services API (JSON)
API’et har support for følgende kald/end points.
Generelt:
GET /api/: returner system-status på fmcgProducts.
GET /api/openapi: returner dokumentation i OpenAPI-format.
GET /api/openapi.json: returner dokumentation i OpenAPI-format som JSON.
Ét produkt/GTIN:
GET /api/status/<product id>: returner status på produktet hvor product id er GTIN.TargetMarket.
eksempel: https://<kundeinstans>.fmcgproducts.dk/api/status/04005514026085.752
GET /api/details/<product id>?fields=D8256,D8258,D8245: returner status samt specifikke felter (eksemplet returnerer leverandørens varenr, leverandørens varenavn samt GPC kode).
GET /api/details/<product id>/<eksport-profil>: returner status samt specifikke felter defineret i eksport-profilen.
POST /api/: opretter/opdaterer et produkt. Nøglen er GTIN via feltet D8165 samt target market via feltet D8255. Retursvar svarer til /api/status/<product id>. Dermed fås validation errors (GDSN og specifikke regler for de enkelte target markeds) med retur.
Med feltet “test” sat til true, kan der testes uden at oprette/opdatere produkter, og der kommer stadig korrekt retursvar tilbage.
Input er 'case sensitive', så Dxxxx-felter skal angives med store bogstaver.
Yderligere parametre:
-
?displayValues=true: Viser keyword-værdi som oversat værdi fremfor som "teknisk" værdi.
Bemærk: ved brug af eksport-profil, så bestemmes dette ud fra indstilling på selve eksport-profilen.
Flere produkter/GTINs.
GET /api/products/status: returner status på alle produkter med mulighed for at begrænse antal produkter med fromdate, limit og offset.
GET /api/products/status?fromdate=01-01-2022: returner status på alle produkter som er sendt til GS1 siden 1/1-2022.
GET /api/products/status?fromdate=01-01-2022&offset=25&limit=25: returner status på alle produkter som er sendt til GS1 siden 1/1-2022, men bruger offset og limit til at hente en delmængde (paging).
En selektion af flere produkter/GTINs.
Der kan defineres en eller flere selektioner ud fra nogle givne kriterier. Selektionen gemmes i kundeinstansen under et ”viewname”, som angives i web API-kaldet. API’et returnerer alle de produkter som opfylder de givne kriterier. Dermed kan man definere et antal selektioner, f.eks. på udvalgte leverandører (GLN = ??? OR GLN = ??? etc.), på GPC kode og så videre, som returnerer præcist de produktdata som der er behov for.
Eksempler:
GET /api/view/<view id>: Returnerer alle produkter fra den angivne selektion/oversigt i JSON-format.
GET /api/view/<view id>/xml: Returnerer alle produkter fra den angivne selektion/oversigt i XML-format.
GET /excel.xsp?request=view&viewname=<view id>&template=<excel template>: Med ”excel.xsp” og ” &template=Excel” returneres der Excel fil (med felter som specificeret i Excel-templaten <excel template>)
Yderligere parametre:
- &fieldnames: Der kan angives ”gs1” som returnerer gs1 feltnavne, eller andre feltnavne efter aftale (svarende til de feltnavne som modtager systemet anvender)
- &gridsToArray=true: Samler felter fra samme grid i ét JSON array fremfor at vise felterne i en flad struktur
- &allergensToBold=true: Angiver allergener i ingrediensbeskrivelse D8179 i fed (med <b> og </b>) baseret på allergen-filteret for det pågældende sprog for produktets target market
- &displayValues=true: Viser keyword-værdi som oversat værdi fremfor som "teknisk" værdi
- &limit=<antal>&offset<start fra nummer>: Returnerer et antal produkter fra den angivne ”offset” (paging)
- &modifiedsince=<minutter>: Returnerer de produkter i det pågældende view/selektion, som er rettet inden for XXX minutter. Det kræver at første kolonne i den tilhørende oversigt er enten D8260 ("Sidst ændret"-dato for GS1-felter) eller X9101 ("Sidst ændret"-dato for GS1- og egne felter)
PDF.
GET /api/pdf/<product id>: henter produktblad som PDF for produktet hvor product id er GTIN.TargetMarket. Som PDF template bruges default for pågældende enhedstype.
GET /api/pdf/<product id>/<PDF template>: henter produktblad som PDF for produktet hvor product id er GTIN.TargetMarket.
GET /api/pdf/<item id>/<country>/<PDF template>: henter produktblad som PDF for produktet med det angivne varenummer (item id) fra det angivne target market.
GET /api/web/<product id>/<PDF template>: henter produktblad som HTML til visning direkte i browseren for produktet hvor product id er GTIN.TargetMarket.
GET /api/web/<item id>/<country>/<PDF template>: henter produktblad som HTML til visning direkte i browseren for produktet med det angivne varenummer (item id) fra det angivne target market.
I alle tilfælde er "PDF template" navnet på templaten eller id på templaten. Hvis navn ikke matcher, så bruges den PDF template som er default for pågældende enhedstype.
Sikkerhed.
API tilgås med basic authentication.
fmcgProducts og fmcgProductsIntegrator afvikles i et dubleret servermiljø bestående af et cluster med servere fordelt på 2 fysiske lokationer.
Der anvendes Nginx til fordeling af HTTPS-trafik og omdiregering ved fejl på en server.
Som alternativ til basic authentication kan alle services låses til én eller flere IP-adresser, og det er dermed alene de specificerede IP-adresser som får adgang til at kalde API'et.
Caching.
Alle kald til /api/ returnerer en ETag HTTP header. Værdien i ETag HTTP header skal sendes retur i efterfølgende kald til API'et på samme forespørgsel i en If-None-Match HTTP header for at udnytte caching og dermed få hurtigere svar hvis data ikke er ændret siden sidste kald (conditional GET).
Limits/throttling.
API har en limit på 90 requests/minut for at begrænse load på backend-serverene. Hvis limit overskrides, svarer API retur med HTTP 429 "Too Many Requests".