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.

Note: templateName is optional

📘
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",
  "calculationType: "S",
  "contentMonth": "07",
  "contentYear": "2025",
  "profileId": "telco",
  "businessType": "01",
  "customerType": "02",
  "taxSitusRule": "T",
  "sellerType": "01",
  "templateName": ""
}
'

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://..."
  }
]