4.9 Batch File Upload API

4.9.1. INIT batch process

4.9.1.1. Adjusting Invoices

It will change the status of All Invoice, CreditMemo and DebitMemo to CarriedOver for the current Organization

POST /rest/batchProcess?mode=BatchInit

      
Request Payload  

• • jobId=unique Job id to track the process

  • carryforwardInvoices,carryForwardCreditMemos,carryForwardDebitMemos = self explanatory if true then those invoices will be adjusted.

  • zeroOutCustomerBalance - if true then current balance of all the customers within the organization will be set to zero. Set to true only prior to a new data load.
    
    
    

<batchProcess>

    <jobId>AUGUST_2020_INIT</jobId>

    <carryForwardInvoices>true</carryForwardInvoices>

    <carryForwardCreditMemos>true</carryForwardCreditMemos>

    <carryForwardDebitMemos>true</carryForwardDebitMemos>

    <zeroOutCustomerBalance>true</zeroOutCustomerBalance>

</batchProcess>

Response From the above request

• • batchprocess=a parent batch process node

  • id = batch id to track the process.

  • jobId = unique Job id to track the process

  • child = child node, it will have the child batch processes for carryForwardInvoices, carryForwardCreditMemo              and  carryForwardDebitMemo 

  • based on the type (Invoice, CreditMemo, DebitMemo) response will be produced.
    
    
    

<batchProcess>

    <id>1</id>

    <jobId>AUGUST_2020_INIT</jobId>

    <child>

        <carryForwardInvoice>

            <id>2</id>

            <jobId></jobId>

            <status>Success</status>

            <operation>CarryForward</operation>

            <subOperation>Invoice</subOperation>

            <successCount>20375</successCount>

            <successMessage>Success, 20375 records successfully processed,0failed</successMessage>

            <errorMessage></errorMessage>

            <failCount>0</failCount>

        </carryForwardInvoice>

        <carryForwardCreditMemo>

            <id></id>

            <jobId></jobId>

            <status></status>

            <operation></operation>

            <subOperation></subOperation>

            <successCount></successCount>

            <successMessage></successMessage>

            <errorMessage></errorMessage>

            <failCount></failCount>

        </carryForwardCreditMemo>

        <carryForwardDebitMemo>

            <id></id>

            <jobId></jobId>

            <status></status>

            <operation></operation>

            <subOperation></subOperation>

            <successCount></successCount>

            <successMessage></successMessage>

            <errorMessage></errorMessage>

            <failCount></failCount>

        </carryForwardDebitMemo>

    </child>

</batchProcess>

4.9.2. Customer File Upload 

4.9.2.1. Generate Customer Csv File upload URL 

POST /rest/batchProcess?mode=S3FileUpload

• • jobId = a unique identifier

  • inputType = API call 

  • operation,SubOperation = process specific ( must be same as in XML )

  • inputFilename = name of the file to be uploaded. 

     Request Payload

<batchProcess>

    <jobId>AUGUST_2020_CUS</jobId>

    <inputType>API</inputType>

<operation>eBill-Import</operation>

<subOperation>Customer</subOperation>

<inputFilename>CUS_AUG_2020_100RECORDS.csv</inputFilename>

</batchProcess>

Response From the above request.

<batchProcess>

    <id>3</id>

    <jobId>AUGUST_2020_CUS</jobId>

    <status>Draft</status>

    <operation>eBill-Import</operation>

    <subOperation>Customer</subOperation>

    <successCount>0</successCount>

    <successMessage>BatchProcess is created</successMessage>

    <errorMessage></errorMessage>

    <failCount>0</failCount>

<uploadUrl>https://batch-upload-dev.s3.us-east-2.amazonaws.com/acme/in/CUS_21ST_SEPT_1PM.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210921T071553Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIA57LHJLIXGV5ECL6Z%2F20210921%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=b7077f85ca23c44b8e49dee7766a1b751960a900f687f86aaeca5e6df9c41cd1</uploadUrl>

</batchProcess>

• • • • id = a unique identifier to track the batch process

      • jobId = alternate unique identifier (can be alphanumeric) to 

      • status = the status of the process

      • operation = process specific (for batch file upload  'eBill-Import' )

      • subOperation = process specific (for Customer file upload 'Customer')

      • successCount =  no of successful records processed 

      • successMessage = description of success status

      • errorMessage = error status description 

      • failCount = no of incorrect rows of Customer in csv file 

      • uploadUrl = the url to be used to upload the customer csv file.

here we need to upload the file with the URL generated. Here is a  postman screenshot to do so. 

paste the uploadUrl as shown above and  click on 'select file'  and select the required file from the Windows Explorer 

now we are moving to finalize stage.

4.9.2.2.  Batch Finalize (Process Csv file into the system)

PUT /rest/batchProcess?mode=BatchFinalize

• • id= batch Process id, generated from the previous request.

  • jobId = which was provided earlier

     Request Payload   **request can be send with any one or both the parameters**

<batchProcess>

    <id>3</id>

    <jobId>AUGUST_2020_CUS</jobId>

</batchProcess>

Response From the above request.

<batchProcess>

<id>3</id>

<jobId>AUGUST_2020_CUS</jobId>

<status>Queued</status>

<operation>eBill-Import</operation>

<subOperation>Customer</subOperation>

<successCount>0</successCount>

<successMessage>BatchProcess is in Queue</successMessage>

<errorMessage></errorMessage>

<failCount>0</failCount>

<downloadUrl></downloadUrl>

</batchProcess>

• • • • id = a unique identifier to track the batch process

      • jobId = alternate unique identifier (can be alphanumeric) to 

      • status = the status of the process in this case it ahs been queued ('Queued')

      • operation = process specific (for batch file upload  'eBill-Import' )

      • subOperation = process specific (for Customer file upload 'Customer')

      • successCount =  no of successful records processed 

      • successMessage = description of success status

      • errorMessage = error status description 

      • failCount = no of incorrect rows of Customer in csv file 

      • downloadUrl= download link to the output file with the status of each customer records after processing

  now we proceed to Batch upload status

4.9.2.3.  Batch Upload Status

GET /rest/batchProcess?id=[id]  or /rest/batchProcess?jobId=[jobId]

• • id= batch Process id, generated from the customer file upload API 

  • jobId = which was provided at the time of calling customer file upload API

    Response From the above request. 

for statuses 1,2  downloadUrl will be empty. For statuses 3,4,5 it will have the value as shown below.

<batchProcess>

    <id>3</id>

    <jobId>AUGUST_2020_CUS</jobId>

    <status>Success</status>

    <operation>eBill-Import</operation>

    <subOperation>Customer</subOperation>

    <successCount>100</successCount>

    <successMessage>Success, 100 records successfully processed, 0 failed</successMessage>

    <errorMessage></errorMessage>

    <failCount>0</failCount>

<downloadUrl>https://batch-upload-stag.s3.amazonaws.com/ashishtest/archive/out/CUS_21ST_SEPT_930AM_Batch_64236_1632200289161_output.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210921T045810Z&X-Amz-SignedHeaders=host&X-Amz-Expires=25140&X-Amz-Credential=AKIASGPKJ3MBB6IE3RLS%2F20210921 loo%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=a45d883b5e930a85aca832e8f73bc1cd8fdac3a56b5653ecce15aa1ea5b735fe</downloadUrl>

</batchProcess>

• • id = a unique identifier to track the batch process

  • jobId = alternate unique identifier (can be alphanumeric) to 

  • status = the status of the process in this case it ahs been queued ('Queued')

  • operation = process specific (for batch file upload  'eBill-Import' )

  • subOperation = process specific (for Customer file upload 'Customer')

  • successCount =  no of successful records processed 

  • successMessage = description of success status

  • errorMessage = error status description 

  • failCount = no of incorrect rows of Customer in csv file 

  • downloadUrl= download link to the output file with the status of each customer records after processing

4.9.3. Invoice File Upload 

4.9.3.1. Generate Invoice Csv File upload URL 

POST /rest/batchProcess?mode=S3FileUpload

     
Request Payload

<batchProcess>

    <jobId>AUG_2020_INV</jobId>

    <inputType>API</inputType>

<operation>eBill-Import</operation>

<subOperation>Invoice</subOperation>

<inputFilename>INV_AUG_2020_100RECORDS.csv</inputFilename>

</batchProcess>

Response From the above request will be same as in section  4.9.1.1. Generate Customer Csv File upload  URL 

<batchProcess>

    <id>4</id>

    <jobId>AUG_2020_INV</jobId>

    <status>Draft</status>

    <operation>eBill-Import</operation>

    <subOperation>Customer</subOperation>

    <successCount>0</successCount>

    <successMessage>BatchProcess is created</successMessage>

    <errorMessage></errorMessage>

    <failCount>0</failCount>

<uploadUrl>https://batch-upload-dev.s3.us-east-2.amazonaws.com/acme/in/CUS_21ST_SEPT_1PM.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210921T071553Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIA57LHJLIXGV5ECL6Z%2F20210921%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=b7077f85ca23c44b8e49dee7766a1b751960a900f687f86aaeca5e6df9c41cd1</uploadUrl>

</batchProcess>

 If there is more than one Invoice file to upload then upload them as done above one by one and keeping the         jobid and batchid noted for further usage. 

If there is no more Invoice files to upload then we proceed to ITM (Invoice Line Item) file upload

4.9.3.2. Generate Invoice Line Item (ITM) Csv File upload URL 

POST /rest/batchProcess?mode=S3FileUpload

     Request Payload

• • parentBatchProcess= this is the batch id generated while generating the upload URL for the Invoice Csv (section 4.9.2.1. Generate Invoice Csv File upload URL )

  • parentBatchProcessJobId = jobId of the Invoice Batch process

  • subOperation = process specific (for ITM file Upload - 'Invoice Line Item')

  • inputFilename = name of the ITM file to be uploaded.

 **out of parentBatchProcess or parentBatchProcessJobId any one value provided will do**

<batchProcess>

<parentBatchProcess>4</parentBatchProcess>

<parentBatchProcessJobId>AUG_2020_INV</parentBatchProcessJobId>

    <jobId>AUG_2020_ITM_1</jobId>

    <inputType>API</inputType>

<operation>eBill-Import</operation>

<subOperation>Invoice Line Item</subOperation>

<inputFilename>ITM_AUG_2020_200RECORDS_1.csv</inputFilename>

</batchProcess>

if there are more than one ITM file to upload. Then upload them with the request keeping the parentBatchProcess id (so that the file gets uploaded under the same invoice batch process ) same and using different jobid  for each ITM file.

4.9.3.3. Finalize Batch for  Invoice (INV) Csv File

PUT /rest/batchProcess?mode=BatchFinalize

 Request Payload   **request can be send with any one or both the parameters**

• • • • id= the batch id of Invoice Batch process  (parentbatchprocess id )

      • jobId = the jobId of Invoice Batch process 

<batchProcess>

    <id>4</id>

    <jobId>AUG_2020_INV</jobId>

</batchProcess>

this will pick up the Invoice file and all the ITM files associated with this invoice file and process them.

Response from the above request will be,
for status 1,2 (referring to  Table 4.9.1.3)  same as in the table.

for others (3,4,5) it will be like this.

<batchProcess>

    <id>4</id>

    <jobId>AUG_2020_INV</jobId>

    <status>Success</status>

    <operation>eBill-Import</operation>

    <subOperation>Invoice</subOperation>

    <successCount>100</successCount>

    <successMessage>Success, 100 records successfully processed, 0 failed</successMessage>

    <errorMessage></errorMessage>

    <failCount>0</failCount>

<downloadUrl>https://batch-upload-stag.s3.amazonaws.com/ashishtest/archive/out/INV_21TH_SEPT_930AM_1_Batch_64238_1632201579742_output.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210921T051940Z&X-Amz-SignedHeaders=host&X-Amz-Expires=25140&X-Amz-Credential=AKIASGPKJ3MBB6IE3RLS%2F20210921%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=32479d1e9dbdee4e43e9940818d16dbe393614becbbb906f207dcf336e560982</downloadUrl>

    <child>

        <batchProcess>

            <id>5</id>

            <jobId>AUG_2020_ITM_1</jobId>

            <status>Success</status>

            <operation>eBill-Import</operation>

            <subOperation>Invoice Line Item</subOperation>

            <successCount>200</successCount>

            <successMessage>Success, 200 records successfully processed, 0 failed</successMessage>

            <errorMessage></errorMessage>

            <failCount>0</failCount>

            <downloadUrl>https://batch-upload-stag.s3.amazonaws.com/ashishtest/archive/out/ITM_21TH_SEPT_930AM_1_Batch_64239_1632201582981_output.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210921T051943Z&X-Amz-SignedHeaders=host&X-Amz-Expires=25140&X-Amz-Credential=AKIASGPKJ3MBB6IE3RLS%2F20210921%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=5aaeaebef9469c5eb23ee5c1d00c916d5256a36d22ddb104a233971375a9004f</downloadUrl>

        </batchProcess>

    </child>

</batchProcess>

Here the child nodes are the ITM files responses.. For as many ITM files there will be that no of child batch process xml records in response under the same invoice batch process.