Using Postman with DocDigitizer PowerCapture API
Brief description how to use DocDigitizer PowerCapture API using Postman
In this tutorial, we'll lead you through the basic steps on how to integrate with DocDigitizer PowerCapture API using Postman.
DocDigitizer PowerCapture API is a REST API that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.
For this tutorial, use a standard Customer scenario using Windows App Postman.
You can download the app from Postman
If you aren't familiar with Postman, please check the following resources:
Postman Learning
Postman Getting Started
Request access
The first step is to request DocDigitizer to create an Account.
To request a Free Trial Account, go to this below link and fill out the request form.
Free Trial Account
After you will receive an email with information to help get started and with Postman Collection.
The Postman Collection is already configured with API_KEY that authorizes access to the DocDigitizer PowerCapture API and also identifies the organization/company/entity.
Setup Postman Collection
Open Postman and import the Collection file that you received.
Process flow overview
The standard customer scenario involves 3 requests to DocDigitizer PowerCapture API, and as an optional service, DocDigitizer sends notifications about the status of the document submitted client side.
HTTP Headers & Authorization
As previously mentioned, for your request to be authorized you need API_KEY.
Click on one of the requests and go to the "Header" tab and check KEY "Authorization" where you can see your API_KEY.
The Content-Type = "multipart/form-data" is needed only for the "Submit document," because in this service you are sending files (encode the data that forms the body of the request).
Submit document
Purpose: submit a file for processing indicating the class of the document. In the response, there is the value of “document_id” that identifies the submission
Method: POST
Path Parameters:
document_class: “financial-document”
The “Document Class” in the scope of Free Trial Accounts are: “Financial Documents”
To obtain information about these types of documents (Invoice, Credit Note, etc.) in the scope of “Financial Documents” and their rules, please consult Guides Financial Documents
To get detailed information about fields extracted from “Financial Documents” and the meaning of each file, please consult Data Schema
Body Parameters:
files: file to submitted to extract datacallback_url: (optional parameter) you can add the URL of your service to receive a notification when there is a change in the status of the document submitted (e.g. review process finished).
When sending the request, in case of Accepted (Status=202), you will receive a response similar to the following:
{
"detail": "Accepted",
"status": 202,
"task": {
"created": "2021-11-02T12:14:26.564283",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"links": {
"self": "/api/v1/tasks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"collection": "/api/v1/tasks"
},
"status": "PENDING"
}
}
To get the ID of documents submitted to the DocDigitizer platform, you need to check the Header of the response.
On the Postman response area, go to the "Header" tab and check KEY X-Document-Location
The document ID value is the GUID that you find at end of the URL (see image below).
This value will be used on the next services.
Receive data extracted from the document
Purpose: Get data extract from any given document
Method: GET
Path params:
document_id: (if callback) Id send in the notification service; Id receive "Submit Document"
For this tutorial we will assume that there is no service (callback) to receive the notification.
Use the Document Id receive on the "Submit Document" and used when calling this service.
When you call this service, check the response and see values:
- "reviewed": if True this means that the process of this document has finished, otherwise (False) reviewed process is still "running."
If True check "annotations" group that will have data extracted (when reviewed is False the fields can have values but the the validation/human process is not finished) - "rejected": If True, this means that the process has finished and the document was rejected.
Note: The extraction/reviewed process is asynchronous and by default (as is the case of Free Trial Account) involves “Human Revision.”
For this reason, the data extract will not be immediately available, having an SLA of 30 minutes
To get detailed information about fields extracted from “Financial Documents” and the meaning of each file, please consult Data Schema
{
"status": 200,
"detail": "Ok",
"document": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"annotation_status": "success",
"reviewed": true,
"context": "[email protected]",
"rejected": false,
"annotations": {
"links": {
"self": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/annotations",
"document": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"data": {
"document:financial-document:document_type": "Invoice",
"document:financial-document:supplier_name": "ACME LDA",
"document:class": "financial-document",
"document:financial-document:due_date": "2021-01-31T00:00:00",
"document:financial-document:amount_tax_total": "28.52",
"document:financial-document:tax_breakdown": [
{
"tax_total": "152.52",
"tax_rate": "0.23",
"tax_base": "124.00",
"tax_amount": "28.52",
"tax_code": "IVA"
}
],
"document:financial-document:amount_rounding": "",
"document:financial-document:amout_base_total": "124.00",
"document:financial-document:currency": "EUR",
"document:financial-document:document_identifier": "FT A/173",
"document:financial-document:amount_total": "152.52",
"document:financial-document:order_number": [],
"document:financial-document:line_items": [
{
"item_base_amount": "2.00",
"item_base_total_amount_base": "4.00",
"item_tax": "",
"item_code": "",
"item_description": "CUSTOM - CANDIDATURAS",
"item_unit": "",
"item_amount": "",
"item_amount_total": "4.92",
"item_rate": "0.23",
"item_order_number": "",
"item_quantity": "2.0"
},
{
"item_code": "",
"item_amount_total": "147.60",
"item_base_amount": "40.00",
"item_amount": "",
"item_tax": "",
"item_base_total_amount_base": "120.00",
"item_rate": "0.23",
"item_order_number": "",
"item_description": "CUSTOM - DESCRIPTION",
"item_unit": "",
"item_quantity": "3.0"
}
],
"document:financial-document:recipient_tax_number": "506412580",
"document:financial-document:issue_date": "2021-01-31T00:00:00",
"document:financial-document:amount_due": "152.52",
"document:financial-document:recipient_name": "ACME SERVICES, S.A.",
"document:financial-document:amount_paid": "",
"document:financial-document:supplier_tax_number": "123456789"
}
},
"created": "2021-10-29T10:48:51.813448+00:00",
"tags": [],
"links": {
"self": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"collection": "/api/v1/documents",
"reviews": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/reviews",
"annotations": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/annotations",
"assets": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/assets"
},
"review_date": "2021-10-29T11:07:04.876735+00:00"
}
}
In the scenario that you supplied "callback_url" (Notification service), call this service when receiving “Notification” with “status“=“annotated” (passing the corresponding “document_id”)
Get rejection information
Reject a document
Purpose: Get information about rejection of a document of given document
Method: GET
Path params:
document_id: id send in the notification
Call this service when receiving a response with "rejected"=True
You will receive a response with information about the rejection.
{
"status": 200,
"detail": "Ok",
"rejection": {
"rejected_at": "2021-07-09T15:04:55.555487+00:00",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"justification_code": "OTHER",
"justification": "Invalid document type"
}
}
Noification Service
Notification
Purpose: Receive notification about a change in the status of the submitted document
Service to be provider by the Customer
Method: GET
Parameters:
document_id: id of the documentstatus: status of the document (annotated, rejected, …)
For more information see Callback service (status notification)
Next steps
Postman lets you explore the DocDigitizer PowerCapture API and easily add or change any requests that you want to test.
You can use the requests that came with the Collection provided and transform them into program code.
Postman offers functionalities to transform the request you issue with its Generate Code Snippets tool.
Updated almost 2 years ago