API do usługi Comarch OCR - Baza Wiedzy programu Comarch ERP Optima

Spis treści

Tworzenie sesji użytkownika (POST)
Usuwanie sesji użytkownika (DELETE)
Przetwarzanie dokumentu (POST)

Usługa Adres

Comarch OCR https://www.erp.comarch.pl/OCR/

Comarch OCR API https://ocr.erp.comarch.pl/v1.0/api/

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

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

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

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

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

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 Opcjonalny - język rozpoznawania dokumentu,
0 - j. polski (jeśli na fakturze zostanie rozpoznany język angielski, rozpoznanie nastąpi jak dla faktur angielskich),
1 - j. niemiecki,
2 - j. francuski,
3 - j. angielski
-1 – rozpoznanie na podstawie języka wykrytego na dokumencie
(domyślnie - j. polski)

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

OneInvoiceFile Opcjonalny - informacja jak należy łączyć strony w przesłanym pliku, 0 - łączenie stron w dokumenty na podstawie danych zawartych na stronach, 1 - jeden przesłany plik to jeden dokument

DefaultPaymentForm Opcjonalny – domyślna forma płatności jaka ma zostać zwrócona w przypadku nie wykrycia formy płatności na dokumencie (np. „gotówka”)

Language Opcjonalny – informacja w jakim języku mają byc zwrócone komunikaty, 0 - j. polski, 1 - j. niemiecki (domyślnie - j. polski)

PagesToRecognize Opcjonalny – informacja które strony w pliku mają zostać rozpoznane (np. "1-3,5")

RawRecognitionText Opcjonalny – informacja czy ma zostać zwrócona oryginalna, niezmieniona treść wykryta na stronie, 0 - brak oryginalnej treści, 1 - oryginalna treść zostanie zwrócona

PaymentMethodMapping Opcjonalny – tylko dla dokumentów w języku angielskim, informacja czy forma płatności ma zostać mapowana na podstawową formę płatności (gotówka, przedpłata, karta, przelew), 0 - brak mapowania, 1 - mapowanie

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	Opcjonalny - język rozpoznawania dokumentu, 0 - j. polski (jeśli na fakturze zostanie rozpoznany język angielski, rozpoznanie nastąpi jak dla faktur angielskich), 1 - j. niemiecki, 2 - j. francuski, 3 - j. angielski -1 – rozpoznanie na podstawie języka wykrytego na dokumencie (domyślnie - j. polski)
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
OneInvoiceFile	Opcjonalny - informacja jak należy łączyć strony w przesłanym pliku, 0 - łączenie stron w dokumenty na podstawie danych zawartych na stronach, 1 - jeden przesłany plik to jeden dokument
DefaultPaymentForm	Opcjonalny – domyślna forma płatności jaka ma zostać zwrócona w przypadku nie wykrycia formy płatności na dokumencie (np. „gotówka”)
Language	Opcjonalny – informacja w jakim języku mają byc zwrócone komunikaty, 0 - j. polski, 1 - j. niemiecki (domyślnie - j. polski)
PagesToRecognize	Opcjonalny – informacja które strony w pliku mają zostać rozpoznane (np. "1-3,5")
RawRecognitionText	Opcjonalny – informacja czy ma zostać zwrócona oryginalna, niezmieniona treść wykryta na stronie, 0 - brak oryginalnej treści, 1 - oryginalna treść zostanie zwrócona
PaymentMethodMapping	Opcjonalny – tylko dla dokumentów w języku angielskim, informacja czy forma płatności ma zostać mapowana na podstawową formę płatności (gotówka, przedpłata, karta, przelew), 0 - brak mapowania, 1 - mapowanie

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

Klucz Wartość

authToken Token sesji

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

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)

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

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

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.

14 3 Błędny token sesji. (W przypadku korzystania z OCR API)

15 3 Brak dostępu do API OCR (W przypadku korzystania z OCR API)

17 3 Nierozpoznany język na dokumencie (W przypadku korzystania z OCR API)

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.
14	3	Błędny token sesji. (W przypadku korzystania z OCR API)
15	3	Brak dostępu do API OCR (W przypadku korzystania z OCR API)
17	3	Nierozpoznany język na dokumencie (W przypadku korzystania z OCR API)

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" }