Met Mercator 10.10 of later kan een document ter ondertekening naar een klant, leverancier of andere externe bedrijfsrelatie worden gestuurd. Deze verzending ter ondertekening gebeurt via de dienst Ok!Sign. Deze dienst staat los van Mercator, maar Mercator heeft een API die een gemakkelijke interfacing mogelijk maakt. Het is dus noodzakelijk een account te openen bij Ok!Sign en eventueel kredieten te verstrekken.
(Voor een elektronische ondertekening van een PDF ter plaatse: zie deze pagina)
In het Ok!Sign-portaal, moet de API worden geactiveerd door een organisatietoken aan te maken. Zodra dit token is aangemaakt (een willekeurige string met alleen deze tekens [a-zA-Z0-9-]), noteert u de waarde x-oksign-authorization.
Deze waarde moet ook worden ingesteld in CallbackURL : https://restapi.mercator.eu/api/OkSignWebHook. De andere twee URL's kunnen leeg blijven.
Interfacing gebeurt via de API van Mercator, die te vinden is in MercatorTunnel.dll : MercatorSigning.Ok!Sign.
public static OkSignResponse UploadPdfForSignature(string fileName, FormDescriptor formDescriptor, string authorizationHeader, out string error, int timeOutSec = 10, CancellationTokenSource cancellationTokenSource = null)
public static async Task<(OkSignResponse response, string error)> UploadPdfForSignatureAsync(string fileName, FormDescriptor formDescriptor, string authorizationHeader, int timeOutSec = 10)
public static bool Remove(string docId, string authorizationHeader, out string error, int timeOutSec = 10)
public static async Task<(bool result, string error)> RemoveAsync(string docId, string authorizationHeader, int timeOutSec = 10)
public static OkSignResponse.FileInfoDescriptor DocumentExists(string docId, string authorizationHeader, out string error, int timeOutSec = 10)
public static async Task<(OkSignResponse.FileInfoDescriptor result, string error)> DocumentExistsAsync(string docId, string authorizationHeader, int timeOutSec = 10)
public static byte[] DocumentRetrieve(string docId, string authorizationHeader, out string error, int timeOutSec = 10)
public static async Task<(byte[] result, string error)> DocumentRetrieveAsync(string docId, string authorizationHeader, int timeOutSec = 10)
public static DocumentStatusRet DocumentStatus(string docId, string authorizationHeader, out string error, int timeOutSec = 10)
public static async Task<(DocumentStatusRet, string error)> DocumentStatusAsync(string docId, string authorizationHeader, int timeOutSec = 10)
De parameter authorizationHeader moet de waarde x-oksign-authorization bevatten.
Het proces begint altijd met het uploaden van het te ondertekenen document via de methode UploadPdfForSignature of UploadPdfForSignatureAsync. De specifieke parameters die moeten worden doorgegeven zijn
- het PDF-bestand, met het volledige pad. Het kan een pad zijn dat compatibel is met SqlFileView
- FormDescriptor die het handtekeningformulier beschrijft dat aan het PDF-bestand moet worden gekoppeld.
De samenstelling van het ondertekeningsformulier wordt op deze pagina nader toegelicht. Om de samenstelling ervan te vergemakkelijken, stelt de Mercator API de klasse MercatorSigning.OkSign.FormDescriptor.FormHelper ter beschikking. In het onderstaande voorbeeld tonen we hoe we een document ter ondertekening naar twee ondertekenaars kunnen sturen:
- een externe ondertekenaar (de klant)
- een interne ondertekenaar (de afzender) voor wie de automatische medeondertekening is geactiveerd in het Ok!Sign portaal, wiens id bt_0000-0000-0000-000569645580 is (Belangrijk: in het Ok!Sign portaal moet de tekening van de handtekening bestaan en het selectievakje "Mijn handtekening delen met andere gebruikers" moet geactiveerd zijn).
// eerste ondertekenaar = de klant
MercatorSigning.OkSign.FormDescriptor.FormHelper formHelper1 = new MercatorSigning.OkSign.FormDescriptor.FormHelper
{
FieldMarker = "Signature_1",
FieldWidth = 175,
FieldHeight = 70,
FieldSigningOptions = MercatorSigning.OkSign.FormDescriptor.FormHelper.SigningOptionsEnum.Tan | MercatorSigning.OkSign.FormDescriptor.FormHelper.SigningOptionsEnum.Eid | MercatorSigning.OkSign.FormDescriptor.FormHelper.SigningOptionsEnum.Pen | MercatorSigning.OkSign.FormDescriptor.FormHelper.SigningOptionsEnum.Itsme,
SignerInfoName = actionEngine.ActionsRecord.NOM,
SignerInfoMobile = actionEngine.ACTIONS["NUM_GSM"].ToString(),
SignerInfoActingAs = actionEngine.ACTIONS["FONCTION"].ToString(),
SignerInfoEmail = actionEngine.ActionsRecord.EMAIL,
};
// tweede ondertekenaar = automatische medeondertekening geautoriseerd via het OkSign-portaal
MercatorSigning.OkSign.FormDescriptor.FormHelper formHelper2 = new MercatorSigning.OkSign.FormDescriptor.FormHelper
{
FieldMarker = "Signature_2",
FieldWidth = 175,
FieldHeight = 70,
TeamMemberId = "bt_00000000-0000-0000-0000-000569645580"
};
MercatorSigning.OkSign.FormDescriptor formDescriptor = new MercatorSigning.OkSign.FormDescriptor
{
SendToMeEmail = "info@mercator.eu", // niet vereist als het te gebruiken e-mailadres dat van het OkSign-account is.
Logo = "https://www.mercator.eu/assets/images/logo.png", // niet vereist als het te gebruiken logo het logo in het OkSign-account is
FileName = Api.JustFName(fileToSign) // naam van het bestand dat zichtbaar is voor de ondertekenaar. Mag een vrije string bevatten die eindigt op .pdf
};
formDescriptor.FormHelpers.AddRange(formHelper1, formHelper2); // voeg hier eventueel meerdere ondertekenaars toe
MercatorSigning.OkSign.OkSignResponse response = MercatorSigning.OkSign.UploadPdfForSignature(fileToSign, formDescriptor, actionEngine.TagString, out string error);
if (!string.IsNullOrEmpty(error))
{
...;
}
In dit voorbeeld zien we dat elke handtekening wordt ingevoerd in een kader van 70x175 pixels. Deze twee frames worden respectievelijk geplaatst op de plaatsen waar de woorden Signature_1 en Signature_2 staan. Het is mogelijk om de positie van de handtekeningen anders te bepalen, met bijvoorbeeld :
- FieldPageNbr : paginanummer
- FieldPosY : verticale positie
- FieldPosX : horizontale positie
U kan de FormHelper overslaan, en de lijst met Fields en SignersInfo rechtstreeks verstrekken. Merk op dat beide lijsten hetzelfde aantal elementen moeten hebben en gekoppeld moeten zijn via de eigenschappen SignerId = Id. Deze waarde moet voor elke ondertekenaar met 1 worden verhoogd.
FormDescriptor formDescriptor = new FormDescriptor
{
SendToMeEmail = "info@mercator.eu",
FileName = "myinvoice.pdf",
Fields = new List<FormDescriptor.Field>
{
new FormDescriptor.Field
{
Marker = "Signature_1",
InputType = "CanvasSIG",
Name = "SIG_FIELD_1",
Required = true,
Width = 175,
Height = 70,
SignerId = "bt_00000000-0000-0000-0000-000000000001",
SigningOptions = new FormDescriptor.Signingoptions
{
Eid = new FormDescriptor.Eid(),
Pen = new FormDescriptor.Pen(),
Tan = new FormDescriptor.Tan(),
//Itsme = new FormDescriptor.Itsme()
}
}
},
SignersInfo = new List<FormDescriptor.Signersinfo>
{
new FormDescriptor.Signersinfo
{
Name = "Jules Leboss",
Mobile = "+32499799999",
ActingAs = "Administrator",
Id = "bt_00000000-0000-0000-0000-000000000001",
Email = "jules.leboss@company.com"
}
}
};
De methode UploadPdfForSignature stuurt bij succes een MercatorSigning.OkSignResponse terug. De eigenschap Result bevat een lijst met URL's voor handtekeningen die (per e-mail) naar elke ondertekenaar moeten worden verzonden. response.Result[i].Url
Voorbeelden van implementaties
Belangrijke opmerking over de GDPR
PDF-documenten worden geüpload naar de Ok!Sign-servers en blijven daar totdat ze worden verwijderd. Deze bestanden kunnen worden verwijderd
- via de methode Remove of RemoveAsync,
- rechtstreeks in het Ok!Sign portaal.
Deze PDF's kunnen persoonsgegevens bevatten. Bovendien worden e-mailadressen en mobiele telefoonnummers doorgegeven. Daarom is het noodzakelijk Ok!Sign op te nemen in uw GDPR nalevingsstrategie.
Volgens de GDPR is een handtekening een gevoelig persoonsgegeven. Het gebruik en de opslagperiode ervan moeten strikt beperkt zijn en in verhouding staan tot het doel. Deze gevoelige gegevens moeten worden beschermd. Dit alles valt onder de interne procedures van het bedrijf.
Mercator verzamelt geen informatie uit het hier beschreven proces (PDF-inhoud, e-mailadressen, mobiele telefoonnummers, enz.). Geen enkele van deze persoonlijke informatie of gevoelige gegevens passeert via de servers van Mercator.
Het enige doel van de Mercator webhook is om de ID's van de documenten voor en na de ondertekening te vergelijken en het aantal handtekeningen te tellen. Deze anonieme informatie wordt dus bewaard door Mercator:
- accountnbr : eerste deel van x-oksign-authorization
- source doc id : in de vorm van 897215-59BFAC70-6257-1260-F259-6259A18EECE0
- signed doc id : in de vorm van 656858-6072474D-80A0-D54A-4937-4FD639BAE9B6
- aantal verwachte handtekeningen
- aantal verkregen handtekeningen
- datum en tijd van de laatste oproep aan de webhook door de Ok!Sign-servers voor dit document.
Overwegingen betreffende de geldigheid van de handtekeningen
Elektronische handtekeningen vallen onder de regelgeving van eIDAS. Alle door Ok!Sign aangeboden handtekeningmethoden zijn verenigbaar met deze verordening; inclusief PEN- en TAN/SMS-handtekeningen.
Er moet echter altijd, afhankelijk van de wetgeving van de betrokken landen en het soort document dat moet worden ondertekend, worden nagegaan of deze methode van digitale handtekening geldig is.
Ok!Sign is een Belgisch bedrijf. Het biedt niet de mogelijkheid om te ondertekenen met buitenlandse identiteitskaarten of certificaten. Indien nodig is het raadzaam een TAN/SMS-code te gebruiken.
Met Ok!Sign kunt u ondertekenen met andere commerciële certificaten (zoals Isabel, bijvoorbeeld).
OK!Sign gebruikt het Betrust platform voor veilige handtekeningen.
Trefwoorden : OkSign