API do usługi Comarch OCR

UsługaAdres
Comarch OCRhttps://www.erp.comarch.pl/OCR/
Comarch OCR APIhttps://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:

KluczWartość
authKeyKlucz wygenerowany w panelu do zarządzania Comarch OCR
authSecretSekret wygenerowany w panelu do zarządzania Comarch OCR

Opis struktury JSON odpowiedzi

PropertyOpis
sessionTokenToken sesji

Przykładowa odpowiedź JSON

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

Możliwe kody odpowiedzi HTTP:

KodZnaczenie
200Poprawnie wygenerowano token sesji.
400Brak wymaganych parametrów w nagłówku żądania lub błędne dane.
403Wymagane 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:

KluczWartość
authTokenToken sesji

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

Przetwarzanie dokumentu (POST)

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

 

Opis struktury JSON zapytania

PropertyOpis
DataPlik o rozszerzeniu *.jpg, *.png, *bmp lub *.pdf w postaci binarnej
InvoiceGuidOpcjonalne - GUID
FilenameNazwa pliku wraz z rozszerzeniem
ReturnDataOpcjonalne - informacja czy usługa ma zwrócić pliki dla przetworzonych dokumentów, wartość parametru 1 – pliki są dołączone do odpowiedzi
RecognitionLanguageOptionOpcjonalny - 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)
BarCodeRecognitionOpcjonalny - 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
OneInvoiceFileOpcjonalny - 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
DefaultPaymentFormOpcjonalny – domyślna forma płatności jaka ma zostać zwrócona w przypadku nie wykrycia formy płatności na dokumencie (np. „gotówka”)
LanguageOpcjonalny – informacja w jakim języku mają byc zwrócone komunikaty, 0 - j. polski, 1 - j. niemiecki (domyślnie - j. polski)
PagesToRecognizeOpcjonalny – 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
PaymentMethodMappingOpcjonalny – 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:

KluczWartość
authTokenToken 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

PropertyOpis
ExportStringOdpowiedź w formacie JSON
MessageKomunikat o wyniku przetwarzania dokumentu przez usługę
CodeKod odpowiedzi
StatusStatus odpowiedzi
AdditionalMessageDodatkowa informacja o pozostałych dokumentach, gdy w pakiecie pozostało 10 lub mniej dokumentów
UriToDownloadAdres 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

CodeStatusOpisDodatkowe informacje
Dowolny1Informacja
Dowolny2OstrzeżenieNależy sprawdzić czy coś się znajduje w AdditionalMessage lub UriToDownload
Dowolny3BłądNależy sprawdzić czy coś się znajduje w AdditionalMessage lub UriToDownload

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

CodeStatusOpisDodatkowe informacje
11Dokument rozpoznany prawidłowo.
12Dokument 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.
21Dokument rozpoznany częściowo lub błędnie.
22Dokument 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.
33Dokument nierozpoznany.
43Funkcja niedostępna.
53Przerwa techniczna.
63Niepoprawne zapytanie.
73Niepoprawny numer klucza.
83Brak podpisanej klauzuli RODO.Link do formularza z umową znajduje się w UriToDownload.
93Brak wykupionego pakietu przez klienta.Link do sklepu Comarch znajduje się w UriToDownload.
103Wykorzystany pakiet dokumentów.Link do sklepu Comarch znajduje się w UriToDownload.
113Klient zaznaczył dokument w którym jest więcej stron niż pozostało w pakiecie.Link do sklepu Comarch znajduje się w UriToDownload.
123Rozmiar pojedynczej strony przekracza obsługiwany limit.
133Klient został zablokowany ze względu na brak opłaconego pakietu.
143Błędny token sesji. (W przypadku korzystania z OCR API)
153Brak dostępu do API OCR (W przypadku korzystania z OCR API)
173Nierozpoznany 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"
}