Osmond identiteitsscans

Met een Osmond-identiteitslezer kun je paspoorten, ID-kaarten en rijbewijzen scannen. De reader stuurt een zip-pakket met o.a. document.xml en pagina-afbeeldingen naar de Tillor-connector op je lokaal netwerk. De connector stuurt dat pakket door naar je Tillor-organisatie, waar het document wordt ingelezen, versleuteld wordt opgeslagen en je als medewerker kunt koppelen aan een klant of contact.

Overzicht van de route

Connector en netwerk

• De connector luistert voor Osmond op poort 8765 (WebSocket). Zie ook Connector voor Docker-poorten en omgevingsvariabelen.
• De reader moet als Host het IP-adres of de hostnaam van de machine met de connector kunnen bereiken (niet localhost vanaf een ander toestel). In de connector-log staat een hint met een LAN-IP en waar zip-bestanden tijdelijk worden weggeschreven.
• Doorsturen naar Tillor gebeurt alleen als TILLOR_API_URL, TILLOR_API_TOKEN en TILLOR_ORG_ID zijn ingesteld. Dan POST de connector het zip-bestand base64-gecodeerd naar je organisatie-endpoint. De aanvraag bevat de header X-Tillor-Connector zodat alleen de connector deze upload mag gebruiken.
• Als de API-URL of het token ontbreekt, start de WebSocket-server wel, maar wordt er niet naar Tillor doorgestuurd.
• Eén upload mag het zip-pakket niet groter zijn dan ongeveer 25 MB ruw zip; grotere pakketten worden aan de serverzijde geweigerd.

Wat Tillor doet met het pakket

Na ontvangst wordt het zip-bestand uitgepakt, rasterbeelden zo nodig naar JPEG genormaliseerd, en door de Osmond-parser verwerkt (document.xml, chip- en MRZ-gegevens waar aanwezig). Tillor slaat onder andere op:

• een scanrecord met documenttype, naamgegevens, nationaliteit, geboortedatum, document- en persoonsnummers, enz. waar beschikbaar;
• het originele connector-zip en elk overig bestand uit het pakket per stuk versleuteld in organisatie-opslag; pagina-afbeeldingen van het document krijgen vóór versleuteling een semi-transparante, herhaalde watermark met de Engelse tekst Not valid as ID, zodat een gelekte afbeelding duidelijker niet bedoeld is als officiële legitimatie; het portret (uitgesneden op basis van Osmond-geometrie) en het losse chip-/portretbestand uit het zipbestand laten Tillor daarbij ongemarkeerd (de Engelse zin gebruiken we vooral op de documentpagina, omdat documenten veel talen gebruiken);
• waar mogelijk een afgeleid portret voor weergave en export.

Gebonden scans (en suggesties) worden daarna ververst via dezelfde realtime-kanalen.

Nieuwe klant of contact in de app

• Nieuwe klant (en Nieuw contact op Klanten > Contacten): zolang er geschikte openstaande scans zijn, heeft de knop een dropdown. Kies Manueel om het dialoog met het gewone formulier te openen, of kies direct een scan in de lijst eronder. Na het kiezen van een scan opent eerst dezelfde bevestigingsdialog als bij het koppelen (raster, MRZ-gegevens, Annuleren / Klant aanmaken of Contact aanmaken). Bij Nieuwe klant is dat dezelfde actie als Klant aanmaken op basis van scan op de dockkaart (modules.identityDocumentScans.overlay.actionCreateCustomer). Zijn er geen geschikte scans, dan is het weer een enkele knop die alleen het handmatige dialoog opent.
• Bij Nieuw contact staan in de dropdown alleen scans die nog geen contact hebben en minstens een voornaam hebben. Een scan die alleen bij de klant als identiteit hoort, zit niet in deze wachtrij - die hoort daar niet dubbel gekoppeld te worden naar een contact.
• In Reservering starten: wanneer je een nieuwe klant wilt aanmaken boven aan de reservering, verschijnt dezelfde dropdown (Manueel, daarna de geschikte scans) zolang openstaande scans bestaan.
• Waar je op het klant- of contactprofiel een gestippelde kaart gebruikt om een openstaande scan te koppelen: na kiezen uit de lijst verschijnt een bevestigingsdialog. Daarin vind je naam en documenttype, nationaliteit, geboortedatum, persoonlijk nr. en documentnr. (als die bekend zijn), een raster voorbeeld met tabs zoals bij het kleine icoon onder Identiteit geverifieerd (voorzijde, achterzijde, portret indien beschikbaar), plus Annuleren en Scan koppelen.

Waar je de scan in de app ziet

Activiteiten onderaan rechts

Zolang er scans zonder gekoppelde klant zijn, verschijnen ze in het dock rechtsonder (dezelfde plek als actieve telefoongesprekken). Op kleine schermen is er een zwevende knop om het paneel te openen.

• Aria-label voor het paneel komt overeen met Openstaande identiteitsdocument-scans en actieve telefoongesprekken (modules.identityDocumentScans.overlay.dockAriaLabel).
• Elke kaart toont naam- en MRZ-gegevens, raster en Klant aanmaken op basis van scan (modules.identityDocumentScans.overlay.actionCreateCustomer). Om een scan aan een bestaande klant of een contact te koppelen ga je naar Klanten en gebruik je de gestippelde scan koppelen-prompt op het klant- of contactprofiel.

Klantprofiel

• Onder Klantgegevens op de klantpagina verschijnen gekoppelde scans die alleen bij de klant horen (niet bij een specifiek contact).
• Als er openstaande scans zijn en deze klant nog geen dergelijke scan heeft, verschijnt een gestippelde kaart: je kunt direct een pending scan aan deze klant koppelen (zonder alleen het dock rechtsonder te gebruiken).
• In de klantheader kan een badge tonen dat een identiteitsdocument gekoppeld is (Identiteit geverifieerd, of waarschuwing bij bijna verlopen of verlopen document).

Contactpersonen

• Elke contactkaart toont eventueel gekoppelde scans voor dat contact.
• Heeft een contact nog geen eigen scan, dan verschijnt (als er geschikte openstaande scans zijn) op die kaart een gestippelde prompt om daar één aan dit contact te koppelen.

API voor integrators

Je kunt optioneel identityDocumentScanId meesturen bij klant aanmaken (POST /customers) of contact aanmaken (POST /contacts). Tillor koppelt de identity document-scan dan in dezelfde database-transactie aan de nieuwe klant of het nieuwe contact. Bij klant-create moet de scan nog geen klant hebben; bij contact-create mag de scan al aan dezelfde customerId hangen, maar nog niet aan een ander contact. Details staan in de OpenAPI-specificatie.

Workflow: scan koppelen

• Tillor kan exacte naam-matches voor klanten en contacten tonen bij de kop van de dockkaart.
• Als een geldig document al een bestaande klant met hetzelfde rijksregisternummer heeft, blijft de suggestie zichtbaar maar staat Klant aanmaken op basis van scan uit; de uitleg staat onder customerActionsDisabledByNationalIdMatch in de vertalingen.
• Nieuwe klant vereist minimaal een voornaam in de scan; zonder voornaam staat aanmaken uitgeschakeld met de bijbehorende hint.

Na het koppelen: welke gegevens worden overgenomen

Na koppeling vult Tillor waar mogelijk de klant of het contact aan met gegevens uit de opgeslagen scan (voornaam, achternaam, geboortedatum, adresregel, postcode, gemeente, staat of provincie, land, geboorteplaats, persoonlijk nummer, voorkeurstaal). Voor contacten worden velden die niet op het contactmodel bestaan (zoals aparte postcode/kolom stad) niet weggeschreven; de rest wel.

PDF exporteren en archief downloaden

• Gekoppelde scans ondersteunen PDF-samenvatting exporteren en versleuteld archief downloaden (AES-256; aantallen staan in de UI).
• Onder Instellingen in de organisatie-instellingendialoog kun je Identiteitsdocument automatisch printen bij koppeling inschakelen. Dat vereist PDF-afdrukken en een geconfigureerd PDF-printer-IP. Labelteksten komen uit modules.organizationSettings.

Ondersteunde documenttypen in de UI

In Tillor worden documenten onder meer getoond als ID-kaart, Paspoort, Rijbewijs of Document wanneer het type niet zeker is (modules.identityDocumentScans.documentKind).

Problemen oplossen

1. Geen scan in Tillor - Controleer of de reader het juiste IP/poort 8765 van de connector gebruikt, of de connector TILLOR_API_URL en TILLOR_API_TOKEN heeft, en of de connectorlogs geen uploadfout tonen.
2. Scan verschijnt niet in het dock - Alleen scans zonder gekoppelde klant worden in die lijst getoond; reeds gekoppelde scans vind je op het klant- of contactprofiel.
3. Kan geen klant aanmaken uit scan - Controleer of de scan een voornaam bevat; zo niet, vul die op de reader bij of koppel handmatig.
4. Grote of trage uploads - Houd zip-grootte en netwerk in de gaten; bij fouten na twee minuten opnieuw proberen of pakket verkleinen.