API do usługi Comarch OCR

Spis treści


UsługaAdres
Comarch OCR – panel do zarządzaniahttps://www.erp.comarch.pl/OCR/
Comarch OCR - APIhttps://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:

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 „session” (DELETE)

Adres: https://cr.erp.comarch.pl/api/v1/session

 

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

Adres: https://cr.erp.comarch.pl/api/v1/invoice/recognize

 

Opis struktury JSON zapytania

PropertyOpis
FilePlik o rozszerzeniu *.jpg, *.png, *bmp lub *.pdf w postaci binarnej
GuidOpcjonalne - GUID
RecognizeConfiguration.RecognitionLanguageOpcjonalny - 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.ReturnDataOpcjonalny - 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.BarCodeRecognitionOpcjonalny - 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.MergingPagesOptionOpcjonalny - 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.ReturnDocumentPositionsOpcjonalny – 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.PaymentMethodMappingOpcjonalny – 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.RawRecognitionTextOpcjonalny – 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.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”)
(domyślnie – brak)
RecognizeConfiguration.PagesToRecognizeOpcjonalny – informacja o numerze NIP kontrahenta który wysyła dokument (np. "1234567890")
(domyślnie – brak)
RecognizeConfiguration.DateRangeOpcjonalny – informacja jakie daty na dokumencie mają zostać uwzględnione w rozpoznaniu (np. "1.01.2023-31.12.2023")
(domyślnie – brak)
RecognizeConfiguration.RegisterTypeOpcjonalny – 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:

KluczWartość
authTokenToken sesji

Schemat zapytania (request body):
ParametrFile 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

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
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
HttpCodeInternalErrorCodeOpisDodatkowe informacje
401101Błąd podczas autentykacji użytkownika
401102Niepoprawny numer klucza
503104Przerwa techniczna
401105Token sesji wygasł lub jest niepoprawny
401106Brak podpisanej klauzuli RODOLink do formularza z umową w 'Url'
402107Brak wykupionego pakietu przez klienta
401108Klient został zablokowany ze względu na brak opłaconego pakietu
401109Brak dostępu do API OCR (autentykacja przez token)
401110Wykorzystany pakiet dokumentówLink do sklepu w 'Url'
401111Brak wystarczającej liczby dokumentów w pakiecieLink do sklepu w 'Url'
500112-116,199Błędy po stronie serwera
401117Błąd podczas autentykacji użytkownika z wykorzystaniem NIPu
503118Przerwa serwisowa
400119Niepoprawny parametrNazwa parametru w 'Message'
401101Błąd podczas autentykacji użytkownika
401102Niepoprawny numer klucza
503104Przerwa techniczna
401105Token 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.