Page Properties | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
In order to extract document information, the document source file should be first submitted to Gini.
Submit documents by sending a POST request to the /documents
resource path. After successful submission, the location of the new document is returned in the Location
header.
Info |
---|
Please note that we reject and don’t process files with wrong format or bad quality. In this case we return 400 error in the response message. |
The Gini Pay API currently supports two different variants of uploads, one optimized for web applications running in a web browser and the other for all other types of clients. The first variant optimized for web applications expects the documents to be uploaded using a multipart/form-data
encoding method. The second variant for all other clients simply uses the request body (independent of the request Content-Type
) as the document.
Code Block | ||
---|---|---|
| ||
//documents can be submitted by doing a POST request to the /documents resource.
POST /documents |
...
Supported file formats
Gini supports PDF files, GIF files (non-animated), PNG files, JPEG files, TIFF files as well as plain text formats (including parsed QR codes). You can use native documents (PDF only) and scanned documents (all other supported formats).
...
The above applies both to single-page documents as well as and to each page in multi-page multipage documents.
...
Document uploading schemes
...
This is the standard way of uploading a document to the Gini extraction system. A PDF document can contain single or multiple pages. JPEG and PNG documents are also accepted. When it is uploaded, it the document is processed by the system normally and without any adjustments regarding its structure.
Request
Headers
Header | Value |
---|---|
|
|
| |
|
|
|
|
|
|
The x-document-metadata-*
headers are used to add some meta information to the upload. This information is used in analytics and reporting.
branchid
is used to group uploads from a specific client, for example, branches for banksdeviceclass
specifies from which kind of device the upload comes, for example, if it was uploaded from a desktop computer or a smartphone
Requesting
...
query parameters
If the upload is performed without multipart/form-data
you can optionally provide a file name for the submitted document with a query parameter:
Name | Type | Description |
---|---|---|
|
|
Optional |
: File name of the submitted document. |
Body
Only in case of Content-Type: multipart/form-data
(applications running in a web browser):
Key | Description |
---|---|
|
|
| File contents of document. |
Response
Headers
Status Code | Description |
---|---|
201 (Created) | Operation is successful. |
Header | Value |
---|---|
|
|
| Absolute URI (created document URI). Can be used to check progress and receive document information. |
Errors
Status Code | Description |
---|---|
400 (Bad Request) | Returned when a file is sent in an invalid format or has a bad quality which we are unable to process. |
401 (Unauthorized) | Authorization credentials are either missing, wrong or outdated. |
415 | Content type is not supported. |
503 | Service unavailable. |
Try again later. |
Code Block | ||
---|---|---|
|
...
//upload a document
variant for web applications running in a web browser with access token:
curl -H 'Authorization: BEARER <token>'
--form 'file=@file.pdf'
-H 'Accept: application/vnd.gini.v1+json'
-i https://pay-api.gini.net/documents
variant for all other types of applications:
curl -H 'Authorization: BEARER <token>'
--data-binary '@file.pdf'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/pdf'
-i https://pay-api.gini.net/documents?filename=file.pdf
or with X-User-identifier (see how to setup X-User-identifier):
curl -H 'X-User-Identifier: user1'
--form 'file=@file.pdf'
-H 'Accept: application/vnd.gini.v1+json'
-u 'client-id:client-secret'
-i https://pay-api.gini.net/documents |
...
Upload a document page by page
Partial upload should be performed in two steps: partial document upload and composite document upload. Complete
Note |
---|
Please complete Step 1 |
...
before moving to Step 2! |
Step 1 (upload each page as a partial document)
Pages that are part of the document are referred to as partial documents. If you want to upload a page (or a page picture) that belongs to the document, your request header should additionally include Content-Type
field with application/vnd.gini.v1.partial+png
value or application/vnd.gini.v1.partial+pdf
in case of PDF page. See the examples below.
In case you want to submit a parsed QR code, please use application/vnd.gini.v1.partial+qr+json
. The parsing of the QR fields is optional. The paymentdata
needs to contain at least the iban
and the paymentRecipient
keys. Hence, the minimal valid QR code body could be the following:
Code Block | ||
---|---|---|
| ||
{
"qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65¤cy=EUR",
"paymentdata": {
"iban": "DE01234567898765432101",
"paymentRecipient": "Telekom GmbH"
}
} |
Mandatory QR fields
Key | Value |
---|---|
|
|
|
|
Optional QR fields
Key | Value |
---|---|
|
|
|
|
|
|
See the complete QR request example below.
Request
In order to upload a page picture or a partial document, specify a different content type:
Info |
---|
application/vnd.gini.v1.partial+<FILE_TYPE> For example, `applicationapplication/vnd.gini.v1.partial+png` png for images |
Headers
Header | Value |
---|---|
|
|
| |
|
|
|
|
|
|
The x-document-metadata-*
headers can be used to add some meta information to the upload. This information is used in analytics and reporting.
branchid
is used to group uploads from a specific client (eg e.g. branches for banks)deviceclass
specifies from which kind of device the upload comes from. E. Egg. if it was uploaded from a desktop computer or a smart phonesmartphone.
Request
...
query parameters
Name | Type | Description |
---|---|---|
|
|
Optional |
: File name of the submitted document. |
Body
File contents of the document.
Response
Headers
Status Code | Description |
---|---|
201 (Created) | Operation is successful. |
Header | Value |
---|---|
|
|
| Absolute URI (created partial document URI) which should be referred by a composite document. |
Errors
Status Code | Description |
---|---|
400 (Bad Request) | Returned when the sent file has invalid format or has a bad quality which we are unable to process. |
401 (Unauthorized) | Authorization credentials are either missing, wrong or outdated. |
415 | Content type is not supported. |
503 | Service unavailable. |
Try again later. |
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||
---|---|---|
| ||
//upload a partial document
//variant for web applications running in a web browser with access token:
curl -H 'Authorization: BEARER <token>'
--form 'file=@file.JPEG'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.partial+png'
-i https://pay-api.gini.net/documents
//variant for other types of applications with access token:
curl -H 'Authorization: BEARER <token>'
--data-binary '@file.JPEG'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.partial+png'
-i https://pay-api.gini.net/documents?filename=file.JPEG
//or with X-User-identifier (see how to setup X-User-identifier):
curl -H 'X-User-Identifier: user1'
--form 'file=@file.JPEG'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.partial+png'
-u 'client-id:client-secret'
-i https://pay-api.gini.net/documents
// variant for QR code
curl -H 'Authorization: BEARER <token>'
--form 'data.json={
"qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65¤cy=EUR",
"paymentdata": {
"amountToPay": "25.79:EUR",
"paymentRecipient": "Telekom GmbH",
"iban": "DE01234567898765432101",
"bic": "SPESDE3EXXX",
"paymentReference": "Nr.12345"
}
}'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.partial+png'
-i https://pay-api.gini.net/documents |
Step 2 (upload JSON as a composite document)
After successfully uploading all pages as partial documents, announce their locations to the extraction system by uploading a composite document, which is a simple JSON file with corresponding locations of partial documents.
...
Info |
---|
application/vnd.gini.v1.composite+json |
Headers
Header | Value |
---|---|
|
|
|
|
Request
...
query parameters
If the upload is performed without multipart/form-data
, you can optionally provide a file name for the submitted document with a query parameter:
Name | Type | Description |
---|---|---|
|
|
Optional |
: File name of the submitted document. |
Body
Raw bytes of the composite JSON.
Key | Description |
---|---|
| A list of partial documents (the location is returned after the partial documents are successfully uploaded). |
Response
Headers
Status Code | Description |
---|---|
201 (Created) | Operation is successful. |
Header | Value |
---|---|
|
|
| Absolute URI of created document (document URI) to check progress and getting document information. |
Errors
Status Code | Description |
---|---|
400 (Bad Request) | Returned when a file was sent in an invalid format |
or has a bad quality which we are unable to process. | |
401 (Unauthorized) | Authorization credentials are either missing, wrong or outdated. |
415 |
Content type not supported. | |
503 | Service unavailable. |
Try again later. |
Code Block |
---|
//upload a composite document
//variant for web applications running in a web browser with access token:
curl -H 'Authorization: BEARER <token>'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.composite+json'
-X POST -d'{...}'
-i https://pay-api.gini.net/documents
//or
curl -H 'Authorization: BEARER <token>'
--data-binary '@data.json'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.composite+json'
-i https://pay-api.gini.net/documents
//or with X-User-identifier (see how to setup X-User-identifier):
curl -H 'X-User-Identifier: user1'
-H 'Accept: application/vnd.gini.v1+json'
-H 'Content-Type: application/vnd.gini.v1.composite+json'
-u 'client-id:client-secret'
-X POST - d'{...}'
-i https://pay-api.gini.net/documents
//with post body of
{
"partialDocuments": [
{
"rotationDelta": 0,
"document": "localtion of parital doc 1"
},
{
"rotationDelta": 0,
"document": "location of partial doc 2"
},
...
]
}
//location in form of https://pay-api.gini.net/documents/e8606210-56ed-11ea-b823-b351b84ae4b3 |