API do usługi Comarch OCR
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/ |
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.