API do usługi Comarch OCR

Usługa	Adres
Comarch OCR	https://www.erp.comarch.pl/OCR/
Comarch OCR API	https://ocr.erp.comarch.pl/v1.0/api/

W celu korzystania z usługi Comarch OCR API należy po zalogowaniu w aplikacji Comarch OCR wygenerować klucze dostępowe.

Metody

Tworzenie sesji użytkownika (POST)

Adres: https://ocr.erp.comarch.pl/v1.0/api/sessions/post

 

W nagłówku zapytania należy dołączyć następujące dane uwierzytelniające:

Klucz	Wartość
authKey	Klucz wygenerowany w panelu do zarządzania Comarch OCR
authSecret	Sekret wygenerowany w panelu do zarządzania Comarch OCR

Opis struktury JSON odpowiedzi

Property	Opis
sessionToken	Token sesji

Przykładowa odpowiedź JSON

{
"sessionToken": "00000000-0000-0000-0000-000000000000""
}


Możliwe kody odpowiedzi HTTP:

Kod	Znaczenie
200	Poprawnie wygenerowano token sesji.
400	Brak wymaganych parametrów w nagłówku żądania lub błędne dane.
403	Wymagane jest użycie SSL

Usuwanie sesji użytkownika (DELETE)

Adres: https://ocr.erp.comarch.pl/v1.0/api/sessions/delete

 

W nagłówku zapytania należy dołączyć następujące wartości:

Klucz	Wartość
authToken	Token sesji

Kod	Znaczenie
204	Sesja poprawnie zakończona
400	Brak tokenu sesji w nagłówku żądania.
403	Wymagane jest użycie SSL

Przetwarzanie dokumentu (POST)

Adres: https://ocr.erp.comarch.pl/v1.0/api/invoice/post

 

Opis struktury JSON zapytania

Property	Opis
Data	Plik o rozszerzeniu *.jpg, *.png, *bmp lub *.pdf w postaci binarnej
InvoiceGuid	Opcjonalne - GUID
Filename	Nazwa pliku wraz z rozszerzeniem
ReturnData	Opcjonalne - informacja czy usługa ma zwrócić pliki dla przetworzonych dokumentów, wartość parametru 1 – pliki są dołączone do odpowiedzi
RecognitionLanguageOption	Opcjonalne – informacja w jakim języku ma zostać rozpoznany dokument, wartość parametru 1 – dokument w języku niemieckim
BarCodeRecognition	Opcjonalny - informacja czy należy rozpoznawać kody kreskowe da dokumentach, opcja wymaga ustawienia ExportFormat=1, 0 - nie rozpoznaje kodów, 1 - rozpoznaje kody, 2 - łączy strony na podstawie rozpoznanych kodów

W nagłówku zapytania należy dołączyć następujące wartości:

Klucz	Wartość
authToken	Token sesji

Schemat zapytania:

{

       "type": "object",

       "properties": {

                   "Data": {
                           "type": [
                                    "string"
                           ]
                    },
                    "InvoiceGuid": {
                           "type": [
                                    "string"
                           ]
                    },
                    "Filename": {
                           "type": [
                                    "string"
                           ]
                    },
                    " ReturnData": {
                           "type": [
                                    "integer"
                           ]
                    },
                    " RecognitionLanguageOption ": {
                           "type": [
                                    "integer"
                           ]
                    },
                    " BarCodeRecognition ": {
                            "type": [
                                    "integer"
                           ]
                    }
       },
       "required": [
              "Data",
              "Filename",
       ]

 

Opis struktury JSON odpowiedzi

Property	Opis
ExportString	Odpowiedź w formacie JSON
Message	Komunikat o wyniku przetwarzania dokumentu przez usługę
Code	Kod odpowiedzi
Status	Status odpowiedzi
AdditionalMessage	Dodatkowa informacja o pozostałych dokumentach, gdy w pakiecie pozostało 10 lub mniej dokumentów
UriToDownload	Adres URL do strony spójnej z kodem odpowiedzi

Schemat odpowiedzi:

 

Struktura przykładowego pliku w formacie JSON zawartego w odpowiedzi z serwera usługi Comarch OCR.

Struktura przykładowego pliku w formacie JSON dla faktur w języku niemieckim zawartego w odpowiedzi z serwera usługi Comarch OCR. ( dla RecognitionLanguageOption=1)

Ogólny opis możliwych scenariuszy odpowiedzi z serwera usługi Comarch OCR

Code	Status	Opis	Dodatkowe informacje
Dowolny	1	Informacja
Dowolny	2	Ostrzeżenie	Należy sprawdzić czy coś się znajduje w AdditionalMessage lub UriToDownload
Dowolny	3	Błąd	Należy sprawdzić czy coś się znajduje w AdditionalMessage lub UriToDownload

Szczegółowy opis możliwych scenariuszów odpowiedzi z serwera usługi Comarch OCR

Code	Status	Opis	Dodatkowe informacje
1	1	Dokument rozpoznany prawidłowo.
1	2	Dokument rozpoznany prawidłowo.	Klientowi pozostało w pakiecie 10 lub mniej dokumentów, szczegółowa informacja w AdditionalMessage, link do sklepu Comarch znajduje się w UriToDownload.
2	1	Dokument rozpoznany częściowo lub błędnie.
2	2	Dokument rozpoznany częściowo lub błędnie.	Klientowi pozostało w pakiecie 10 lub mniej dokumentów, szczegółowa informacja w AdditionalMessage, link do sklepu Comarch znajduje się w UriToDownload.
3	3	Dokument nierozpoznany.
4	3	Funkcja niedostępna.
5	3	Przerwa techniczna.
6	3	Niepoprawne zapytanie.
7	3	Niepoprawny numer klucza.
8	3	Brak podpisanej klauzuli RODO.	Link do formularza z umową znajduje się w UriToDownload.
9	3	Brak wykupionego pakietu przez klienta.	Link do sklepu Comarch znajduje się w UriToDownload.
10	3	Wykorzystany pakiet dokumentów.	Link do sklepu Comarch znajduje się w UriToDownload.
11	3	Klient zaznaczył dokument w którym jest więcej stron niż pozostało w pakiecie.	Link do sklepu Comarch znajduje się w UriToDownload.
12	3	Rozmiar pojedynczej strony przekracza obsługiwany limit.
13	3	Klient został zablokowany ze względu na brak opłaconego pakietu.

W przypadku odpowiedzi z serwera z Code innym niż wymienione w tabeli powyżej należy wyświetlić informację zgodnie ze Statusem.

Komunikat tej informacji znajduje się w Message lub AdditionalMessage, i ewentualny link w UriToDownload.

Przykładowe zapytanie JSON

{
"Data": "[DANE BINARNE]",
"InvoiceGuid":"dce8b807-2846-4816-a24b-12d7eca140ed",
"Filename":"255430.pdf",
}

Przykładowa odpowiedź JSON
{
"ExportString": "[ODPOWIEDŹ W FORMACIE JSON]",
"Message": "Rozpoznano dokument 255430.pdf.",
"Code": 1,
"Status": 2,
"AdditionalMessage": "W bezpłatnym pakiecie Demo OCR zostało jeszcze 7 dokumentów do
wykorzystania. Kliknij w ten komunikat, aby przejść do Sklepu Comarch i kupić
odpowiedni Pakiet Comarch OCR.",
"UriToDownload": "https://sklep.comarch.pl/produkty/ocr,2,16251"
}