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

API Skanuj.to zawiera wiele metod pozwalających na szeroką integrację. Zakres integracji zależy od konkretnego przypadku użycia, oraz potrzeb integrującego, np. inny będzie zakres integracji dla jednoinstancyjnego systemu workflow, czy dla systemu księgowego.

Ogólny zakres funkcji został przedstawiony na schemacie:

Jeśli Twoja integracja zakłada tylko przesłanie dokumentu do rozpoznania oraz odbiór treści dla jednej firmy - nie ma konieczności implementacji pozostałych funkcji.

b. Schemat użycia - WORKFLOW z weryfikacją dokumentów iFrame

Częstym przypadkiem integracji z serwisem Skanuj.to jest integracja przez Partnerów posiadających swój własny system do obiegu dokumentów (workflow). Parametry niezbędne do integracji (id firmy, email, token) są przechowywane w ustawieniach klienta w systemie Partnera, a sama integracja obejmuje:

  • Dodanie dokumentu - partner Autoryzuje się w serwisie Skanuj.to by uzskać token a następnie dodaje dokument z określeniem adresu odpowiedzi zwrotnej, tak by dostać na swój konkretny adres dane dokumentu po przetworzeniu (tak by wyzwolić kolejny krok),
  • Weryfikacja dokumentu w ramach iframe - po przetworzeniu dokumentu następuje zmiana stanu w systemie workflow partnera wskazująca na konieczność weryfikacji dokumentu, użytkownikowi systemu Partnera prezentowana jest formatka weryfikacji zaciągnięta ze skanuj.to (bez nagłówka / stopki),
  • Pobranie danych dokumentu po weryfikacji - po zakończeniu przetwarzania / weryfikacji dane dokumentu są przekazywane w tej samej strukturze, w przypadku problemów z połączeniem, niedostępności serwerów Partnera - należy stworzyć dodatkowe pobieranie danych dokumentu po danym czasie (np. Nie dostałem odpowiedzi po X minutach od dodania - pobieram dane, jeśli state = 1 - dokument jest w kolejce przetwarzania i pytam się ponownie po X minutach, jeśli state = 3 - dokument jest gotowy do weryfikacji)
  • Oznaczenie dokumentu jako wyeksportowany (blokada) - w celu uniemożliwienia użytkownikowi późniejszej modyfikacji danych - warto skorzystać z opcji blokady dokumentu (oznaczenia jako wyeksportowany). Nie stosujemy tego kroku jeśli użytkownik zamierza importować dane dokumentów do systemu FK przy użyciu konektora Skanuj.to.

Implementacja wskazanych metod oraz autoryzacji jest wystarczająca w tym modelu użycia.

c. 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.

3. Metody dostępu do API / WWW

Aby rozpocząć pracę z API Skanuj.to lub wywołać konkretny moduł aplikacji bez konieczności logowania użytkownika 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".

Są dwie możliwości autoryzacji:

  • Autoryzacja ogólna (opisana w podpunktach a i b)
  • Autoryzacja do konkrentego dokumentu (opisana w podpunktach c i d).

a. 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/postman: 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'
C#: using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace Aplikacja.Structures { public class Token { public string token { get; set; } public string user { get; set; } public string pass { get; set; } public bool first_run { get; set; } } } 4 public Token GetToken(string email, string apikey) //autoryzacja { var request = new RestRequest("auth", Method.POST); request.AddParameter("apikey", apikey); request.AddParameter("email", email); return Execute(request); }
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.

b. Logowanie do WWW z użyciem tokenu ogólnego

Dla Partnerów planujących udostępnienie funkcjonalności serwisu (np. weryfikacji dokumentu) w ramach swojej aplikacji - istnieje możliwość realizacji tego poprzez osadzenie iframe z następującym adresem:

https://app.skanuj.to /auth/login ? usr_email =EMAIL@DOMENA.PL& usa_token =TOKEN& cmp_id =COMPANYID& redirect_url =KONTROLERDOCELOWY

gdzie:

  • usr_email - email użytkownika, można użyć jednego konta systemowego (wtedy kontrola uprawnień do dokumentów leży po stronie Partnera),
  • usa_token - token (wymagana wcześniejsza autoryzacja powyższą metodą)
  • cmp_id - id firmy - zakładając przez API dostają je Państwo w odpowiedzi, można zapisać w ustawieniach, zakładając firmę w panelu - jest id widoczne w przełączaniu firm,
  • redirect_url - documents/edit-page/!!!!!TU ID DOKUMENTU!!!!!/0

W przypadku przekazywania parametru w redirect_url należy pamiętać o escapowaniu ampersanda (tj. zamiast & => %3F, np. %3Flang=en).

Zalecamy dla iframe użycia id = iframe-document-verification, pozwoli to na odebranie komunikatu z iframe poprzez WebAPI postMessage() (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) w momencie zakończenia weryfikacji dokumentu.

c. Uzyskanie tokenu dedykowanego dla dokumentu

Metoda OPCJONALNA - służy autoryzacji per 1 dokument (uzyskanie tokenu ważnego tylko dla konkretnego dokumentu).

W celu bezpiecznego uruchamiania strony weryfikacji Skanuj.to w iframe Partnera można pobrać tymczasowy doken umożliwiający dostęp do dokumentu w ramach iframe. Dzięki tej metodzie w źródle strony widoczny jest tylko token ważny dla konkretnego dokumentu.

URI /api/docauth POST
Headers - -
Form-data doc_id
email
password lub apikey
Nasze doc_id
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, "doc_token": "547dae1c92fc8", "user_token": "187df21c41661" }
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/docauth' -d 'doc_id=NNNN&email=XXX&apikey=YYY' curl -X POST --url 'https://app.skanuj.to/api/docauth' -d 'doc_id=NNNN&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ść.

d. Logowanie do WWW z użyciem tokenu dedykowanego dla dokumentu

customer/document/token/TOKEN

Gdzie -TOKEN - token do wybranego dokumentu ze skanuj.to

e. Sterowanie iframe

Wyświetlany iframe pozwala na dostosowanie się do potrzeb integratora:

  • Ukrycie layoutu, czyli ukrycie nagłówka, stopki serwisu, by widzieć same formularze - należy podać w parametrach żądania GET parametr hide_wrap=1.
  • Ukrycie nawigacji, czyli ukrycie przełączania się między dokumentami i innych przycisków nawigacji - należy podać w parametrach żądania GET parametr hide_nav=1.
  • Ustawienie jezyka aplikacji - aplikacja umożliwia pracę w języku polskim (pl) i angielskim (en). Aby wywołać aplikację w wybranym z języków należy przekazać dodatkowo parametr lang, np.: lang=pl.
  • Ustawienie pełnej szerokości okna - należy przekazać dodatkowo parametr fluid=1.
  • Wybór dostępnych pól na walidacji oraz ich tłumaczenie - pozwalamy na określenie pól, które mają być widoczne na formatce weryfikacji oraz ich nazewnictwa.
    Możliwe pola do edycji (nazwa pola (klucz)):
    • Faktura korygująca (isCorrective)
    • Faktura wewnątrz wspólnotowa (isIntraCommunity)
    • Kategoria księgowa (accountingCategory)
    • Rodzaj transakcji (taxProcedure)
    • Rejestr (registry)
    • Seria (series)
    • Numer zamówienia (orderNumber)
    • Data zamówienia (orderDate)
    • Waluta (currency)
    • Rabat kwotowo na wszystkich pozycjach (discountAmount)
    • Rabat % na wszystkich pozycjach (discount)
    • j.m. na wszystkich pozycjach (unit)
    • PKWiU / Kod na wszystkich pozycjach (code)
    • Kategoria księgowa na wszystkich pozycjach (category)
    • Kraj (Country)
    • numer rachunku bankowego (bankAccountNumber)
    • Mechanizm podzielonej płatności (splitPayment)
    • Notatka (comments)
    • Tagi (tags)
    Klucze z możliwością tłumaczeń:
    • Numer dokumentu (invoiceNumber)
    • Data wystawienia (serviceDate)
    • Data dostawy / wykonania usługi (issueDate)
    • Miesiąc księgowy (accountingMonth)
    • Data wpływu (sellDate)
    • Sposób płatności (paymentMethod)
    • Termin płatności (paymentDeadlineDate)
    Parametry:
    • hide_fields (string) (wartości po przecinku)
    • translate (json) (klucz_pola: tłumaczenie)
    Przykładowe wywoływanie:
    modules-documents/ocr/validate/{docId}/0?hide_fields=bankAccountNumber,comments&translate={"comments":"test"}

4. 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.

5. Dokumenty

Cykl życia dokumentu w serwisie (state):

Oznaczenia stawek VAT:

  • 23% => 23
  • 8% => 8
  • 5% => 5
  • 0% => 0
  • zw (zwolniony) => -1
  • np (nie podlega) => -2
  • oo (odwrotne obciążenie) => -4

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
multipages
extra
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)
opcjonalne pole - jeśli skan zawiera wiele dokumentów i system ma dokonać automatycznej analizy / podziału - przekazujemy wartość 1 (multipages=1)
opcjonalne pole służące do sterowania rozpoznaniem. Przykładowe elementy pola: { "forceUploadExisted":1, //aby wymusić ponowne dodanie i przetworzenie dokumentu już istniejącego w systemie "type": 2, //aby wymusić konkretny typ dokumentu, tu fv koszt "attributes": { "SprzedawcaNIP": "PL1234567888", "SprzedawcaNazwa": "testowa nazwa sprzedawcy", "SprzedawcaKod": "20450", "SprzedawcaAdres": "Testowa 1", "SprzedawcaMiejscowosc": "Wolka" } }
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("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 listy id dokumentów gotowych do pobrania

Metoda zwraca identyfikatory dokumentów do pobrania, w których nastąpiły zmiany.

URI /api/document/mode/list-id-to-retrieve GET
Headers token
company_id
token uzyskany przy autoryzacji
id firmy (skanuj.to) do której chcemy zawęzić wyszukiwanie
Form-data state
status
Stan: 2 - zweryfikowane, 3 - do weryfikacji
Status eksportu: 0 - niewyeksportowane, 1 - wyeksportowane
Odpowiedź pozytywna Przykładowa odpowiedź: [66666661, 66666662, 66666663]
Odpowiedź negatywna Zgodnie z błędami autoryzacji.
Przykład wywołania curl -X GET --url 'https://app.skanuj.to/api/document/mode/list-id-to-retrieve' -H "token:5XXXX9a8a1&company_id=1"
Uwagi brak

d. 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".
W przypadku, kiedy przetwarzany dokument był wysłany z flagą multipages=1 przy zapytaniu o dokument rodzica (id1) zostaną zwrócone dane pierwszego dziecka (id1a) wraz sekcją children - zawierającą dane główne wszystkich dzieci.

e. 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

f. Ustawianie statusu eksportu na dokumencie

URI /api/document POST
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

g. Usuwanie dokumentu

URI /api/document?id=NN DELETE
Headers token token uzyskany przy autoryzacji
Form-data
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).