Versions Compared

Version Old Version 3 New Version Current
Changes made by

Bjørn Hamre

Bjørn Hamre

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The integrator initiates the process by sending a data structure (as described in the WSDL) to the web service. Etinglysing will return an object containing the document itself, a reference to the document in etinglysing and some key information about it.

...

Normal flow

Example request:

Code Block
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:dok="http://dokument.ws7.etinglysing.no/">
    <soapenv:Header/>
   <soapenv:Body>
      <dok:generatePantedokument>
         <pantedokument referanse="Example">
            <panteobjekter>
               <panteobjekt>
                  <matrikkel 
                    kommunenummer="1234" 
                    gaardsnummer="1" 
                    bruksnummer="1" 
                    festenummer="0" 
                    seksjonsnummer="0" 
                    eiendomsnivaa="G"/>
                  <hjemmelshavere>
                     <hjemmelshaver>
                       <organisasjon id="123456789">
                           <navn>Organization name</navn>
                           <!--Optional, not needed for production-->
                           <!--Will be validated towards Enhetsregisteret if present-->
                           <signaturberettigede> 
                              <signaturberettigede id="12345678901">
                                 <fornavn>First Name</fornavn>
                                 <etternavn>Surname</etternavn>
                                 <epost>person@example.com</epost>
                              </signaturberettigede>
                           </signaturberettigede>
                        </organisasjon>
                        <broek teller="1" nevner="1"/>
                     </hjemmelshaver>
                  </hjemmelshavere>
               </panteobjekt>
            </panteobjekter>
            <pantebeloeper>
               <pantebeloep valuta="NOK" verdi="100000"/>
            </pantebeloeper>
            <panthavere>
               <panthaverId>123456789</panthaverId>
            </panthavere>
            <dokumentflyt>DOKUMENT_TIL_TINGLYSING</dokumentflyt>
            <refinansiering>false</refinansiering>
         </pantedokument>
         <options>
            <returnPdf>false</returnPdf>
         </options>
      </dok:generatePantedokument>
   </soapenv:Body>
</soapenv:Envelope>

...

Code Block
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:generatePantedokumentResponse xmlns:ns2="http://dokument.ws7.etinglysing.no/">
         <return>
            <status>
               <created>2018-09-06T14:09:34.710+02:00</created>
               <id>15742141</id>
               <statusCode>OPPRETTET</statusCode>
            </status>
            <documentHolder>
               <content>PEJhbmtJRFhNT...</content>
               <format>BIDXML</format>
               <type>PANTEDOKUMENT</type>
            </documentHolder>
            <documentVersion>KARTVERKET</documentVersion>
         </return>
      </ns2:generatePantedokumentResponse>
   </soap:Body>
</soap:Envelope>

Validation & error handling

...

Example response:

Code Block
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/
Drawio
zoom1
simple0
inComment0
custContentId1446281352
pageId1202192544
lbox1
diagramDisplayNameDiagram uten navn.drawio
contentVer1
revision1
baseUrlhttps://ambita.atlassian.net/wiki
diagramNameDiagram uten navn.drawio
pCenter0
width501
links
tbstyle
height331

Validation and error handling

Example response:

Code Block
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Ugyldig personnr eller organisasjonsnr: 123456789</faultstring>
         <detail>
            <ns2:FellesDokumentException xmlns:ns2="http://dokument.ws7.etinglysing.no/">
               <exceptionId>1536235901863</exceptionId>
               <documentMessages>
                  <documentMessage>
                     <errorGroup>VALIDERINGSFEIL</errorGroup>
                     <message>Ugyldig personnr eller organisasjonsnr: 123456789</message>
                     <errorCode>9014</errorCode>
                  </documentMessage>
               </documentMessages>
            </ns2:FellesDokumentException>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

...

When generating a mortgage you may have two scenarios:

  1. Send the document to the Land Registry

  2. Send the document to a broker

This you can control by setting the flow. The possible flows are:

...

Code Block
<panteobjekter>
   <panteobjekt>
      <matrikkel  kommunenummer="1234" 
                  gaardsnummer="1" 
                  bruksnummer="1" 
                  festenummer="0" 
                  seksjonsnummer="0" 
                  eiendomsnivaa="G"/>
   </panteobjekt>
</panteobjekter>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:dok="http://dokument.ws7.etinglysing.no/">
    <soapenv:Header/>
   <soapenv:Body>
      <dok:generatePantedokument>
         <pantedokument referanse="Example">
            <panteobjekter>
               <panteobjekt>
                  <matrikkel 
                    kommunenummer="1234" 
                    gaardsnummer="1" 
                    bruksnummer="1" 
                    festenummer="0" 
                    seksjonsnummer="0" 
                    eiendomsnivaa="G"/>
                  <hjemmelshavere>
                     <hjemmelshaver>
                       <organisasjon id="123456789">
                           <navn>Organization name</navn>
                           <!--Optional, not needed for production-->
                           <!--Will be validated towards Enhetsregisteret if present-->
                           <signaturberettigede> 
                              <signaturberettigede id="12345678901">
                                 <fornavn>First Name</fornavn>
                                 <etternavn>Surname</etternavn>
                                 <epost>person@example.com</epost>
                              </signaturberettigede>
                           </signaturberettigede>
                        </organisasjon>
                        <broek teller="1" nevner="1"/>
                     </hjemmelshaver>
                  </hjemmelshavere>
               </panteobjekt>
            </panteobjekter>
            <pantebeloeper>
               <pantebeloep valuta="NOK" verdi="100000"/>
            </pantebeloeper>
            <panthavere>
               <panthaverId>123456789</panthaverId>
            </panthavere>
            <dokumentflyt>DOKUMENT_TIL_TINGLYSING</dokumentflyt>
            <refinansiering>false</refinansiering>
         </pantedokument>
         <options>
            <returnPdf>false</returnPdf>
         </options>
      </dok:generatePantedokument>
   </soapenv:Body>
</soapenv:Envelope>
How to

...

For some cases it is not enough that the owners sign the document. This typically means that there are “rettighetshavere” that needs to be taken into account. If not taken into account the service will respond with validation errors on generate (and that could be valuable and correct). If the case is, however, that you intend to get these signatures, the signature role must be applied. This tells the service that “I’ve got it!”.

There are four types of roles:

Role

Description

BORTFESTER

The land owner that lease out land
(feste))

RETTIGHETSHAVER_I_URAADIGHET

A legal person is blocking registration
unless his consent is given (signature on the document)

UTSTEDER

The seller is not the land owner
(only relevant for deeds)

PANTSETTER

The legal person if not equal to the land owner
(hjemmelshaver)

In V7 this is put outside the property, hence yields the whole document (across all properties)

...

set total fraction

Previously total fraction was modelled as attributes on the matrikkel element (totalnevner and totalteller):

Code Block
 <matrikkel totalnevner="1" totalteller="1" ...>

From V7 the attributes have been replaced by an element on the panteobjekt element.

Code Block
<panteobjekt>
  <borettsandel .../>
  <hjemmelshavere>
  ...
  </hjemmelshavere>
<totalBroek teller="1" nevner="1"/> 
</panteobjekt>

If totalBroek is specified for a pantedokument with dokumentflyt = DOKUMENT_TIL_TINGLYSING the hjemmmelshaver broek will be validated and superseded according to grunnboken. totalBroek must be equal to sum broek for hjemmelshavere.

If totalBroek is specified for a pantedokument with dokumentflyt = DOKUMENT_TIL_OPPGJOER or dokumentflyt = DOKUMENT_TIL_EKSISTERENDE_OPPGJOER, the hjemmelshaver broek will NOT be validated. Hjemmelshavere are the new owners and at the time of writing, it is not possible to validate.
If totalBroek is 1/1, the fractions for hjemmelshavere will be disregarded. Because there is no requirement for fraction in a pantedokument includes the entire property.
If totalBroek is less than 1/1, sum broek for hjemmelshavere must be equal to totalBroek, and hjemmelshaver broek must be correct according to the buyer contract.

How to handle additional signatures

For some cases it is not enough that the owners sign the document. This typically means that there are “rettighetshavere” that needs to be taken into account. If not taken into account the service will respond with validation errors on generate (and that could be valuable and correct). If the case is, however, that you intend to get these signatures, the signature role must be applied. This tells the service that “I’ve got it!”.

There are four types of roles:

Role

Description

BORTFESTER

The land owner that lease out land
(feste)). Only relevant for deeds.

RETTIGHETSHAVER_I_URAADIGHET

A legal person is blocking registration
unless his consent is given (signature on the document)

UTSTEDER

The seller is not the land owner
(only relevant for deeds)

PANTSETTER

The legal person if not equal to the land owner
(hjemmelshaver)

In V7 this is put outside the property, hence yields the whole document (across all properties)

Code Block
<pantedokument referanse="Demo">
  <!--Optional:-->
  <signatarroller>
     <!--OptionalZero or more repetitions:-->
          <signatarrolle>
<signaturberettigede>               <!--Zero1 or more repetitions:-->
        <signatarrolleTyper></signatarrolleTyper>
     <signaturberettigede   <organisasjon id="?">
           <navn>?</navn>
     <fornavn>?</fornavn>      <!--Optional:-->
           <etternavn>?</etternavn><signaturberettigede>
                 <!--OptionalZero or more repetitions:-->
              <signaturberettigede id="?">
  <epost>?</epost>               </signaturberettigede><fornavn>?</fornavn>
                 <etternavn>?</signaturberettigede>etternavn>
                 </organisasjon>!--Optional:-->
                <person id="?"><epost>?</epost>
              <fornavn>?</fornavn>signaturberettigede>
           <etternavn>?</etternavn>signaturberettigede>
        </organisasjon>
     <!--Optional:-->
           <epost>?</epost>
        </person>
     </signatarrolle>
</signatarroller>
</pantedokument>

How to handle fractions

If you do not have the individual fraction owned by each person (“idell andel”) you may set the total fraction per property instead..

We have added two optional attributes to the WSDL on the Eiendom node (Matrikkel or Borett).
There are:

  • Totalteller (Total nominator)

  • Totalnevner (Total denominator)

Once these are given, the teller and nevner applied to the individual hjemmelshaver are ignored and correct values are loaded from Grunnboken. This will not work for documents used in transfer of ownership (skjøte), as the future fractions are not known.

Example:

...

Figure 4: Example total fractions

The picture shows how the borettsandel has added the two new attributes. The teller/nevner shown in the example are not used, and can therefore contain any value.

Validation. Using total fractions will check if the total fraction equals the summed fractions, fetched from Grunnboken, of the hjemmelshaver-list. Also, if owners (hjemmelshaver) do not match the Grunnbok, exceptions will be thrown.

How to handle roles

This feature enables the integrator to generate documents on behalf of another organization. Once added into the request, the document will be generated accordingly unless the validation fails to validate that the respective organisation is defined as rekvirent or panthaver (dokumenteier) in the user profile.

...

   <person id="?">
           <fornavn>?</fornavn>
           <etternavn>?</etternavn>
           <!--Optional:-->
           <epost>?</epost>
        </person>
     </signatarrolle>
</signatarroller>
</pantedokument>

How to handle fractions

If you do not have the individual fraction owned by each person (“idell andel”) you may set the total fraction per property instead..

We have added two optional attributes to the WSDL on the Eiendom node (Matrikkel or Borett).
There are:

  • Totalteller (Total nominator)

  • Totalnevner (Total denominator)

Once these are given, the teller and nevner applied to the individual hjemmelshaver are ignored and correct values are loaded from Grunnboken.

But there is an important thing to mention regarding this. The system can only help to calculate this fraction if the ‘dokumentflyt’ element is ‘DOKUMENT_TIL_TINGLYSING’. This will be cases where the customer want to refinance their existing loans. For transfer of ownership where the pantedocuments are going to be sent to broker we have no way of knowing the fraction. (‘dokumentflyt’ equal to DOKUMENT_TIL_OPPGJOER or DOKUMENT_TIL_EKSISTERENDE_OPPGJOER). In these cases the fraction element in each ‘hjemmelshaver’ element needs to be correct.  

Example:

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <generatePantedokument xmlns="http://dokument.ws7.etinglysing.no/">
      <pantedokument referanse="N/A" xmlns="">
        <panteobjekter>
          <panteobjekt>
            <borettsandel organisasjonsnummer="948145596" andelsnummer="33" borettslagnavn="MIKVOLD VESTRE BORETTSLAG"/>
            <hjemmelshavere>
              <hjemmelshaver>
                <personMedSivilstand id="01105******">
                  <fornavn>Ivar</fornavn>
                  <etternavn>Nubdal</etternavn>
                  <sivilstand fellesBolig="false" beggeHjemmelshavere="true" gift="true"/>
                </personMedSivilstand>
                <broek teller="1" nevner="1"/>
              </hjemmelshaver>
              <hjemmelshaver>
                <personMedSivilstand id="10016******">
                  <fornavn>Trude</fornavn>
                  <etternavn>Nubdal</etternavn>
                  <sivilstand fellesBolig="false" beggeHjemmelshavere="true" gift="true"/>
                </personMedSivilstand>
                <broek teller="1" nevner="1"/>
              </hjemmelshaver>
            </hjemmelshavere>
          <totalBroek teller="1" nevner="1"/>
          </panteobjekt>
        </panteobjekter>
        <pantebeloeper>
          <pantebeloep valuta="NOK" verdi="2400000"/>
        </pantebeloeper>
        <panthavere>
          <panthaverId>985621551</panthaverId>
        </panthavere>
        <dokumentflyt>DOKUMENT_TIL_TINGLYSING</dokumentflyt>
        <refinansiering>false</refinansiering>
      </pantedokument>
      <options xmlns=""/>
    </generatePantedokument>
  </s:Body>
</s:Envelope>

Figure 4: Example total fractions

The picture shows how the borettsandel has added the two new attributes. The teller/nevner shown in the example are not used, and can therefore contain any value.

Validation. Using total fractions will check if the total fraction equals the summed fractions, fetched from Grunnboken, of the hjemmelshaver-list. Also, if owners (hjemmelshaver) do not match the Grunnbok, exceptions will be thrown.

How to handle roles

This feature enables the integrator to generate documents on behalf of another organization. Once added into the request, the document will be generated accordingly unless the validation fails to validate that the respective organisation is defined as rekvirent or panthaver (dokumenteier) in the user profile.

...

Figure 5 Example rekvirent & panthaver

Using Ambita’s signing service

Ambita has a signing service named Esignering. Almost all bank customers have their own signing service they use for signing documents. However, a new feature in Etinglysing allows bank customers to use Ambita’s signing service for signing Pantedokument.

Using the options element sendToCustomerSigning will send the generated document to the specified parties for signing with their BankID (they will receive an email with link to www.esignering.no for signing the document).

Code Block
<options>
...
   <sendToCustomerSigning>true</sendToCustomerSigning>
</options>

Handle signer’s notification in your own system

From version 51.67 (February 2024) it is possible for integrated clients to handle all signing notification and dialogue in their own system. This may require additional configuration of your account in Etinglysing. Contact customer support if you are interested in using this feature

It is now possible to suppress the email notification that is sent from Esignering to all parties that is expected to sign the document. By also setting the option returnCustomerSigningLinks to true the response from generatePantedokument will include an additional signing information object.

Request

Code Block
<options>
...
   <sendToCustomerSigning>true</sendToCustomerSigning>
   <returnCustomerSigningLinks>true</returnCustomerSigningLinks>
</options>

Response

Code Block
<signingInformation>
  <signingLinks>
    <signingLink id="01010122222" signed="false">https://beta.esignering.no/kunde/login/055c018e-79h6-4c75-938g-ac78c1e53832</signingLink>
    <signingLink id="02020233333" signed="false">https://beta.esignering.no/kunde/login/d6s01844-6e63-488c-d396-4617626eff61</signingLink>
  </signingLinks>
</signingInformation>

The id attribute is the social security number (fødselsnummer), signed is the current signing status for that person and the element text is the link for that person to use for signing the document. Integrated clients can now present the link in their own system or be responsible for sharing the links to the parties in their preferred way.

Check signing status

For documentation about how to check the signing status, see Get status signing