Frequently Asked Questions
Info
You can find solutions to common issues on the Troubleshooting page.
Where can I download the latest Web API version?
Please use the Regula Download Manager tool.
Note that the Regula Downloads Manager is only required for the download of the package and has no further impact on the Regula Document Reader Web API operation.
How to change the service base address?
The config file is saved under the following path:
-
C:\Program Files\Regula\Document Reader Web API.env for the х64 version
-
C:\Program Files (x86)\Regula\Document Reader Web API.env for the x86 version
To change the service base address, you need to change the value: DOCREADER_BIND="0.0.0.0:8080"
By default, the service base address is:
-
"0.0.0.0:8080" for HTTP
-
"0.0.0.0:443" for HTTPS
How to run the Web API service using HTTPS?
- Option 1. Recommended. Nginx as a reverse-proxy
Run Nginx as a frontend container for HTTPS processing and proxy service requests to the backend docreader container. See the NGINX Reverse Proxy page.
- Option 2. Docreader via HTTPS
To run the docreader service via HTTPS:
- add 644 permissions to certificates so the server is able to read certificates
- pass cert.crt & cert.key files to the container
- pass DOCREADER_CERT_FILE, DOCREADER_KEY_FILE environment variables
- forward container port to 8443 host port
chmod 644 ~/cert.crt ~/cert.key
docker run -it -p 8443:8080 -v ~/regula.license:/app/extBin/unix_x64/regula.license -v ~/cert.crt:/app/cert.crt -v ~/cert.key:/app/cert.key -e DOCREADER_CERT_FILE="/app/cert.crt" -e DOCREADER_KEY_FILE="/app/cert.key" regulaforensics/docreader
How to recognize multi-page documents?
You should submit both document pages within a single transaction as in the example below. Please, mark every separate page image with a different page index value. The transaction will be processed as usual. When the results are ready, the XML or JSON structure will contain a list with the results in accordance with the requested result type (for each page).
[
{ "Base64ImageString": "base64 string",
"Format": ".jpg",
"LightIndex": 6,
"PageIndex": 0
},
{ "Base64ImageString": "base64 string",
"Format": ".jpg",
"LightIndex": 6,
"PageIndex": 1
}
]
Where can I find logs?
You can find logs under the following directory:
C:\Program Files\Regula\Document Reader Web API\logs
The logs are turned on in the .env file of the service root: DOCREADER_PROCESS_RESULTS_LOG_PATH='logs/process/'
LOGS_ACCESS_CONSOLE="false" LOGS_ACCESS_FILE="true" LOGS_ACCESS_FILE_PATH='logs/access/document-reader-access.log'
LOGS_APP_CONSOLE="true" LOGS_APP_FILE="true" LOGS_APP_FILE_PATH='logs/app/document-reader-app.log'
Liveness/Readiness Probes
You can leverage the /api/ping endpoint for monitoring the container health and checking the availability of the container and the status of the license - expired or not.
Make sure to pick the interval between probes responsibly. A too low interval can flood the workers and affect the processing time. A too high interval can delay the identification of a malfunctioning container.
Is there a sample client available?
Sure, check out the resources below.
-
Installation Packages and Quick Start Guide: https://docs.regulaforensics.com/develop/doc-reader-sdk/web-service/installation/platforms/ There'll be options available for Windows, Linux, Docker, Kubernetes.
-
Service has integrated demo webpage for functional tests and is available http://localhost:8080
-
You are also welcome to address our Public API client Demo:
Release version: https://api.regulaforensics.com/
Nightly version: https://test-api.regulaforensics.com/
- Postman collection for testing https://www.getpostman.com/collections/5eaef8bf356619e56f19
The service API is simple: it is synchronous, has only one endpoint ~api/process~ for actual data processing, and ~api/ping~ for a health check. Results are delivered in JSON format.
SDK documentation
-
OpenAPI specification published on GitHub https://github.com/regulaforensics/DocumentReader-web-openapi
-
JavaScript client published on GitHub https://github.com/regulaforensics/DocumentReader-web-js-client with examples. npm package available https://www.npmjs.com/login?next=/package/@regulaforensics/document-reader-client
-
Java client published on GitHub https://github.com/regulaforensics/DocumentReader-web-java-client with examples. maven package available https://maven.regulaforensics.com/RegulaDocumentReaderWebClient/
-
Python client published on GitHub https://github.com/regulaforensics/DocumentReader-web-python-client with examples. pipy package available https://pypi.org/project/regula.documentreader.webclient/)
-
C# client published on GitHub https://github.com/regulaforensics/DocumentReader-web-csharp-client with examples. NuGet package is available at https://www.nuget.org/packages/Regula.DocumentReader.WebClient/
Image quality requirements: https://support.regulaforensics.com/hc/en-us/articles/360000092623-Image-quality-requirements
To receive notifications once the new SDK version is released, subscribe to updates: https://support.regulaforensics.com/hc/en-us
-
Release notes: https://downloads.regulaforensics.com/work/SDK/SDK%20Release%20Notes%20(en).pdf
-
Learn how to set initial parameters and form requests: document-reader-static-doc.html.
What capabilities value do you use on api.regulaforensics.com?
The default capabilities value used on the demo website api.regulaforensics.com is 500. It includes MRZ, Visual Zone OCR, Document Type, Visual Graphics and Barcode Processing.