Pielāgoti elementi: API

API saskarne ir veidlapa, kuras aizpildītās vērtības Skava kā JSON nosūta uz jūsu norādītu adresi (jūsu backend). Tā jūs droši savienojat Skava ar savām sistēmām.

API saskarnes iestatīšana

Saskarne sastāv no ievades laukiem (tie veido JSON), mērķa adreses un autentifikācijas.

1. Izveidojiet laukus: katrs lauks saņem JSON atslēgu. Labajā pusē reāllaikā redzat JSON priekšskatījumu, kas tieši tādā veidā tiek nosūtīts uz jūsu backend.
2. Adrese (URL): jūsu backend https:// adrese. Atļautas ir tikai HTTPS adreses, kas ir publiski pieejamas (skatiet sadaļu Drošība zemāk).
3. Metode: POST (noklusējums), PUT, PATCH vai GET. Ar GET vērtības tiek pievienotas adresei kā parametri, nevis sūtītas pieprasījuma pamatdaļā.
4. Autentifikācija: iestatiet galvenes nosaukumu (piemēram, Authorization) un vērtības priedēkli (piemēram, Bearer ), pēc tam saglabājiet tokenu. Pēc izvēles norādiet derīguma beigu datumu.
5. Atbildes lauki (pēc izvēles): ar ceļu norādiet, kuras vērtības no backend atbildes tiek rādītas, piemēram, order.id vai items[0].sku.
6. Pārbaudiet ar Ping un Test Request, pēc tam nospiediet Publicēt.

Droša tokena glabāšana

Tokens tiek glabāts šifrēts un nekad netiek atdots klientiem: lietotne rāda tikai to, vai tokens ir iestatīts un kad beidzas tā derīgums. Sūtot Skava to servera pusē pievieno norādītajai galvenei. Ja esat norādījis derīguma beigu datumu, pēc tā Skava izsaukumu noraida un lūdz atjaunot tokenu.

Testēšana: Ping un Test Request

• Ping ir viegla sasniedzamības pārbaude. Tā pārbauda tikai to, vai jūsu adrese atbild, un pie tam nesūta ne tokenu, ne veidlapas datus. Rāda sasniedzamību, statusu un atbildes laiku. Ideāls pirmais solis.
• Test Request ir īsts izmēģinājums: nosūta uz jūsu adresi parauga datus kopā ar tokenu un parāda pilnu atbildi, kā arī izgūtos atbildes laukus.

Kā administrators varat palaist abus vēl melnraksta stadijā, lai pārbaudītu savienojumu pirms publicēšanas.

Melnraksts un publicēšana

Katra saskarne sākumā ir melnraksts, un to var brīvi rediģēt. Kad viss ir gatavs, jūs to publicējat ar Publicēt.

Drošība

Kā komanda izmanto publicētu saskarni

Tiklīdz saskarne ir publicēta, visi uzņēmuma darbinieki var to palaist tieši no tērzēšanas, redaktors tam nav vajadzīgs. Gaita ir tāda pati kā ar dokumentu veidnēm: izvēlēties, aizpildīt, nosūtīt.

1. Tērzēšanā nospiediet Plus apakšā un izvēlieties Pielāgotu elementu.
2. Izvēlieties no saraksta vajadzīgo veidni vai saskarni.
3. Aizpildiet veidlapu un nospiediet Sūtīt.
4. Rezultāts parādās tērzēšanā kā kartīte, redzama visiem tērzēšanas dalībniekiem.

Ļaujiet mākslīgajam intelektam izveidot elementu

Kā uzņēmuma administratoram jums nav pašam jāizmanto redaktors. Pasakiet to Skava asistentam tērzēšanā, piemēram: „izveido man pasūtījuma veidlapu pēc mana kataloga ar daudzumu un piegādes adresi“. No tā viņš izveido melnrakstu, vēlāk var mainīt laukus pa vienam, un viņš pazīst jūsu augšupielādēto artikulu katalogu: pasūtījumiem tas iesaka produktu izvēli, nevis teksta lauku artikula numuram.

Ko tas drīkst iestatīt vēl: endpoint un metodi, kā arī lietotāju loku („tikai uzņēmuma darbinieki“ vai „arī cilvēki no malas tajā pašā tērzēšanā“). Par lietotāju loku tas vispirms pajautā, nevis vienkārši iestata, jo tas nosaka, kas drīkst kaut ko palaist no ārpuses.

Ko tas apzināti neaiztiek: piekļuves tokenu. Tas nekad to neprasa un nekad nepieņem, jo tērzēšanas ziņas tiek glabātas. To jūs ievadāt pats redaktorā, citādi neviens izsaukums netiek veikts. Un tas nevar publicēt: pēdējais solis paliek jūsu ziņā, tāpēc klientiem nekas nekļūst redzams nepārbaudīts.

Kas to drīkst palaist

Cilne „Endpoint“ nosaka, kas drīkst izmantot elementu. Pēc noklusējuma tie ir jūsu uzņēmuma darbinieki. Otrs iestatījums to atver arī cilvēkiem no malas, bet tikai tādā tērzēšanā, kurā klāt ir arī kāds no jūsu uzņēmuma, tātad tieši tajā gadījumā, kuram tas ir domāts: klients pasūta pie jums. Kad jūsu uzņēmums pamet tērzēšanu, atļauja beidzas pati no sevis.

Preces no sava kataloga

Kad esat augšupielādējis savu artikulu katalogu, veidotājs piedāvā produktu izvēles bloku. Nekādas iespējas nav jāuztur: saraksts ir jūsu katalogs. Pasūtītājs tajā meklē, redz attēlu, nosaukumu un artikula numuru, bet jūsu backend saņem artikula numuru. Numuru, kas nav jūsu katalogā, Skava noraida. Daudzumam blakus ielieciet parastu skaitļa lauku.

Nosakiet kartīti pats

Ko kartīte saka, izlemj jūsu backend. Skava pārbauda tikai formu, izmēru un drošību, bet nekad nozīmi: tā nepazīst ne pasūtījumu statusus, ne lauku nosaukumus. Tāpēc atbildiet ar objektu card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v jābūt veselam skaitlim 1. Bez tā atbilde netiek uzskatīta par kartīti un tiek piemērota elementā iestatītā atbildes sasaiste.
• state nosaka tikai krāsu un ikonu: ok, pending, warn vai error. Viss, kam ir nozīme, nonāk laukā status_text kā brīvs teksts.
• fields ir apzīmējuma un vērtības saraksts, ne vairāk kā 20 ieraksti. Pārāk garas vērtības tiek saīsinātas, nevis noraidītas, tāpēc pasūtījums nekad neizgāžas kādas detaļas dēļ.

Lietotāja ievadītais pieder serverim: tas paliek neskarts neatkarīgi no tā, ko sūta jūsu backend. Tas ir ieraksts tērzēšanā par to, kas patiešām tika iesniegts.

Statusa paziņošana vēlāk

Kad elements tiek palaists, Skava nosūta divas papildu vērtības: callback_url un callback_token. Paziņojiet tur vēlāk jaunu statusu, un tērzēšanā parādās jauna kartīte, arī telefonā, kamēr kāds skatās. Iepriekšējā paliek, tāpēc ir salasāms, kad kurš statuss tika paziņots. Nosūtiet to pašu objektu card kā iepriekš, ar POST un galveni Authorization: Bearer <callback_token>. Blakus kartītei var padot trīs neobligātas vērtības:

• seq: jūsu pašu skaitītājs. Paziņojums ar mazāku vai vienādu vērtību tiek atmests, tāpēc divi paziņojumi nevar apsteigt viens otru.
• final: noslēdz mijiedarbību. Tokens kļūst nederīgs, un kartīte ir galīga.
• notify: iestatiet false, lai kartīte tiktu publicēta klusi, bez nelasīto skaitītāja un bez paziņojuma. Starpsoļiem, kuriem nevienu nevajag modināt. Bez tā kartīte ir pilnīgi parasta ziņa.

Viena mijiedarbība drīkst publicēt ne vairāk kā 50 kartītes. Viens un tas pats paziņojums divreiz otru kartīti nerada.

Skava atbild ar 200 un sarakstu hints, ja kaut kas tika saīsināts vai izlaists, un ar 422, ja kartīte nebija lietojama. Mijiedarbība pieņem paziņojumus 90 dienas.

Kartītes publicē Skava sistēmas sūtītājs, nevis cilvēks, kas palaida elementu, un ne kāds jūsu uzņēmuma konts. Kura sistēma raksta, ir norādīts kartītes virsrakstā.

Pilns piemērs kopēšanai atrodas repozitorijā mapē example_order_server/ un darbojas vietnē api.skava.io.

Saistīts

Vai tā vietā vēlaties izveidot aizpildāmu dokumenta veidni? Skatiet Pielāgoti elementi: Dokumenti.

Biežāk uzdotie jautājumi