API do usługi Comarch OCR (archiwum)
| Usługa | Adres |
|---|---|
| Comarch OCR | https://www.erp.comarch.pl/OCR/ |
| Comarch OCR API | https://ocr.erp.comarch.pl/v1.0/api/ |
InformacjaW 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 (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:
{
"type": "object",
"properties": {
"ExportString": {
"type": [
"string",
"null"
]
},
"Message": {
"type": [
"string",
"null"
]
},
"Code": {
"type": "integer"
},
"Status": {
"type": "integer"
},
"AdditionalMessage": {
"type": [
"string",
"null"
]
},
"UriToDownload": {
"type": [
"string",
"null"
]
}
},
"required": [
"ExportString",
"Message",
"Code",
"Status",
"AdditionalMessage",
"UriToDownload"
]
}
Struktura przykładowego pliku w formacie JSON zawartego w odpowiedzi z serwera usługi Comarch OCR.
[
{
"Fields": {
"DocumentNumber": "12/03/2019", - numer faktury
"DateOfIssue": "2018-11-08", - data wystawienia
"DateOfSale": "2018-11-08", - data sprzedaży
"DueDate": "2018-11-08", - data płatności
"PaymentForm": "gotówka", - sposób płatności
"BankAccountNumber": "11100110011001100110011001" - numer rachunku
},
"IsCorrection": true, - informacja czy faktura jest korektą
"CorrectedDocumentNumber": "11/03/2019", - numer dokumentu korygowanego
"Language": "PL", - język rozpoznany na dokumencie
"NumberOfPagesLeft": 123, - liczba stron, które pozostały do wykorzystania w pakiecie
"SellerContractor": { - dane sprzedawcy
"TIN": "1111111111",
"CompanyName": "PRZYKŁADOWA SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
"Street": "ul. Życzkowskiego",
"StreetNumber": "",
"ApartmentsNumber": "12",
"PostCode": "11-111",
"PostOffice": "Kraków",
"City": "Kraków",
"Voivodeship": "MAŁOPOLSKIE",
"ActiveVATTaxpayer": true
},
"BuyerContractor": { - dane nabywcy
"TIN": "1111111111",
"CompanyName": "PRZYKŁADOWA SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
"Street": "ul. Życzkowskiego",
"StreetNumber": "",
"ApartmentsNumber": "12",
"PostCode": "11-111",
"PostOffice": "Kraków",
"City": "Kraków",
"Voivodeship": "MAŁOPOLSKIE",
"ActiveVATTaxpayer ": true
},
"Currency": "PLN", - symbol waluty, jeżeli puste to oznacza, że waluta PLN
"VatPositions": [ - pozycje tabeli VAT
{
"VatRate": 23,
"Subtotal": -62.52,
"VAT": -14.38,
"Total": -76.9,
"VatStatus": 0 – 0 – opodatkowana, 1- zwolniona, 2- nie podlega
}
],
"PageProperties": {
"FirstPageNumber": 1, - informacja na której stronie pliku pdf znajduje się dokument
"DocumentLength": 1, - informacja ile stron posiada dokument
"PageRotation": 0 - informacja o ile stopni zgodnie z ruchem wskazówek zegara należy obrócić dokument w formacie .pdf, aby był wyświetlany poprawnie
}
"ProductItems": [ - pozycje tabeli produktów
{
"Name": "Produkt 1",
"Unit": "szt",
"ProductCode": "123456789012",
"Count": 2,
"NettoUnitPrice": 31.26,
"BruttoUnitPrice ": 39.8,
"Netto": 62.52,
"Brutto": 79.6,
"VatRate": 0.23,
"VatAmount": 14.38
}
],
"Attachment": "JVBERi0xLjQKJdP0zOEKMSAwIG9iago8…", - plik binarny przetworzonego dokumentu w formacie base64
"Barcode": { - rozpoznany na dokumencie kod kreskowy
"Text": 1, - odczytany numer
"Type": "EAN8" - rodzaj kodu kreskowego
}
"JpkCodes": [ - kody JPK_V7 występujące na fakturze
{
"Code": "GTU_01",
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)
{
"Fields": {
"DocumentNumber": "12/03/2019", - numer faktury
"DateOfIssue": "2018-11-08", - data wystawienia
"GrossPrice": "52,50", - kwota brutto
"UstIDNumber": "79865412", - numer identyfikacyjny sprzedawcy
"OrderNumber": "A123456789", - numer identyfikacyjny sprzedawcy
"PurchaseOrderNumber ": "B123456789", - numer identyfikacyjny sprzedawcy
"TaxIdentificationNumber": "B123456789", - Steuernummer sprzedawcy
"Reference": "0110454", - referencja z kodu QR
"AdditionalInformation": "0110454", - dodatkowe informacje z kodu QR
"BillInformation": "052375900000000000001765321", - informacje o rachunku z kodu QR
"EsrCode": "001104549>052375900000000000001765321+ 0110454", - kod ESR
"EsrReference": "052375900000000000001765321", - referencja z kodu ESR
"EsrSubscriberNumber": "0110454", - numer subskrybenta z kodu ESR
},
"BuyerContractor": { - dane nabywcy
"CompanyName": "Comarch",
"Street": "Maximilianstraße",
"StreetNumber": "12",
"ApartmentsNumber": "10",
"PostCode": "01010",
"City": "München ",
},
"SellerContractor": { - dane sprzedawcy, gdy nie rozpoznano UstIDNumber
"CompanyName": "Comarch",
"Street": "Friedrichtraße",
"StreetNumber": "24",
"ApartmentsNumber": "20",
"PostCode": "02020",
"City": "München ",
},
"Currency": "EUR",
"Language": "DE", - język rozpoznany na dokumencie
"NumberOfPagesLeft": 123, - liczba stron, które pozostały do wykorzystania w pakiecie
"PageProperties": {
"FirstPageNumber": 1, - informacja na której stronie pliku pdf znajduje się dokument
"DocumentLength": 1, - informacja ile stron posiada dokument
"PageRotation": 0 - informacja o ile stopni zgodnie z ruchem wskazówek zegara należy obrócić dokument w formacie .pdf, aby był wyświetlany poprawnie
}
"Attachment": "JVBERi0xLjQKJdP0zOEKMSAwIG9iago8…", - plik binarny przetworzonego dokumentu w formacie base64
}
]
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)
[
{
"Fields": {
"DocumentNumber": "12/03/2019", - numer faktury
"DateOfIssue": "2018-11-08", - data wystawienia
"DateOfSale": "2018-11-08", - data sprzedaży
"DueDate": "2018-11-08", - data płatności
},
"BuyerContractor": { - dane nabywcy
"CompanyName": "Comarch",
"Street": " Rue Paul Langevin ",
"StreetNumber": "12",
"ApartmentsNumber": "10",
"PostCode": "01010",
"City": "Paris",
},
"BuyerContractor": { - dane nabywcy
"CompanyName": "Comarch",
"Street": "Rue Paul Langevin",
"StreetNumber": "12",
"ApartmentsNumber": "10",
"PostCode": "01010",
"City": "Paris",
},
"Currency": "EUR", - symbol waluty
"Language": "FR", - język rozpoznany na dokumencie
"NumberOfPagesLeft": 123, - liczba stron, które pozostały do wykorzystania w pakiecie
"VatPositions": [ - pozycje tabeli VAT
{
"VatRate": 23,
"Subtotal": -62.52,
"VAT": -14.38,
"Total": -76.9,
"VatStatus": 0 – 0 – opodatkowana, 1- zwolniona, 2- nie podlega
}
],
"PageProperties": {
"FirstPageNumber": 1, - informacja na której stronie pliku pdf znajduje się dokument
"DocumentLength": 1, - informacja ile stron posiada dokument
"PageRotation": 0 - informacja o ile stopni zgodnie z ruchem wskazówek zegara należy obrócić dokument w formacie .pdf, aby był wyświetlany poprawnie
}
"ProductItems": [ - pozycje tabeli produktów
{
"Name": "Produit 1",
"Unit": "pcs",
"ProductCode": "123456789012",
"Count": 2,
"NettoUnitPrice": 31.26,
"BruttoUnitPrice ": 39.8,
"Netto": 62.52,
"Brutto": 79.6,
"VatRate": 0.23,
"VatAmount": 14.38
}
],
"Attachment": "JVBERi0xLjQKJdP0zOEKMSAwIG9iago8…", - plik binarny przetworzonego dokumentu w formacie base64
}
]
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"
}