API do usługi Comarch OCR (archiwum)

UsługaAdres
Comarch OCRhttps://www.erp.comarch.pl/OCR/
Comarch OCR APIhttps://ocr.erp.comarch.pl/v1.0/api/

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 (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:

{  
    "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

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