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 |
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 brukerdefault. - Administratorvarselet søkes alltid opp for språket
defaultog 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.
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 ettershop_idfra listen over butikker, hvis du ikke sender det selv,language_iso– verdien av parameterenlanguage.
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.
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:
Ved feil:
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. |
Takk for tilbakemeldingen.