Uwaga! Poniższa dokumentacja dotyczy wersji Platformy Autenti znajdującej się pod adresem https://app.autenti.eu/login.
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} |
| 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.
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 { |
| note |
This method creates a new document and returns its id. Files are attached in next step. Attributes:
|
| 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 |
|
| URI |
/api/identities/{identityId}/documents/{documentId}/start |
| method |
POST |
| headers |
Authorization: Bearer {access_token} Content-Type: application/json; charset=UTF-8 |
| payload |
{ ‘requireSmsCode’ : false, ‘redirectUrl’ : ‘https://xxx’ |
| response |
200 OK |
| note |
It sends URL to the document by email to receivers and viewers.
|
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 |
|
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 |
{ |
| note |
|
| URI |
/api/identities/{identityId}/documents/{documentId}/remind |
| method |
POST |
| headers |
Authorization: Bearer {access_token} |
| payload | |
| response |
200 OK |
| example |
curl -X POST -H „Authorization: Bearer 6e7871f7-xxxx-481e-84ec-894d19bb7871” https://app.autenti.eu/api/identities/33/documents/250 |
| Note |
|
| 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:
- naruszają powszechnie obowiązujące prawo oraz prawa osób trzecich,
- naruszają dobre obyczaje,
- wprowadzają użytkowników w błąd,
- 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.