Ingest Documents via JSON
Upload a sale or purchase document with JSON payload.
A maximum of 100 invoice line item objects can be ingested in one request.
POST
{{BASE_URL}}/integration/v2/ingest/json/{{templateType}}
Replace the
{{BASE_URL}}
with the one mentioned here based on whether you are using sandbox or production.Parameter | Data Type | Field Validations | Description |
---|---|---|---|
x-cleartax-auth-token | String | Cannot be empty. | |
x-cleartax-gstin | String | Cannot be empty | Mandatory. GSTIN of the taxpayer registered on CFC. |
Content-Type | String | | application/json |
Parameter | Data Type | Field Validations | Description |
---|---|---|---|
templateType | String | Enum: sales, purchase | Type of document. sales - Sales document. purchase- Purchase document. |
There are no query parameters for this API.
Parameter | Data Type | Field Validation | Description |
---|---|---|---|
userInputArgs | String | NA | |
jsonRecords | Array | MaxLength: 100 | Mandatory. An array of Sale Document Line Objects or Purchase Document Line Objects based on templateType used in the path param. |
Parameter | Data Type | Field Validation | Description |
---|---|---|---|
templateId | String | NA | Mandatory. For a sale document, the system template ID is "618a5623836651c01c1498ad". For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b". For custom upload templates, use the custom upload template ID. |
groupId | String | NA | Unique ID across the PAN to group a set of documents as a single record on the Clear Import History page. Default: Autogenerated random ID. |
settings | Object | NA |
Parameter | Data Type | Field Validation | Description |
---|---|---|---|
ignoreHsnValidation | Boolean | NA | Optional. Indicates if HSN validation has to be ignored or not. true - HSN validation error will be ignored. false - HSN validation error will not be ignored.
Default: false |
1
{
2
"userInputArgs": {
3
"templateId": "618a5623836651c01c1498ad",
4
"groupId": "TEST123",
5
"settings": {
6
"ignoreHsnValidation": true
7
}
8
},
9
"jsonRecords": [
10
{
11
"documentType": "Invoice",
12
"documentDate": "2022-11-29",
13
"documentNumber": "Inv-123",
14
15
"erpSource": "Tally",
16
"voucherNumber": "Inv-123",
17
"voucherDate": "2022-11-29",
18
19
"isBillOfSupply": "N",
20
"isReverseCharge": "N",
21
"isDocumentCancelled": "N",
22
23
"supplierName": "Defmacro Software Private Limited",
24
"supplierGstin": "29AAFCD5862R1ZR",
25
26
"customerName": "Clearsharp Technology Private Limited",
27
"customerAddress": "Cust1 Mst Addr1, Cust1 Mst Addr2, Cust1 Mst Addr3",
28
"customerState": "Karnataka",
29
"customerGstin": "29AAECC3822D1ZY",
30
"placeOfSupply": "Karnataka",
31
32
"itemDescription": "Item1",
33
"itemCategory": "G",
34
"hsnSacCode": "48",
35
"itemQuantity": 500,
36
"itemUnitCode": "PCS",
37
"itemUnitPrice": 250,
38
"itemDiscount": 0,
39
"itemTaxableAmount": 125000,
40
"cgstRate": 9,
41
"cgstAmount": 11250,
42
"sgstRate": 9,
43
"sgstAmount": 11250,
44
"igstRate": 0,
45
"igstAmount": 0,
46
"cessRate": 0,
47
"cessAmount": 0,
48
49
"documentTotalAmount": 147500
50
}
51
]
52
}
1
{
2
"userInputArgs": {
3
"templateId": "60e5613ff71f4a7aeca4336b",
4
"settings": {
5
"ignoreHsnValidation": true
6
}
7
},
8
"jsonRecords": [
9
{
10
"documentType": "Invoice",
11
"documentDate": "2022-11-29",
12
"documentNumber": "Inv-123",
13
14
"erpSource": "Tally",
15
"voucherNumber": "Inv-123",
16
"voucherDate": "2022-11-29",
17
18
"isBillOfSupply": "N",
19
"isReverseCharge": "N",
20
"isDocumentCancelled": "N",
21
22
"supplierGstin": "29AAECC3822D1ZY",
23
"supplierName": "Clearsharp Technology Private Limited",
24
"supplierAddress": "Cust1 Mst Addr1, Cust1 Mst Addr2, Cust1 Mst Addr3",
25
"supplierState": "Karnataka",
26
27
"customerGstin": "29AAFCD5862R1ZR",
28
29
"placeOfSupply": "Karnataka",
30
31
"itemDescription": "Item1",
32
"itemCategory": "G",
33
"hsnSacCode": "48",
34
"itemQuantity": 500,
35
"itemUnitCode": "PCS",
36
"itemUnitPrice": 250,
37
"itemDiscount": 0,
38
"itemTaxableAmount": 125000,
39
"cgstRate": 9,
40
"cgstAmount": 11250,
41
"sgstRate": 9,
42
"sgstAmount": 11250,
43
"igstRate": 0,
44
"igstAmount": 0,
45
"cessRate": 0,
46
"cessAmount": 0,
47
48
"documentTotalAmount": 147500
49
}
50
]
51
}
HTTP Status Code | Description |
---|---|
200 | For a successfully processed request (may be a success or validation error). |
400 | If the request schema is not valid. |
401 | If the user is not authenticated for the operation. |
403 | If the user is not authorized for the operation. |
500 | If there are any unhandled exceptions on Clear side. |
Parameter | Data Type | Field Constraints | Description |
---|---|---|---|
gstinStats | Array | NA | Upload statistics aggregated at the GSTIN level. An array of GSTIN stats object. In case of non-validation errors, this will be an empty Array ([]). |
jsonRecordErrors | Array | NA | Validation Errors. An array of JSON record error details objects. In case there are no errors, this will be an empty Array ([]). |
errors | Array | NA | Non-Validation Errors. An array of non-validation error details objects. In case there are no errors, this will be an empty Array ([]). |
Parameter | Data Type | Field Constraints | Description |
---|---|---|---|
gstin | String | NA | Seller GSTIN that these stats belong to. |
totalDocumentCount | Number | NA | Total count of documents parsed successfully. |
validRows | Number | NA | Total count of valid document line objects. |
invalidRows | Number | NA | Total count of invalid document line objects. |
Parameter | Data Type | Field Constraints | Description |
---|---|---|---|
recordIndex | Number | NA | Array index of the record in request jsonRecords. The index starts from 0. |
recordErrors | Array | NA | |
externalId | String | NA | External ID that was sent in the request to identify the document, if any. In case an external ID was not sent, this field will not exist. |
externalLineItemId | String | NA | External ID that was sent in the request to identify the document line item, if any. In case an external ID was not sent, this field will not exist. |
Parameter | Data Type | Field Constraints | Description |
---|---|---|---|
errorId | String | NA | Error ID |
columnName | Array | NA | Array of strings representing field keys in the jsonRecords of the request that has an error. |
errorMessage | String | NA | User friendly error message. |
Parameter | Data Type | Field Constraints | Description |
---|---|---|---|
errorCode | String | NA | Error code |
errorMessage | String | NA | Error message. |
errorField | | NA | Error field. |
errorValues | | NA | Error values. |
errorResolution | | NA | Error resolution. |
Success - HTTP Status Code - 200
1
{
2
"gstinStats": [
3
{
4
"gstin": "29AAFCD5862R1ZR",
5
"totalDocumentCount": 1,
6
"validRows": 1,
7
"invalidRows": 0
8
}
9
],
10
"jsonRecordErrors": [...],
11
"errors": null
12
}
Validation Error - HTTP Status Code - 200
1
{
2
"gstinStats": [
3
{
4
"gstin": "29AAFCD5862R1ZR",
5
"totalDocumentCount": 0,
6
"validRows": 0,
7
"invalidRows": 1
8
}
9
],
10
"jsonRecordErrors": [
11
{
12
"recordIndex": 0,
13
"externalId": "INVOICE_maxitc123_06ADECO9084R5Z4_29AAFCD5862R000_2022_0",
14
"externalLineItemId": "INVOICE_maxitc123_06ADECO9084R5Z4_29AAFCD5862R000_2022_0",
15
"recordErrors": [
16
{
17
"errorId": "HSN_OR_SAC_TYPE_ERROR",
18
"columnName": ["hsnSacCode"],
19
"errorMessage": "1234 is not a valid HSN "
20
}
21
]
22
}
23
],
24
"errors": null
25
}
Non-Validation Error - HTTP Status Code - 401
1
{
2
"gstinStats": [],
3
"jsonRecordErrors": [],
4
"errors": [
5
{
6
"errorCode": "AUTHORIZATION_FAILED",
7
"errorMessage": "Invalid Auth Token",
8
"errorField": null,
9
"errorValues": null,
10
"errorResolution": null
11
}
12
]
13
}
Non-Validation Error - HTTP Status Code - 500
1
{
2
"gstinStats": [],
3
"jsonRecordErrors": [],
4
"errors": [
5
{
6
"errorCode": "INTERNAL_ERROR",
7
"errorMessage": "Internal Service Error",
8
"errorField": null,
9
"errorValues": null,
10
"errorResolution": null
11
}
12
]
13
}
There are more than 200 field validations as well as business validations on the Clear API side. For data validation errors, the validation error message will be sent back in the `jsonRecordErrors` field in the response.
- 1.This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.
- 2.If the auth token is valid, but the user does not have the authorization, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have permission to create a document.
If you are integrating with Max ITC, once the documents are uploaded, trigger the reconciliation using the Trigger MaxITC Workflow API.