Spis treści
- Tworzenie sesji użytkownika (POST)
- Usuwanie sesji użytkownika (DELETE)
- Przetwarzanie dokumentu (POST)
| Usługa | Adres |
|---|---|
| Comarch OCR – panel do zarządzania | https://www.erp.comarch.pl/OCR/ |
| Comarch OCR - API | https://cr.erp.comarch.pl/api/v1/ |
Informacja
W celu korzystania z usługi Comarch OCR należy odblokować komunikację do adresów *.erp.comarch.pl na porcie 443 (SSL).
W pierwszym kroku należy zalogować się w aplikacji Comarch OCR i wygenerować klucze dostępowe.
Metody
Tworzenie sesji użytkownika „session” (POST)
Adres: https://cr.erp.comarch.pl/api/v1/session
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 „session” (DELETE)
Adres: https://cr.erp.comarch.pl/api/v1/session
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 |
Adres: https://cr.erp.comarch.pl/api/v1/invoice/recognize
Opis struktury JSON zapytania
| Property | Opis |
|---|---|
| File | Plik o rozszerzeniu *.jpg, *.png, *bmp lub *.pdf w postaci binarnej |
| Guid | Opcjonalne - GUID |
| RecognizeConfiguration.RecognitionLanguage | 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) |
| RecognizeConfiguration.ReturnData | Opcjonalny - informacja czy usługa ma w odpowiedzi odesłać pliki dla przetworzonych dokumentów 0 – bez plików 1 – z plikami (domyślnie – opcja 0) |
| RecognizeConfiguration.BarCodeRecognition | Opcjonalny - informacja czy należy rozpoznawać kody kreskowe da dokumentach, 0 - nie rozpoznaje kodów 1 - rozpoznaje kody 2 - łączy strony na podstawie rozpoznanych kodów (domyślnie – opcja 0) |
| RecognizeConfiguration.MergingPagesOption | Opcjonalny - informacja czy należy rozpoznawać kody kreskowe da dokumentach, 0 - nie rozpoznaje kodów 1 - rozpoznaje kody 2 - łączy strony na podstawie rozpoznanych kodów (domyślnie – opcja 0) |
| RecognizeConfiguration.ReturnDocumentPositions | Opcjonalny – czy na rozpoznanych dokumentach mają być zwrócone poszczególne pozycje z tabeli produktów 0 – bez pozycji 1 – z pozycjami (domyślnie – opcja 0) |
| RecognizeConfiguration.PaymentMethodMapping | Opcjonalny – czy na rozpoznanych dokumentach metoda płatności ma być mapowana do standardowych form płatności czy odczytana zgodnie z treścią na dokumencie 0 – bez mapowania 1 – z mapowaniem (domyślnie – opcja 0) |
| RecognizeConfiguration.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 (domyślnie – opcja 0) |
| RecognizeConfiguration.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”) (domyślnie – brak) |
| RecognizeConfiguration.PagesToRecognize | Opcjonalny – informacja o numerze NIP kontrahenta który wysyła dokument (np. "1234567890") (domyślnie – brak) |
| RecognizeConfiguration.DateRange | Opcjonalny – informacja jakie daty na dokumencie mają zostać uwzględnione w rozpoznaniu (np. "1.01.2023-31.12.2023") (domyślnie – brak) |
| RecognizeConfiguration.RegisterType | Opcjonalny – typ rejestru, który ma być uwzględniony przy rozpoznaniu 0 – rejestr zakupu 1 – rejestr sprzedaży (domyślnie – rejestr zakupu) |
W nagłówku zapytania należy dołączyć następujące wartości:
| Klucz | Wartość |
|---|---|
| authToken | Token sesji |
Schemat zapytania (request body):
| Parametr | File to recognize |
|---|---|
| File string($binary) | |
| Guid string | |
| ErpModule string | |
| RecognizeConfiguration.RegisterType integer($int32) | 1 = Purchase 2 = Sale |
| RecognizeConfiguration.RecognitionLanguage integer($int32) | 0 = PL 1 = DE 2 = FR 3 = EN -1 = UNSET |
| RecognizeConfiguration.ReturnData integer($int32) | 0 = WithoutData 1 = WithData |
| RecognizeConfiguration.BarCodeRecognition integer($int32) | 0 = NoRecognition 1 = CodeRecognition 2 = DocumentBundleRecognition |
| RecognizeConfiguration.MergingPagesOption integer($int32) | 0 = MergingAlgorithm 1 = FileIsOneDocument |
| RecognizeConfiguration.ReturnDocumentPositions integer($int32) | 0 = WithPositions 1 = WithoutPositions |
| RecognizeConfiguration.PaymentMethodMapping integer($int32) | 0 = WithoutMapping 1 = WithMapping |
| RecognizeConfiguration.RawRecognitionText integer($int32) | 0 = WithoutRawRecognitionText 1 = WithRawRecognitionText |
| RecognizeConfiguration.DefaultPaymentForm string | |
| RecognizeConfiguration.PagesToRecognize string | |
| RecognizeConfiguration.ConfigurationNipNumber string | |
| RecognizeConfiguration.DateRange string |
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
Kod 200
{
"invoices": [
{
"recognizedElements": {
"documentNumber": "string",
"kSeFNumber": "string",
"dateOfIssue": "string",
"dateOfSale": "string",
"dueDate": "string",
"paymentForm": "string",
"bankAccountNumber": "string",
"orderNumber": "string",
"isCorrection": true,
"correctedDocumentNumber": "string",
"currency": "string",
"currencyExchange": {
"rate": 0,
"multiplier": 0,
"date": "string"
},
"language": "string",
"carBodyNumber": "string",
"isDateInRange": true
},
"sellerContractor": {
"tin": "string",
"companyName": "string",
"street": "string",
"streetNumber": "string",
"apartmentsNumber": "string",
"postCode": "string",
"postOffice": "string",
"city": "string",
"voivodeship": "string",
"activeVATTaxpayer": true
},
"buyerContractor": {
"tin": "string",
"companyName": "string",
"street": "string",
"streetNumber": "string",
"apartmentsNumber": "string",
"postCode": "string",
"postOffice": "string",
"city": "string",
"voivodeship": "string",
"activeVATTaxpayer": true
},
"vatPositions": [
{
"vatRate": 0,
"vatRateDecimal": 0,
"vatStatus": 0,
"subtotal": 0,
"vat": 0,
"total": 0
}
],
"pageProperties": {
"firstPageNumber": 0,
"documentLength": 0,
"pageRotation": 0
},
"pages": [
{
"pageNumber": 0,
"image": "string",
"rawText": "string"
}
],
"productItems": [
{
"name": "string",
"unit": "string",
"productCode": "string",
"ean": "string",
"contractNumber": "string",
"count": {
"value": 0,
"status": 0
},
"nettoUnitPrice": {
"value": 0,
"status": 0
},
"bruttoUnitPrice": {
"value": 0,
"status": 0
},
"netto": {
"value": 0,
"status": 0
},
"brutto": {
"value": 0,
"status": 0
},
"vatRate": {
"value": 0,
"status": 0
},
"vatAmount": {
"value": 0,
"status": 0
},
"vatStatus": {
"value": 0,
"status": 0
},
"discount": {
"value": 0,
"status": 0
}
}
],
"attachment": {
"canRead": true,
"canWrite": true,
"canSeek": true,
"canTimeout": true,
"length": 0,
"position": 0,
"readTimeout": 0,
"writeTimeout": 0
},
"fileUrl": "string",
"barcode": {
"text": "string",
"type": "string"
},
"barcodes": [
{
"text": "string",
"type": "string"
}
],
"guid": "string"
}
],
"message": "string",
"url": "string",
"numberOfPagesLeft": 0,
"guid": "string"
}
Kod 400
{
"httpCode": 0,
"internalErrorCode": 0,
"message": "string",
"url": "string"
}
Kod 403
{
"httpCode": 0,
"internalErrorCode": 0,
"message": "string",
"url": "string"
}
Kod 415
{
"httpCode": 0,
"internalErrorCode": 0,
"message": "string",
"url": "string"
}
Tabela błędów metody „invoice/recognize” w przypadku kodu błędu >= 400
| HttpCode | InternalErrorCode | Opis | Dodatkowe informacje |
|---|---|---|---|
| 401 | 101 | Błąd podczas autentykacji użytkownika | |
| 401 | 102 | Niepoprawny numer klucza | |
| 503 | 104 | Przerwa techniczna | |
| 401 | 105 | Token sesji wygasł lub jest niepoprawny | |
| 401 | 106 | Brak podpisanej klauzuli RODO | Link do formularza z umową w 'Url' |
| 402 | 107 | Brak wykupionego pakietu przez klienta | |
| 401 | 108 | Klient został zablokowany ze względu na brak opłaconego pakietu | |
| 401 | 109 | Brak dostępu do API OCR (autentykacja przez token) | |
| 401 | 110 | Wykorzystany pakiet dokumentów | Link do sklepu w 'Url' |
| 401 | 111 | Brak wystarczającej liczby dokumentów w pakiecie | Link do sklepu w 'Url' |
| 500 | 112-116,199 | Błędy po stronie serwera | |
| 401 | 117 | Błąd podczas autentykacji użytkownika z wykorzystaniem NIPu | |
| 503 | 118 | Przerwa serwisowa | |
| 400 | 119 | Niepoprawny parametr | Nazwa parametru w 'Message' |
| 401 | 101 | Błąd podczas autentykacji użytkownika | |
| 401 | 102 | Niepoprawny numer klucza | |
| 503 | 104 | Przerwa techniczna | |
| 401 | 105 | Token sesji wygasł lub jest niepoprawny |
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.