Egna element: API

Ett API-gränssnitt är ett formulär vars ifyllda värden Skava skickar som JSON till en adress du anger (ditt backend). På så sätt kan du koppla Skava säkert till dina egna system.

Konfigurera ett API-gränssnitt

Ett gränssnitt består av inmatningsfält (de bildar JSON), måladress och autentisering.

1. Skapa fält: Varje fält får en JSON-nyckel. Till höger ser du JSON-förhandsvisningen i realtid, som skickas till din backend exakt på det här sättet.
2. Adress (URL): https://-adressen till din backend. Endast HTTPS och publikt tillgängliga adresser är tillåtna (se Säkerhet nedan).
3. Metod: POST (standard), PUT, PATCH eller GET. Med GET läggs värdena till som frågeparametrar istället för att skickas i brödtexten.
4. Autentisering: Ange namnet på huvudet (t.ex. Authorization) och prefixet för värdet (t.ex. Bearer ), och spara sedan token. Du kan också ange ett utgångsdatum.
5. Svarsfält (valfritt): Definiera via sökväg vilka värden från backend-svaret som ska visas: t.ex. order.id eller items[0].sku.
6. Kontrollera med Ping och Test Request, och publicera sedan med Release.

Spara token säkert

Token sparas krypterad och returneras aldrig till klienter: appen visar endast om en token är inställd och när den löper ut. Vid sändning lägger Skava till den server-side i den konfigurerade headern. Om du anger ett utgångsdatum vägrar Skava anropet efter utgång och ber dig förnya token.

Testning: Ping och Testanrop

• Ping: en enkel tillgänglighetskontroll. Den kontrollerar endast om din adress svarar och skickar inte token eller formulärdata under processen. Visar tillgänglighet, status och svartid. Perfekt som första steg.
• Testanrop: den riktiga provkörningen: skickar exempeldata inklusive token till din adress och visar dig hela svaret samt de extraherade svarsfälten.

Som administratör kan du köra båda medan du fortfarande är i utkastläge för att verifiera integrationen innan lansering.

Utkast och publicering

Varje gränssnitt börjar som ett utkast och kan redigeras fritt. När allt är klart publicerar du det med Publicera.

Säkerhet

Så använder teamet en publicerad gränssnitt

När ett gränssnitt har publicerats kan alla medarbetare i företaget aktivera det direkt från en chatt, utan redigerare. Det finns ingen gemensam inmatning och inget mellandialogfönster: varje publicerad element finns i plusmenyn under sitt eget namn, med logotypen för det företag som erbjuder det.

1. I chatten, tryck på Plus längst ner och tryck på det element du vill ha, till exempel Materialorder.
2. Fyll i formuläret och Skicka.
3. Resultatet visas som ett kort i chatten, synligt för alla i chatten.

Låt AI:n bygga ett element

Som företagsadmin behöver du inte använda redaktören själv. Berätta för Skava-assistenten i chatten, till exempel "skapa en beställningsformulär för min katalog med antal och leveransadress". Den skapar ett utkast utifrån det, kan ändra fält ett och ett senare och känner igen din uppladdade artikelkatalog: vid beställningar föreslår den produktväljaren istället för ett textfält för artikelnummer.

Den kan också ställa in: endpoint och metod samt målgrupp ("endast företagsmedlemmar" eller "även externa i samma chatt"). För målgruppen frågar den först istället för att bara ställa in det, eftersom det avgör vem som får köra något från utomhus.

Det den uttryckligen inte rör: åtkomsttoken. Den frågar aldrig efter en och accepterar aldrig en, eftersom chattmeddelanden sparas. Du anger den själv i redaktören, annars skickas inget anrop. Och den kan inte publicera: det sista steget ligger hos dig, så inget blir synligt för kunder utan kontroll.

Vem får köra det

Fliken "Endpoint" anger vem som får använda ett element. Standardinställningen är medlemmarna i ditt företag. Den andra inställningen öppnar upp för externa, men endast i en chatt där någon från ditt företag också är närvarande: exakt det fall det är avsett för, kunden som beställer från dig. När ditt företag lämnar chatten upphör behörigheten av sig själv.

Produkter från din egen katalog

När du har laddat upp din artikelkatalog erbjuder byggaren en produktväljare. Det finns inga alternativ att underhålla: listan är din katalog. Personen som beställer söker i den, ser bild, namn och artikelnummer, och din backend tar emot artikelnumret. Skava avvisar ett nummer som inte finns i din katalog. För mängden, lägg ett vanligt tal-fält bredvid.

Definiera kortet själv

Din backend bestämmer vad kortet säger. Skava kontrollerar bara form, storlek och säkerhet, aldrig mening: den känner varken orderstatuser eller fältnamn. För att göra det, svara med ett card-objekt:

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

• v måste vara heltalet 1. Utan det räknas svaret inte som ett kort och responsmappningen som konfigurerats i elementet tillämpas.
• state är bara färg och ikon: ok, pending, warn eller error. Allt som bär på mening hamnar i status_text som fri text.
• fields är en lista med etikett och värde, högst 20 poster. Värden som är för långa förkortas istället för att avvisas, så en order misslyckas aldrig på grund av en detalj.

Användarens inmatning tillhör servern: den förblir orörd oavsett vad din backend skickar. Den är chatten spår av vad som faktiskt skickades in.

Rapportera statusen senare

När elementet körs skickar Skava två extra värden: callback_url och callback_token. Rapportera ett nytt tillstånd dit senare och ett nytt kort visas i chatten, även på mobilen, medan någon tittar. Det tidigare kortet finns kvar, så det går att se vilket tillstånd som rapporterades. Skicka samma card-objekt som ovan, via POST med huvudet Authorization: Bearer <callback_token>. Tre valfria värden placeras bredvid kortet:

• seq: din egen räknare. En rapport med ett lägre eller lika värde kasseras, så två rapporter kan inte överhala varandra.
• final: avslutar interaktionen. Token blir ogiltig och kortet är slutgiltigt.
• notify: sätt till false för att posta kortet tyst, utan oläst-räknare och utan notis. För mellansteg som inte ska väcka någon. Utan det är kortet ett helt vanligt meddelande.

En interaktion kan posta högst 50 kort. Samma rapport två gånger ger inte ett andra kort.

Skava svarar med 200 och en lista av hints om något förkortades eller kassades, och med 422 om kortet var oanvändbart. En interaktion accepterar rapporter i 90 dagar.

Kortskickenheten skickas av Skavas systemskickare, inte av den person som körde elementet och inte av ett konto hos ert företag. Vilket system som skriver anges i kortets titel.

Ett komplett exempel att kopiera finns i repot under example_order_server/ och körs på api.skava.io.

Relaterat

Vill du istället bygga en fyllbar dokumentmall? Se Custom Elements: Dokument.

Vanliga frågor