Denna sida är för utvecklare som kopplar ett företags backend till Skava. Hur ett API-element skapas och släpps beskrivs på Custom Elements: API-gränssnitt; här täcker vi allt som måste hända på andra sidan linjen.

Idén på en mening: Skava känner inte till din domän. Den känner exakt ett format, kortet. Du bestämmer vad det säger, vi kontrollerar bara form, storlek och säkerhet. En materialbeställning är ett exempel; nästa företag samlar in användarfeedback, och det efter det sparar en bild från byggarbetsplatsen i sina egna register.

Flödet i korthet

1. En företagsadministratör skapar ett API-element i Skava: ett formulär plus din backends adress, metod och token.
2. Någon i chatten fyller i formuläret och skickar det.
3. Skava anropar din backend och skickar de ifyllda värdena som JSON.
4. Ditt svar blir kortet i chatten.
5. Valfritt kan du rapportera nya tillstånd senare via callback. Varje rapport blir ett nytt kort; det föregående finns kvar.

Krav på din backend

• HTTPS. Endast https://, inget http, inga inloggningsuppgifter i adressen, högst 2000 tecken.
• Offentligt tillgänglig. Värdnamnet måste enbart upplösas till offentliga IP-adresser. Lokalt nätverk, privata nätverk, länkspecifika adresser och molnmetadata avvisas, och detta kontrolleras vid varje anrop.
• Fast adress. Skava upplöser värdnamnet en gång och låser anslutningen till den IP-adressen. En DNS-ändring under anropet har ingen effekt.
• Inga omdirigeringar. En 301-omdirigering till den "korrekta" adressen räknas som ett misslyckande. Ange den slutgiltiga adressen direkt.
• Svarstid. Tidsgränsen är konfigurerbar per element och har en hård övre gräns på 30 sekunder. Om du behöver längre tid, svara omedelbart och rapportera resultatet senare via callback.
• Svarstorlek. Skava läser högst 256 KiB.
• Content-Type. Kroppen tolkas endast med application/json.

Begäran som når dig

Metoden är GET, POST, PUT eller PATCH, beroende på elementet. Med POST, PUT och PATCH kommer värdena som en JSON-kropp, medan de med GET kommer som frågeparametrar.

Autentisering är ett huvud vars namn och värdeprefix konfigureras i elementet, vanligtvis Authorization med prefixet Bearer . Token lagras krypterat på vår sida. Huvuden host, content-length, content-type, cookie och accept-encoding kan inte anges.

Kroppen är ett platt objekt. Nycklarna väljs av den som skapade elementet; inbäddning förekommer endast där de lade till en tabell eller en produktväljare:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Tre nycklar kommer alltid från oss, så använd dem inte själv:

• locale: användarens språkkod. Svara på det språket; vi översätter inte dina texter.
• callback_url och callback_token: återkopplingen för denna interaktion, se nedan. De finns bara när anropet kommer från en chatt.

Kontextfält som name, company, project eller subchat fylls av servern själv, härledda från kanalen där elementet kördes. En manipulerad klient kan inte hävda ett annat projektnamn där.

Svaret: kortformatet

Svara med 2xx och ett card-objekt. Det är exakt vad som blir kortet i chatten:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

• v (krävs): heltalsvärdet 1. Som text ("1") avvisas det. Utan detta räknas svaret inte som ett kort och det svarsmappning som är konfigurerad i elementet tillämpas.
• title: kortets rubrik.
• state: endast färg och ikonton, ett av ok, pending, warn, error. Ett okänt värde faller tillbaka till ok och du får en hint.
• status_text: fri text som vi inte tolkar. Den placeras högst upp på kortet och är också det som visas i chattlistan och i en push-notis.
• fält: en lista med label och value. Max 20 poster, label 80 tecken, value 200, title och status_text 120 vardera. För långa värden förkortas, inte avvisas: en beställning ska inte misslyckas på grund av en detalj.
• ikon: se nedan.

Vad Skava gör med dina texter innan de når chatten: radbrytningar och styrtecken tas bort (ett höger-till-vänster-tecken skulle annars kunna vända visningen av ett belopp), backticks ersätts och allt som börjar med [SKAVA: neutraliseras. Det sista förhindrar att ett kortvärde tolkas som ett annat chattelement, till exempel en betalningsbegäran.

Länkar i fält, HTML och bilder kan inte anges. En chatt är en betrodd miljö och en klickbar adress från en extern backend skulle vara en inbjudan att bygga om en inloggningssida.

Användarens inmatningar tillhör servern: de visas på det första kortet och du kan inte skriva över dem. I chatten är de registret över vad som faktiskt skickades in.

Ikoner

Med icon får kortet sin egen markering i rubriken. Två sätt:

Ett namn från den inbyggda uppsättningen: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Eller din egen SVG som en sträng. Skava tar endast geometrin (path, circle, ellipse, rect, line, polyline, polygon med deras numeriska attribut) och bygger sin egen bild. Skript, stilar, externa referenser, foreignObject och händelseattribut kasseras; en doctype eller en entitet leder till avvisning; filen får vara högst 8 KiB och innehålla högst 16 former. Färg, streckbredd och storlek bestäms av Skava, så en ikon kan inte utge sig för en kontroll. Arbeta med ett 24 gånger 24 rutnät.

Utan icon förblir standardmarkeringen.

Återanropet: rapportering av senare tillstånd

Anropet innehåller callback_url och callback_token. Använd dem för att rapportera nya tillstånd senare:

POST <callback_url> med Authorization: Bearer <callback_token> och Content-Type: application/json, brödtext högst 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Utöver kortet finns tre valfria värden:

• seq: din egen räknare. En rapport med ett mindre eller lika stort värde kasseras så att två rapporter inte kan passera varandra. Utan seq vinner den sista som anländer.
• final: avslutar interaktionen. Tokenen blir ogiltig och inga fler kort visas. Tillåts också i det first svaret för flöden utan uppföljning.
• 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.

Varje rapport blir sitt eget kort i chatten, det föregående stannar kvar. På så sätt är det läsbar vilket tillstånd som rapporterades. Därav en rekommendation: skicka bara vad som ändrades. Ett kort som upprepar ordernummer, poster och totalbelopp för fjärde gången är bara brus för läsaren.

Två begränsningar: samma rapport två gånger ger inte ett andra kort, och en interaktion kan publicera högst 50 kort. En interaktion accepterar rapporter i 90 dagar.

Svar du bör reagera på

• 200 med {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Läs hinterna: de anger vad som förkortades eller droppades.
• 401: fel token eller interaktions-id. Försök inte igen.
• 410: interaktion stängd eller utgången. Försök inte igen.
• 422: kortet kan inte användas, med hints som orsak. Åtgärda det först.
• 400 trasig JSON, 413 för stort, 429 för många förfrågningar (försök igen med back-off), 500 vårt fel, försök senare.

Exempel 1: en order med statushistorik

Steg 1, förfrågan till din backend:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Steg 2, ditt omedelbara svar:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Chatten visar nu ett kort med en paketikon, status och användarens inmatningar.

Steg 3, senare vid plockning:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Ett tyst andra kort utan fält: endast statusen ändrades.

Steg 4, vid leverans:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Detta kort kan väcka någon, därför inget notify: false.

Steg 5, vid mottagning:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Med final är interaktionen avslutad och token fungerar inte längre.

Exempel 2: en åtgärd utan uppföljning

Alla flöden har inte en historik. Ett element med ett enda fält som överlämnar något till ditt system behöver bara ett svar:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true är viktigt här: annars skulle interaktionen förbli öppen i 90 dagar med en giltig token, även om du aldrig kommer att rapportera något igen.

Produktväljare från katalogen

När företaget har laddat upp sin artikelkatalog kan elementet innehålla blocket produktväljare. Användaren sätter ihop en varukorg från den, och du får den som en lista under den nyckel som den som byggde elementet har valt:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Eftersom nyckeln är fri, leta efter den första listan som har denna form istället för ett fast namn. Innan sändning kontrollerar Skava att varje nummer verkligen finns i företagets katalog, högst 50 poster. I kortet visas posterna som en lista med produktbild, namn och kvantitet.

Testning

• Ping i elementredigeraren skickar en ren HEAD-förfrågan utan token och utan data. Svara med vad som helst; vilket HTTP-svar som helst räknas som nåbart.
• Testa förfrågan skickar en riktig anrop med exempelvärden, även medan elementet fortfarande är ett utkast, och visar förfrågan, svaret och kortvaliderarens meddelanden.
• Förhandsgranskning i fliken bredvid: klistra in ditt JSON-svar, kontrollera och se det färdiga kortet plus antydningarna. Det kontrolleras på servern med samma kod som i produktion.
• Exempelserver: en komplett exempelleverantör körs på api.skava.io och använder allt som beskrivs ovan. Källkoden finns i förvaringen under example_order_server/, cirka 600 rader ren standardbibliotekskod, avsedd att kopieras.

Vad du bör veta mer om

• Kortet är ett helt vanligt chattmeddelande. Det visas i sökresultat, kan citeras och sparas i historiken.
• Det skickas av systemavskickaren, inte av ett konto för ditt företag. Det visas ändå på sidan av den som körde elementet, och vars system som skriver anges i titeln.
• Vem som får köra det ställs in på elementet: endast företagsmedlemmar, eller även utomstående som delar en chatt med det. När ditt företag lämnar chatten upphör behörigheten automatiskt.
• En API-element med ett utgått token är inaktivt och visas inte ens i menyn förrän en administratör sparar ett nytt.

Relaterat

Skapa och publicera: Custom Elements: API-gränssnitt. Fyllbara dokument istället för gränssnitt: Custom Elements: Dokument.