Anpassade element: API

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

Konfigurera ett API-gränssnitt

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

1. Skapa fält: Varje fält får en JSON-nyckel. Till höger ser du en JSON-förhandsvisning i realtid, som skickas till din backend exakt på detta sätt.
2. Adress (URL): din backends https://-adress. Endast HTTPS och offentligt tillgängliga adresser är tillåtna (se Säkerhet nedan).
3. Metod: POST (standard), PUT, PATCH eller GET. Med GET läggas värdena till som frågeparametrar istället för att skickas i kroppen.
4. Autentisering: Ange rubriknamnet (t.ex. Authorization) och värdeprefixet (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 Testa begäran, och slutför sedan med Släpp.

Lagra token säkert

Token lagras 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 serverbaserat i den konfigurerade rubriken. Om du anger ett utgångsdatum vägrar Skava anropet efter utgångsdatumet och ber dig förnya token.

Testning: Ping och Testa begäran

• Ping : en enkel kontroll av tillgänglighet. Den kontrollerar endast om din adress svarar och skickar inte token eller formulärdata i processen. Visar tillgänglighet, status och svars tid. Idealiskt som första steg.
• Testförfrågan : den faktiska provkörningen: skickar exempeldata inklusive token till din adress och visar dig det fullständiga 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 släpp.

Utkast och publicera

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

Säkerhet

Hur teamet använder en släppt gränssnitt

När ett gränssnitt är släppt kan alla företagsmedlemmar aktivera det direkt från en chatt: ingen redigerare krävs. Flödet är samma som med dokumentmallar: välj, fyll i, skicka.

1. I chatten, tryck på Plus längst ner och välj Eget element.
2. Välj önskad mall eller gränssnitt från listan.
3. Fyll i formuläret och Skicka.
4. Resultatet visas som ett kort i chatten: synligt för alla i chatten.

Låt AI:n bygga ett element

Som företagsadministratör behöver du inte använda redigeraren själv. Be Skava-assistenten i chatten, till exempel "skapa ett beställningsformulär för min katalog med kvantitet och leveransadress". Den skapar ett utkast från det, kan ändra fält ett i taget senare och känner till din uppladdade artikelkatalog: för beställningar föreslår den produktväljaren istället för ett textfält för artikelnumret.

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

Vad den explicit inte rör vid: åtkomsttoken. Den frågar aldrig efter en och accepterar aldrig en, eftersom chattmeddelanden lagras. Du anger den själv i redigeraren, annars går inget anrop ut. Och den kan inte publicera: det sista steget stannar hos dig, så inget blir synligt för kunder utan kontroll.

Vem får köra det

Fliken "Ändpunkt" anger vem som får använda ett element. Standardinställningen är medlemmarna i ditt företag. Den andra inställningen öppnar det för utomstående, men bara i en chatt där någon från ditt företag också är närvarande: exakt det fall det är avsett för, när kunden beställer från dig. När ditt företag lämnar chatten upphör behörigheten automatiskt.

Produkter från din egen katalog

När du har laddat upp din artikelkatalog erbjuder byggaren en produktväljare. Det finns inga inställningar att underhålla: listan är din katalog. Personen som beställer söker i den, ser bilden, namnet och artikelnumret, och din backend får artikelnumret. Skava avvisar ett nummer som inte finns i din katalog. För kvantitet, placera ett vanligt sifferruta bredvid.

Definiera kortet själv

Din backend bestämmer vad kortet säger. Skava kontrollerar bara form, storlek och säkerhet, aldrig betydelse: den känner inte till beställningsstatus 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 heltalsvärdet 1. Utan det räknas svaret inte som ett kort och det svarsmappning som är konfigurerad i elementet tillämpas.
• state är endast färg och ikon: ok, pending, warn eller error. Allt som bär på betydelse placeras 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 beställning misslyckas aldrig på grund av en detalj.

Användarens inmatningar tillhör servern: de förblir oförändrade oavsett vad din backend skickar. De är registret i chatten över vad som faktiskt skickades in.

Rapportera status senare

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

• seq: din egen räkare. En rapport med ett mindre eller lika stort värde kasseras, så två rapporter kan inte passera varandra.
• final: avslutar interaktionen. Token blir ogiltig och kortet är färdigställt.
• notify: sätt till false för att publicera kortet tyst, utan oläst räkning och utan notifikation. För mellanliggande steg som inte ska väcka någon. Utan det är kortet ett helt vanligt meddelande.

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

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

Korten publiceras av Skavas systemavskickare, inte av den person som körde elementet och inte av ett konto för ditt eget företag. Vilket system som skriver anges i kortets rubrik.

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

Relaterat

Vill du istället skapa en ifyllbar dokumentmall? Se Custom Elements: Dokument.

Vanliga frågor