×
Menu
Index
Search
 
   
   
   
 
  • REST-API
www.softrules.com
 

REST-API

Introductie

De communicatie met de SoftRules® server kan op verschillende manieren.
Dit hoofdstuk beschrijft de communicatie via een REST API. Deze REST API is generiek opgezet zodat deze voor altijd voor alle toepassingen en alle formulieren gebruikt kan worden. De URL https://test.softrules.com is voor elke klant anders. De REST API draait altijd op een server bij de klant.
 

REST API

De URL van de REST API:
https://test.softrules.com/restsoftrules/softrules.svc
 
Om toegang te verkrijgen is een username en password nodig. Om te testen kunnen middels POSTMAN berichten direct aangeboden worden aan de REST API.
 

Het SoftRulesUserinterface xml

De userinterface Xml’s is een eigen formaat dat binnen SoftRules® gebruikt wordt. Voor alle formulieren (userinterfaces) geldt dat de structuur gelijk is. Onderstaand plaatje geeft een eerste indruk van het velden van een SoftRulesUserinterface.
 
 
Alle velden van van dit XML worden hier beschreven. Neem alstublieft contact met ons op voor het XML schema.
 

.net Standard Library en C# code voor het lezen en schrijven van de berichten

Voor het parsen van het verkregen Xml is een zip file beschikbaar met daarin een .net standard library welke aan het project toegevoegd kan worden. Deze wordt inclusief de C# code geleverd. Ook dit kan en mag door u gebruikt worden, bijvoorbeeld in een PHP implementatie.
Bij elke update van SoftRules® zal deze code meegeleverd worden zodat wijzigingen altijd meekomen en dus up-to-date zijn. Het heeft ook de voorkeur dat deze code opgegenomen wordt in het project voor de frontend. Ook functies voor het bepalen of een Group, Question, Button of Label zichtbaar of verplicht is, zijn hierin opgenomen.
 
Nadat het SoftRulesUserinterface van de REST API opgehaald is, kan met onderstaande code een scherm opgebouwd gaan worden.
De items uit de userinterface (Groups, Questions, Buttons en Labels) kunnen eigenschappen bezitten welke aangeven of ze getoond moeten worden (VisibleExpression), verplicht zijn (RequiredExpression), enabled of readonly zijn.
(DefaultStateExpression) en bij Groups en Questions of de UpdateUserinterface uitgevoerd moet worden (UpdateExpression). Middels een aantal functies uit de library kunnen deze expressions geresolved worden:
 
 

Aanvragen SessieID

Bij elke bevraging van de REST API is een sessieID nodig. Via de sessie wordt de autorisatie geregeld en houdt de REST API gegevens van de transactie vast.
Uri:
https://test.softrules.com/restsoftrules/softrules.svc/getsession?username=<username>&password=<password>
 
Methode: GET
<SoftRulesAPI>
    <Result>
        <Resultcode>0</Resultcode>
        <ResultDescription />
    </Result>
    <Session>
        <SessionID>34f96534-5df9-4d71-88a8-803a1d18b6c2</SessionID>
    </Session>
</SoftRulesAPI>
 
Een ongedige username/password combinatie levert een resultcode van 1 op.
<SoftRulesAPI>
    <Result>
        <Resultcode>1</Resultcode>
        <ResultDescription>De combinatie gebruikersnaam en wachtwoord kan niet geautoriseerd worden.</ResultDescription>
    </Result>
    <Session>
        <SessionID />
    </Session>
</SoftRulesAPI>
 

Opvragen beschikbare producten

De producten die beschikbaar zijn via de REST API worden opgehaald middels de volgende call:
Uri:
https://test.softrules.com/restsoftrules/softrules.svc/products/<sessieID>
 
Methode: GET
<SoftRulesAPI>
    <Result>
        <Resultcode>0</Resultcode>
        <ResultDescription />
    </Result>
    <Products>
        <Product>
            <Name>AVP</Name>
            <Description>Aansprakelijkheid particulieren</Description>
        </Product>
        <Product>
            <Name>WOONHUIS</Name>
            <Description>Woonhuis</Description>
        </Product>
        <Product>
            <Name>INBOEDEL</Name>
            <Description>Inboedel</Description>
        </Product>       
    </Products>
</SoftRulesAPI>
 

Opvragen van de eerste pagina van een product

Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/Userinterface/<productnaam>/firstpage/<sessieID>
 
Bij de POST kan eventueel in de body een Xml als input meegegeven worden. Hierin kunnen waarden vooraf ingevuld worden, zoals:
 
<SR xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <ActionID>Nieuw</ActionID>
    <Relatiedocument>
        <Relatiemantel>
            <AL>
                <TP>
                    <TP_IDNR>1</TP_IDNR>
                    <TP_TPAAND>100</TP_TPAAND>
                    <KP>
                        <KP_EMAIL>hbienefelt@comparity.nl</KP_EMAIL>
                        <KP_ENTREF>253376a3-0e61-4931-ac50-0104dde88833</KP_ENTREF>
                        <KP_TEAM></KP_TEAM>
                    </KP>
                </TP>
                <VE>
                    <VE_IDNR>2</VE_IDNR>
                </VE>
            </AL>
            <VP>
                <VP_ANAAM></VP_ANAAM>
                <VP_EMAIL></VP_EMAIL>
                <VP_GEBDAT/>
                <VP_GESLACH/>
                <VP_GSSC></VP_GSSC>
                <VP_IBAN></VP_IBAN>
                <VP_LAND></VP_LAND>
                <VP_PARZAKC></VP_PARZAKC>
                <VP_PCODE></VP_PCODE>
                <VP_PLAATS></VP_PLAATS>
                <VP_RELNUM></VP_RELNUM>
                <VP_RELSRTC></VP_RELSRTC>
                <VP_STRAAT></VP_STRAAT>
                <VP_TOEVOEG></VP_TOEVOEG>
                <VP_VOORL></VP_VOORL>
                <VP_VOORV></VP_VOORV>
            </VP>
        </Relatiemantel>
        <Pakket>
            <Mantel>
                <PK>
                    <PK_NUMMER/>
                    <PK_EXTERN/>
                    <PK_OFFERTE/>
                    <PK_PRODUCC/>
                </PK>
            </Mantel>
            <Onderdeel>
                <PP>
                    <PP_PRODCFG></PP_PRODCFG>
                    <PP_NUMMER></PP_NUMMER>
                    <PP_EXTERN></PP_EXTERN>
                    <PP_OFFERTE></PP_OFFERTE>
                    <PP_PRODUCC/>
                </PP>
            </Onderdeel>
        </Pakket>
    </Relatiedocument>
</SR>
 
Het gaat hier om gegevens van de relatie, tussenpersoon en / of polisnummers.
 
We gaan in dit document het product AVP (Aansprakelijkheid particulieren) uitwerken. Samen met het verkregen sessionID wordt de aanroep voor de eerste pagina van het formulier:
 
https://test.softrules.com/restsoftrules/softrules.svc/Userinterface/AVP/firstpage/34f96534-5df9-4d71-88a8-803a1d18b6c2
 
De response is dan een userinterfaceXml met daarin dus alleen de eerste pagina. Na het parsen van de userinterfaceXml kan onderstaand scherm getoond worden:
 
Als we de Question Postcode verder bekijken:
 
<Question State="New">
     <Name>VP_PCODE</Name>
     <Description>Postcode</Description>
     <Value/>
     <HelpText>Postcode woonadres verzekeringnemer</HelpText>
     <DefaultState>Editable</DefaultState>
     <IncludeInvisibleQuestion>False</IncludeInvisibleQuestion>
     <UpdateExpression>
          <Conditions>
               <Condition>                   
               </Condition>
               <Condition>                   
               </Condition>
          </Conditions>
          <StartValue>True</StartValue>
          <Description/>
     </UpdateExpression>
     <DataType>string</DataType>
     <Restrictions>
          <pattern>/^[1-9][0-9]{3}[\s]?[A-Za-z]{2}$</pattern>
     </Restrictions>
     <Parameter>
          <Name>VP</Name>
          <Path>SR/Relatiedocument/Relatiemantel/VP</Path>
     </Parameter>
     <ElementPath>SR/Relatiedocument/Relatiemantel/VP</ElementPath>
     <UpdateUserInterface Description="" ProcessOnShow="False">True</UpdateUserInterface>
     <InvalidMessage>Vul een geldige postcode in</InvalidMessage>
     <QuestionID>d2b8a091-0b6a-4390-bbbb-e4338cd3b0da~8aba1f56-7703-4026-b472-8f038adad712</QuestionID>
</Question>
 
De helptext is gevuld waardoor een ‘?’ getoond kan worden. In het voorbeeld wordt na een hover over dit plaatje de tekst getoond.
 
Er is een pattern aanwezig welke het formaat aangeeft van de postcode. Als het ingevulde daar niet aan voldoet, met de tekst getoond worden uit InvalidMessage.
 
De DefaultState geeft aan of de Question default Editable of ReadOnly is. Middels een DefaultStateExpression kan deze eigenschap wel of niet van toepassing zijn.
 
Het veld UpdateUserinterface is True. Dit houdt in dat er een server side actie vereist is. In dit geval zal SoftRules® de postcode extern gaan ophalen. Eerst moet na het verlaten van dit veld een controle plaatsvinden of de waarde goed ingevuld is, daarna moet de UpdateExpression (indien aanwezig) ook True zijn. Bij een updateUserinterface (zie verderop) is het QuestionID van belang om samen met de tot zover ingevulde userinterfaceXml naar de REST API te sturen. Als response wordt de gehele userinterface weer teruggestuurd. Er kunnen andere Questions gevuld zijn zoals hier de Straatnaam en de Woonplaats. Deze Question zijn hier ReadOnly.
 
De Question Gezinssamenstelling heeft ook nog een aantal TextValues.
 
<TextValues TextValuesID="14" TextQuestionID="">
     <Item>
          <Value>#</Value>
          <Text>Maak uw keuze</Text>
     </Item>
     <Item>
          <Value>A</Value>
          <Text>Eenpersoonshuishouding</Text>
     </Item>
     <Item>
          <Value>I</Value>
          <Text>Meerpersoonshuishouding</Text>
     </Item>
</TextValues>
 
Hiervan wordt een selectbox van gemaakt. De Value uit de Question is de default selectie voor de selectbox.
 
Dit is pagina 1 van 5 waardoor een volgende knop getoond moet worden.
 
Let op!
Na het verlaten van elke question:
Eigenschap UpdateUserinterace is True? ->UpdateUserinterface
Anders alle expressies op het formulier voor alle compomenten langslopen:
 
Als extra mogelijk kan hier bij de aanroep van de pagina het eerder verkregen SoftRulesSessionID meegegeven worden. Je hebt dan een mogelijkheid ‘verder’ te gaan met een eerder gestarte berekening, offerte of aanvraag.
 
Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/Userinterface/<productnaam>/firstpage/<SoftRulesSessionID>/<sessieID>
 

UpdateUserinterface

Questions en Groups hebben een eigenschap UpdateUserinterface. Indien deze de waarde True hebben en de UpdateExpression is True is een server side actie noodzakelijk. Welke dat is, bepaalt SoftRules® zelf. Dit kan een bevraging van een postcode zijn, het ophalen van kentekengegevens of een ander in SoftRules® gedefinieerde actie.
 
Voor alle UpdateUserinterfaces geldt dat het gehele userinterfaceXml opgestuurd moet worden in de body van het bericht en dat de Guid van de control welke de update initieert in de URL komt te staan gevolgd door het sessionID.
 
Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/UpdateUserinterface/<QuestionID>/<SessionID>
 
https://test.softrules.com/restsoftrules/softrules.svc/UpdateUserinterface/d2b8a091-0b6a-4390-bbbb-e4338cd3b0da~8aba1f56-7703-4026-b472-8f038adad712/34f96534-5df9-4d71-88a8-803a1d18b6c2
 

POSTMAN

 
 
In de response is weer een UserinterfaceXml.
 

Opvragen van de volgende pagina van een product

Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/Userinterface/<productnaam>/nextpage/<sessieID>
 
Ingevuld:
https://test.softrules.com/restsoftrules/softrules.svc/ Userinterface/AVP/nextpage/34f96534-5df9-4d71-88a8-803a1d18b6c2
 
De eerder verkregen userinterfaceXml wordt meegeven in de body van het bericht.
 
Pagina 2 uit het voorbeeld kan er zo uitzien:
 
 
In de userinterfaceXml staat nu de volgende pagina. Page is nu 2 geworden en Pages staat nog steeds 5. Nu mag een Volgende en een Vorige knop getoond worden.
 
Op deze pagina staat een Group van het type table met daaronder een Group van het type row.
 
 
Op de Questions Provisie en Relatiekorting staat een displayType Slider. Hierbij horen Customproperties MinValue, StepSize en MaxValue.
 
<Question State="Changed">
    ..
    <DisplayType>Slider</DisplayType>
    <CustomProperties>
        <CustomProperty>
            <Name>MinValue</Name>
            <Value>0</Value>
        </CustomProperty>
        <CustomProperty>
            <Name>StepSize</Name>
            <Value>1</Value>
        </CustomProperty>
        <CustomProperty>
            <Name>MaxValue</Name>
            <Value>25</Value>
        </CustomProperty>
    </CustomProperties>
    ..
</Question>
 
Op de Button staat een updateUserinterface die een (her)berekening uitvoert.
Nadat alle velden gevuld en geldig zijn volgens de Expressions kan de volgende pagina opgeroepen worden. Er is geen validatie van toepassing op Questions die niet zichtbaar zijn.
 

Opvragen van de vorige pagina van een product

Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/Userinterface/<productnaam>/previouspage/<sessieID>
 
Ingevuld:
https://test.softrules.com/restsoftrules/softrules.svc/ Userinterface/AVP/ previouspage/34f96534-5df9-4d71-88a8-803a1d18b6c2
 
De eerder verkregen UserinterfaceXml wordt meegeven in de body van het bericht.
 

Laatste pagina: Process

Op de laatste pagina (pagina 5) staat geen volgende button, maar een button met de tekst verwerken of afsluiten. De actie naar SoftRules® wordt nu:
 
Uri (POST):
https://test.softrules.com/restsoftrules/softrules.svc/Process/<product>/<sessionID>
 
In de body staat weer de gehele userinterfaceXml.
 
Naast een process op de laatste pagina kan met de process functie ook gebruikt worden voor losstaande functies zoals het ophalen van Clausules, Voorwaarden, Verzekeringskaarten, Relaties enz. De input zal dan afhankelijk van de functionaliteit een (AFD) Xml zijn met daarin de gegevens om de bewerking te kunnen doen.
 
Bovenstaande is afhankelijk van de implementatie bij de klant.
 

DisplayTypes en Customproperties

Deze zijn hier beschreven.