...
Types of payment summaries
positive summary (preferred): the extraction was correct and confirmed by the user without modification.
complementary summary: the extraction system extracted nothing, for example, the response doesn't contain the requested label. The user manually entered the correct value.
negative summary: the extraction was incomplete or erroneous. The user manually corrected the extraction.
informative summary: the extraction was changed for another reason, for example, if a line item is returned, the quantity extraction gets summary "0" and a return reason.
...
| Code Block | ||
|---|---|---|
| ||
//submitting payment summary on extractions
PUT /documents/{id}/extractions/feedback |
| Note |
|---|
IMPORTANT! In REST requests, the payment summary is called feedback. Hence, in the examples below, “feedback” is payment summary. |
Request
Headers
Header | Value |
|---|---|
|
|
...
Status Code | Description |
|---|---|
204 (No Content) | The payment summary was successfully processed. |
404 (Not Found) | The document or the label could not be found. |
406 (Not Acceptable) | The request headers were not set correctly. |
422 (Unprocessable Entity) | At least one value was not valid regarding entity validation rules of the label. |
Test example
In order to test the integration of the summary functionality, we offer a PDF test document with the expected outcome in a JSON format. This document can be used for an integration test of Gini’s Pay API in general. Furthermore, we provide a query for sending summary where all fields are correct except for the amountToPay. After sending this summary, we show you how to ensure that the summary with your confirmation and correction for the field values was successful.
Sending the test document to the Gini Pay API. See Submit Files.
Requesting the results. See Retrieve Extractions.
You should get a JSON like in the example.
Correcting the document with the following JSON. Here we change the
amountToPayfrom "995.00:EUR" to "950.00:EUR" and confirm the other field values (iban,bic,paymentRecipient,paymentReference).
| Code Block | ||
|---|---|---|
| ||
{
"feedback": {
"amountToPay": {
"value": "950.00:EUR"
},
"iban": {
"value": "DE68130300000017850360"
},
"bic": {
"value": "BYLADEM1001"
},
"paymentPurpose": {
"value": "RE-20170512-02"
},
"paymentRecipient": {
"value": "Fahrrad Rückenwind"
}
}
} | ||
| Code Block | ||
|
Below we show a more elaborated example here in order to explain different types of the payment summary. The example scenario is as follows: the user uploads a document where the labels amountToPay, paymentReference, iban are extracted. Unfortunately, the label paymentRecipient could not be extracted. The response to the extractions request is as follows:
| Info |
|---|
The boxes are optional. Boxes should only be sent if your use case visualizes the document with the locations of the extractions. Thus, the user can confirm the correct location of an extraction. |
| Code Block | ||
|---|---|---|
| ||
{ "candidates": { }, "extractions": { "amountToPay": { "box": { "height": 8.0, "left": 545.0, "page": 1, "top": 586.0, "width": 17.0 }, "candidates": "amounts", "entity": "amount", "value": "5.60:EUR" }, "iban": { "box": { "height": 7.0, "left": 447.0, "page": 1, "top": 746.0, "width": 100.0 }, "candidates": "ibans", "entity": "iban", "value": "DE68130300000017850360" }, "paymentReference": { "entity": "reference", "value": "ReNr 123, KdNr 32" } }, "compoundExtractions": { "lineItems": [ { "artNumber": { "value": "10101", "entity": "text" , "box": { "height": 7.0, "left": 55.0, "page": 1, "top": 546.0, "width": 100.0 } }, "quantity": { "value": "12", "entity": "numeric" } }, { "artNumber": { "value": "10103", "entity": "text" }, "quantity": { "value": "3", "entity": "numeric" } } ] } } // |
The
...
user
...
adds
...
the missing
...
paymentRecipient
...
value
...
(complementary
...
summary)
...
and
...
corrects
...
the
...
paymentReference
...
to
...
"ReNr
...
1735,
...
KdNr
...
37"
...
(negative
...
summary).
...
Sets
...
the
...
quantity
...
of
...
one
...
line
...
item
...
to
...
0
...
and
...
adds
...
a
...
reason
...
for
...
returning
...
the
...
articles.
...
The
...
iban,
...
amountToPay
...
and
...
the
...
remaining
...
part
...
of
...
lineItems
...
are
...
correct
...
(positive
...
summary).
...
The
...
document
...
is
...
not
...
shown,
...
so
...
we
...
can
...
leave
...
out
...
the
...
boxes.
...
Then
...
the
...
resulting
...
summary request
...
is
...
as
...
follows:
...
| Code Block | ||
|---|---|---|
| ||
{
"extractions": {
"amountToPay": {
"value": "5.60:EUR"
},
"iban": {
"value": "DE68130300000017850360"
},
"paymentReference": {
"value": "ReNr 1735, KdNr 37"
},
"paymentRecipient": {
"value": "Zalando SE"
}
},
"compoundExtractions": {
"lineItems": [
{
"artNumber": {
"value": "10101"
},
"quantity": {
"value": "0"
},
"returnReason": {
"value": "r3"
}
},
{
"artNumber": {
"value": "10103"
},
"quantity": {
"value": "3"
}
}
]
}
}
Give summary and correct or verify multiple specific labeled extraction patterns with a single PUT or POST request to the document extractions URI.
The labels must correspond to the names of the extraction types e.g. amountToPay. See available specific extractions for possible values.
Headers
Header Value
Content-Type application/vnd.gini.v1+json
Body
Key Type Description
extractions object Summary on atomic extractions
compoundExtractions object Summary on compound extractions
The boxes are optional. Boxes should only be sent if your use case visualize the document with the locations of the extractions. Thus, the user can confirm the correct location of a extraction.
Response
Status Code Description
204 (No Content) The summary was successfully processed.
404 (Not Found) The document or the label could not be found.
406 (Not Acceptable) The request headers were not set correctly.
422 (Unprocessable Entity) At least one value was not valid regarding entity validation rules of the label.
Test Example
In order to test the integration of the summary functionality, we offer a PDF test document with the expected outcome in a JSON format. This document can be used for an integration test of Gini’s Pay API in general. Furthermore, we provide a query for sending feedback where all fields are correct except for the amountToPay. After sending this feedback we show you how you can ensure that the feedback with your confirmation and correction for the field values was successful.
Sending the test document to the Gini Pay API (see also submitting files)
Requesting the results (see also retrieving extractions)
You should get a JSON like in example.
Correcting the document with the following JSON (see also submitting summary on extractions). Here we change the amountToPay from "995.00:EUR" to "950.00:EUR" and confirm the other field values (iban, bic, paymentRecipient, paymentReference).
{
"feedback": {
"amountToPay": {
"value": "950.00:EUR"
},
"iban": {
"value": "DE68130300000017850360"
},
"bic": {
"value": "BYLADEM1001"
},
"paymentPurpose": {
"value": "RE-20170512-02"
},
"paymentRecipient": {
"value": "Fahrrad Rückenwind"
}
}
} |
Submit payment summary on invalid extractions
...
Then the resulting payment summary request is as follows:
| Code Block | ||
|---|---|---|
| ||
{
"feedback": {
"amountToPay": {
"value": "950.00:EUR"
},
"iban": {
"value": "DE68130300000017850360"
},
"bic": {
"value": "BYLADEM1001"
},
"paymentPurpose": {
"value": "RE-20170512-02"
},
"paymentRecipient": {
"value": "Fahrrad Rückenwind"
}
}
} |
Submit payment summary on invalid extractions
Request
In case an extraction was erroneously found (i.e. not present in the source document), you can delete it by issuing a DELETE request to the extraction URI:
| Code Block | ||
|---|---|---|
| ||
//submitting summary on invalid extractions
DELETE /documents/{id}/extractions/{label} |
Response
Status Code | Description |
|---|---|
204 (No Content) | Label removal was successful. |
404 (Not Found) | The document or the label could not be found. |
...
| language | json |
|---|
...