Leveringsguiden tjeneste for henting av informasjon om Postens transportprodukter Versjonshistorikk: Dato Versjons Status nummer 30.mars 2006 1.0 à jour Endring Side 1 av 12
Innholdsfortegnelse Innholdsfortegnelse... 2 1. Forord... 2 2. Innledning... 3 1.1 Leveringsguiden skal bidra til at:... 3 1.2 Leveringsguiden gir kjøperen informasjon om... 3 3. Systemoversikt... 4 4. Installasjon av Leveringsguiden... 5 5. Input/Output format... 6 5.1 Input-format... 6 5.2 Output-format... 10 6. Spesielle merknader.... 11 7. Feilmeldinger... 12 8. TPD Tyngre på døren... 12 1. Forord Dette dokumentet er en teknisk beskrivelse av formatet/syntaksen på XML for kommunikasjon med systemene som utgjør Leveringsguiden som er utviklet på oppdrag fra Posten av ErgoGroup. Dokumentet er ment å skulle kunne benyttes for kunder som skal benytte Leveringsguiden(heretter kalt LG) til sine systemer. Side 2 av 12
2. Innledning Leveringsguiden er en applikasjon som er utviklet for å gi handlende i nettbutikker informasjon om hvilke av Postens transportprodukter de kan velge for å få levert varene sine, hvor lang tid dette vil ta og hvor mye det vil koste. Aktuelle produkter, leveringstid og kostnad er beregnet med utgangspunkt i Postens produktattributter, hva kunden har handlet (innhold i handlekurven) samt til fra postnummer. All informasjon om Postens produkter er lagret i en database i Leveringsguiden. Når Leveringsguiden skal gi informasjon om hvilke transportprodukter en enkelt kunde kan velge og hvor mye de forskjellige leveringsmåtene vil koste, hentes den informasjonen fra denne databasen. 1.1 Leveringsguiden skal bidra til at: Netthandel blir enklere for kjøperen Postens leveranseprodukter kan velges på en enkel måte når varer kjøpes og selges over Internett Bestilling av vareleveranser over Internett er trygt og brukervennlig Varer som handles over Internett kommer fram i henhold til de avtaler om leveringstidspunkt og pris som er inngått mellom nettbutikken og kjøperen 1.2 Leveringsguiden gir kjøperen informasjon om Mulige leveringsmåter Leveringstid pr leveringsmåte Leveringspris basert på Postens produkter. Leveringsguiden sjekker også at postnummeret eksisterer og at det stemmer med poststed. Side 3 av 12
3. Systemoversikt Leveringsguiden er en nettverksbasert tjeneste som er utviklet i Java. All input og output går via spesifisert format over TCP/IP. Systemet er designet for å tilby data om transportprodukter til andre systemer som har behov for slike data. Figur 2.1: Figuren viser systemkonfigurasjon for løsningen. Klientsystem 1 Klientsystem 2.... Klientsystem n Internett Applikasjons-server tcp /ip Leveringsguiden Database-server (db2) En eller flere klienter (butikksystemer for eksempel) kan kommunisere med applikasjonsserveren (Leveringsguiden) over tcp/ip via internett. Kommunikasjonen foregår ved at klienter sender xml-dokumenter til applikasjons-serveren. Resultatet av valgt tjeneste er for eksempel en kommaseparert liste som sendes tilbake til klienten. Side 4 av 12
4. Installasjon av Leveringsguiden. Interesserte foretak tar kontakt med sin selger og ber om å få knytte seg til Leveringsguiden. Foretakets tekniske kontaktperson får da utdelt et brukernavn og passord til testserveren. Denne heter for tiden lake.interpost.no. Det vil også lages noen eksempler på enkle xml er som kan benyttes. Disse vil normalt bli lagt på http://lake.interpost.no/brukernavn der brukernavnet er det den tekniske kontaktpersonen får tilsendt pr mail. Når foretaket har testet og bestemmer seg for å bruke LG, gir de beskjed til sin selger som vil sørge for at brukernavnet og passordet blir migrert til produksjon. Da kan foretaket begynne å gjøre spørringer mot produksjonsserveren, som for tiden heter torsk.interpost.no. Et alias som er sikrere å benytte er http://leveringsguiden.posten.no Dette vil alltid være konfigurert til å peke på produksjonsserveren. Fremgangsmåten for å gjøre spørringer mot LG er å poste et tekstfelt som heter "xmltekst". Det er viktig at inputnavnet er dette. Disse spørringene integreres i foretakets nettbutikk, eller eksisterende grensesnitt der de ønsker å bruke LG. Det er ikke behov for å installere noen moduler eller noe annet i systemet til foretaket. Side 5 av 12
5. Input/Output format Dette kapitlet spesifiserer formatet på inn- og utdata som de forskjellige tjenestene benytter seg av. 5.1 Input-format Dataene som sendes inn til Leveringsguiden, er basert på XML-format. Det er ikke utarbeidet noen DTD for dette formatet. <?xml version="1.0" endcoding= ISO-8859-1?> må alltid være med i første linje. Denne spesifiserer hva slags XML-versjon som brukes og hvilken encoding dokumentet har. Det er mulig å spesifisere flere spørringer i samme xml-dokument. Dette gjøres ved å bruke taggen <REQUEST-LIST> som hovedtagg. Inne i denne taggen spesifiserer man så spørringene ved taggen <REQUEST>. Attributten reqnr brukes for å spesifisere rekkefølge på spørringene. Merk at man ikke trenger å spesifisere flere spørringer og da bruker man <REQUEST>-taggen som hovedtagg (se under). Hovedtaggen for spørringer skal være: <REQUEST>... </REQUEST> I <REQUEST> er XML-koden delt opp i brukersjekk og de TRE hovedkategoriene ACTION, DELIVERLYLIST og PACKET. Brukersjekken har XML-kode: <USERNAME>username</USERNAME> <PASSWORD>password</PASSWORD> Eks: <USERNAME>bruker</USERNAME> <PASSWORD>passord</PASSWORD> Hver butikk får utdelt eget username og passord. Om de tre HOVEDkategoriene i XML-koden: <ACTION> Forteller hva slags informasjon som skal hentes fra transportdatabase. Action har disse taggene: <GET-FTIME> ON: Forsendelsestid ønskes. OFF: Forsendelsestid ønskes ikke. Eks: <GET-FTIME>ON<GET-FTIME> <GET-FTIME-WORLD> Side 6 av 12
ON: Forsendelsestid for utlandsprodukter ønskes. OFF: Forsendelsestid for utlandsprodukter ønskes ikke. <GET-COST> ON: Transportkost ønskes. OFF: Transportkost ønskes ikke. Eks: <GET-COST>ON</GET-COST> <GET-COST-WORLD> ON: Pris for utlandsprodukter ønskes. OFF: Pris for utlandsprodukter ønskes ikke. <GET-DELIVERLYLIST> ON: Liste over leveringstidsalternativer ønskes. OFF: Liste over leveringstidsalternativer ønskes ikke. < GET-ORGI> ON: Organisasjon for MottakerBetaltHjemlevering ønskes. OFF: Organisasjon for MottakerBetaltHjemlevering ønskes ikke. <RETURNTYPE> COMMA: Leveringsguiden returnerer komma-separert liste XML: Leveringsguiden returnerer XML-kode. <TRANSFORM> ON: XML-kode skal konverteres til HTML. OFF: XML-kode skal ikke konverteres til HTML. <GROSS-PRICE> ON: Beregner pris med moms. OFF: Beregner pris uten moms. BEGRENSNINGER: Hvis man velger GET-FTIME og/eller GET-COST er det IKKE mulig å velge GET- DELIVERYLIST. Og vise versa. <DELIVERYLIST> Hvis man har valgt GET-DELIVERYLIST kan man velge hvor lang denne listen skal være. Den parameteren som gir den korteste listen, gjelder. <MAX-LENGTH> Numerisk tall: Maks lengde på listen Eks: <MAX-LENGTH>10</MAX-LENGTH> <MAX-DAY> Side 7 av 12
Numerisk tall: Maks antall dager i listen. Eks: <MAX-DAY>15</MAX-DAY> <PACKET> Informasjon om pakkefakta, når den skal sendes og hva slags transportprodukt det ønskes informasjon om. <NAME> Liste over de pakkene det ønskes informasjon om. Eks: <NAME>ALL</NAME> [ Informasjon om ALLE pakketypene. ] MERK: ALL må bare brukes unntaksvis og for testing. Om man bruker ALL vil man kunne få feil, da det er spesielle produkter som ikke kan sendes til alle postnummer. Eks: <NAME>SERVICEPAKKE,A-POST</NAME> Eks: <NAME>A-POST, B-POST, EKSPRESS-OVER-NATT-AVTALE</NAME> Alle navn oversettes til store bokstaver. Begrensning: Hvis det er valgt <GET-DELIVERLYLIST> MÅ det bare velges ETT transportprodukt. Eks: <NAME>SERVICEPAKKE</NAME> <FROM-PNR> numerisk: Postnummeret postproduktet sendes fra. Eks: <FROM-PNR>0255</FROM-PNR> <TO-PNR> numerisk tall: Postnummeret postproduktet sendes til. Eks: <TO-PNR>0375</TO-PNR> <COUNTRY> tekst: Angir mottakerland. Erstatter FROM-PNR og TO-PNR for utlandsprodukter. <DATE> dato: Datoen når postproduktet sendes. Datoformat: dd.mm.yyyy Eks: <DATE>12.12.1999</DATE> <WEIGHT> numerisk tall: Vekten på transportproduktet oppgitt i antall gram. Eks: <WEIGHT>200</WEIGHT> Side 8 av 12
Volum tagger, om det er et volumberegnet produkt så må informasjon om volum oppgis for riktig pris. <LENGTH> numerisk tall: Lengde på transportproduktet i antall centimeter. Eks: <LENGTH>75</LENGTH> <WIDTH> numerisk tall: Bredde på transportproduktet i antall centimeter. Eks: <WIDTH>18</WIDTH> <HEIGHT> numerisk tall: Høyde på transportproduktet i antall centimeter. Eks: <HEIGHT>10</HEIGHT> <VOLUME> numerisk tall: Volum på transportproduktet i antall kubikkdesimeter, dm 3. Eks: <VOLUME>10</VOLUME> 10 dm 3 er det samme som 10cmx10cmx10cm, som er det samme som 1000 cm 3 Om man oppgir <VOLUME> så ignoreres <LENGTH>, <WIDTH> og <HEIGHT>. <ADDRESS> Brukes til å spesifisere et postnummer som skal sjekkes. POSTNR tekst POSTSTED tekst Eks: <?xml version="1.0"?> <REQUEST> <USERNAME>bruker</USERNAME> <PASSWORD>passord</PASSWORD> <ACTION> <RETURNTYPE>COMMA</RETURNTYPE> <CHECK-PNR>on</CHECK-PNR> </ACTION> <ADDRESS> <POSTNR>1158</POSTNR> <POSTSTED>Oslo</POSTSTED> </ADDRESS> </REQUEST> Side 9 av 12
Returnerer: 1158,OSLO,0301,OSLO altså postnummer, poststed, kommune nr, og kommune Eksempel på XML-fil Bytt ut bruker1 og passord med dem du har mottatt fra din selger. <?xml version="1.0" encoding= ISO-8859-1?> <REQUEST> <USERNAME>bruker1</USERNAME> <PASSWORD>passord</PASSWORD> <ACTION> <transform>on</transform> <RETURNTYPE>XML</RETURNTYPE> <GET-FTIME>off</GET-FTIME> <GET-COST>off</GET-COST> <GET-DELIVERYLIST>on</GET-DELIVERYLIST> </ACTION> <DELIVERYLIST> <MAX-LENGTH>10</MAX-LENGTH> <MAX-DAY>15</MAX-DAY> </DELIVERYLIST> <PACKET> <NAME>HJEM-PÅ-DØREN</NAME> <FROM-PNR>0255</FROM-PNR> <TO-PNR>0375</TO-PNR> <DATE>12.02.2005</DATE> <CLOCK>1900</CLOCK> <WEIGHT>200</WEIGHT> <LENGTH>75</LENGTH> <WIDTH>18</WIDTH> <HEIGHT>10</HEIGHT> </PACKET> </REQUEST> 5.2 Output-format Hvis man spesifiserer flere spørringer, må XML-format benyttes som outputformat. Da vil man få svaret i en <TRANSPORT-LIST>-tagg. Innenfor denne taggen vil svarene være spesifisert i en <TRANSPORT>-tagg for hver spørring. <TRANSPORT>-taggen har en reqnr attributt som kobler svaret til spørringen med den tilsvarende attributtverdien. Hvis GET-DELIVERYLIST = ON Da får returlisten følgende form: dd.mm.yyyy : hhmm-hhmm,dd.mm.yyyy : hhmm-hhmm, osv. Eks: 13.12.1999 : 1200-1500,13.12.1999 : 1700-1900,13.12.1999 : 1900-2100,14.12.1999 : 12.00-15.00, osv. Side 10 av 12
Hvis GET-FTIME = ON Da får returlisten følgende form: Transportproduktnavn1,ftime,opprinnelig forsendelsestid, reell forsendelsestid,dato for eksakt levering,transportproduktnavn2 og tilsvarende parameter som til transportproduktnavn1 Eks: A-POST,ftime,1,2,14.12.1999,B-POST,2,3,15.12.1999,NorgesPakken,ftime,1,2,14.12.1999 Hvis GET-COST=ON Da får returlisten følge form: Transportproduktnavn1,cost,prisen til transportproduktet i antall øre,0,00.00.0000,transportproduktnavn2, osv osv. Eks: A-POST,cost,1400,0,00.00.0000,B- POST,1200,0,00.00.0000,NorgesPakken,cost,5000,0,00.00.0000 Hvis GET-ORGI=ON Da får returlisten følge form: Emailadresse til,emailadresse cc,enhetsnummer, poststedsnavn RETUR AV MULIGE FEILMELDINGER Hvis feil oppstår returneres feilmelding på følgende format: Returmelding: TMERROR,kode,melding. Se feilkoder i kap. 7 Hvis DATO-formatet er feil eller ikke eksisterer: Vil det ikke være mulig å beregne reell fremsendingstid. Det returneres da: A-post,2,2,00.00.0000 Hvis WEIGHT-formatet er feil eller utenfor transportproduktets grenser Det returneres da: A-post,cost,-1,0,00.00.0000 Hvis GET-DELIVERYLIST er valgt og det er valgt MER enn et transportprodukt Returmelding: TMERROR,102,No service in TransportService.doService() 6. Spesielle merknader. Forskjellig navn på A-prioritert for innland og utland. Legg merke til at a-post har forskjellig navn om den benyttes for innland eller utland. Navnet man bruker om det er innland er: A-POST Side 11 av 12
Navnet man benytter om det er utland: BREV A-PRIORITERT Må bruke ALL i navn tagg unntaksvis. Man kan benytte ALL i navnetaggen for å få en liste over produkter, men den må bare brukes i test, ikke som del av den daglige drift. Dette fordi det er enkelte produkter som er noe spesielle og kan skape problemer mot enkelte postnummer. Det beste er å liste opp produktene man ønsker å benytte atskilt med komma. 7. Feilmeldinger Følgende feilmeldinger er definert for feil i forbindelse med input-formatet: 100 = Unknown error in Transport-module / java-program-error 102 = No service selected 103 = From-pnr missing 104 = To-pnr missing 105 = From-pnr nonexiting 106 = To-pnr nonexiting 107 = Product missing 108 = Postaddress not found 109 = Product missing in orderdata 110 = Name missing in orderdata 111 = Postnr missing in orderdata 112 = Poststed missing in orderdata 113 = Store-username missing in orderdata 114 = Postnr in order nonexisting 115 = Wrong username or password 116 = Organisation not found Dette er feilmeldinger som sendes tilbake til klienten. Det kan oppstå andre feilmeldinger ved for eksempel programfeil, databasefeil etc. som ikke sendes tilbake, men skrives ut til error-loggen. 8. TPD Tyngre på døren Om foretaket ønsker å benytte produktet Tyngre På Døren sammen med Leveringsguiden, er dette dokumentert i et eget dokument. Du må be spesifikt om å få dette. Side 12 av 12