API documentation

1. Podstawowe informacje

Środowisko produkcyjne Skanuj.to jest dostępne pod adresem: https://app.skanuj.to/

Do celów integracji istnieje możliwość udostępnienia środowiska testowego. W tym celu należy skontaktować się z nami (kontakt@skanuj.to).

Do celów praktycznego zapoznania się API zalecamy dodatek do Chrome - POSTMAN.

2. Rozpoczęcie pracy z API Skanuj.to

a. Ogólny przebieg czynności

b. Rejestracja

Aby skorzystać z API Skanuj.to należy posiadać konto w systemie.

Autoryzacja przez API oraz zakres dostępnych funkcji może być zależna od posiadanego pakietu usług, dlatego przed przystąpieniem do prac prosimy o kontakt z kontakt@skanuj.to w celu nadania właściwego pakietu.

Istnieje możliwość rejestracji kont dla Klientów przez API. Opcja udostępniana Partnerom na żądanie - po uzgodnieniu modelu działania.

c. Autoryzacja

Aby rozpocząć pracę z API Skanuj.to należy pierwszej kolejności dokonać autoryzacji, gdyż w każdym zapytaniu do serwisu skanuj.to (oprócz zapytania autoryzującego), w nagłówku requestu musi znaleźć się pole "token".


Aby uzyskać token należy autoryzować użytkownika za pomocą:

URI /api/auth POST
Headers - -
Form-data email, password lub apikey adres email uzytkownika tożsamy z loginem w app.skanuj.to hasło lub klucz API dostępny do pobrania z ustawień w app.skanuj.to (ustawienia -> moje konto -> hasło / klucz API)
Odpowiedź pozytywna { "msg": "Authorization correct", "code": 10, "token": "547dae1c92fc8" }
Odpowiedź negatywna { "msg": "User does not exist or bad credentials", "code": 98 }
Przykład wywołania curl -X POST --url 'https://app.skanuj.to/api/auth' -d 'email=XXX&apikey=YYY'
curl -X POST --url 'https://app.skanuj.to/api/auth' -d 'email=XXX&password=YYY'
Uwagi Token ma swój termin ważności, każde zapytanie z poprawnym tokenem resetuje ten czas. Obecnie jest ustawiony na 30min, po których (w przypadku braku aktywności) token straci ważność.

W przypadku zapytań opisanych poniżej możemy oczekiwać odpowiedzi związanych z brakiem autoryzacji:

Odpowiedź negatywna - brak tokenu { "msg": "No token in request", "code": 99 }
Odpowiedź negatywna - błędy lub wygaśnięty token { "msg": "Token expired or invalid", "code": 99 }

Dodatkowo - w przypadku wywołania błędnej akcji (poniżej literówka) otrzymamy zwrot:

Odpowiedź negatywna - nie rozpoznana akcja { "msg": "Unrecognized action MODE get-managed-companiesssss”, "code": 98 }
gdzie MODE = metoda http.

3. Praca w kontekście firm

a. Pobieranie firm

Liste firm obsługiwanych przez użytkownika otrzymamy dzięki następującej metodzie:

URI /api/user POST
Headers token token uzyskany przy autoryzacji
Form-data mode get-user-company
Odpowiedź pozytywna [ { "id": 7000145, "name": "Skanuj.to TEST", "nip": "PL7831672243", "dir_name": "SKANUJ_TO TEST . 7000145.7831672243", "dbname": "TEST4" } ]
Odpowiedź negatywna Zgodnie z błędami autoryzacji
Przykład wywołania curl -X POST --url 'https://app.skanuj.to/api/user' -H "token:TTT" -d 'mode=get-user-company'
Uwagi dbname - jest to nazwa bazy danych / id firmy przekazany przy zakładaniu firmy, jeśli nie zostanie taki parametr przekazany - będzie tożsamy z nazwą firmy

b. Dodawanie firmy

Do prawidłowego rozpoznania danych dokumentów lub przypisanie faktury wymagane jest umieszczanie dokumentów w ramach kontekstu firmy użytkownika.

Aby dodać firmę(y) należy wywołać następującą metodę

URI /api/user POST
Headers token token uzyskany przy autoryzacji
Form-data mode, companies add-companies
Tablica firm z atrybutami:
  • name - nazwa firmy
  • nip - nip firmy
  • country - kraj
  • city - miejscowość
  • post_code - kod pocztowy
  • address - adres (ulica, numer domu i mieszkania)
  • dbname - nazwa bazy danych firmy / id w systemie zewnętrznym
Odpowiedź pozytywna Firma dodana:
{ "code": 10, "msg": " OK: 0 - testow2a - added" “data”:{“Test2”:”2131”} }
Firma powiązana z istniejącą:
{ "code": 10, "msg": " OK: 0 - testow2a linked with 7014162 - testow2a" “data”:{“Test2”:”2131”} }
Odpowiedź negatywna { "code": 98, "msg": “No companies in request” }
{ "code": 98, "msg": “ERR: 0 - empty company name” “data”:{} }
{ "code": 98, "msg": “ERR: 0 - no limit for companies” “data”:{} }
Przykład wywołania curl -X POST --url 'https://app.skanuj.to/api/user' -H "token:TTT" -d 'mode=add-companies&companies[1][name]=test2&companies[1][nip]=9512120072&companies[1][country]=Polska&companies[1][city]=Warszawa&companies[1][post_code]=00-001&companies[1][address]=ul. Testowa 1&companies[1][dbname]=TEST’
W przypadku postmana należy przekazać w value tablicę w JSON:
[{“name”:”test2”,”nip”:”9512120072”,”country”=”Polska”,”city":"Warszawa","post_code":"00-001","address":"ul. Testowa 1", "dbname":"TEST"}]
Uwagi W odpowiedzie w polu data znajdziemy tablicę z id założonych firm, kluczem w tablicy jest podany dbname (nazwa jeśli dbname puste)..

c. Import kontrahentów do firmy

Aby dodać do firmy kontrahentów należy wywołać jedną z 2 metod:

URI /api/contractor POST
Headers token token uzyskany przy autoryzacji
Form-data mode, contractors add-contractors LUB add-contractors-by-id
Tablica elementów per firma key:id firmy lub dbname (patrz poniżej), value: tablica kontrahentów z atrybutami:
  • id - klucz lokalny (w systemie zewnętrznym)
  • nip - nip firmy
  • name - nazwa firmy
  • country - kraj
  • city - miejscowość
  • post_code - kod pocztowy
  • address - adres (ulica, numer domu i mieszkania)
  • akronim - akronim / skrócona nazwa
  • incidental - pole nieobowiązkowe, czy kontrahent incydentalny
  • extra - pole na dodatkowe dane
W przypadku add-companies kluczem jest przekazany wcześniej dbname, w przypadku add-companies-by-id id firmy w skanuj.to
Odpowiedź pozytywna {"code":10,"msg":" OK: contractors - 7376 - added|contractors - 7377 - added","data":{"1":7376,"2":7377}}
Odpowiedź negatywna {"code":98,"msg":"ERR: contractors - no complete data - not added OK: contractors - 7377 - added","data":{"2":7377}}
Przykład wywołania Tablica contractors w JSON (mode = add-companies-by-id, gdzie id firmy do której dodajemy kontrahentów to 7000001):
{ "contractors": { "Key": 7000001, "Value": [ { "id": "1", "nip": "9512120072", "name": "Kontrahent1", "country": "Polska", "city": "Warszawa", "post_code": "00-001", "address": "ul. Testowa 1" }, { "id": "2", "nip": "9512120073", "name": "Kontrahent2", "country": "Polska", "city": "Warszawa", "post_code": "00-001", "address": "ul. Testowa 1" } ] } }
Uwagi brak

d. Inne parametry firm

W przypadku gdy będzie wykorzystany w rozwiązaniu zintegrowanym również frontend aplikacji Skanuj.to istnieje możliwość zasilenia dodatkowych parametrów firm, min.:

  • Rejestry,
  • Serie,
  • Kategorie,
  • Plan kont.

Odpowiednie zasilenie tymi danymi wymaga uprzednich konsultacji w znaczeniu, sposobie wykorzystania konkretnych atrybutów i procesów które są z nimi związane, dlatego w takim wypadku należy wpierw skontaktować się ze Skanuj.to.

4. Dokumenty

Cykl życia dokumentu w serwisie (state):

a. Wysyłanie dokumentu do przetworzenia


Dokument do przetworzenia wysyłamy za pomocą:

URI /api/document POST
Headers token
company_id
token uzyskany przy autoryzacji
id firmy ze skanuj.to do której wysyłamy dokument
Form-data mode
source
response
response_type
FILE
upload-file
integracja (o ile nie uzgodnione inaczej)
url na jaki ma aplikacja odpowiedzieć po przetworzeniu dokumentu
typ odpowiedzi, przyjmuje - ‘FULL’ (odpowiednik mode:one-xt) lub ‘SIMPLE’ (odpowiednik mode:all)
plik
Odpowiedź pozytywna {"good-uploads":[{"name":"faktura-auchan-produkty.jpg","type":-1,"tmp_name":"\/tmp\/phpen9Hiy","error":0,"size":"616882","options":{"ignoreNoFile":false,"useByteString":true,"magicFile":null,"detectInfos":true},"validated":false,"received":false,"filtered":false,"validators":["Zend_Validate_File_Upload","Zend_Validate_File_Extension"],"destination":"\/var\/www\/skanuj_to\/web_app\/public\/frontend\/user-files\/a49e9411XXXXXXXXX3","file_extension":"jpg","hash":"XXXXXXXXXX8e62ebe560","uploaded_date":"2013-08-2811:55:56","uploaded_type":1,"user_id":434,"raw_path":"\/public\/frontend\/user-files\/a4XXXXXd09ad10a15b3\/e550161c7e0307c17XXXXXe560","notice":"","doc_id":1XXX3}],"bad-uploads":[],"notices":[]}
Odpowiedź negatywna Zgodnie z błędami autoryzacji. Patrz też bad-uploads w odpowiedzi powyżej.
{ "code": 98, "msg": “Company id = 12 not found” } { "code": 98, "msg": “The user does not have permissions to the company id =12” }
Przykład wywołania CURL:
curl -X POST -F "FileUpload=@PLIK.pdf" -F "mode=upload-file" --url "https://app.skanuj.to/api/document" -H "company_id:NNN" -H "token:TTT" -H "Expect:"
C#:
public SkApiResponse uploadDocument(int company_id, string file_name, string path, bool multi)
{
var request = new RestRequest(Method.POST);
request.Resource = "document";
request.AddParameter("mode", "upload-file", ParameterType.GetOrPost);
request.AddParameter("company_id", company_id, ParameterType.HttpHeader);
request.AddParameter("multipages", multi, ParameterType.GetOrPost);
request.AddParameter("source", "integracja", ParameterType.GetOrPost);
request.AddFile(file_name, path);
return Execute(request);
}

public T Execute(RestRequest request) where T : new()
{
var client = new RestClient();
client.BaseUrl = "https://app.skanuj.to/api";
if (!string.IsNullOrEmpty(token))
{
request.AddParameter("token", token, ParameterType.HttpHeader); // used on every request
}
var response = client.Execute(request);
if (response.ErrorException != null)
{
throw response.ErrorException;
}
return response.Data;
}
Uwagi Obsługiwane formaty wejścia: pdf, tif, tiff, jpg.

Po wysłaniu pliku otrzymamy jsona z dwoma kluczami "good-uploads" oraz "bad-uploads", odpowiednio zawierają informację o powodzeniu, bądź niepowodzeniu odebrania pliku.

b. Pobieranie listy dokumentów

Listę dokumentów otrzymamy odwołując się do poniższego zasobu.

URI /api/document/mode/all
/api/document/mode/search
GET
Headers token
company_id
identstr
token uzyskany przy autoryzacji
id firmy (skanuj.to) do której chcemy zawęzić wyszukiwanie
unikatory string identyfikujący dany program
Url params




count
tablica dodatkowych parametrów przekazana w JSON::
  • page - nr strony
  • search
    • text ="..." - treść dokumentu,
    • type =1 .. - typ doumentu (patrz przykładowa odpowiedź)
limit zwracanych wyników,
Odpowiedź pozytywna Przykładowa odpowiedź: [{ "id": 6743, //id dokumentu "user_id": 1027, //id usera który dany dokument uploadował "uploaded_date": "2013-10-03 11:36:57", //data uploadu "uploaded_type": 1, //multipage "status": 0, /* 0 domyślny 1 wyeksportowany UWAGA! Dla potrzeb integracji można wykorzystywać tą flagę korzystając z metod oznaczania dokumentów jako wyeksportowane */ "type": -1, /* -1 nieokreślony 1 fv sprzedaż 2 fv kupno 3 inny 5 paragon 6 rachunek 7 bilet 8 fv 9 umowa */ "category": 1 //kategoria dokumentu "name": "skan2.pdf", //nazwa pliki źródłowego "hash": "88985cba", //hash "pages": 1, //ilość stron "deleted": false, //czy usunięty "comments": null, //komentarz "raw_path": "/public/frontend/user-files/883e881bb4d22a7add958f2d6b052c9f/88985cba", //ścieżka do pliku "state": 1, /* 0 dodany 1 w przetwarzaniu 2 zweryfikowany 3 do weryfikacji 4 wielostronicowy brak akcji */ "verified_by": null, //kto weryfikował "last_modified": "2013-10-03 11:36:58.088544", //data ostatniej modyfikacji "split_for_many_docs": false, //czy wydzielany z pliku "company_id": 938, //id firmy "locked_by": null, "registry_id": null, "resend_try_count": 0, "worker_error": 1, "parent_doc_id": null, "is_parent_doc": false, "block_sending_to_flexi": false, "description": null, "verified_at": null, "was_resended_to_process": false, "verification_start": null, "verification_stop": null, "verification_enter_count": 0, "verification_total_idle": 0, "series_id": 0, "added_by_name": "XXXXXXXXXXXXXXXXX", "verified_by_name": null, "all_count": 2, "type_dict": "Niezidentyfikowany", "file_path": "https://app.skanuj.to/files/download-file/h/88985cba", "contractor": [], "attributes": { "TerminPlatnosci": "", "DataSprzedazy": "", "DataWystawienia": "", "RazemBrutto": 0, "RazemNetto": 0, "RazemVAT": 0, "Kategoria": "", "Waluta": "PLN", "KursWaluty": 0 }, "positions": [], "company": { "id": 938, "name": "XXXXXXXXXXXXXXXXXX", "nip": "PLXXXXXXXXXXX", "country": "Polska", "city": "Warszawa", "post_code": "XX-XXX", "address": "ul. XXXXXXXXXXX", "email": null, "type": 0, "accounting_type": 2, "deleted": false, "vat_payer": true, "phone": null, "vat_declaration": 1, "owner_id": 1027, "accounting_office_id": null, "adding_date": "2013-08-27 10:41:40.349514", "block_adding_docs": false, "weryfikacjast": false, "first_run": true, "has_notverified_docs": false, "billin_id": 8957, "mkt_src": "cpc", "rob": "", "ucj_id": 883, "company_id": 938, "role": 1, "ucj_deleted": false }, "percent": 0, "user_integration": { "user": "", "pass": "", "company": "" }, "series_name": "" }]
Odpowiedź negatywna Zgodnie z błędami autoryzacji.
Przykład wywołania curl -X GET --url 'https://app.skanuj.to/api/document/mode/all' -H "token:5XXXX9a8a1" -H "company_id:NN"
Przykład:
https://app.skanuj.to/api/document/mode/search?params={“search”:{“text”=”ala”}}&count=1
Uwagi Nie podając dodatkowych parametrów wyszukiwania - zwrócona będzie lista zawierająca dokumenty wszystkich firm do których zalogowany użytkownik ma dostęp.
Aby przefiltorwac dokumenty po firmie (tzn. aby wywołanie zwróciło dokumenty konkretnej firmy) w nagłówku powinien się znaleźć parametr "company_id".

c. Pobieranie pojedyńczego dokumentu (rozszerzone dane)

URI /api/document/mode/one-xt GET
Headers token
company_id
token uzyskany przy autoryzacji
id firmy (skanuj.to) do której chcemy zawęzić wyszukiwanie
Form-data id id dokumentu (skanuj.to)
Odpowiedź pozytywna Odpowiedź zawiera każdy atrybut dokumentu jako tablicę:
  • value - wartość atrybutu
  • left - koordynata lewego ograniczenia tekstu skąd został przeczytany atrybut
  • right - koordynaga prawego ograniczenia tekstu skąd został przeczytany atrybut
  • top - koordynata górnego ograniczenia tekstu skąd został przeczytany atrybut
  • bottom - koordynata dolnego ograniczenia tekstu skąd został przeczytany atrybut
  • page - strona skąd został przeczytany atrybut,
  • is_valid - współczynnik pewności danej w zakresie 0-1
  • status - status atrybutu (0 - nie wymagający weryfikacji, 1 - wymagający weryfikacji, 2 - zweryfikowany)
  • aspect_ratio - współczynnik skalowania obrazu (do prawidłowego określania koordynat)
Odpowiedź negatywna Zgodnie z błędami autoryzacji.
Przykład wywołania curl -X GET --url 'https://app.skanuj.to/api/document/mode/one-xt/id/6666666' -H "token:5XXXX9a8a1"
Uwagi Nie podając dodatkowych parametrów wyszukiwania - zwrócona będzie lista zawierająca dokumenty wszystkich firm do których zalogowany użytkownik ma dostęp.
Aby przefiltorwac dokumenty po firmie (tzn. aby wywołanie zwróciło dokumenty konkretnej firmy) w nagłówku powinien się znaleźć parametr "company_id".

d. Pobieranie dodatkowych danych dla pojedyńczego dokumentu - dane tekstowe i pozycyjne treści

URI /api/document/mode/data GET
Headers token token uzyskany przy autoryzacji
Form-data id id dokumentu (skanuj.to)
Odpowiedź pozytywna Odpowiedź zawiera tablicę (indeksowaną numerem strony, poczynając od 0) zserializowanych danych treści na stronie.
Odpowiedź negatywna Zgodnie z błędami autoryzacji.
Przykład wywołania curl -X GET --url 'https://app.skanuj.to/api/document/mode/data/id/6666666' -H "token:5XXXX9a8a1"
Uwagi brak

e. Ustawianie statusu eksportu na dokumencie

URI /api/document GET
Headers token token uzyskany przy autoryzacji
Form-data mode
id
status
change-status
id dokumentu (skanuj.to)
0 - nie wyeksportowany, 1 - wyeksportowany
Odpowiedź pozytywna { “msg”:”Status changed”, “code”:10 }
Odpowiedź negatywna { “msg”:”No document id in request”, “code”:98 }
{ “msg”:”No user rights to document”, “code”:98 }
Przykład wywołania curl -X POST --url 'https://app.skanuj.to/api/document/’ -d 'id=6666666&mode=change-status' -H "token:5XXXX9a8a1"
Uwagi brak

f. Usuwanie dokumentu

URI /api/document?id=NN GET
Headers token token uzyskany przy autoryzacji
Form-data mode
id
status
change-status
id dokumentu (skanuj.to)
0 - nie wyeksportowany, 1 - wyeksportowany
Odpowiedź pozytywna {"msg":"Document deleted", "code":10}
Odpowiedź negatywna { “msg”:”No document id in request”, “code”:98 }
{ “msg”:”No user rights to document”, “code”:98 }
Przykład wywołania curl -X DELETE --url 'https://app.skanuj.to/api/document/id=6666666’ ' -H "token:5XXXX9a8a1"
Uwagi Poprzez usunięcie pliku rozumiemy oznaczenie pliku jako usuniętego. Usuwanie fizyczne obrazu, miniatur i danych dokumentów jest realizowane przez proces batchowy - ustawienia interwału zależne od ustawień Klienta (wymagany kontakt ze wsparcie@skanuj.to).