PETRA Användarhandbok Ekonomimeddelande Version 1.11 Utgiven 2008-01-21 Författare Henrik Nyman Filnamn PETRA Användarhandbok Ekonomimeddelande.doc
Innehåll 0 Revisioner...3 1 Inledning...4 2 Innehåll i XML-meddelandet...5 2.1 DTD...5 2.2 Beskrivning av meddelandestrukturen...5 2.2.1 Säljställe 9 2.2.2 Beställare av första raden (fr o m 2007-06-02) 9 2.2.3 Händelser 10 2.2.4 Säljställekategori (fr o m 2006-11-11) 10 2.2.5 Kontokortsuppgifter 10 2.2.6 Kundkort för betalare 10 2.2.7 Konteringsinformation 11 2.2.8 Fakturareferens (fr o m 2008-03-08) 11 2.2.9 Kundprioritet (fr o m 2008-03-08) 11 2.2.10 Kundkort för resenär 11 2.2.11 Tjänstepris 11 2.2.12 Krediteringsorsak (fr o m 2008-03-08) 12 2.2.13 Antal resenärer 12 2.2.14 Komponentlöpnummer 12 2.2.15 Komponenttyper 13 2.2.16 Lokaler 13 2.2.17 Komfort, prisnivå, prisgrupp och fare type 13 2.2.18 Datum och tid 14 2.2.19 Statistikkilometer (fr o m 2006-11-11) 15 2.2.20 Beräknad andel av tjänstepris och moms på delsträckenivå 15 2.2.21 Orabatterat pris 15 2.2.22 Bokningsavgift 16 3 Exempel...18 3.1 SectionType...18 3.1.1 Exempel på bokad resa 18 3.1.2 Exempel på färdbiljett 19 3.1.3 Exempel på platsreservation 19 3.1.4 Exempel på övriga tjänster 20 3.1.5 Exempel på ombokningsskydd 21 3.2 Resetjänster...22 3.2.1 1 klass med mat, kan återbetalas 22 3.2.2 1 klass med mat, kan ombokas 22 3.2.3 2 klass, kan återbetalas, utan plats 23 3.2.4 2 klass, kan ombokas 23 3.2.5 2 klass, kan ej ombokas 23 3.2.6 2 klass, kan ej ombokas 23 3.2.7 Separat platsreservation 24 3.2.8 Internet ombord 24 4 Planerade förändringar 2008-03-08...25 5 Referenser...26 2
0 Revisioner Följande revisioner av dokumentet är gjorda: Datum Avsnitt Kommentar 2008-01-21 2.2, 2.2.8, 2.2.9, Nya element <ReasonCode>, <InvoiceReferences> och 2.2.12, 4 <Priority> fr o m 2008-03-08. 2007-11-05 3.2, 4 Exempel på hur SJs nya tjänsteutbud ser ut i EM. Förhandsbesked om planerade förändringar. 2007-10-18 3.1.5 Exempel på ombokningsskydd 2007-05-29 2.2.7 Utökad beskrivning av <CustomerAccount>. 2007-04-10 2.2, 2.2.15, 4 Nyheter fr o m 2007-06-02. 2007-01-10 2.2.20 Utökad beskrivning av beräknad andel av tjänstepriset. 2006-12-04 2.2, 2.2.22 <PaymentText> slopat. <BookingFee1> och <BookingFee2> tillkommer i. 2006-10-20 4 Planerade förändringar uppdaterat. 2006-10-12 2.2.11, 2.2.13, Kompletterande beskrivning av några element. 2.2.21 2006-09-30 2.2.6 Nytt element <PaymentInfo><TravellerCard> för KPS. 2006-09-19 2.2, 4 Elementet <PaymentText> används inte. 2006-09-15 1, 2.2 Version 1.8 av EM är inarbetat. 2006-05-22 Elementet <Price> i är frivilligt. Elementet <PriceInclDiscount> består av <PriceIncVat>, inte <Price>. 2006-05-17 Nytt värde U på <DebitCredit> vid efterregistrering av tillfällig resenär på beställningsrad. 2006-05-05 Fastställd version 1.7.1 som Linkon kommer att utgå från vid leverans 2006-11-11 av EM version 1.8. 2006-04-27 1 Kompletterande detaljer om Kreditering särskilda fall. 2006-04-21 Nytt attribut ComponentOrderNumber i elementet. 2006-04-10 <Price incldiscount=nnn.nn> ersatt av nytt element <PriceInclDiscount> 2006-04-06 2.2.15 Nytt avsnitt om <SectionType>. Mindre justeringar av <Price>. 2006-04-05 Nytt element <Points>. 2006-04-04 Fler värden på <DebitCredit>. Element <SalesUnitCategoryCode> flyttat. Nytt element <StatisticalKilometer> 2006-03-20 2.2 Mindre justeringar av vissa element. 2006-03-01 <DiscountData> på komponentnivå behövs inte i KPS. 2006-02-27 2.2, 2.2.17 Lagt till termlängder och ytterligare några förklaringar. 2006-02-24 4 Beskrivning av planerade förändringar i EM. 2006-02-22 Diverse mindre tillägg och justeringar 3
1 Inledning Detta dokument beskriver version 1.10 av PETRA Ekonomimeddelande, som tas i produktion 2007-06-02. PETRA Ekonomimeddelande är ett XML-meddelande som kan skickas från PETRA till: 1. Ett resekontoföretag om valt betalningsmedel har åtgärden Ekonomimeddelande. 2. Säljställen som har tjänsten Ekonomimeddelande. 3. Beställningens betalande kund om denne har tjänsten Ekonomimeddelande. 4. Externa kompletteringssystem och säljsystem (för närvarande Icomera, SJ Kundprogramsystem och AccesRail) om beställningen har aktiva rader vars varunummer ska generera ett ekonomimeddelande. Ekonomimeddelande kan sändas då någon av följande transaktioner genomförs: Beställ tjänst (enligt punkt 4 ovan) Debitera beställning Uppdatering av tillfällig resenär på beställningsrad (enligt punkt 4 ovan) Avbeställa beställningsrad (enligt punkt 4 ovan) Kreditera beställningsrad (inklusive Kreditera annan orsak) Kreditera särskilda fall Betala hos Biljett direkt Uthämtning av beställning (enligt punkt 4 ovan) fr o m 2007-03-10 Vid Kreditera särskilda fall skapas en ny beställning med ett nytt beställningsnummer och ett annat varunummer än den vara eller tjänst som krediteras. Inga detaljerade uppgifter om resenärer, sträckor, platser etc finns i detta meddelande. Orsaken till detta är att uppgifterna i den ursprungliga beställningen inte finns kvar eller att försäljningen gjorts i ett annat system än PETRA. 4
2 Innehåll i XML-meddelandet 2.1 DTD En DTD som utgör den formella definitionen på meddelandet finns på http://docs.linkon.se/ekonomimeddelande/. Normalt finns det två versioner publicerade, där den ena är aktuell version i produktionsmiljön. I de element som kan innehålla text ersätts vissa specialtecken med koder enligt XMLstandarden, till exempel: Tecken < < & Skrivs i XML som & 2.2 Beskrivning av meddelandestrukturen Meddelandet är hierarkiskt uppbyggt och innehållet hämtas från orderboken i PETRA. Efter vissa element finns styrtecken med följande betydelse:? Frivilligt element som kan utelämnas eller förekomma en gång + Obligatoriskt element som kan förekomma en eller flera gånger * Frivilligt element som kan utelämnas eller förekomma en eller flera gånger Meddelandets innehåll (utan sluttaggar): Element Beskrivning Längd Källa <Em> Ekonomimeddelande <Data> <MessageInfo> <HostSystem> Avsändare 6 LINKON <Version> Version av EM Varierar 1.11 <AgentInfo> Se avsnitt 2.2.1 <Destination> Mottagande resekontosystem 2 TFK.KORTKOD <PaymentSalesUnitId> Betalande säljställe resp. Krediterande säljställe 4 TFO.BETSTNR TFOR.KDTSTNR <SalesUnitName> Säljställenamn 30 TMSST.SSTNMN <UserId> Användarid 6 TFO.BETANVDID <OrderCreator> Beställare 10 TFO.BSKNDNR <TerminalId> <PaymentDateTime> Betalningsterminal resp. Krediteringsterminal Betalningstidpunkt resp. Krediteringsdatum 8 TFO.BETTMLID TFOR.KDTTMLID TFO.BETDAT & TFO.BETTD TFOR.KDTDAT <RetrievalDateTime> Uthämtningstidpunkt TFO.UTHDAT & TFO.UTKLS <SalesUserName>? Resebyråns säljares namn 8 TFORBS.SLJNMN <OrderCreatorCardNumber>* <CreatorUserId> Beställarens kortnummer (Commeomedlemsnummer) Användarid för den som skapat första beställningsraden <OrderInfo> Beställning 19 TFKIK.KORTNR 6 Se avsnitt 2.2.2 <OrderId> Beställningsnummer 8 TFO.BSNR 5
Element Beskrivning Längd Källa <DebitCredit> Händelse 1 Se avsnitt 2.2.3 <Reference1> Beställningens referensefternamn 35 TFONMN.KNDENMN <Reference2> Beställningens referensförnamn 15 TFONMN.KNDFNMN <SalesUnitCategoryCode>? Säljställekategori för säljstället som skapat händelsen i <DebitCredit> <PaymentInfo> <CustomerId> Betalande kund (PETRA kundnummer) 2 Se avsnitt 2.2.4 (fr o m 2006-11-11) 10 TFO.KNDNR <PaymentType> Betalningsmedel 2 TFO.BETKOD <CreditCardCode> Kortkod 2 TFO.KKORTDATA <CreditCardNumber> Kontokortsnummer 19 Se avsnitt 2.2.5 <CreditCardValidThru> Kontokortsgiltighet <Month> 2 TFO.KKORTDATA <Year> Tvåsiffrigt årtal 2 TFO.KKORTDATA <RequisitionId> Rekvisitionsnummer 6 TFO.REKVNR <Pay menttype2>? Betalningsmedel 2. Används bl a vid restidsgaranti. 2 TFO.BETKOD2 <TravellerCard>? Kundkort för betalare Se avsnitt 2.2.6 <CardType> Korttyp 2 TFO.KORTTYP <CardNumber> Kortnummer 24 TFO.KORTNR <CustomerInfo>? <TravelAgentCustomerId> Säljställets kunds kundnummer 14 TFORBS.RBRKNDNR <CompanyName> Säljställets kunds företagsnamn 20 TFORBS.FTGAVDNMN <CustomerAccount> Säljställets kunds kostnadskonto 50 Se avsnitt 2.2.7 <InvoiceReferences>? Säljställets fakturareferenser Se avsnitt 2.2.8 <InvoiceReference>+ Fakturareferens n 50 TFOFKTRF.FKTREFn <Note> Säljställets anteckningar 20 TFORBS.RSTXT <StreetName> Säljställets kunds gatuadress 30 TFORBS.KNDGTAADR <ZipCode> Säljställets kunds postnummer 6 TFORBS.KNDPSTNR <CityName> Säljställets kunds postadress 20 TFORBS.KNDPSTADR <TextInfo>? Beställningsanteckningar <OrderNote>+ Anteckningsrad 50 TFOANT.ATKRD <RowInfo>+ Beställningsrader <RowData> <PassengerInfo> <TravellerId> Resenärens kundnummer 10 TFOR.RENKNDNR <CustomerName> används för att slå upp: <FirstName> Resenärens förnamn 15 TFK.KNDFNMN <LastName> Resenärens efternamn 35 TFK.KNDENMN <EmployeeId>? Används inte <Priority>? Kundprioritet 3 Se avsnitt 2.2.9 <TravellerCard>* Kundkort Se avsnitt 2.2.10 <CardType> Korttyp 2 TFKKK.KORTTYP <CardNumber> Kortnummer 19 TFKKK.KORTNR <DocumentInfo> <OrderItemId> Beställningsradnummer 3 TFOR.BSRDNR <ProducerCode> Första komponentens färdmedelsproducent (bör inte användas) 3 TFORK.FMPRCNR <TicketId> Biljettnummer 12 TFOR.BJTNR <FareInfo> 6
Element Beskrivning Längd Källa <ServiceName> Varunamn 20 TCT.VRANMN <FareType> Varunamnförkortning 10 TCT.VRANMNFKN <Price> Tjänstepris resp. Krediteringsbelopp Se avsnitt 2.2.11 <PriceVat> <PriceIncVat> <Money> <Vat> <CurrencyCode> Valutaslagkod 3 TFOR.VALSLAKOD <Amount> 14.2 TFOR.TJPRS TFOR.KDTBEL Moms på tjänstepriset resp. krediteringsbeloppet <Money> <CurrencyCode> Valutaslagkod 3 TFOR.VALSLAKOD <Amount> Momsbelopp 14.2 TFOR.MOMSBEL TFOR.KDTMOMSBEL <VatPercentage>? Momsprocent (om tjänsten är momsbelagd) 11.2 TFOR.MOMSPROC <ServiceId> Varunummer 8 TFOR.VRANR <BookingFee1>? Bokningsavgift 1 för tjänsten (används inte f n) <PriceIncVat> <Money> Se avsnitt 2.2.22 <CurrencyCode> 3 TFOR.VALSLAKOD <Amount> 14.2 SUM(TFORK.AVGIFT1) <BookingFee2>? Bokningsavgift 2 för tjänsten (återbetalas ej) <PriceIncVat> <Money> <Price2>? Se avsnitt 2.2.22 <CurrencyCode> 3 TFOR.VALSLAKOD <Amount> 14.2 SUM(TFORK.AVGIFT2) Andel av tjänstepris betalt med <PaymentType2>. <PriceVat> <PriceIncVat> <Money> Se avsnitt 2.2.11 <CurrencyCode> 3 TFOR.VALSLAKOD <Amount> 14.2 TFOR.TJPRSBET2 <Vat> <Money> <CurrencyCode> <Amount> 14.2 TFOR.MOMSBEL eller 0 om priset skiljer sig från tjänstepriset. <VatPercentage> 11.2 TFOR.MOMSPROC <CampaignCode>? Kampanjkod för PETRA-kampanjer 20 TFOR.KAMPANJKOD (fr o m 2006-11-11) <ReasonCode>? Krediteringsorsak 2 Se avsnitt 2.2.12 <DiscountInfo>? <DiscountData>+ <DiscountCode> Rabattformskod för standardrabatt 3 TFOR.RBTFOSTDn <NumberOfDiscounts> Antal rabatterade resenärer 4 TFOR.ANTRBTFOSTD n <InvoiceReferences>? Säljställets fakturareferenser Se avsnitt 2.2.8 <InvoiceReference>+ Fakturareferens n 50 TFOFKTRF.FKTREFn <Quantity>? Se avsnitt 2.2.13 7
Element Beskrivning Längd Källa <Traveller>+ <Category> Resenärstyp 2 TFORK.RENTKn <NumberOfTravellers> Antal resenärer 3 TFORK.ANTRENTn <Section ComponentOrderNumber= n>+ Komponenter Se avsnitt 2.2.14 <SectionType> Typ av tjänst 2 Se avsnitt 2.2.15 <Departure> Avgångsstation <Location> Se avsnitt 2.2.16 <LocationId> Lokalnummer 5 TFORK.LOKAL1 <LocationShortName> Lokalnamn 15 TMSTN.STNNMNFKN <LocationProducerCode> Landsnummer 3 TFORK.LOKALPRCNR1 <DateTime> Avgångsdatum och tid TFORK.DATUM1 & TFORK.KLS1 <Arrival> Ankomststation <Location> Se avsnitt 2.2.16 <LocationId> Lokalnummer 5 TFORK.LOKAL2 <LocationShortName> Lokalnamn 15 TMSTN.STNNMNFKN <LocationProducerCode> Landsnummer 3 TFORK.LOKALPRCNR2 <DateTime> Ankomstdatum och tid TFORK.DATUM2 & TFORK.KLS2 <TravelRoute> Resväg 2 TFORK.RVGKOD <RailwayService> <ProducerCode> Färdmedelsproducent 3 TFORK.FMPRCNR <TransportId> Färdmedelsnummer (tågnummer) 5 TFORK.FMNR <Comfort> Komfort (bokningsklass) 2 TFORK.KMFT <ProductCode> Produktkod (tågtyp) 3 TFORK.PRDKOD <SeatInfo>* Platsreservationer <SpecialCompartment> Särskild avdelning 2 TFORKPS.UTREGS <CarriageId> Vagnsnummer 3 TFORKPS.SKLTVGNNR <SmokingDepartment> Rökutrymme 2 TFORKPS.UTRROK <CompartmentType> Sovkupéns kön 2 TFORKPS.UTRKON <PlacementOrientation> Platsplacering 2 TFORKPS.PLSPLAC <PlacementNumber> Platsnummer 3 TFORKPS.PLSNR <PlacementCharacteristics> Platsegenskap 2 TFORKPS.PLSEGS <CompartmentSize> Utrymmesstorlek 2 TFORK.UTREGS <StatisticalKilometer>? Statistikkilometer 4 Se avsnitt 2.2.19 (fr o m 2006-11-11) <Price>? Beräknad andel av tjänstepriset för denna komponent. -- Se avsnitt 2.2.20 (fr o m 2006-11-11) <PriceVat> -- (fr o m 2006-11-11) <PriceIncVat> -- (fr o m 2006-11-11) <Money> -- (fr o m 2006-11-11) <Vat> <CurrencyCode> Valutaslagkod 3 TFOR.VALSLAKOD (fr o m 2006-11-11) <Amount> Belopp 14.2 TFORK.BERATJPRS (fr o m 2006-11-11) Moms på beräknad andel av tjänstepriset -- (fr o m 2006-11-11) <Money> -- (fr o m 2006-11-11) <CurrencyCode> Valutaslagkod 3 TFOR.VALSLAKOD (fr o m 2006-11-11) <Amount> Momsbelopp 14.2 TFOR.MOMSBEL * TFORK.BERATJPRS / 8
Element Beskrivning Längd Källa TFOR.TJPRS (fr o m 2007-03-10) <VatPercentage>? <PriceInclDiscount>? Momsprocent (om tjänsten är momsbelagd) Beräknad andel av tjänstepriset för denna komponent inklusive rabattbelopp 11.2 TFOR.MOMSPROC (fr o m 2006-11-11) -- Se avsnitt 2.2.21 (fr o m 2006-11-11) <PriceIncVat> -- (fr o m 2006-11-11) <Money> -- (fr o m 2006-11-11) <CurrencyCode> Valutaslagkod 3 TFOR.VALSLAKOD (fr o m 2006-11-11) <Amount> Belopp 14.2 TFORK.BERATJPRS + TFORK.BERARABBELSTD (fr o m 2006-11-11) <Points>? Kundprogramsrabatt uttryckt i poäng 8 TFORK.KPSPOANG (fr o m 2006-11-11) <BookingFee1>? Bokningsavgift 1 för komponenten (används inte f n) <PriceIncVat> <Money> Se avsnitt 2.2.22 (fr o m 2007-03-10) <CurrencyCode> 3 TFOR.VALSLAKOD <Amount> 14.2 TFORK.AVGIFT1 <BookingFee2>? Bokningsavgift 2 för komponenten (återbetalas ej) <PriceIncVat> <Money> Se avsnitt 2.2.22 (fr o m 2007-03-10) <CurrencyCode> 3 TFOR.VALSLAKOD <Amount> 14.2 TFORK.AVGIFT2 Vid eventuella skillnader i elementens namn, placering, längd eller beskrivning så är det EM.DTD som gäller framför detta dokument. 2.2.1 Säljställe I EM finns information om det betalande respektive krediterande säljstället i elementet <AgentInfo>. Det finns ingen information om beställande eller avbeställande säljställe. En beställning kan innehålla flera beställlningsrader <RowInfo> och raderna behöver inte vara beställda av samma säljställe som tar betalt. Flera olika säljställen kan lagra beställningsrader i beställningen innan den betalas. 2.2.2 Beställare av första raden (fr o m 2007-06-02) Fältet <CreatorUserId> i <AgentInfo> innehåller användarnamnet på den som beställt den första aktiva raden i beställningen. Fältet är obligatoriskt, men kan innehålla en tom sträng. Innehållet hämtas från TFOR.BSANVDID för första beställningsraden. 9
2.2.3 Händelser I elementet <DebitCredit> finns information om vid vilken händelse i PETRA som ekonomimeddelandet har skickats. Följande händelser kan generera ett ekonomimeddelande: <DebitCredit> Händelse i PETRA Kommentar B D U A K Beställning av en poängtjänst Debitering av en beställning Uppdatering av en beställningsrads tillfälliga resenär Avbeställning av en eller flera beställningsrader Kreditering av en eller flera beställningsrader Detta meddelande skickas endast till SJ Kundprogramsystem (KPS-gränssnitt I018) vid prisfråga på en poängtjänst. Övriga prenumeranter får inte några meddelanden vid denna händelse. Hela beställningen skickas till mottagaren då den betalas i PETRA. Detta meddelande skickas endast till SJ Kundprogramsystem (KPS-gränssnitt 1012) vid efterregistrering av en intjäningstjänst med setretroactivemember. Övriga prenumeranter får inte några meddelanden vid denna händelse. Detta meddelande skickas till SJ Kundprogramsystem (KPSgränssnitt I012) och Icomera. Övriga prenumeranter får inte några meddelanden vid avbeställning. Den eller de återköpta raderna skickas till mottagaren. SJ Kundprogramsystem får detta meddelande endast vid återköp av poängtjänster. 2.2.4 Säljställekategori (fr o m 2006-11-11) Säljställekategorin för säljstället som skapat händelsen i <DebitCredit> finns i elementet <SalesUnitCategoryCode>. Värdet hämtas från TMSST.SSTKAT. Exempel på värden: <SalesUnitCategoryCode> AG AR BD BM CC CW IK PR SJ TF Säljställekategori Agent AccesRail Biljett direkt SJ Biljettautomat Connex contact center Connex webb SJ Internet kundbokning Pressbyrån/7-eleven SJ Resebutik SJ Telefonförsäljning 2.2.5 Kontokortsuppgifter Elementet <CreditCardNumber> innehåller för kontokortsnummer ett maskat kortnummer, dvs ett antal siffror i mitten har ersatts med asterisker. Om betalningsmedlet är Resekonto så innehåller elementet ett resekontonummer, och detta nummer maskas ej. Innehållet hämtas från TFO.KKORTDATA. 2.2.6 Kundkort för betalare Om en medlem i SJ Kundprogram har köpt s k poängtjänster finns medlemskortets uppgifter i elementet <TravellerCard> i <PaymentInfo>. Existensen av detta element 10
innebär att en eller flera av beställningsraderna har rabatterats med poäng från SJ Kundprogram och innehåller information om vilket konto i SJ Kundprogramsystem (KPS) som ska belastas. Detta element är endast av intresse för KPS. Övriga prenumeranter på EM kan ignorera detta element. 2.2.7 Konteringsinformation Fr o m 2007-06-02 kommer kunders konteringsinformation normalt att överföras i elementet <CustomerAccount> (Säljställets kunds kostnadskonto) i stället för som tidigare i elementet <Reference1> (Beställningens referensefternamn). Det är dock upp till säljaren respektive säljklienten exakt vad som lagras var. Innehållet hämtas från TFORBS.KSTKTO. 2.2.8 Fakturareferens (fr o m 2008-03-08) Vissa PETRA-klienter kan lagra upp till fem rader med fakturareferensuppgifter i en beställning. Fr o m 2008-03-08 skickas dessa fakturareferenser i ekonomimeddelandet i elementet <InvoiceReferences>. Fakturareferenser på beställningsnivå finns i elementet <CustomerInfo> och fakturareferenser på radnivå finns i elementet <RowData>. 2.2.9 Kundprioritet (fr o m 2008-03-08) Fr o m 2008-03-08 finns ett frivilligt fält för kundprioritet med i <PassengerInfo>. Elementet finns bara med för kända kunder (med kundnummer) som har en kundprioritet i kundregistret (TFK.KNDPRIO). För närvarande förekommer följande värden: <Prioritiy> Betydelse 1 Commeo 1-stjärnig medlem 2 Commeo 2-stjärnig medlem 4 Commeo 4-stjärnig medlem Vit Grå Sva SJ Prio-medlem på vit nivå SJ Prio-medlem på grå nivå SJ Prio-medlem på svart nivå 2.2.10 Kundkort för resenär Om kunden har kundkort registrerade i PETRA, finns varje giltigt kundkort med som ett <TravellerCard>, till exempel SJ årskort eller Commeokort. Om en medlem i SJ Kundprogram registrerat ett medlemskortnummer på beställningsraden finns detta kortnummer med i <TravellerCard>. Inga andra medlemskort för SJ Kundprogram finns då med. 2.2.11 Tjänstepris Det pris som kunden betalar lagras i <FareInfo><Price> och inkluderar eventuell moms i <Vat> och bokningsavgift i <BookingFee1> och <BookingFee2>. För närvarande används inte <BookingFee1>. I vissa fall, till exempel vid betalning med en restidsgarantivoucher, kan det hända att två olika betalningsmedel har använts för att betala tjänsten. I elementet <FareInfo><Price> 11
finns tjänstens totala pris varav den del som är betald med betalningsmedlet <PaymentInfo><PaymentType2> finns i elementet <Fareinfo><Price2>. 2.2.12 Krediteringsorsak (fr o m 2008-03-08) Fr o m 2008-03-08 finns krediteringsorsaken med vid kreditering, dvs då <DebitCredit> har värdet K. Vid övriga händelser finns inte <ReasonCode> med i meddelandet. Krediteringsorsaken hämtas från TFOR.KDTORSAK och kan för närvarande ha följande värden: <ReasonCode> AT BY FE RG TO Betydelse Normalt återköp Byte Felexpediering Restidsgaranti Timeout 2.2.13 Antal resenärer Normalt gäller en tjänst endast för en resenär, vilket innebär att det endast förekommer ett element av typen <Quantity> <Traveller> <Category>VU</Category> <NumberOfTravellers>1</NumberOfTravellers> </Traveller> </Quantity> För gruppresor och vissa nattågsbiljetter kan flera resenärer förekomma i samma tjänst och då kan det se ut så här när 10 vuxna och 20 ungdomar åker: <Quantity> <Traveller> <Category>VU</Category> <NumberOfTravellers>10</NumberOfTravellers> </Traveller> <Traveller> <Category>UN</Category> <NumberOfTravellers>20</NumberOfTravellers> </Traveller> </Quantity> Gruppbiljettens tjänstepris i <FareInfo><Price> gäller för hela gruppen. Det finns inga uppgifter om priset per person. 2.2.14 Komponentlöpnummer Elementet kompletteras med attributet ComponentOrderNumber, som innehåller komponentlöpnumret TFORK.KOMPLOPNR, då EM skickas till SJ Kundprogramsystem (KPS) vid beräkning av poängvärde för en tjänst, dvs då <DebitCredit> innehåller värdet B. Svaret från KPS måste innehålla samma värde på attributet som frågan. I övriga fall används inte detta attribut. 12
2.2.15 Komponenttyper En tjänst <RowInfo> består av en eller flera komponenter. Det finns flera olika typer av komponenter i ett EM: <SectionType> Förklaring BR F R ÖV Bokad resa, dvs tjäns ten består av både en färdkomponent för resan och en platskomponent för reservationen. Färdbiljett, dvs en tjänst utan platsreservation. Reservation, dvs enbart en platsreservation. Normalt måste den kompletteras med en färdbiljett för att gälla för resa. Övriga komponenter. Dessa används för att beskriva tjänster som inte är tågresor, till exempel avgifter, årskort, parkering, tågtaxi eller hyrbil. OS Ombokningsskydd (fr o m 2007-06-02) Denna komponent kommer i förekommande fall sist i listan med och mottagande system bör inte tolka innehållet i denna som en del av resan. Innehåll i <ProducerCode> Sträckproducent för sträckan. Sträckproducent för sträckan. Färdmedelsproducent för tåget. Normalt tomt, men för tågtaxi finns uppgifter om det tåg som taxin ansluter till. Tomt Innehåll i <TransportId> Tågnummer för tåget. Eventuellt tågnummer för tåget, men inte alla färdbiljetter är kopplade till ett specifikt tåg. Tågnummer för tåget. Normalt tomt, men för tågtaxi finns uppgifter om det tåg som taxin ansluter till. Tomt I avsnitt 3.1 finns exempel på hur olika SectionType kan se ut. 2.2.16 Lokaler Alla lokaler eller stationer beskrivs i elementet <Location> och identifieras med sitt landsnummer och sitt lokalnummer, till exempel: <LocationProducerCode> <LocationId> <LocationShortName> 74 1 Stockholm C 74 100 Limmared 76 100 Oslo S 86 1 Frederikshavn Följande landsnummer förekommer i SJs trafik: <LocationProducerCode> Land 74 Sverige 76 Norge 80 Tyskland 86 Danmark 2.2.17 Komfort, prisnivå, prisgrupp och fare type Det finns många begrepp som beskriver vilken typ av biljett som finns i beställningen. I säljdialogen används normalt begreppet prisgrupp som en sammanfattande beskrivning av 13
biljettens innehåll och regelverk. Internt i PETRA används prisnivå vid prissättning av färdkomponenter och komfort vid platsreservation. Term XML-element Databaskolumn Beskrivning Exempel <ServiceId> VRANR Varunumret identifierar unikt den tjänst som sålts. Vissa tjänster kan bestå av olika komponenter och därför går det inte alltid att dra slutsatser om exakt vad som sålts enbart med hjälp av varunumret. Varunamn <ServiceName> VRANMN Varunamnet beskriver i klartext vilken tjänst som sålts. Komfort <Comfort> KMFT Beskriver komforten i fordonet, dvs bredd och benutrymme för stolen samt vissa andra komfortegenskaper som kan finnas i olika fordon. Prisnivå PRSNV Beskriver prisets nivå och är det grundläggande begreppet för prissättning. Prisgrupp DEFGRP Beskriver mycket kortfattat biljettens egenskaper och vilka produkter (tågtyper) som kan ingå i biljetten. Prisgruppen kopplar ihop prisnivå och komfort. Varunummer Varunamnförkortning <FareType> VRANMNFKN Fare type används i Linkons ekonomimeddelande (EM) och i Amadeus SIR-meddelande. Elementet används endast i ekonomimeddelanden samt i vissa rapporter i PETRA Ekonomi. I PETRA Sälj används det inte. 10132002 1 KL FK (1 klass), AK (2 klass) AM (1 klass Plus ), AL (1 klass), F1 (Just nu 1 kl), NO (Normal), FO (Just nu 2 kl), SM (Sista minuten) AM (1 klass Plus ), AL (1 klass), S1 (1 klass utrikes), F1 (Just nu 1 kl), NO (2 klass), S2 (2 klass utrikes), FO (Just nu 2 kl, SM (Sista minuten) 1 KL PLUS, 1 KL, 2 KL, JUST NU, SM 2.2.18 Datum och tid Alla datumelement är uppbyggda av en <DateTime>: Element Beskrivning Längd Källa <DateTime> <TimeZone> Tidzon 3 CET <Year> År 4 <Month> Månad 2 <Day> Dag 2 <Hour>? Timmar 2 <Minute>? Minuter 2 <Second>? Sekunder 2 Dessa element är inte specificerade i tabellen med meddelandebeskrivning ovan. 14
Elementet <TimeZone> innehåller alltid CET oavsett om vintertid eller sommartid tillämpas vid den aktuella tidpunkten. Även avgångstider och ankomsttider i länder utanför den centraleuropeiska tidzonen har värdet CET. För avgångstider och ankomsttider är elementet <Second> alltid fyllt med 00. Ankomst vid midnatt den 1 februari 2006 anges som: <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>02</Month><Day>01</Day> <Hour>24</Hour> <Minute>00</Minute><Second>00</Second> </DateTime> Avgång vid midnatt den 2 februari 2006 (dvs vid samma tidpunkt som ankomsten ovan) anges som: <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>02</Month><Day>02</Day> <Hour>00</Hour> <Minute>00</Minute><Second>00</Second> </DateTime> 2.2.19 Statistikkilometer (fr o m 2006-11-11) Elementet <StatisticalKilometer> innehåller delsträckans avstånd i kilometer (SUM(TFORKDS.STATKM)) och används endast om <DebitCredit> = B och endast för färdkomponenter. 2.2.20 Beräknad andel av tjänstepris och moms på delsträckenivå Elementet <Price> innehåller den beräknade andelen av tjänstepriset och momsen som finns i elementet <FareInfo><Price>. Elementet används inte vid kreditering (<DebitCredit>K</DebitCredit>). Elementet är i första hand avsett för SJ Kundprogramsystem (KPS) och bör inte användas generellt av andra mottagande system. Summan av alla priser och momsbelopp på nivån kan avvika från motsvarande uppgifter i <FareInfo> på grund av avrundning. 2.2.21 Orabatterat pris <PriceInclDiscount> är ett frivilligt element och förekommer endast då ekonomimeddelanden skickas vid debitering och endast då tjänsten är rabatterad med standardrabatten Byte av resa, som används för tjänster som har restriktioner på återköp, men tillåter byte till en annan avgång. Elementet är i första hand avsett för SJ Kundprogramsystem (KPS) och bör inte användas generellt av andra mottagande system. Nedanstående exempel visar hur en tjänst rabatterad för Byte av resa ser ut i ekonomimeddelandet. Endast relevanta delar av meddelandet visas här. <RowData> <FareInfo> 15
<Price> <PriceVat> <PriceIncVat> <Money> <CurrencyCode>SEK</CurrencyCode> Beställningsraden är rabatterad 100 % <Amount>00000000000.00</Amount> och därför är tjänstepriset 0 kr. </Money> </PriceIncVat> </PriceVat> </Price> </FareInfo> <DiscountInfo> <DiscountData> <DiscountCode>BAR</DiscountCode> <NumberOfDiscounts>001</NumberOfDiscounts> </DiscountData> </DiscountInfo> </Rowdata> <Price> <PriceVat> <PriceIncVat> <Money> <CurrencyCode>SEK</CurrencyCode> <Amount>00000000000.00</Amount> </Money> </PriceIncVat> </PriceVat> </Price> <PriceInclDiscount> <PriceIncVat> <Money> <CurrencyCode>SEK</CurrencyCode> <Amount>00000000410.00</Amount> </Money> </PriceIncVat> </PriceInclDiscount> Den använda rabattformen är Byte av resa. Komponentens andel av tjänstepriset är 0 kr. Utan rabatt skulle komponentens andel av tjänstepriset varit 410 kr. 2.2.22 Bokningsavgift Bokningsavgift i <BookingFee1> och <BookingFee2> tas i vissa fall ut för en tjänst och lagras på beställningsradsnivå i <FareInfo>. Fr o m 2007-03-10 finns bokningsavgiften specificerad per komponent (delsträcka). Dessa element är i första hand avsett för SJ Kundprogramsystem (KPS) och bör inte användas generellt av andra mottagande system. Summan av alla bokningsavgifter på nivån kan avvika från motsvarande uppgifter i <FareInfo> på grund av avrundning. 16
17
3 Exempel 3.1 SectionType 3.1.1 Exempel på bokad resa <SectionType>BR</SectionType> <Departure> <Location> <LocationId>00001</LocationId> <LocationShortName>Stockholm C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>08</Hour><Minute>15</Minute><Second>00</Second> </DateTime> </Departure> <Arrival> <Location> <LocationId>00002</LocationId> <LocationShortName>Göteborg C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>11</Hour><Minute>17</Minute><Second>00</Second> </DateTime> </Arrival> <TravelRoute>01</TravelRoute> <RailwayService> <ProducerCode>074</ProducerCode> <TransportId>425</TransportId> <Comfort>FK</Comfort> <ProductCode>X2</ProductCode> <SeatInfo> <SpecialCompartment></SpecialCompartment> <CarriageId>1</CarriageId> <SmokingDepartment>IR</SmokingDepartment> <CompartmentType></CompartmentType> <PlacementOrientation>G</PlacementOrientation> <PlacementNumber>5</PlacementNumber> <PlacementCharacteristics>SG</PlacementCharacteristics> </SeatInfo> <CompartmentSize></CompartmentSize> </RailwayService> En bokad resa har alltid en avgångsstation och en ankomststation. Resvägskod finns alltid. En sträckproducent och ett tågnummer finns alltid. En bokad resa har alltid uppgifter om vagn och plats i tåget. 18
3.1.2 Exempel på färdbiljett <SectionType>F</SectionType> <Departure> <Location> <LocationId>00001</LocationId> <LocationShortName>Stockholm C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>08</Hour><Minute>15</Minute><Second>00</Second> </DateTime> </Departure> <Arrival> <Location> <LocationId>00002</LocationId> <LocationShortName>Göteborg C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>11</Hour><Minute>17</Minute><Second>00</Second> </DateTime> </Arrival> <TravelRoute>01</TravelRoute> <RailwayService> <ProducerCode>074</ProducerCode> <TransportId>425</TransportId> <Comfort></Comfort> <ProductCode>X2</ProductCode> <CompartmentSize></CompartmentSize> </RailwayService> En separat färdbiljett har alltid en avgångsstation och en ankomststation. En sträckproducent finns alltid. Normalt finns också ett tågnummer. Komfort är alltid tomt och inga uppgifter om sittplats finns. 3.1.3 Exempel på platsreservation <SectionType>R</SectionType> <Departure> <Location> <LocationId>00001</LocationId> <LocationShortName>Stockholm C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>08</Hour><Minute>15</Minute><Second>00</Second> </DateTime> En platsreservation har alltid en avgångsstation 19
</Departure> <Arrival> <Location> <LocationId>00002</LocationId> <LocationShortName>Göteborg C</LocationShortName> <LocationProducerCode>074</LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour>11</Hour><Minute>17</Minute><Second>00</Second> </DateTime> </Arrival> <TravelRoute></TravelRoute> <RailwayService> <ProducerCode>074</ProducerCode> <TransportId>425</TransportId> <Comfort>FK</Comfort> <ProductCode>X2</ProductCode> <SeatInfo> <SpecialCompartment></SpecialCompartment> <CarriageId>1</CarriageId> <SmokingDepartment>IR</SmokingDepartment> <CompartmentType></CompartmentType> <PlacementOrientation>G</PlacementOrientation> <PlacementNumber>5</PlacementNumber> <PlacementCharacteristics>SG</PlacementCharacteristics> </SeatInfo> <CompartmentSize></CompartmentSize> </RailwayService> och en ankomststation. Resvägskod saknas. En färdmedelsproducent och ett tågnummer finns alltid. En platsreservation har alltid uppgifter Om vagn och plats i tåget. 3.1.4 Exempel på övriga tjänster <SectionType>ÖV</SectionType> <Departure> <Location> <LocationId></LocationId> <LocationShortName></LocationShortName> <LocationProducerCode></LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour></Hour><Minute></Minute><Second></Second> </DateTime> </Departure> <Arrival> <Location> <LocationId></LocationId> <LocationShortName></LocationShortName> <LocationProducerCode></LocationProducerCode> En övrig tjänst kan ha uppgift om en station, men många tjänster saknar helt uppgift om station Första giltighetsdatum finns alltid. I vissa fall finns också klockslag. Normalt finns ingen ankomststation, men tågtaxi kan ha det. 20
</Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour></Hour><Minute></Minute><Second></Second> </DateTime> </Arrival> <TravelRoute></TravelRoute> <RailwayService> <ProducerCode></ProducerCode> <TransportId></TransportId> <Comfort></Comfort> <ProductCode></ProductCode> <CompartmentSize></CompartmentSize> </RailwayService> Sista giltighetsdatum finns alltid. I vissa fall finns också klockslag. Resvägskod saknas. Uppgift om producent och tågnummer finns normalt inte, Men tågtaxi kan ha det. 3.1.5 Exempel på ombokningsskydd Ombokningsskyddet har inga andra egenskaper än ett giltighetsdatum. <SectionType>OS</SectionType> <Departure> <Location> <LocationId></LocationId> <LocationShortName></LocationShortName> <LocationProducerCode></LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour></Hour><Minute></Minute><Second></Second> </DateTime> </Departure> <Arrival> <Location> <LocationId></LocationId> <LocationShortName></LocationShortName> <LocationProducerCode></LocationProducerCode> </Location> <DateTime> <TimeZone>CET</TimeZone> <Year>2006</Year><Month>04</Month><Day>06</Day> <Hour></Hour><Minute></Minute><Second></Second> </DateTime> </Arrival> <TravelRoute></TravelRoute> <RailwayService> <ProducerCode></ProducerCode> <TransportId></TransportId> <Comfort></Comfort> <ProductCode></ProductCode> Ett ombokningsskydd Första giltighetsdatum finns alltid. Sista giltighetsdatum finns alltid. 21
<CompartmentSize></CompartmentSize> </RailwayService> 3.2 Resetjänster I december 2007 inför SJ ett nytt tjänsteutbud som medför att flera olika kombinationer av <SectionType> kan förekomma i en <RowInfo>. I detta avsnitt finns några exempel på de vanligaste kombinationerna. Övriga producenters utbud förändras inte. 3.2.1 1 klass med mat, kan återbetalas Med en delsträcka (ett tågnummer) och platsreservation: <RowInfo> <SectionType>BR</SectionType> </RowInfo> Med två delsträckor och med platsreservation på båda delsträckorna: <RowInfo> <SectionType>BR</SectionType> <SectionType>BR</SectionType> </RowInfo> 1 klass-tjänster inkluderar Internet ombord. 3.2.2 1 klass med mat, kan ombokas Med två delsträckor och med platsreservation på båda delsträckorna: <RowInfo> <SectionType>BR</SectionType> <SectionType>BR</SectionType> <SectionType>OS</SectionType> </RowInfo> 1 klass-tjänster inkluderar Internet ombord. 22
3.2.3 2 klass, kan återbetalas, utan plats Med en delsträcka utan platsreservation: <RowInfo> <SectionType>F</SectionType> </RowInfo> 3.2.4 2 klass, kan ombokas Med två delsträckor utan platsreservation: <RowInfo> <SectionType>F</SectionType> <SectionType>F</SectionType> <SectionType>OS</SectionType> </RowInfo> 3.2.5 2 klass, kan ej ombokas Med två delsträckor och platsreservation på den första delsträckan: <RowInfo> <SectionType>BR</SectionType> <SectionType>F</SectionType> <SectionType>ÖV</SectionType> </RowInfo> 3.2.6 2 klass, kan ej ombokas Med en delsträcka utan platsreservation: <RowInfo> <SectionType>F</SectionType> <SectionType>ÖV</SectionType> </RowInfo> 23
3.2.7 Separat platsreservation Separata platsreservationer med en delsträcka kommer att vara mycket sparsamt förekommande på resor i Sverige. De förekommer däremot mer frekvent för internationella resor: <RowInfo> <SectionType>R</SectionType> </RowInfo> 3.2.8 Internet ombord En separat avgift för Internet ombord (för användning i 2 klass): <RowInfo> <SectionType>ÖV</SectionType> </RowInfo> 24
4 Planerade förändringar 2008-03-08 I version 1.11 av EM, som produktionssätts 2008-03-08 införs ett antal nya element. Ett nytt frivilligt element för fakturareferenser införs i ekonomimeddelandet: <!ELEMENT InvoiceReferences ( InvoiceReference+ )> <!ELEMENT InvoiceReference (%String;) > Fakturareferenser läggs till i befintligt element <CustomerInfo> på beställningsnivå: <!ELEMENT CustomerInfo (TravelAgentCustomerId, CompanyName, CustomerAccount, InvoiceReferences?, Note, StreetName, ZipCode, CityName )> På radnivå läggs fakturareferenser till i befintligt element <RowData>: <!ELEMENT RowData (PassengerInfo, DocumentInfo, FareInfo, DiscountInfo?, InvoiceReferences?)> Det befintliga elementet <PassengerInfo> kompletteras med ett nytt element <Priority> för kundprioritet. <!ELEMENT Priority (%String;) > <!ELEMENT PassengerInfo ( TravellerId, CustomerName, EmployeeId?, Priority?, TravellerCard* )> Se även avsnitt 2.2.9. Vid kreditering av en beställningsrad finns krediteringsorsak med i ett element <ReasonCode>. <!ELEMENT ReasonCode (%String;) > <!ELEMENT FareInfo ( ServiceName, FareType, Price, ServiceId, BookingFee1?, BookingFee2?, Price2?, CampaignCode?, ReasonCode? )> 25
5 Referenser I Petra2 Implementation Guide Economy Message Infrastructure finns ytterligare information om hur en applikation kan konfigureras för att ta emot ekonomimeddelanden. En formell beskrivning av aktuell version av ekonomimeddelandet med DTD finns på http://docs.linkon.se/ekonomimeddelande/. En rutinbeskrivning för hur förändringar av ekonomimeddelandet görs finns i SJs dokument Rutin för ändringar av innehållet i ekonomimeddelandet (EM). 26