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