Ordre
Denne tjenesten registrerer en ordre i systemet. En ordre kan bestå av 1 til mange ordrelinjer. Ordre som leveres til systemet kan være forhåndsbetalt med kredittkort (hvis gyldig avtale eksisterer), skal faktureres av Mediaconnect eller være forhåndsbetalt på andre måter.
Webservice URI: /client/{clientId}/order
HTTP-metode: POST
(eksempel: /client/1/order)
Eksempel på minimums-ordre (produkt angitt ved produktkode):
<?xml version="1.0" encoding="UTF-8"?>
<orders>
<order externalOrderId="minimal_order_01">
<externalCustomer>
<externalCustomerId>123456789</externalCustomerId>
<externalCustomerIdType>spid</externalCustomerIdType>
</externalCustomer>
<orderTime>2010-01-07T10:12:54</orderTime>
<marketingCouponcode>MARKED1</marketingCouponcode>
<marketingCouponno>50001</marketingCouponno>
<paymentMethod>invoice</paymentMethod>
<totalInclVat>125.00</totalInclVat>
<payer>
<firstName>Mikke</firstName>
<lastName>Mus</lastName>
<street>Solvang</street>
<postalCode>2843</postalCode>
<postalPlace>Eina</postalPlace>
<countryCode>NO</countryCode>
</payer>
<lines>
<line>
<productSpecType>product</productSpecType>
<orderProduct>SAKS</orderProduct>
<quantity>1</quantity>
<unitPrice>125.00</unitPrice>
</line>
</lines>
</order>
</orders>Eksempel på minimums-ordre (produkt angitt ved kupongkode og kupongnummer):
<?xml version="1.0" encoding="UTF-8"?>
<orders>
<order externalOrderId="minimal_order_02">
<externalCustomer>
<externalCustomerId>123456789</externalCustomerId>
<externalCustomerIdType>spid</externalCustomerIdType>
</externalCustomer>
<orderTime>2010-01-07T10:12:55</orderTime>
<paymentMethod>invoice</paymentMethod>
<totalInclVat>125.00</totalInclVat>
<payer>
<firstName>Mikke</firstName>
<lastName>Mus</lastName>
<street>Solvang</street>
<postalCode>2843</postalCode>
<postalPlace>Eina</postalPlace>
<countryCode>NO</countryCode>
</payer>
<lines>
<line>
<productSpecType>coupon</productSpecType>
<productSpecCode>ORD</productSpecCode>
<productSpecNo>303</productSpecNo>
<quantity>1</quantity>
<unitPrice>125.00</unitPrice>
</line>
</lines>
</order>
</orders>Eksempel på minumums-ordre betalt med kredittkort:
<?xml version="1.0" encoding="UTF-8"?>
<orders>
<order externalOrderId="minimal_order_02">
<externalCustomer>
<externalCustomerId>123456789</externalCustomerId>
<externalCustomerIdType>spid</externalCustomerIdType>
</externalCustomer>
<orderTime>2009-12-31T07:50:00</orderTime>
<marketingCouponcode>WEBANNONSE</marketingCouponcode>
<marketingCouponno>50001</marketingCouponno>
<paymentMethod>creditcard</paymentMethod>
<mspContractId>0010A</mspContractId>
<mspOrderReference>prefix-123</mspOrderReference>
<mspTransactionId>123456789</mspTransactionId>
<totalInclVat>625.00</totalInclVat>
<payer>
<firstName>Mikke</firstName>
<lastName>Mus</lastName>
<street>Andeveien</street>
<postalCode>0975</postalCode>
<postalPlace>Oslo</postalPlace>
<countryCode>NO</countryCode>
</payer>
<lines>
<line>
<productSpecType>product</productSpecType>
<orderProduct>BOK</orderProduct>
<quantity>1</quantity>
<unitPrice>625.00</unitPrice>
</line>
</lines>
</order>
</orders>Beskrivelse av de forskjellige XML-elementene når du skal registrere en ordre:
| Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
|---|---|---|---|
| <orders> | - | Rot-element - Dette er rot-elementet som inneholder alle order elementene | - |
| <order> | <orders> | Hoved-element - Dette angir en ordre, du kan ha n antall <order> elementer som barn av <orders> elementet i et XML dokument. <order> elementer KAN ha EN, og kun EN attributt; externalOrderId. Dette attributtet kan settes av klienten og vil i så fall være tilstede i responsen slik at klienten kan skille mellom de forskjellige <order> elementene ved tolkning av responsen for å finne status på hver ordre. | externalOrderId - tekst |
| <externalCustomer> | <order> | Ekstern kunde Angir kunden på en unik måte i det eksterne systemet som kaller opp denne tjenesten. Mediaconnect bestemmer om dette feltet er nødvendig. | - |
| <externalCustomerId> | <externalCustomer> | Ekstern ID for kunde Unik ID for en kunde i eksternt system. | Tekst - maks 64 tegn |
| <externalCustomerIdType> | <externalCustomer> | Type av ekstern ID for kunde Kode som angir type av ekstern id. Lovlige verdier: facebook Facebook google+ Google+ spid SPiD | Tekst - maks 12 tegn |
| <orderCreatorProfile> | <order> | Ordre-registrator profil Kode som angir hvem som registrerer ordren. Dette elementet er interessant hvis samme ordre- registrator leverer ordre som skal behandles på forskjellige måter. Elementet brukes da for å bestemme hvilken profil som skal brukes. Mediaconnect bestemmer om dette feltet er nødvendig, og tildeler kode(r) som skal brukes. | Tekst - maks 12 tegn |
| <orderTime> | <order> | Dato/klokkeslett ordren ble registrert Tidsstempel på når ordren ble registrert (ordretidspunkt i det eksterne ordresystemet/ webshop/etc). | Dato/klokkeslett - yyyy-MM-ddThh:mm:ss (standardverdi = dato og klokkeslett når ordren registreres av Mediaconnect |
| <marketingCouponcode> | <order> | Markedsdata - kupongkode Markedsdata-kupongkode. Denne koden (sammen med <marketingCouponno>) kan brukes for å angi markedsdata ved bestilling. Markedsdata kan være for å angi kanal, kampanje, annonse osv. Et typisk eksempel på bruk av dette er hvis banner-annonser på forskjellige steder peker inn til samme webshop. Ved å benytte forskjellige markedsdata-koder for de forskjellige annonsene er det enkelt å ha oversikt over hvilken kanal/annonse en bestilling kom inn fra. Kodene som skal brukes <marketingCouponcode> og <marketingCouponno> tildeles av Mediaconnect. | Tekst - maks 12 tegn |
| <marketingCouponno> | <order> | Markedsdata - kupongnummer Markedsdata-kupongnummer. Brukes sammen med <marketingCouponcode> for å angi markedsdata. | Heltall |
| <paymentMethod> | <order> | Betalingsmetode Angir hvordan ordren skal betalingshåndteres. invoice - Mediaconnect skal generere faktura for ordren. creditcard - ordrebeløp er reservert av klienten og skal trekkes av Mediaconnect når ordren effektueres. Elementene <mspContractId> og <mspTransactionId> skal være utfylt. prepaid - ordre er forhåndsbetalt hos klienten. prepaidCreditcard - ordrebeløp er både reservert og trukket av klienten. Elementene <mspContractId> og <mspTransactionId> skal være utfylt. prepaidSms - ordrebeløp er trukket av klienten. sms - ordrebeløp skal trekkes av Mediaconnect når ordren effektueres. | Tekst - invoice, creditcard, prepaid, prepaidCreditcard, prepaidSms eller sms (standardverdi=invoice) |
| <mspContractId> | <order> | Merchant service provider contract id (betalingsformidler kontrakt id). Benyttes ved kredittkortsbetalt ordre (paymentMethod = creditcard). Identifikasjon/avtalenummer til avtale med betalingsformidler. Benyttes for avstemming av kredittkortsbetalte ordre. | Tekst - maks. 40 tegn |
| <mspOrderReference> | <order> | Merchant serviceprovider order reference (betalingsformidler ordrereferanse). Benyttes dersom betalingen blir reservert men ikke trukket. Trekket vil da bli gjort i Connect. Ordrereferansen som ble brukt ved reservasjonen vil bli brukt ved trekket. NB! Nummerserier må avklares med Mediaconnect. | Tekst - maks. 40 tegn |
| <mspTransactionId> | <order> | Merchant service provider transaction id (betalingsformidler transaksjonsid). Benyttes ved kredittkortsbetalt ordre (paymentMethod = creditcard). Transaksjonsid ved forhåndsbetalt ordre. Typisk transaksjonsid mottatt fra betalingsformidler. Benyttes for avstemming av kredittkortsbetalt ordre. | Tekst - maks. 40 tegn |
| <mspTicket> | <order> | Merchant service provider ticket id Betalingsformidlers referanse til lagret kortinfo. Ved SMS-betaling er dette telefon-nummeret som blir brukt til å betale med. | Tekst - maks 128 tegn |
| <mspCardNumberMasked> | <order> | Maskert kortnummer til bruk ved visning av lagret betalingsreferanse. | Tekst - maks 64 tegn |
| <mspExpMonth> | <order> | Utløpsmåned for lagret betalingsreferanse. | Tekst - maks 2 tegn |
| <mspExpYear> | <order> | Utløpsår for lagret betalingsreferanse. | Tekst - maks 2 tegn |
| <mspCardTypeName> | <order> | Korttype for lagret betalingsreferanse. | Tekst - maks 32 tegn |
| <msp3DSecure> | <order> | 3D Secure status. | Tekst - maks 1 tegn |
| <mspEnrolled> | <order> | - | Tekst - maks 1 tegn |
| <mspVerificationIdPresent> | <order> | - | Tekst - maks 1 tegn |
| <totalInclVat> | <order> | Total ordresum inkl. MVA Ordresum angis alltid inklusiv eventuell MVA; det er ikke eget felt for MVA. Grunnen til dette er at i henhold til regnskapsloven er det forlagets ansvar å beregne riktig MVA selv om den som registrerer ordren har fortalt kunden noe feil. | Desimal - maks. 13 tegn |
| <currency> | <order> | Valuta | Tekst - maks 3 tegn (standardverdi = NOK) |
| <payer> | <order> | Regningsmottakers navn og adresse-element | - |
| <payer> | NB! Se under for liste over felles felter for navn og adresse. | ||
| <lines> | <order> | Inneholder alle <line> elementene for gjeldende <order> element | - |
| <line> | <lines> | Inneholder alle linjeelementene en ordre består av. Det er ingen (praktisk) øvre grense for antall linjer i en ordre | - |
| <productSpecType> | <line> | Produkt spesifikasjonstype Angir hvordan produktet på gjeldende linje er spesifisert. coupon - Produktet er definert som en kupong angitt vha. kupongkode og kupongnummer. productSpecCode inneholder kupongkode, productSpecNo inneholder kupongnummer og orderProduct kan innehold en produktkode, men er vanligvis blank. product - Produktet er definert som et produkt vha. en produktkode productSpecCode skal være blank, productSpecNo skal være blank og orderProduct inneholder produktkoden. issue - Produktet er angitt både som en kupong angitt vha. kupongkode og kupongnummer, samt som et produkt vha. en utgavekode productSpecCode inneholder kupongkode, productSpecNo inneholder kupongnummer og orderProduct inneholder utgavekoden. | Tekst - coupon, product eller issue |
| <productSpecCode> | <line> | Produkt spesifikasjons kode Se productSpecType for spesifikasjon av dette elementet. | Tekst - maks 12 tegn |
| <productSpecNo> | <line> | Produkt spesifikasjons nummer Se productSpecType for spesifikasjon av dette elementet. | Heltall |
| <orderProduct> | <line> | Product Se productSpecType for spesifikasjon av dette elementet. | Tekst - maks 12 tegn |
| <quantity> | <line> | Antall | Desimaltegn - maks 13 tegn inklusive skilletegn |
| <unitPrice> | <line> | Enhetspris inkl. MVA | Desimaltegn - maks 13 tegn inklusive skilletegn |
| <voucherCode> | <line> | Voucher-kode | Tekst - maks 12 tegn |
| <receiver> | <line> | Mottakers navn og adresse-element Brukes kun hvis mottakers navn og adresse er forskjellig fra regningsmottaker | - |
| <payerType> | <receiver> | Regningsmottaker-type regularPayer - vanlig regningsbetalerordre hvor faktura sendes til regningsmottaker og produktene sendes til mottaker. giftShipToReceiver - gaveordre hvor faktura sendes til giver (regningsmottaker) og produktene sendes til mottaker. giftShipToPayer - gaveordre hvor faktura sendes til giver (regningsmottaker) og produktene også sendes til giver (regningsmottaker). Hvis ordren er en abonnementsordre vil første utgave av produktet sendes til giver og påfølgende utgaver sendes til mottaker. | Tekst - regularPayer, giftShipToReceiver giftShipToPayer |
| <receiver> | NB! Se under for liste over felles felter for navn og adresse. | ||
| <recruiter> | <line> | Ververs navn og adresse-element Brukes kun hvis ordren har en verver som skal registreres. | - |
| <recruiter> | NB! Se under for liste over felles felter for navn og adresse. | ||
| <guardian> | <line> | Foresattes navn og adresse-element Brukes kun hvis ordren har en foresatt som skal registreres. | - |
| <guardian> | NB! Se under for liste over felles felter for navn og adresse. |
Felles felter for navn og adresse i følgende elementer: <payer>, <receiver>, <recruiter> og <guardian>. Felter som ikke er felles er dokumentert ovenfor. (Kolonnen 'Elementets forelder (parent)' referer til en av de nevte elementene dersom ikke annet er angitt.):
| Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
|---|---|---|---|
| <customerNumber> | se kommentar over | Kundenr Kundenummer til betaler, mottaker eller verver (hvis kjent). Kan benyttes for å koble mottaker til en allerede eksisterende kunde. | Heltall |
| <companyName> | Firmanavn | Tekst - maks 40 tegn | |
| <department> | Avdelingsnavn | Tekst - maks 40 tegn | |
| <firstName> | Fornavn | Tekst - maks 30 tegn | |
| <middleName> | Mellomnavn | Tekst - maks 30 tegn | |
| <lastName> | Etternavn | Tekst - maks 30 tegn | |
| <coName> | Co navn | Tekst - maks 40 tegn | |
| <street> | Gatenavn | Tekst - maks 40 tegn | |
| <streetNumber> | Gatenummer | Heltall | |
| <entrance> | Oppgang | Tekst - maks 12 tegn | |
| <floor> | Etasje | Heltall | |
| <suite> | Leilighetsnummer | Tekst - maks 10 tegn | |
| <postalCode> | Postnummer | Tekst - maks 10 tegn | |
| <postalPlace> | Poststed | Tekst - maks 30 tegn | |
| <postalAddress> | Postboks adresse | Tekst - maks 40 tegn | |
| <postalAddressPostalCode> | Postboks adresse postnr | Tekst - maks 10 tegn | |
| <postalAddressPostalPlace> | Postboks adresse postnr | Tekst - maks 30 tegn | |
| <countryCode> | Landkode ISO 3166 - alpha-2 | Tekst - maks 3 tegn | |
| <phoneNumbers> | Telefonnummer Inneholder en liste med 0, 1 eller mange <phoneNumber> elementer | - | |
| <phoneNumber> | <phoneNumbers> | Telefonnummer Inneholder ett attributt: type som angir hvilken type telefonnummer det er. Gyldige verdier for attributtet: work, private, fax eller mobile | Tekst - maks 20 tegn |
| <emails> | Epost Inneholder en liste med 0, 1 eller mange <email> elementer | - | |
| <email> | <emails> | Epost Inneholder en epost adresse | Tekst - maks 60 tegn |
| <birthDate> | Fødselsdato | Dato - yyyy-MM-dd | |
| <sex> | Kjønn | Tekst - male, female, unknown, n/a (standardverdi = unknown) | |
| <altAddressFreetext> | Fritekst adresse Felt som kan brukes til å holde en fullstendig adresse. Brukes typisk når kunde selv har fyllt inn sin adresse i ett enkelt tekstfelt, via mobil eller lignende. Dersom dette feltet har en verdi vil ordredata alltid sjekkes før overføring til klientens database, og kan da brukes som et alternativ til ovenstående felter. | Tekst - opptil 255 tegn |
Svar:
<?xml version="1.0" encoding="UTF-8"?>
<orderStatus>
<order orderId=1234>
<externalOrderId>TST01</orderId>
<status>ok</status>
<message>order registered</message>
</order>
<order orderId=1235>
<status>ok</status>
<message>order registered</message>
</order>
</orderStatus>Beskrivelse av de forskjellige XML-elementene i et svar fra CWS når du har registrert en ordre:
| Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
|---|---|---|---|
| <orderStatus> | - | Rot-element - Dette er rot-elementet som inneholder alle <order> elementene | - |
| <order> | <orderStatus> | Hoved-element Inneholder elementer som viser status på en ordre. Inneholder ett attributt: orderId (heltall) som er den unike ordre id'en på ordren (denne genereres av Mediaconnect), se externalOrderId for den evt. eksterne ordre id'en | - |
| <externalOrderId> | <order> | Ekstern ordre id Inneholder det samme som kom i attributtet externalOrderId på order elementet når ordren ble registrert. | Tekst |
| <status> | <order> | Ordrestatus Status på ordren preliminary - foreløpig ordre som ikke er bekreftet ok - ordre registrert ok error - feil ved registrering av ordre, se message elementet for detaljert feilmelding | Tekst - preliminary, ok, error |
| <message> | <order> | Statusmelding Klartekst som beskriver statusen | Tekst |
| <customerNumber> | <order> | Kundenummer Kundenummer dersom det er funnet/generert | Heltall |
| <completed> | <order> | Behandlingsstatus Angir om ordren er ferdigbehandlet eller er til videre behandling f.eks. ved feil data i ordren. | Boolsk verdi (true/false) |
Samtykke
Det er mulig å registrere samtykke samtidig med registrering av ordre. Det er mulig å registrere samtykke på både betaler og mottaker.
Følgende (eksempel) XML-fragment kan plasseres i et <payer> eller <receiver> element.
...
<permissions>
<enterprise enterprise="ENTERPRISE_CODE">
<channel type="PERMISSION">DM</channel>
</enterprise>
<orderType enterprise="ENTERPRISE_CODE" orderType="ORDER_TYPE">
<channel type="PERMISSION">EM</channel>
<channel type="SHIELD">SM</channel>
</orderType>
</permissions>
...Ovenfor vil man registrere et samtykke på konsern-nivå for kanalen DM. Det vil også bli registrert et samtykke på ordretype-nivå for kanalen EM, samt et vern for kanalen SM.
Verdiene i attributtene ENTERPRISE_CODE og ORDER_TYPE, samt tekst-verdien i <channel> elementet må finnes i systemet før samtykke (eller evenetuelle vern) registreres. Det vil ikke bli kastet et unntak for verdier som ikke finnes i systemet, så lenge XML-strukturen er i orden. Selve bestillingen vil bli prioritert.
Nye nivå kan bli implementert senere. Merk at det ikke nødvendigvis er mulig å registrere samtykke på enkelte nivå, eller vern på andre.
Beskrivelse av de forskjellige XML-elementene for samtykke:
| Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
|---|---|---|---|
| <permissions> | <payer> eller <receiver> | Samtykker - Inneholder en eller flere samtykke-registreringer av ulike typer. | - |
| <enterprise> | <permissions> | * Attributt: enterprise (Tekst - maks 12 tegn) | |
| <orderType> | <permissions> | * Attributt: enterprise (Tekst - maks 12 tegn) * Attributt: orderType (Tekst - maks 12 tegn) | |
| <channel> | <enterprise> eller <orderType> | * Attributt: type * Verdi: PERMISSION eller SHIELD | Tekst - maks 2 tegn |
AvtaleGiro
Det er mulig å angi at kunden har til hensikt å tegne AvtaleGiro for et produkt
Følgende XML-fragment kan plasseres i et <order> element.
... <autogiro>yes</autogiro> ...
Andre måter å fremstille dette fragmentet på vil ikke gi riktig resultat.
Når dette parameteret blir gitt sammen med ordren, og ordren blir fullstendig registrert i klientens database vil <ordre> elementet i retur-data få påført de ekstra data som behøves for å kunne sende kunden videre til BBS for tegning av AvtaleGiro på det bestilte produktet. Det vil bli som i følgende (eksempel) XML-fragment. Tjenesten returnerer kun data dersom databasen er satt opp til å håndtere AvtaleGiro.
<order orderId=1234> ... <customerNumber>12345678</customerNumber> <orderType>CONNECT</orderType> <companyName>Magazines%20AS</companyName> <accountNumber>12345678910</accountNumber> <cid>987651234567800003</cid> <orderLimit>5000</orderLimit> </order>
Beskrivelse av de forskjellige XML-elementene i et svar fra CWS når systemet kan motta AvtaleGiro på ordren:
| Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
|---|---|---|---|
| <customerNumber> | <order> | Kundenr som brukes til å knytte data til eksisterende kunde etter registrering. Dette feltet skal ikke sendes til BBS. | Heltall |
| <orderType> | <order> | Produkt som brukes til å knytte data til tidligere bestilling etter registrering. Dette feltet skal ikke sendes til BBS. | Tekst - maks 12 tegn |
| <companyName> | <order> | Firmanavn som hører sammen med kontonr i feltet nedenfor. URL enkodet. | Tekst - maks 12 tegn |
| <accountNumber> | <order> | Kontonr som avtalen skal registreres på. Hører til produktet som bestillingen er gjort på. | Tekst - 11 tegn |
| <cid> | <order> | KID som brukes for å koordinere betalinger mellom BBS og betalingsmottaker. | Tekst - 18 tegn |
| <orderLimit> | <order> | Beløpsgrense for avtalen. Dette feltet trenger ikke sendes til BBS uten endringer, men er kun en kvalifisert gjetning på et passende tall. Kunden kan selv endre denne under opprettingen av avtalen på BBS sine nettsider. | Heltall |
Adresse-kategorier
Det er mulig å registrere ekstra adresse-data samtidig med registrering av ordre. Det er mulig å registrere data på alle adresser i en ordre. Noen spesielle kategorier støtter frie verdier, angitt med feltet freeValue.
Følgende (eksempel) XML-fragment kan plasseres i et <payer>, <receiver>, <recruiter> eller <rguardian> element.
...
<categories>
<category>
<addressCategory>KATEGORI</addressCategory>
</category>
...
<category>
<addressCategory>KATEGORI2</addressCategory>
<freeValue>verdi</freeValue>
</category>
</categories>
...Ovenfor vil man registrere at kategori-koden KATEGORI skal registreres på kunden. Oppsettet av kategori-kodene bestemmer hvordan dette blir håndtert i Connect.