Referință API

Reguli de gestionare a erorilor

Pentru erorile rezultate din invocările interfeței SOAP, MSign returnează SOAP faults cu coduri de eroare (fault codes) și motive ale erorii (fault reasons) care descriu eroarea în limbaj clar. Dacă MSign nu returnează niciun SOAP fault, consumatorul serviciului ar trebui să considere că rezultatul operației returnat, conform contractului serviciului MSign, este valid și poate fi utilizat direct, fără verificări suplimentare de eroare.

Rețineți că un SignResponse conține SignStatus, care poate avea valorile Pending, Failure sau Expired, ceea ce înseamnă că nu sunt returnate rezultate de semnare (Results).

Cod eroare	Descriere
AuthenticationFailed	Procesul de autentificare a consumatorului serviciului a eșuat. Vezi Autentificare
AuthorizationFailed	Procesul de autorizare a consumatorului serviciului a eșuat. Vezi Autorizare
InvalidParameter	Un parametru de intrare este invalid. Consultați textul returnat în Fault Reason și descrierea operației apelate.
RequestNotFound	requestID furnizat la apelarea GetSignResponse nu a fost găsit de MSign. Poate fi incorect sau expirat (adică eliminat din baza de date online).

Pentru consumatorii care utilizează limbaje de programare ce suportă blocuri try…catch, capturarea excepțiilor specifice framework-ului pentru SOAP Fault este modalitatea corectă de a gestiona erorile de invocare a serviciului.

Operațiile serviciului

PostSignRequest

Semnătură	PostSignRequest(request: SignRequest): string
Descriere	Trimite o cerere de semnătură pentru semnare ulterioară.
Returnează	Un string reprezentând ID-ul cererii, care poate fi utilizat ulterior cu GetSignResponse.

Parametri de intrare

Nume	Tip	Descriere
request	SignRequest	O structură reprezentând cererea de semnătură.

Erori

Cod	Motiv
AuthenticationFailed	Certificat de autentificare furnizat invalid, consumator de serviciu necunoscut: {numărul de serie al certificatului}
InvalidParameter	Un parametru de intrare este invalid. Consultați textul returnat în Fault Reason și descrierea operației apelate.

GetSignResponse

Semnătură	GetSignResponse(requestID: string, language: string): SignResponse
Descriere	Obține statusul și rezultatul cererii de semnătură aferente.
Returnează	O structură care conține statusul și rezultatele semnăturii.

Parametri de intrare

Nume	Tip	Descriere
requestID	string	ID-ul SignRequest-ului trimis anterior prin operația PostSignRequest.
language	string	Limba utilizată pentru localizarea răspunsului. Valori permise: „ro”, „ru”, „en”. Pentru compatibilitate retroactivă, acest parametru este opțional, iar valoarea implicită este „ro”.

Erori

Cod	Motiv
AuthenticationFailed	Certificat de autentificare furnizat invalid, sistem necunoscut sau neînregistrat: {numărul de serie al certificatului}
AuthorizationFailed	Această cerere de semnătură nu a fost inițiată de acest sistem
InvalidParameter	Un parametru de intrare este invalid. Consultați textul returnat în Fault Reason și descrierea operației apelate
RequestNotFound	Nu se poate găsi o astfel de cerere

VerifySignatures

Semnătură	VerifySignatures(request: VerificationRequest): VerificationResponse
Descriere	Solicită verificarea semnăturii. Având în vedere că procesul de verificare poate dura mai mult decât se așteaptă, se recomandă invocarea acestei operații în mod asincron, astfel încât aplicația apelantă să nu pară blocată.
Returnează	O structură care conține rezultatul verificării semnăturii.

Parametri de intrare

Nume	Tip	Descriere
request	VerificationRequest	O structură reprezentând cererea de verificare.

Erori

Cod	Motiv
AuthenticationFailed	Certificat de autentificare furnizat invalid sau consumator de serviciu necunoscut: {numărul de serie al certificatului}
InvalidParameter	Un parametru de intrare este invalid. Consultați textul returnat în Fault Reason și descrierea operației apelate.
RequestNotFound	Nu se poate găsi o astfel de cerere

Structuri

Important. Ordinea în care sunt descriși membrii mai jos este doar în scop descriptiv. Ordinea elementelor în structurile XML efective, definite în WSDL, este alfabetică. Pentru a obține o implementare corectă, se recomandă utilizarea unui instrument de conversie automată din WSDL în limbajul sau mediul dumneavoastră de programare.

Membru	Tip	Obligatoriu/Opțional	Descriere
SignRequest
ContentDescription	string (512)	Opțional, implicit: identic cu ShortContentDescription	Descrierea conținutului de semnat. Afișată de paginile web MSign.
ShortContentDescription	string (90)	Obligatoriu	Descrierea scurtă a conținutului de semnat. Afișată pe telefonul mobil dacă se utilizează Semnătura Mobilă.
SignatureReason	string (255)	Opțional	Motivul semnăturii, de ex. Rezoluție, Aprobat, Revizuit etc. În prezent, aplicabil doar pentru PDF.
ContentType	enumerare ContentType	Obligatoriu	Tipul conținutului de semnat.
Contents	Array de SignContent	Obligatoriu, cel puțin un element	Lotul efectiv de conținuturi de semnat.
ExpectedSigner	ExpectedSigner	Opțional	Dacă este furnizat, MSign va verifica dacă semnatarul efectiv corespunde informațiilor furnizate.
SignResponse
Status	enumerare SignStatus	Obligatoriu	Statusul cererii de semnătură
Message	string (100)	Opțional, returnat pentru cererile cu status Failure sau Expired	Mesajul de eșec al cererii de semnătură, localizat conform parametrului language.
Results	Array de SignResult	Disponibil când Status nu este Pending	Rezultatele semnăturii pentru cererea de semnătură solicitată.
VerificationRequest
SignedContentType	enumerare ContentType	Obligatoriu	Tipul conținutului care a fost semnat anterior.
Language	string (2)	Opțional, implicit: ro	Limba utilizată pentru localizarea răspunsului. Valori permise: „ro”, „ru”, „en”
Contents	Array de VerificationContent	Obligatoriu, cel puțin un element	Lotul efectiv de semnături de verificat.
VerificationResponse
Results	Array de VerificationResult	Obligatoriu	Rezultatele verificării pentru cererea de verificare.
SignRequest
CorrelationID	string (36)	Opțional	ID-ul de corelare pentru acest conținut. Trebuie să fie unic în cadrul unei cereri de semnătură.
MultipleSignatures	Bool	Opțional, implicit: false	Specifică dacă conținutul poate avea mai multe semnături (adică poate fi cosemnat). În prezent, această setare se aplică doar pentru PDF.
Name	string (256)	Opțional	Numele fișierului PDF; pentru Hash, această proprietate este redundantă.
Content	Array de byte	Obligatoriu	Conținutul efectiv de semnat. În prezent, acesta poate fi un hash SHA1 de 20 de byte-i sau un fișier PDF.
ExpectedSigner
ID	String	Obligatoriu	Numărul de identificare personal al semnatarului așteptat. Rețineți că, dacă nu este furnizat, utilizatorului i se va cere să îl introducă la semnarea PDF-ului prin semnătură mobilă.
DelegatorType	enumerare DelegatorType	Opțional, implicit: None	Tipul delegatorului.
DelegatorID	String	Obligatoriu când DelegatorType nu este None	Identificatorul persoanei sau organizației pe care semnatarul așteptat o poate reprezenta (de care este delegat).
DelegatedRoleID	Int	Opțional, implicit: 0	Rolul semnatarului așteptat în relație cu delegatorul.
SignResult
CorrelationID	string (36)	Returnat ca în SignContent	ID-ul de corelare pentru conținutul semnat, așa cum a fost furnizat inițial în SignContent.
Certificate	Array de byte	Opțional, prezent dacă semnarea a reușit	Certificatul semnatarului în format X509 v3.
Signature	Array de byte	Opțional, prezent dacă semnarea a reușit	Pentru tipul de conținut hash, aceasta este semnătura electronică efectivă în format XAdES-T; pentru tipul de conținut PDF — documentul PDF semnat.
VerificationContent
CorrelationID	string (36)	Opțional	ID-ul de corelare pentru acest conținut. Trebuie să fie unic în cadrul unei cereri de verificare.
Content	Array de byte	Obligatoriu doar pentru conținut de tip Hash.	Hash-ul care a fost semnat inițial. Rețineți că acest parametru este obligatoriu doar pentru verificarea semnăturilor de tip hash. Valoarea sa este necesară pentru verificarea completă a semnăturii.
Signature	Array de byte	Obligatoriu	Semnătura efectivă de verificat. Aceasta trebuie să fie un XAdES sau un PDF semnat.
VerificationResult
CorrelationID	string (36)	Returnat ca în VerificationContent	ID-ul de corelare pentru conținutul de verificare, așa cum a fost furnizat inițial în VerificationContent.
SignaturesValid	Bool	Obligatoriu	Returnat ca true dacă toate semnăturile aplicate conținutului sunt valide.
Message	string (100)	Obligatoriu	Mesajul rezultatului verificării, localizat conform VerificationRequest.Language.
Certificates	Array de VerificationCertificate	Opțional, prezent dacă au fost identificate certificate în semnătură	Lista certificatelor (câte unul pentru fiecare hash semnat, în cazul XAdES) semnatarilor. Returnată în scop de afișare.
VerificationCertificate
SignatureValid	Bool	Obligatoriu	Returnat ca true dacă semnătura corespunzătoare acestui certificat este validă.
Subject	string (250)	Obligatoriu	Detaliile subiectului din certificat. Returnate ca facilitate pentru afișare.
Certificate	Array de byte	Obligatoriu	Certificatul semnatarului în format X509 v3.
SignedAt	Datetime	Opțional	Data și ora semnăturii. Returnată doar dacă a fost aplicată o marcă temporală (timestamp) validă.

Enumerări

Membru	Descriere
ContentType
Hash	Conținutul de semnat este un hash SHA1.
Pdf	Conținutul de semnat este un fișier PDF.
DelegatorType
None	Nu există delegator.
Person	Delegatorul este o persoană.
Organization	Delegatorul este o organizație.
SignStatus
Pending	Semnarea este în curs.
Success	Semnarea s-a finalizat, iar semnătura este validă.
Failure	Semnarea a eșuat. Cererea de semnătură este acum invalidă.
Expired	Cererea de semnătură a expirat. Cererea de semnătură este acum invalidă.

Integrarea prin formulare web

Cererea de semnare

Metodă	POST (recomandat) sau GET
URL	https://msign.gov.md/{requestID}
Descriere	Direcționează utilizatorul pentru a efectua semnarea propriu-zisă. Observați că requestID este integrat în URL-ul metodei

Parametri de formular sau URL

Nume	Tip	Obligatoriu/Opțional	Descriere
ReturnUrl	string	Obligatoriu	URL-ul care va primi rezultatul semnării tranzacției
Instrument	string	Opțional și nerecomandat	Instrumentul de semnare de utilizat, adică omiterea paginii de selectare a instrumentului de semnare. Valori permise: „mobile”, „moldsign”, „nationalid”, „securesign”, „tax”. Rețineți că, pentru ca instrumentul „mobile” să funcționeze fără selectarea instrumentului, trebuie să furnizați MSISDN și ExpectedSigner.ID ale semnatarului așteptat.
MSISDN	string conținând cifre	Opțional	Numărul de telefon mobil al semnatarului așteptat, dacă este cunoscut
RelayState	string	Opțional	String opțional care va fi returnat nemodificat după semnare
lang	string	Opțional	Limba utilizată de interfața utilizator MSign. Valori permise: „ro”, „ru”, „en”

Callback-ul de semnare

Metodă	POST
URL	ReturnUrl-ul furnizat în cererea de semnare
Descriere	Redirecționează utilizatorul către sistemul informațional care a solicitat semnătura, informând totodată sistemul despre finalizarea procesării SignRequest-ului. Acest URL este deschis doar după ce rezultatul semnării este cunoscut (adică SignStatus este fie Failure, fie Success).

Parametri de formular

Nume	Tip	Obligatoriu/Opțional	Descriere
RequestID	string	Obligatoriu	ID-ul SignRequest-ului finalizat
RelayState	string	Opțional și nerecomandat	Valoarea nemodificată a RelayState, așa cum a fost trimisă în cerere

Exemple de mesaje SOAP

Implementare manuală

Vom prezenta aici exemple de mesaje SOAP schimbate. Acestea pot fi utile celor care se integrează cu MSign, dar nu suportă complet generarea proxy-ului de serviciu bazat pe WSDL.

Metoda: PostSignRequest

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/PostSignRequest</Action>
  </s:Header>
  <s:Body>
    <PostSignRequest xmlns="https://msign.gov.md">
      <request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ContentDescription>Sample long description</ContentDescription>
        <ContentType>Hash</ContentType>
        <Contents>
          <SignContent>
            <Content>ZhKVycv51rL2QoQUUEqN7tMCBkE=</Content>
            <CorrelationID>3408cc344e474a529f3425176a75d08e</CorrelationID>
          </SignContent>
        </Contents>
        <ShortContentDescription>MSign Sample.</ShortContentDescription>
      </request>
    </PostSignRequest>
  </s:Body>
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <PostSignRequestResponse xmlns="https://msign.gov.md">
      <PostSignRequestResult>eec7709d372b41109e2ea3e200e99727</PostSignRequestResult>
    </PostSignRequestResponse>
  </s:Body>
</s:Envelope>

Metoda: GetSignResponse

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/GetSignResponse</Action>
  </s:Header>
  <s:Body>
    <GetSignResponse xmlns="https://msign.gov.md">
      <requestID>eec7709d372b41109e2ea3e200e99727</requestID>
      <language>en</language> 
    </GetSignResponse> 
  </s:Body> 
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetSignResponseResponse xmlns="https://msign.gov.md">
      <GetSignResponseResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Results>
          <SignResult>
            <Certificate>MIIG… </Certificate>
            <CorrelationID>3408cc344e474a529f3425176a75d08e</CorrelationID>
            <Signature>PD94… </Signature>
          </SignResult>
        </Results>
        <Status>Success</Status>
      </GetSignResponseResult>
    </GetSignResponseResponse>
  </s:Body>
</s:Envelope>

Metoda: VerifySignatures

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/VerifySignatures</Action>
  </s:Header>
  <s:Body>
    <VerifySignatures xmlns="https://msign.gov.md">
      <request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Contents>
          <VerificationContent>
            <Content>ZhKVycv51rL2QoQUUEqN7tMCBkE=</Content>
            <CorrelationID>bd73ed7eabc44ab290b18181a9e7fd2b</CorrelationID>
            <Signature>PD94… </Signature>
          </VerificationContent>
        </Contents>
        <Language>en</Language>
        <SignedContentType>Hash</SignedContentType>
      </request>
    </VerifySignatures>
  </s:Body>
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <VerifySignaturesResponse xmlns="https://msign.gov.md">
      <VerifySignaturesResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Results>
          <VerificationResult>
            <Certificates>
              <VerificationCertificate>
                <Certificate>MIIG… </Certificate>
                <SignatureValid>true</SignatureValid>
                <Subject>O=Centrul de Guvernare Electronică (e-government) 1010600034203, OU=IT, C=MD, PostalCode=MD-2033, T=Functia, STREET=Piața Marii Adunări Naționale 1, Phone=022250234, S=Republica Moldova, L=Chișinău, SERIALNUMBER=IDNP, CN=Nume Prenume</Subject>
              </VerificationCertificate>
            </Certificates>
            <CorrelationID>bd73ed7eabc44ab290b18181a9e7fd2b</CorrelationID>
            <Message>The signature is valid</Message>
            <SignaturesValid>true</SignaturesValid>
          </VerificationResult>
        </Results>
      </VerifySignaturesResult>
    </VerifySignaturesResponse>
  </s:Body>
</s:Envelope>