The CereTax Batch API supports uploading a batch file of transactions for processing. Creating a transaction batch using the CereTax API involves the following steps:
- Create a batch record and generate a tokenized url for uploading your batch file
- Upload your batch file to the CereTax-generated url
- Confirm your batch file completed processing and download results
Example
1. Create a batch record and generate a tokenized url for uploading your batch file
In this step, you will call the [Create or retrieve a batch](Create or retrieve a batch) endpoint, which will create a record for your batch in the CereTax system, assign it a unique id, and generate a url for you to upload your batch file to.
The name of the file you upload must match the file name stated in this step.
curl --location 'https://batch.cert.ceretax.net/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
"command": "upload",
"fileName": "August2023_Batch_Upload.xlsx",
"batchName": "August 2023 Batch Upload",
"requestType":"telco"
}
'
In the response below, you can see that CereTax was able to create a record for the batch and respond back with a tokenized url that can be used to upload the batch file in the next step. A batchId is also provided in the response, which can be used to retrieve the status of the batch after your batch file is uploaded.
Batch upload url expires after 15 mins
The url returned in this request for uploading your batch file will be valid for 15 mins. After 15 mins, a new url will need to be generated by creating a new batch record.
{
"success": true,
"url": "https://...",
"batchId": "29iNnnfesNoBTO8o0wQDZpna5Vo",
"status": "",
"error": ""
}
2. Upload your batch file to the CereTax-generated url
In this step, you will perform a PUT request against the url generated in Step 1. In this example, an excel file is being upload. Content-Type should be set to one of the following supported types:
- application/json
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
The name of the file you upload must match the file name stated in Step 1
curl --location --request PUT '{url from step 1}' \
--header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
--data '@[dir]/August2023_Batch_Upload.xlsx'
If the file is uploaded successfully, CereTax will respond back with a status code of 200.
3. Confirm your batch file completed processing and download results
After you successfully upload your batch file, you can call the Create or retrieve a batch endpoint again to retrieve the status of your batch. This time, provide the batchId and set the command to "status".
curl --location 'https://batch.cert.ceretax.net' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
"command": "status",
"batchIds": ["29iNnnfesNoBTO8o0wQDZpna5Vo"]
}
'
In the response below, you can see that CereTax has finished processing the batch and set the status to "Batch Complete". The response also includes a url that can be used to download the results of your batch.
Batch download url expires after 15 mins
The url returned in this request for downloading your batch results will be valid for 15 mins. After 15 mins, a new url will need to be generated by making another batch status request.
[
{
"batchId": "29iNnnfesNoBTO8o0wQDZpna5Vo",
"batchName": " August 2023 Batch Upload",
"status": "Batch Complete",
"percentCompleted": 100,
"percentFailed": 0,
"downloadUrl": "https://..."
}
]