Autenti | API

This document describes how to use Autenti API v1 to send a document and check its status:

Authorize (in: clientId and clientSecret – parameters from company account settings (API tab); out: access_token and identity_id).
Create new document (in: access_token and identity_id from previous step + document description, receivers and viewers; out: documentId).
Upload file to the document (in: access_token, identity_id and documentId from previous step + binary PDF file).
Send the document and SMS (in: access_token, identity_id and documentId).
Check document status and download (in: access_token, identityId, documentId; out: document status and URL). Push notifications to callback URL are also available.
Send a reminder.
Withdraw / Cancel.

Before you start coding:

Login to app.autenti.com using your company account (administrative privileges required), go to “Account settings” à “API” and click “Generate API access”.
Copy client id and secret.
Select a person that represents the company. That person will be shown as the person signing the document on behalf of the company. That persons’ e-mail must be used in both methods (/oauth/token – email and /documents/add/ – sender_email).

API URL – v1	https://app.autenti.eu
TLS version	1.2

Good practices:

REST API is based on the HTTP protocol. Each API call returns a status which may be a success („200 OK”) or a failure (almost anything else). The client should always check the status and proceed to the next step only after successful call. The call should be retried after failed response (status code 4xx or 5xx) and after timed out.
If you receive “401 Unauthorized” response it means that the token has expired and you must authorize again and retry the request with a new access_token.
If you execute many requests please authorize only once per email/identity until a token will expire.
There may be errors if you will operate on the same document simultaneously in many sessions.
Check size of the response, if you get an empty response (0 bytes) please retry the request.

Go to API settings in web application and click „Generate API” to get clientId and clientSecret:

URI	/oauth/token
method	POST
headers	Content-Type: application/x-www-form-urlencoded User-Agent: any
payload	client_id={clientId}&client_secret={clientSecret} &grant_type=company_key&[email protected]
response	200 OK { access_token : ‘3f2c097c-xxxx-4b58-9c7c-ab399c5d8254’, token_type : ‘bearer’, refresh_token : ‘42e3244f-xxxx-44c1-8593-74140cbca0a8’, expires_in : ‘43199’, identity_id : ‘xxx’ }
example	curl -X POST -H „Content-Type: application/x-www-form-urlencoded” -d ‚client_id={clientId}&client_secret={clientSecret} &grant_type=company_key&[email protected]’ https://app.autenti.eu/oauth/token
note	This method returns access_token and identity_id which are used in next steps. email – (optional) if there is more than one email allowed in account settings for using API than it must be provided which one will be used for the authentication (it affects returned identity_id), email address should be urlescaped (e.g. “+” character) All parameters should be sent as POST data (payload), not GET.

URI	/api/identities/{identityId}/documents/add
method	POST
headers	Authorization: Bearer {access_token} Content-Type: application/json; charset=UTF-8
payload	{ ‘title’ : ‘Document title’, ‘message’ : ‘Test message’, ‘status’ : ‘NEW’, ‘sender_email’ : ‘[email protected]’, ‘receivers’ : [ { ‘email’ : ‘[email protected]’, ‘phone_number’ : ‘600400300’, ‘user_first_name’ : ‘John’, ‘user_last_name’ : ‘Doe’, ‘company_name’ : ‘‘, ‘company_nip’ : ‘‘, ‘company_country’ : ‘PL’, ‘with_company’ : false } ], ‘viewers’ : [ { ‘email’ : ‘[email protected]’ } ] }
response	200 OK { ’id’ : ‘123’ //this is documentId }
note	This method creates a new document and returns its id. Files are attached in next step. Attributes: sender_email – it must match with email used in /oauth/token method or if there is only one email allowed in account settings for using API it must match with that email receivers – array of one or more signatories viewers – array of one or more observers phone_number – 9 digits (only polish mobile numbers), necessary with requireSmsCode=true in /start method company_name* and company_nip – necessary with option with_company set to true company_country** – 2 letter country code (e.g. PL) * if with_company=true and company_name is null and company_nip is provided, then application will try to search Autenti database for the company name if company_country** is null or is set to ”PL” than company_nip must be valid polish NIP, for other countries NIP is not validated
errors	{ „errors” : [ { „recipient”:”[email protected]”, „type”:”WRONG_NIP”, „value”:”1234123412″ }, { „recipient”:”from+fake_company_user_autenti.com”, „type”:”WRONG_EMAIL”, „value”:”from+fake_company_user_ autenti.com” }, { „recipient”:”[email protected]”, „type”:”EMPTY_COMPANY_NAME”, „value”:”” }, { „recipient”:”[email protected]”, „type”:”EMPTY_COMPANY_NIP”, „value”:”” }, { „recipient”:”[email protected]”, „type”:”INVALID_COMPANY_COUNTRY_CODE”, „value”:”EN” } ], „exception”:”InvalidDocumentRecipientException”, „error”:null }

URI	/api/identities/{identityId}/documents/{documentId}/upload-file
method	POST
headers	Authorization: Bearer {access_token} Content-Type: multipart/form-data; boundary=BOUNDARY Content-Length: {PDF_DATA_LENGTH}
payload	–BOUNDARY Content-Disposition: form-data; name=Filename; filename=”Filename.pdf” Content-Type: application/pdf ………………………………….PDF_BINARY_DATA………………………… –BOUNDARY–
response	200 OK
example	var headers = { ‚Authorization’ : ‚Bearer ‚ + access_token }; var boundary = ‚MYBOUNDARY’; var requestBody = Utilities.newBlob(‚–‚ + boundary + “\r\n” + ‚Content-Disposition: form-data; name=Filename; filename=”Filename.pdf”’ + “\r\n” + ‚Content-Type: application/pdf’ + “\r\n\r\n”).getBytes(); requestBody = requestBody.concat(PDF_DATA); requestBody = requestBody.concat(Utilities.newBlob(“\r\n“ + boundary + “–\r\n”).getBytes()); var options = { ‚method’ : ‚POST’, ‚contentType’ : ‚multipart/form-data; boundary=’ + boundary, ‚headers’ : headers, ‚payload’ : requestBody, ‚ContentLength’ : PDF_DATA_LENGTH }; UrlFetchApp.fetch(url + ‚/api/identities/’ + identity_id + ‚/documents/’ + document_id + ‚/upload-file’, options);
note	Max. file size: 10MB PDF_DATA – binary content of the PDF file PDF_DATA_LENGHT – size of the PDF file Please don’t send “Expect” header (or set it empty).

URI	/api/identities/{identityId}/documents/{documentId}/start
method	POST
headers	Authorization: Bearer {access_token} Content-Type: application/json; charset=UTF-8
payload	{ ‘senderAutosign’ : false, ‘requireSmsCode’ : false, ‘redirectUrl’ : ‘https://xxx’ }
response	200 OK
note	It sends URL to the document by email to receivers and viewers. senderAutosign – (optional) if set true than the document will be automatically signed by the identity with sender_email = email (it requires providing email in /oauth/token and the same sender_email in /documents/add) – using this option requires Autenti permit and additional formal declarations to Autenti from the client requireSmsCode – (optional) if set true receivers get also SMS with PIN code necessary to sign the document and phone_number is required in /documents/add method redirectUrl – (optional) redirects user after signature to provided URL (it should be urlescaped), the URL may contain the following variables: $firstName$, $lastName$, $email$, $phone$, $documentId$ redirectLastSignerOnly – (optional, default true), if set false redirects all signing users, not only the last one

Get one document:

URI	/api/identities/{identityId}/documents/{documentId}
method	GET
headers	Authorization: Bearer {access_token} Content-Type: application/json; charset=UTF-8
payload	–
response	200 OK { „status” : „ACCEPTED”, „files” : [ { extension=pdf, filename=xxx, file_type=DOCUMENT_SIGNED, id=xxx, href=https://app.autenti.eu/api/download/XXX, hash=XXX } ], „sender_identities”: [ ], „receivers”: [ ] }
note	Statuses: NEW, PROCESSING, CANCELED, REJECTED, TERMINATED, ACCEPTED. File types: DOCUMENT_PART (source files), DOCUMENT_MERGED_SOURCES, DOCUMENT_CERTIFICATE, DOCUMENT_SIGNED (this one if the final signed document). Only when the status is ACCEPTED, this method returns also URL to signed document (file_type: DOCUMENT_SIGNED). To download the document, it is also necessary to include in a header valid access token: “Authorization: Bearer {access_token}”.

Get a list of documents:

URI	/api/identities/{identityId}/documents? documentIds={documentId1,documentId2,documentIdX…}
method	GET
headers	Authorization: Bearer {access_token} Content-Type: application/json; charset=UTF-8
payload	–
response	200 OK { „count”:4, „list”:[ { „id”:2001, „title”:”Document one”, „message”:null, „status”:”ACCEPTED”, „files”:[ { „id”:3001, „filename”:”2016-11-10-Some-document.pdf”, „hash”:”xxxxxx-xxx-xxx-xxx-xxx”, „extension”:”pdf”, „href”:”https://app.autenti.eu/api/download/xxxxxxxxxxxx”, „mime_type”:”application/pdf”, „file_type”:”DOCUMENT_SIGNED” }, … ], „person”:{ „name”:”John”, „surname”:”Doe” }, „created_date”:”2016-11-10T22:28:32.357+0100″, „sender_identities”:[ … ], „sender_email”:”[email protected]”, „viewers”:[ { … } ], „receivers”:[ { … } ] }, { … } // subsequent documents ] }
note	The method is like the single document version (a) but returns a list.
example	curl -X GET -H „Content-Type: application/x-www-form-urlencoded” -H „Authorization: Bearer xxxxxx-xxx-xxx-xxx-xxx” https://app.autenti.eu/api/identities/{identityId}/documents?documentIds= 2001,2002,2003,2004

To setup push notifications go to API settings in web application and enter callback URL:

method	POST
body	{ „id”:83112, „status”:”ACCEPTED”, „end_date”:”2018-07-26T14:47:53+0200″ }
note	JSON notification is sent in request body, its format is identical like in the method for checking document status. If there is “?json=” parameter in notification URL, JSON data will be additionally provided in request params of URL (urlencoded).

URI	/api/identities/{identityId}/documents/{documentId}/remind
method	POST
headers	Authorization: Bearer {access_token}
payload	[email protected]
response	200 OK
example	curl -X POST -H „Authorization: Bearer 6e7871f7-xxxx-481e-84ec-894d19bb7871” https://app.autenti.eu/api/identities/33/documents/250 /remind?email=john%[email protected]
Note	email – must be urlescaped

URI	/api/identities/{identityId}/documents/{documentId}/cancel
method	POST
headers	Authorization: Bearer {access_token}
response	200 OK { „response” : „Document id: ” + id + ” cancelled.” }
note	The method is available only for the sender of a document and only for documents in PROCESSING state (it is not available for ACCEPTED).

Niniejszy Regulamin (dalej: „Regulamin”) określa zasady i warunki korzystania z usługi „Autenti API”, świadczonej drogą elektroniczną przez jej Administratora na rzecz Partnerów Autenti, umożliwiającej zdalny dostęp do Platformy Autenti za pomocą zewnętrznych systemów teleinformatycznych, w celu rynkowego rozwoju praktycznych zastosowań podpisu elektronicznego oraz elektronicznej wymiany danych i obiegu dokumentów. Korzystanie z Autenti API możliwe jest jedynie w przypadku akceptacji niniejszego Regulaminu.

I. Definicje

Terminy uzyte w Regulaminie oznaczają:

Administrator – Autenti sp. z o.o. z siedzibą w Poznaniu przy ul. Św. Marcin 29/8, 61-806 Poznań, wpisana do rejestru przedsiębiorców prowadzonego przez Sąd Rejonowy Poznań Nowe Miasto i Wilda w Poznaniu VIII Wydział Gospodarczy Krajowego Rejestru Sądowego pod nr KRS 0000436998, posiadająca NIP 783-169-32-51 oraz kapitał zakładowy w wysokości 2 583 800,00 zł złotych.
Autenti API – usługa świadczona w modelu Software as a Service (tzw. SaaS) przez Administratora dla Partnerów Autenti, umożliwiająca korzystanie z interfejsu dostępowego, wykorzystującego protokół elektronicznej wymiany danych w standardzie JSON, umożliwiający komunikację Oprogramowania z zasobami (modułami) Platformy Autenti.
Platforma Autenti – usługa świadczona drogą elektroniczną przez Administratora w ramach serwisu internetowego udostępnianego pod nazwą „Autenti”, zgodnie z Regulaminem Platformy Autenti.
Regulamin Platformy Autenti – regulamin świadczenia usług drogą elektroniczną, regulujący korzystanie z Platformy Autenti, którego treść dostępna jest na stronie internetowej po adresem https://autenti.com/regulamin/ .
Partner Autenti – przedsiębiorca, który w wyniku zastosowania się do procedur wydawania przez Administratora kluczy autoryzujących dostęp do Autenti API, otrzymał Zestaw Danych Autoryzacyjnych, służących do autoryzacji czynności dokonywanych w Platformie Autenti w sposób zdalny (z pominięciem interfejsu użytkownika aplikacji Autenti).
Serwis wykorzystujący Autenti API – serwis internetowy będąca w posiadaniu, bądź zarządzany przez Partnera Autenti, który dokonuje połączenia z Autenti API.
Oprogramowanie – oprogramowanie będące we władaniu Partnera Autenti, które wykorzystuje Autenti API.
Zestaw Danych Autoryzacyjnych – ustanowiony na rzecz Partnera Autenti indywidualny identyfikator (id) oraz hasło (secret) umożliwiający dostęp oraz korzystanie z Autenti API.

II.Zasady udostępniania dostępu do Autenti API

Złożenie wniosku o uzyskanie dostępu do Autenti API oraz każdorazowe użycie Autenti API z wykorzystaniem Zestawu Danych Autoryzacyjnych odbywa się w ramach niniejszego Regulaminu oraz Regulaminu Platformy Autenti.
Użytkownik ma prawo złożyć wniosek o uzyskanie dostępu do Autenti API, poprzez wypełnienie stosownego formularza elektronicznego i przycisku „Generuj Klucz”, dostępnego w ramach Konta Użytkownika w Platformie Autenti w zakładce Ustawienia/API, do którego został przypisany pakiet funkcjonalny zawierający uprawnienia do wykorzystywania Autenti API lub na podstawie odrębnej umowy z Administratorem.
Użytkownicy, którzy uzyskali Zestaw Danych Autoryzacyjnych, o którym mowa w ust. 2 powyżej, ponoszą wszelką odpowiedzialność za jego wykorzystanie, w tym w szczególności w celach sprzecznych z obowiązującym prawem, dobrymi obyczajami oraz niniejszym Regulaminem. Odpowiedzialność Użytkownika rozciąga się również na działanie osób, którym dane pozwalające na dostęp zostały udostępnione, nawet w sposób niezawiniony.
Administrator ma prawo odmowy przyznania klucza aktywacji bądź jego unieważnienia, w szczególności jeśli ubiegający się o dostęp do Autenti API w ocenie Administratora nie daje należytej rękojmi rzetelnego postępowania zgodnie z przepisami niniejszego Regulaminu, Regulaminu Platformy Autenti bądź w inny sposób może naruszać interesy Administratora bądź jej klientów i kontrahentów.
Wykorzystanie Autenti API jest uzależnione od weryfikacji uprawnień użytkownika na podstawie przedstawienia prawidłowego Zestawu Danych Autoryzacyjnych oraz wydanych na jego podstawie tokenów dostępowych, które służą do autoryzacji czynności dokonywanych w Platformie Autenti.

III. Warunki korzystania

Korzystanie z Platformy Autenti w celu złożenia podpisu elektronicznego, w wyniku zainicjowania przez Partnera Autenti funkcjonalności Autenti API, jest nieodpłatne.
Autenti API nie może być wykorzystywane przez Partnerów Autenti w serwisach, które:
1. naruszają powszechnie obowiązujące prawo oraz prawa osób trzecich,
2. naruszają dobre obyczaje,
3. wprowadzają użytkowników w błąd,
4. działają złośliwie lub na szkodę jakiegokolwiek innego podmiotu.
Odpowiedzialność za naruszenie powszechnie obowiązującego prawa oraz praw osób trzecich wynikłych z korzystania z Autenti API spoczywa na Partnerach Autenti.
Administrator dołoży wszelkich starań, aby zestaw metod Autenti API dostępnych dla Partnerów Autenti odpowiadał funkcjonalnościom Platformy Autenti i był wolny od błędów, ale użycie odbywa się na własne ryzyko na podstawie dokumentacji udostępnionej przez Administratora.
Odpowiedzialność za opracowanie, eksploatację, wspieranie aplikacji wykorzystujących Autenti API ponosi Partner Autenti.
Partner Autenti, który świadczy Serwis wykorzystujący Autenti API zobowiązuje się do podania użytkownikom swoich usług rzetelnej informacji dotyczącej zasad korzystania z Serwisu wykorzystującego Autenti API i określić politykę bezpieczeństwa dotyczącą danych jego użytkowników.
W uzasadnionych przypadkach związanych z rażącymi brakami lub problemami technicznymi, w szczególności dotyczącymi bezpieczeństwa Platformy Autenti lub działań konkurencyjnych na szkodę Administratora, Administrator zastrzega sobie prawo do blokady Zestawów Danych Autoryzacyjnych i wszystkich programów/systemów korzystających z Autenti API.

IV. Spory

Wszelkie spory związane z Autenti API na podstawie niniejszego Regulaminu będą rozstrzygane przez właściwe polskie sądy powszechne.
Administrator zastrzega sobie prawo do zmiany niniejszego Regulaminu. Zmiany Regulaminu wobec Partnerów Autenti, na rzecz których Autenti API świadczona jest odpłatnie wchodzą w życie w terminie wskazanym przez Administratora nie krótszym niż 7 dni od dnia poinformowania ich drogą poczty elektronicznej.
W sprawach nieuregulowanych niniejszym Regulaminem stosuje się odpowiednio postanowienia Regulaminu Autenti.

I. Definicje

II.Zasady udostępniania dostępu do Autenti API

III. Warunki korzystania

IV. Spory

Społeczności

Blog Autenti