China Golden Tax System Integration API Overview

The Golden Tax API is the primary way to get China VAT transaction data in and out of NetSuite. It is a RESTful based API that applications can use to retrieve transaction data and update VAT status.

API Basics

The Golden Tax System API is HTTP-based. The API receives requests that are formatted in JavaScript Object Notation (JSON) format. The China Localization Golden Tax API allows you to specify the needed information and formatting in the request.

Your integration should both send and receive VAT transaction information with NetSuite and the China Golden Tax System.

The following are guidelines when developing an application to integrate with NetSuite China Localization Golden Tax System:

Your integration script should have GET and PUT functions for your RESTlet. Additionally, your integration should contain the following:
- Requests to the China Localization Golden Tax System API endpoint Internal URL. For more information, see Golden Tax System API Internal Script URL.
- Outbound requests to the China Golden Tax System through the GTA RESTful APIs.
The URL in the Self-Built Scripts field in the China Localization configuration page should point to the integration script you built for Golden Tax System Integration.
Your integration should have a status to control progress in the scripts.
Your integration should maintain the status values in the list first before importing new values.
If a partner uses the synchronize method to build the integration, the partner will need to add item volume check validation.
Your integration script should be able to handle both JavaScript (JS) and error responses. Your error handling should also cover GTA RESTful API error responses.
- JS errors need to be handled and try/catched.
- Parse the responses to check if error occurred.

Authentication

The NetSuite China Localization Golden Tax System API requires authentication for every request. For more information, see Authentication Overview.

Golden Tax System API Internal Script URL

For sending and receiving data to and from NetSuite, requests should be sent to the Golden Tax System API endpoint provided. This URL is unique for every account in NetSuite. You will need to find the script file in NetSuite.

To find the Golden Tax System API internal script file:

Go to Customization > Scripting > Script Deployments.
In the Script Deployments filters, select RESTlet in the Type dropdown list.
Locate the script RL CN VAT Export Data in the results.
Click View.
You will find the script URL in the External URL field.

Use this URL when sending your requests to the NetSuite China Localization Golden Tax System API.

Output Requests

The following describes the details when requesting information from NetSuite.

URL:

              https://{accountId}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script={scriptId}&deploy={deploymentId}

Action: GET
Request Parameters: key={key} (for example key=1)
Request Body: N/A

Response Body:

Sample Response Body:

              {
    "taxregisterno": "Subsi1000000000000001",
        "invoices": [
            {
                "internalid": "10275",
                "customername": "Oracle corp.",
                "customeraddressphoneno": "Alex Tong Liu¿¿¿¿¿¿¿¿7Beijing ¿¿¿ 100193¿¿ 40084008",
                "customerbankno": "CMB12345678",
                "customertaxregisterno": "10000000000000001",
                "documentdate": "20190201",
                "itemnameforsales": "",
                "approver": "",
                "receiver": "",
                "sellerbankno": "",
                "selleraddressphoneno": "",
                "remark": "",
                "linequantity": 1,
                "items": [
                    {
                        "name": "Computer",
                        "model": "",
                        "uom": "Box",
                        "quantity": 1,
                        "taxexclusiveamount": 100,
                        "taxrate": 0,
                        "discountamount": "",
                        "taxdenom": 0,
                        "taxamount": "",
                        "discounttaxamount": "",
                        "discountrate": "",
                        "pricemethod": ""
                    }
                ]
            }
        ]
}

Input Requests

The following describes the details when sending information from NetSuite.

URL:

              https://{accountId}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script={scriptId}&deploy={deploymentId}

Action: PUT
Request Parameters: N/A

Request Body:

Sample Request Payload:

              {
    "invoices": [
        {
            "status": "Completed",
            "invoicecategorycode": "abcdefg123",
            "invoiceno": "abcdefg123",
            "invoicedate": "2019-02-15",
            "internalid": "10275",
            "taxexclusiveamount": "100",
            "taxamount": "0"
        }
    ]
}

Response Body:

Sample Response Body:

              { 
   "successcount":1,
   "failurecount":0,
   "failedinvoices":[ 
 
   ]
}

General Notices