Ingen treff

E-shop API – oversikt

E-shop API kobler hvilken som helst nettbutikk til BulkGate. Nettbutikken din bruker det til å varsle BulkGate om hendelser i butikken: ny bestilling, statusendring, betaling, ny kunde og mer. Portalen finner varselet som er satt opp for hendelsen i den aktuelle applikasjonen, setter inn variablene fra forespørselen i malen og sender meldingen til kunden, til butikkens administratorer eller til begge.

API-et bestemmer ikke selv meldingsteksten. Hvis det ikke er satt opp noe varsel for hendelsen, går forespørselen gjennom, men ingenting sendes.

Endepunkter

Alle endepunkter tar imot POST på adressen https://portal.bulkgate.com/api/1.0/eshop/<område>/<handling>.

ENDEPUNKT HENDELSE SIDE
eshop/order/new Ny bestilling Bestillinger
eshop/order/change-status Endret bestillingsstatus Bestillinger
eshop/order/payment Bestillingen er betalt Bestillinger
eshop/order/tracking-number Sporingsnummer er tildelt Bestillinger
eshop/order/product-cancel Produkt kansellert i bestillingen Bestillinger
eshop/order/slip-add Kreditnota lagt til bestillingen Bestillinger
eshop/customer/new Ny kunde Kunder
eshop/product/out-of-stock Produktet er utsolgt Produkter
eshop/product/on-back-order Produktet er i restordre Produkter
eshop/product/update-quantity Endret lagerbeholdning Produkter
eshop/product/delete Produktet er slettet Produkter
eshop/return/new Ny retur Returer
eshop/return/change-status Endret returstatus Returer
eshop/contact/form Innsendt kontaktskjema Kontaktskjema
eshop/setup Oppsett av språk, butikker og statuser Oppsett
Merk

Hvis forespørselen ikke når frem, gjentar du den på reserveserveren backup1.bulkgate.com.

Forespørselsparametere

Hendelsesendepunktene (alle unntatt eshop/setup) tar imot de samme parameterne. En ukjent parameter på øverste nivå avviser forespørselen med feilen invalid_input_parameters, så hendelsesdataene hører hjemme i objektet variables.

PARAMETERNAVN VERDI OBLIGATORISK STANDARDVERDI
application_id Applikasjons-ID Ja -
application_token Applikasjonstoken Ja -
language Språket i kundevarselet, f.eks. no Nei default
shop_id Butikkens ID hvis du har flere butikker Nei 0
variables Hendelsesdata – objekt navn: verdi, verdiene er skalarer Nei {}

Send forespørselen som application/json.

Slik velger portalen varsel

Varsler settes opp i portalen for hver applikasjon for seg, i seksjonene Kundes SMS og Admin SMS. Hvert varsel er knyttet til en hendelse, en butikk (shop_id) og, for kundevarsler, også til et språk. Listen over språk, butikker og bestillings- og returstatuser som portalen tilbyr varsler for, laster nettbutikken din opp via oppsettet.

  • Kundevarselet søkes opp for språket i parameteren language. Hvis applikasjonen ikke har slått på språkversjoner, ignorerer portalen språket og bruker default.
  • Administratorvarselet søkes alltid opp for språket default og sendes til numrene til administratorene som er satt opp for det.
  • Kunde- og administratorvarselet vurderes uavhengig av hverandre – en hendelse kan sende ett av dem, begge eller ingen.
Viktig

Portalen sender ikke samme tekst til samme nummer to ganger innen 24 timer. Gjentatte kall for samme hendelse sender dermed ikke kunden en duplikatmelding.

Kundens telefonnummer

Portalen leter etter kundens nummer i variables. Rekkefølgen bestemmes av variabelen contact_address_preference:

contact_address_preference REKKEFØLGE FOR VARIABLER MED NUMMER REKKEFØLGE FOR VARIABLER MED LAND
delivery (standard) customer_mobile, customer_phone, customer_invoice_mobile, customer_invoice_phone, phone_mobile, phone, phone_number customer_country_id, customer_invoice_country_id, customer_country, customer_invoice_country, iso, country_iso
invoice customer_invoice_mobile, customer_invoice_phone, customer_mobile, customer_phone, phone_mobile, phone, phone_number customer_invoice_country_id, customer_country_id, customer_invoice_country, customer_country, iso, country_iso

Den første variabelen som det kan lages et gyldig nummer av, blir brukt. Portalen leser landet som en tobokstavs ISO-kode (cz, sk, …) og bruker den til å legge til landsprefiks på numre som er oppgitt uten. Hvis portalen ikke finner et gyldig nummer, sendes ikke kundevarselet.

Variabler i maler

Varselmalen bruker variablene fra variables med skrivemåten <navn>, f.eks. <order_id>. En standardverdi skriver du direkte i malen som <navn:verdi>. I tillegg fyller portalen inn:

  • shop_name – butikkens navn etter shop_id fra listen over butikker, hvis du ikke sender det selv,
  • language_iso – verdien av parameteren language.

Variabler du ikke sender, erstattes i teksten med standardverdien – for de fleste en tom streng, for order_id, long_order_id og order_ref en bindestrek. Disse variablene har en standardverdi:

GRUPPE VARIABLER
Butikk shop_id, shop_email, shop_name, shop_domain, shop_currency, shop_phone, store_id, lang_id, language_iso
Kunde customer_id, customer_company, customer_firstname, customer_lastname, customer_name, customer_address, customer_postcode, customer_city, customer_state, customer_country, customer_country_id, customer_phone, customer_mobile, customer_email, customer_vat_number, customer_fax, customer_message, customer_firstname_vokativ, customer_lastname_vokativ
Fakturering customer_invoice_company, customer_invoice_firstname, customer_invoice_lastname, customer_invoice_address, customer_invoice_postcode, customer_invoice_city, customer_invoice_state, customer_invoice_country, customer_invoice_country_id, customer_invoice_phone, customer_invoice_mobile, customer_invoice_vat_number, customer_invoice_firstname_vokativ, customer_invoice_lastname_vokativ
Bestilling order_id, long_order_id, order_ref, order_reference, order_status, order_status_id, order_status_message, order_message, order_currency, order_payment, order_total_paid, order_total_locale, order_date, order_datetime, order_time, order_date1–order_date7, order_time1, order_products1–order_products8, order_smsprinter1–order_smsprinter4, cart_id, id_address_delivery, id_address_invoice
Frakt carrier_id, order_carrier_name, order_carrier_code, order_carrier_url, order_carrier_delay, order_carrier_tracking_number, order_carrier_tracking_date, order_carrier_price, order_carrier_price_locale, order_carrier_weight, order_tracking
Produkt product_id, product_name, product_quantity, product_minimal_quantity, product_model, product_ref, product_description, product_manufacturer, product_supplier, product_supplier_id, product_supplier_ref, product_price, product_price_locale, product_ean, product_ean13, product_upc, product_isbn, product_jan, product_mpn, product_sku
Retur return_id, return_status, return_status_id, return_action, return_action_id, return_reason, return_reason_id, return_date, return_customer_message, return_question, return_products1–return_products8
Ansatt employee_id, employee_email, employee_firstname, employee_lastname

Du kan også sende egne variabler – malen bruker dem på samme måte.

Svar

Ved suksess returneres objektet data med resultatet for hver sendte melding, separat for kunden (customer) og for administratorene (admin). Nøkkelen mangler når det aktuelle varselet ikke er satt opp for hendelsen. Et kundevarsel som er satt opp, men slått av, returnerer en tom matrise.

{ "data": { "customer": [ { "status": "accepted", "message_id": "tmpde1bcd4b1d1", "part_id": ["tmpde1bcd4b1d1"], "number": "420777777777", "channel": "sms" } ] } }

Hvis det ikke er satt opp noe varsel for hendelsen, er svaret {"data": []}.

Hvis varselet ikke kan sendes (ugyldig avsender, nummer på blokkeringslisten, duplikatmelding …), avsluttes forespørselen likevel som vellykket og inneholder en feilkode i stedet for meldingsresultatet:

{ "data": { "customer": [ ["duplicity_message"] ] } }

Ved feil:

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Der:

  • type og error (beskrivelse av feilen) finner du i tabellen over feiltyper
  • code er HTTP-feilkoden
  • detail er tilleggsinformasjon om feilen

Feiltyper i E-shop API

TYPE NÅR DEN OPPSTÅR
unknown_identity application_id eller application_token mangler eller er ugyldig.
invalid_input_parameters Forespørselen inneholder en ukjent parameter eller en parameter med feil type.
unknown_action Handlingen i adressen finnes ikke, f.eks. eshop/order/cancel.
Var denne siden nyttig?