Petra Användarhandbok

Transkript

1 Petra Användarhandbk Infrmatinsmeddelanden Versin 1.5 Utgiven Författare Agneta Eklund

2 Petra Användarhandbk Innehåll 0 Revisiner Inledning Händelser Mttagare Beskrivning av de lika typerna av meddelanden Säljinfrmatinsmeddelande (SM) Reseinfrmatinsmeddelande Ljalitetsinfrmatinsmeddelande (LM) Distributinsmeddelande (DM) Obkatresandeinfrmatinsmeddelande (UM) Innehåll i XML-meddelandet Schema Detaljer för vissa element SalesOrderId Krttyp Lkaler Kmfrt, prisnivå, prisgrupp ch faretype Redigeringsinfrmatin (vid beställningskedja) Redigeringsåtgärd Belpp att faktura vid redigering (resekntföretag med nettfaktura) Plaintexter Versiner Giltiga versiner Referenser

3 0 Revisiner Följande revisiner av dkumentet är gjrda: Petra Användarhandbk Revisin Datum Kmmentar Första versin Nya versiner samt ny typ av meddelande, DM ch UM Justering av kap 2, Händelser Justerat kap ch Nya versiner av schema för LM ch SM, kap Nytt kap Belpp att faktura vid redigering (resekntföretag med nettfaktura) 3

4 Petra Användarhandbk 1 Inledning Handbken beskriver Petra Infrmatinsmeddelande sm lanserades Med infrmatinsmeddelande (IM) avses en lösning för att skicka ut ett XML-baserat meddelande till lika mttagare sm främst mttar meddelandet genm att läsa en MQ-kö. Infrmatinsmeddelande (IM) är ett samlingsnamn för de lika typer av meddelanden sm kmmer kunna skickas. Varje utgående meddelande kmmer att finnas definierat med en meddelandetyp ch en versin. Följande typer av meddelanden finns: Säljinfrmatinsmeddelande (SM) sm innehåller mtsvarande element sm det tidigare Eknmimeddelandet med vissa marginella begränsningar. Reseinfrmatinsmeddelande sm ska förse peratörer med infrmatin m resr, sm behövs i den perativa verksamheten. Ljalitetsinfrmatinsmeddelande (LM) sm ska sändas till peratör sm har bnusprgram för sina kunder. Edh-distributin-message (DM) ska förse peratörer med infrmatin m biljettkd sm skapats efter att SMS biljett sänts ut. Order-unbked-message (UM) sänds för bkade resr. Det kan finnas flera versiner samtidigt för varje typ av meddelande. Av neutralitetsskäl kmmer det vara så att lika typer av mttagare erbjuds lika typer av infrmatinsmeddelanden. Se kapitel 4 4

5 Petra Användarhandbk 2 Händelser För följande händelser kan ett infrmatinsmeddelande skickas. Elementet EVENT. Debitering (betalning) av en beställning ( BET) Avbkning av en beställningsrad (AVB) Kreditering av en beställningsrad (KDT) Uppdatering (Operatinen setretractivemember) (UPD) E-distributin av en beställningsrad (EDI) Händelserna uppdateras i element Event med beskrivning enligt van. Vid debitering av en beställning i status Delbetald kan skickas både debiterings-, avbeställning- ch krediteringsmeddelande. Det kan även vara fler än ett avbeställningsrespektive krediteringsmeddelande sm skickas. Vid Kreditera särskilda fall skapas en ny beställning med ett nytt beställningsnummer ch ett annat varunummer än den tjänst sm krediteras. Inga detaljerade uppgifter m resenärer, sträckr, 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 gjrts i ett annat system än PETRA. Vid Kreditera annan rsak skapas ckså en ny beställning med ett nytt beställningsnummer men det kpieras över en hel del av infrmatin från den gamla beställningsraden. 5

6 Petra Användarhandbk 3 Mttagare Mttagarna av infrmatinsmeddelanden kan vara t ex 1. Ett resekntföretag för visst betalningsmedel (fn Reseknt) 2. Säljställen. 3. Beställningens betalande kund. 4. Externa kmpletteringssystem, kundprgramsystem ch trafikledningssystem m beställningen har aktiva rader vars varunummer ska generera ett eknmimeddelande. 6

7 Petra Användarhandbk 4 Beskrivning av de lika typerna av meddelanden 4.1 Säljinfrmatinsmeddelande (SM) Säljinfrmatinsmeddelande (SM) är tänkt för Säljställe (distributör), Resekntföretag eller Kundföretag. SM initieras genm att visst betalningsmedel, sm reseknt använts, säljställe har ntering på säljställenivå m infrmatinsmeddelande samt att kundföretag i kundregistret har ntering att de ska ha infrmatinsmeddelande. I SM ingår all infrmatin m rdern, eknmisk infrmatin ch uppgift m all säljinfrmatin m t ex säljställe, beställare mm. 4.2 Reseinfrmatinsmeddelande (TM) Reseinfrmatinsmeddelande TM är tänkt för peratörer eller mtsvarande. Infrmatinen är tänkt att användas av den perativa ledningen under resan ch/eller för biljettkntrll. Urval för att sända ut infrmatinen utgår från tjänster sm resp mttagare har i sitt utbud. TM ska innehålla infrmatin m den aktuella peratörens resa, ch viss eknmisk infrmatin, bl a pris per resa. Uppgifter sm rör biljettidentifikatin, beställande/betalande säljställe samt infrmatin sm rör den aktuella resan ch resenären ska ingå i TM. I TM inkluderas infrmatin m andra peratörers delsträckr sm ingår i samma resekedja i syfte att kunna infrmera kund vid byte av förbindelse, förseningar eller bruten förbindelse. Mttagare av TM har ansvar för att beställa registervård för de tjänster för vilka man önskar få TM för. 4.3 Ljalitetsinfrmatinsmeddelande (LM) Ljalitetsmeddelande är till för Operatörer/företag, sm har ljalitetsprgram ch vill samla in infrmatin m sina kunder för att ge någn frm av belöning för att de ska handla mer. LM innehåller infrmatin sm rör detaljerad infrmatin m resan, resenär, priser, kunduppgifter, betalningsmedel, samt tillägg för de specifika fält sm hör till kundprgrammet. Urval för utskick av infrmatinen är peratörens egna tjänster. Ingen infrmatin m övriga peratörer sm ingår i samma resekedja ingår i LM. Dck finns en flagga sm säger att det finns ytterligare rader sm har filtrerats brt. Mttagare av LM har ansvar för att beställa registervård för de tjänster för vilka man önskar få LM för, dck kan man bara beställa registervård för egna tjänster. Om någn mttagare behöver LM för andra samarbetspartners tjänster ska denna registervård beställas av den sm äger de tjänsterna. 4.4 Distributinsmeddelande (DM) Distributinsmeddelande sänds när SMS-biljett är distribuerad. Det skapas DM för aktivering av biljettkd ch vid avbkning även avaktiveringskd. DM kan sändas per peratör. 4.5 Obkatresandeinfrmatinsmeddelande (UM) UM (U för unbked) skall skickas till peratörer när det säljs en bkad resa i Petra. 7

8 Petra Användarhandbk Meddelandet triggas för utvalda varunummer på samma sätt sm LM ch TM görs idag. De primära användningsmrådena är Reskassa ch relatinsbundna peridkrt, typ Uppsala- Stckhlm men ckså för icke relatinsbundna peridkrt sm SL-krt ch ULkrt. UM kan tillsvidare endast användas för att ge ny giltighetstid till eller fylla på (Reskassa) redan befintliga krt. UM innehåller infrmatin sm rör detaljerad infrmatin m prdukten, resenär, pris, kunduppgifter, betalningsmedel samt krtnummer i tillämpliga fall för det krt sm ska få ny giltighetstid eller fyllas på. 5 Innehåll i XML-meddelandet 5.1 Schema För innehåll i schema se InfrmatinMessage: Detaljer för vissa element SalesOrderId I all kmmunikatin med slutkunder skall SalesOrderId (gärna tillsammans med SalesOrderSequenceNumber) användas istället för OrderId. Det är det enda beställningsnummer sm slutkunden känner till Krttyp Elementet <CardType> visar krttypen ch kan för närvarande ha någt av följande värden: <CardType> Beskrivning B C D E Årskrt Guld med Resplus Årskrt Silver Årskrt Silver Plus SJ Tjänsteresekrt F SJ Pri-krt (fr m ) G SJ Årspendlarkrt (utgått ) H SJ Årskrt Silver med Resplus (fr m ) J SJ Årskrt Silver Plus med Resplus (fr m ) K SJ Avtalskrt, tidigare Cmmekrt (utgått 2015), L Årskrt Guld (fr m ) M SJ Månadskrt (fr m ) P Q T U V X Rekryt 9 mån resplus Rekryt 11 mån resplus SJ Fakturakrt SAS ch SJ årskrt Sverige (fr m ). Upphört SAS ch SJ årskrt Destinatin+ (fr m ). Upphört SAS Destinatin, Upphört Lkaler Alla lkaler eller statiner beskrivs i elementet <Lcatin> ch identifieras med sitt landsnummer ch sitt lkalnummer, till exempel: 8

9 Petra Användarhandbk <LcatinPrducerCde> <LcatinId> <LcatinShrtName> 74 1 Stckhlm C Limmared Osl S 86 1 Frederikshavn Följande landsnummer förekmmer till exempel i SJs trafik: <LcatinPrducerCde> Land 74 Sverige 76 Nrge 80 Tyskland 86 Danmark Kmfrt, prisnivå, prisgrupp ch faretype Det finns många begrepp sm beskriver vilken typ av biljett sm finns i beställningen. I säljdialgen används nrmalt begreppet prisgrupp sm en sammanfattande beskrivning av biljettens innehåll ch regelverk. Internt i PETRA används prisnivå vid prissättning av färdkmpnenter ch kmfrt vid platsreservatin. Term XML-element Databasklumn Beskrivning Exempel Varunummer <ServiceId> VRANR Varunumret identifierar unikt den tjänst sm sålts. Vissa tjänster kan bestå av lika kmpnenter ch därför går det inte alltid att dra slutsatser m exakt vad sm sålts enbart med hjälp av varunumret. Varunamn <ServiceName> VRANMN Varunamnet beskriver i klartext vilken tjänst sm sålts. Kmfrt <BkingClass> KMFT Beskriver kmfrten i frdnet, dvs bredd ch benutrymme för stlen samt vissa andra kmfrtegenskaper sm kan finnas i lika frdn. Prisnivå PRSNV Beskriver prisets nivå ch är det grundläggande begreppet för prissättning. Prisgrupp DEFGRP Beskriver mycket krtfattat biljettens egenskaper ch vilka prdukter (tågtyper) sm kan ingå i biljetten. Prisgruppen kpplar ihp prisnivå ch kmfrt KL FK (1 klass), AK (2 klass) AM (1 klass Plus), AL (1 klass), F1 (Just nu 1 kl), NO (Nrmal), 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) 9

10 Petra Användarhandbk Term XML-element Databasklumn Beskrivning Exempel Varunamnförkrtning <FareType> VRANMNFKN Fare type används i Linkns eknmimeddelande (EM) ch i Amadeus SIR-meddelande. Elementet används endast i eknmimeddelanden samt i vissa rapprter i PETRA Eknmi. I PETRA Sälj används det inte. 1 KL PLUS, 1 KL, 2 KL, JUST NU, SM Redigeringsinfrmatin (vid beställningskedja) För identifiering av händelser i beställningskedjr sm kan kräva/önska specialhantering har två flaggr införts. Elementet PaymentSequenceNumber (tidigare = EditPaymentEvent) identifierar att meddelandet ifråga är del av en debitering av delbetald beställning (en redigeringsbetalning), där ett flertal lika typer av infrmatinsmeddelanden skickas. Den visar kedjelöpnumret för den versin av beställningskedjan sm betalades i samband med utskicket av infrmatinsmeddelandet. Genm att läsa SalesOrderId ch PaymentSequenceNumber kan mttagare länka ihp alla de meddelanden sm skickats vid en redigeringshändelse. Elementet <EditedOrder> visar att beställningen, avsett vilken versin av beställningskedjan det specifika infrmatinsmeddelandet skickas för, ingår i just en beställningskedja en redigerad beställning. När så är fallet skall betalnings- ch krediteringsinfrmatin läsas från <PaymentSummaries> för summerad infrmatin ch <PaymentDetails> för detaljerad infrmatin för mer infrmatin. Betalnings- ch krediteringsinfrmatin från <PaymentInf> får då INTE användas då det inte visar den fullständiga bilden Redigeringsåtgärd Elementet <EditActin> beskriver redigeringshändelser på specifika kmpnenter i samband med en redigeringsbetalning. Elementet har följande värden: <EditActin> A CF CT D Betydelse tillägg av kmpnent byte från (vid byte av kmpnentvariant eller platsdetaljer) byte till (vid byte av kmpnentvariant eller platsdetaljer) brttag av kmpnent Belpp att faktura vid redigering (resekntföretag med nettfaktura) Denna del av instruktin är tänkt att användas av resekntföretagen ch liknade, sm vill faktura kunden en nettfaktura, dvs vid tillägg av mattillval faktureras endast tillvalet ch visas i fakturan. Instruktinen i kapitlet gäller även för mbkning i beställningskedja samt tillägg av nya rader inm samma beställningskedja. 10

11 Petra Användarhandbk SM debitering Villkr: EditedOrder i kmbinatin med att det inte finns någn EditActinCde på någn av radens ServiceOptin eller PlacementDescriptin, ch PaymentCde = RE => alla de rader sm uppfyller vanstående villkr ska faktureras. Detta är när helt ny rad lagts till. Villkr: EditedOrder i kmbinatin med att det finns nterad kd för EditActinCde på ServiceOptin eller PlacementDescriptin, ch PaymentCde = RE=> Fakturera detta nya tillägg. Om EditedOrder är satt, så kan det inte kmma med några helt förändrade rader i SM. Meddelandet i sig tillåter att några rader är helt nya medan andra rader är befintliga men där några kmpnenter lagts till. SM kreditering Villkr: EditedOrder i kmbinatin med att det finns nterad editactincde på ServiceOptin eller PlacementDescriptin => kreditera detta tidigare tillägg (ch detta kan gälla för flera tillägg inm samma rad). Villkr: EditedOrder i kmbinatin med att det inte finns någn editactincde på ServiceOptin eller PlacementDescriptin, OCH CreditReasn INTE är BY (dvs ingen mbkning gjrts) => ingenting på denna rad skall krediteras Villkr: EditedOrder i kmbinatin med att det inte finns någn editactincde på ServiceOptin eller PlacementDescriptin OCH CreditReasn är BY (dvs det har gjrts en mbkning) => hela denna rad skall krediteras Om det är en kreditering sm inte görs i samband med en redigering, så ska ingen flagga EditedOrder finnas. => Detta är när hel rad krediteras, även m den tidigare redigerats. I detta fall kan det m redigeringar gjrts tidigare finnas flera lika betalningsmedel med på raderna (t.ex. ett mattillval betalt med vanligt kntkrt), men infrmatin finns m de tillval sm har annan kd är RE. Matchning av betaltransaktin till Betalsystem Om det vid en redigering både tas brt ch läggs till kmpnenter, så skapas: ett debet-sm ett kredit-sm En debet trans till Betalsystem en kredit trans till Betalsystem. 11

12 Petra Användarhandbk Om det vid en redigering bara läggs till kmpnenter, så skapas: ett debet-sm ett kredit-sm, en debet trans till Betalsystem. Om det vid en redigering bara tas brt kmpnenter, så skapas ett debet-sm ett kredit-sm en kredit trans till Betalsystem. SM för debiteringar sm inte har PaymentCde (betalkd) = RE ignreras, enligt lösningsbeskrivningen. Vid en mbkning (även kallat byte) skapas: ett debet-sm ett kredit-sm En debet trans till Betalsystem en kredit trans till Betalsystem. Detta avsett m mbkningen skedd sm en redigering (samma SalesOrderId ch EditedOrder satt) eller inte (dvs nytt SalesOrderId). Detta är för att Ombkningar för betalningsmedel Reseknt alltid hanteras sm Bruttkntkrtstransaktiner, dvs alltid både en debet ch en kredit. 5.3 Plaintexter Plaintexter kan fås på svenska (default), engelska eller i undantagsfall inga plaintexter. Detta knfigureras av Linkn. 12

13 Petra Användarhandbk 6 Versiner 6.1 Giltiga versiner Följande giltiga versiner finns för Infrmatinsmeddelanden: Versin Första giltighetsdatum Sista Huvudsaklig förändring giltighetsdatum SM rder-sales-message SM rder-sales-message SM rder-sales-message nytt element paymentsequencenumber ersätter editpaymentevent SM rder-sales-message Nytt element: SalesUnitClusterTerminal SM rder-sales-message Ändring schema för PaymentSummay till unbunded. Versin Första giltighetsdatum Sista Huvudsaklig förändring giltighetsdatum TM rder-travel-message TM rder-travel-message TM rder-travel-message nytt element; delaycmpensatincde ch paymentsequencenumber Versin Första giltighetsdatum Sista Huvudsaklig förändring giltighetsdatum LM rder-lyalty-message LM rder-lyalty-message LM rder-lyalty-message nytt element; delaycmpensatincde LM rder-lyalty-message Ändring schema för PaymentSummary till unbunded. Versin Första giltighetsdatum Sista Huvudsaklig förändring giltighetsdatum DM edh-distributin-message DM edh-distributin-message anpassning till cmmntypes. Versin Första giltighetsdatum Sista Huvudsaklig förändring giltighetsdatum UM rder-unbked-message 13

14 Petra Användarhandbk För varje meddelande typ kan det finnas flera giltiga versiner samtidigt. Det innebär att mttagare av meddelanden enklare kan planera uppgradering till senare versiner. Nrmalt erbjuder Linkn två parallella versiner. Den föregående versinen fasas nrmalt ut vid nästa större förändring av PETRA eller vid nästa årsrelease, vilket nrmalt innebär att den föregående versinen är tillgänglig ca 6-9 månader efter att en ny versin har prduktinssatts. 14

15 Petra Användarhandbk 7 Referenser I handbk: Petra2 Ecnmy Message Implementatin Guide - Ecnmy Message Infrastructure finns ytterligare infrmatin m hur en applikatin kan knfigureras för att ta emt eknmimeddelanden. Via följande länk hittar du scheman för respektive meddelandetyp: under rubrik InfrmatinMessage. 15