← Alla tjänsteintegrationer

En aktiverbar tjänst är en partnertjänst som användaren aktiverar och avaktiverar på ett objekt under affärens gång, istället för att beställa en gång.

Skillnaden mot standardflödet är att det inte finns någon beställning som levereras och blir klar. Tjänsten har istället ett läge: aktiv eller avaktiverad. Varje gång användaren ändrar läget anropar Vitec Express er, och ni svarar på om det gick bra.

Använd detta flöde när er tjänst ska följa objektet över tid, t. ex. en bevakning eller en publicering som ska kunna stängas av igen.

Tjänsten visas i tjänstelistan på objektet med en aktiveringsknapp. När användaren aktiverar tjänsten flyttas den upp bland de aktiva tjänsterna, och när den avaktiveras hamnar den tillbaka bland de tillgängliga tjänsterna.

Aktiverbara tjänster har varken knappen "Beställ" eller "Avbeställ", och de har inget avbeställningsflöde. Hela interaktionen sker via aktiveringsknappen.

Medan anropet till er pågår är knappen låst. Svarar ni med ett fel så återgår knappen till sitt tidigare läge och användaren får ert felmeddelande.

Börja med att registrera er i vår Connectportal.

Meddela oss på Vitec med följande information genom att klicka här:

• Partner id eller namn så att vi kan identifiera er i Connectportalen.
• Namn på tjänsten.
• Beskrivning av tjänsten.
• Bas-url till er tjänst.
• Om ni vill ha en gemensam endpoint eller två separata för aktivering respektive avaktivering, se Konfiguration nedan.
• Taggningar, ord som användaren ska kunna söka på för att hitta tjänsten.
• Särskilda önskemål (Är det t. ex. endast vissa kunder som ska kunna använda tjänsten?).

Vi märker upp tjänsten som aktiverbar på vår sida. Det är den märkningen som gör att aktiveringsknappen visas i Vitec Express istället för det vanliga beställningsflödet.

Fundera gärna också på vilka metoder det är ni skulle behöva nyttja i Connect.

På tjänsten anges de sökvägar vi ska anropa. Sökvägarna är relativa mot er bas-url. Ni väljer mellan två upplägg, och valet styr om vi skickar med parametern isActive.

Översikt av flödet:

Aktivering och avaktivering sker med ett GET-anrop mot er bas-url sammansatt med den konfigurerade sökvägen. Till skillnad från standardflödet öppnas ingen sida för användaren, utan anropet sker i bakgrunden medan användaren väntar.

För bostäder så kommer ni att få följande information i anropet:

Observera att samma orderId följer med varje gång tjänsten aktiveras eller avaktiveras på ett och samma objekt. Det är alltså inte en ny beställning varje gång användaren aktiverar tjänsten igen.

Vi väntar på ert svar innan användaren får återkoppling. Standardtiden är 60 sekunder, men vi kan konfigurera en annan tid för er tjänst om ni behöver längre tid.

Vi vill att ni svarar med statuskod 200 när ändringen har genomförts hos er. Alla andra statuskoder tolkas som fel.

Ni kan också svara med en body för att styra vad användaren får se. En body med isSuccessful satt till false behandlas som ett fel även om ni svarar med statuskod 200.

{
  "isSuccessful": true
}

{
  "isSuccessful": false,
  "errors": [
    {
      "errorMessage": "Subscription 4711 is not valid for this estate",
      "displayedMessage": "Tjänsten kunde inte aktiveras eftersom abonnemanget har gått ut."
    }
  ]
}

I det här flödet är det Vitec Express som äger statusen på beställningen. Efter ett lyckat anrop till er sätter vi själva statusen:

• Tjänsten aktiveras: status sätts till OrderReceived, och tjänsten visas som aktiv.
• Tjänsten avaktiveras: status sätts till Delivered, och tjänsten visas som avslutad.

Blir det fel sparas ingenting. Det innebär att tjänsten behåller det läge den hade innan användaren försökte ändra den, och att användaren kan försöka igen.

Ni ska därför inte använda metoden för att uppdatera orderstatus för att styra om tjänsten är på eller av. Aktiveringsknappen i Vitec Express läser av statusen på beställningen, så egna statusuppdateringar gör att knappen visar fel läge och att användaren får notifieringar som inte hör hemma i det här flödet. Av samma skäl ingår inte användarinteraktioner i det här flödet.

Behöver ni meddela användaren något, gör det i svaret på anropet via displayedMessage.

En aktiverbar tjänst kan även aktiveras eller avaktiveras automatiskt genom Schemalagda händelser i Vitec Express, t. ex. när ett objekt byter status.

Anropet till er ser exakt likadant ut som när en användare gör ändringen manuellt. Räkna alltså med att kunna ta emot aktiveringar och avaktiveringar utan att någon användare sitter och väntar just då.