CubeMaster API Integration Guide

A RESTful API (Representational State Transfer) is a way for two systems (like NetSuite and CubeMaster) to communicate over the internet using standard HTTP methods. Here’s a quick breakdown:

• HTTP Methods: REST APIs use methods like GET (retrieve data), POST (send data), PUT (update data), and DELETE (remove data). In this guide, we’ll use POST to send load data to CubeMaster.
• Endpoints: These are specific URLs (e.g., https://api.cubemaster.net/loads) where the API accepts requests.
• JSON: Data is typically sent and received in JSON (JavaScript Object Notation), a lightweight format that’s easy to read and write.
• Headers: Additional information (like authentication tokens) is sent in the request headers.
• Status Codes: Responses include codes like 200 (success), 401 (unauthorized), or 500 (server error) to indicate the outcome.

In this guide, you’ll send a POST request to the /loads endpoint with a JSON payload and a TokenID in the headers, all configured within NetSuite’s scripting environment.

NetSuite uses SuiteScript to make HTTP requests. You’ll need to create a script within NetSuite’s UI to call the CubeMaster API. Here’s how to set it up:

1. Log in to your NetSuite account at https://www.netsuite.com. Enter your credentials in the login form at the top-right corner of the page.
2. From the global navigation bar at the top, hover over the Customization menu. This reveals a dropdown with options like “Forms,” “Workflows,” and “Scripting.” Click on Scripting to expand its submenu, then select Scripts. This opens the “Scripts” page, showing a list of existing scripts (if any).
3. On the “Scripts” page, locate the blue + New Script button at the top-right corner above the list table. Click it to start creating a new script.
4. The “New Script” form appears. In the Name field (a required text input labeled “Name”), enter a descriptive name like CubeMasterLoadBuilder. Below that, the Script File field (with a “Choose File” button) will be used later to upload your script—leave it blank for now. Optionally, add a Description in the text area (e.g., “Script to integrate with CubeMaster API”). Click the gray Save button at the bottom-right to create the script record.
5. After saving, you’ll see the script’s detail page with tabs like “General,” “Deployments,” and “Parameters.” You’ll write and upload the code in the next steps, but for now, note the Script ID field (e.g., customscript_cubemasterloadbuilder) under the “General” tab—this is auto-generated and useful for referencing the script later.

UI Tip: If you’re unsure of your role’s permissions, check under Setup > Users/Roles > Manage Roles to ensure you have the “Scripts” and “SuiteScript” permissions enabled.

The /loads endpoint requires a JSON payload describing the load details (cargoes, containers, and rules). Below is the sample request JSON:

{
    "Title": "New Mixed Truck Load",
    "Description": "Hello Web API",
    "Cargoes": [
        {
            "Name": "ITEM001",
            "Length": 72,
            "Width": 30,
            "Height": 75,
            "Weight": 1002.45,
            "OrientationsAllowed": "OrientationsAll",
            "TurnAllowedOnFloor": false,
            "Qty": 16,
            "ColorKnownName": "Brown"
        },
        {
            "Name": "ITEM002",
            "Length": 27.31,
            "Width": 37.5,
            "Height": 76.67,
            "Weight": 521.45,
            "OrientationsAllowed": "OrientationsAll",
            "TurnAllowedOnFloor": false,
            "Qty": 28,
            "ColorKnownName": "Aqua"
        },
        {
            "Name": "SKU0005",
            "Length": 27.31,
            "Width": 9.5,
            "Height": 75.67,
            "Weight": 501.45,
            "OrientationsAllowed": "OrientationsAll",
            "TurnAllowedOnFloor": true,
            "Qty": 24,
            "ColorKnownName": "Beige"
        },
        {
            "Name": "SKU0005",
            "Qty": 23
        },
        {
            "Name": "SKU0008",
            "Qty": 34
        }
    ],
    "Containers": [
        {
            "VehicleType": "Dry",
            "Name": "53FT-Intermodal",
            "Length": 630,
            "Width": 98,
            "Height": 106,
            "ColorKnownName": "Blue"
        }
    ],
    "Rules": {
        "IsWeightLimited": true,
        "IsSequenceUsed": false,
        "FillDirection": "FrontToRear",
        "CalculationType": "MixLoad"
    }
}

You can hardcode this JSON in your SuiteScript or dynamically generate it within NetSuite. To generate it dynamically:

• Navigate to Lists > Accounting > Items to access item records. Filter the list using the Search field at the top (e.g., type “ITEM001”) to find relevant items. Each item’s detail page has fields like “Display Name/Code” (for Name), “Length,” “Width,” “Height,” and “Weight” under the “Inventory” tab.
• Use a SuiteScript record load (e.g., N/record) to fetch these values and map them to the JSON structure.
• For containers, you might store vehicle details in a custom record. Go to Customization > Lists, Records, & Fields > Record Types > New to create a custom record type (e.g., “Container Types”) with fields like “Name,” “Vehicle Type,” “Length,” “Width,” and “Height.” Populate this via Lists > Custom Record.

Use SuiteScript to send the POST request to https://api.cubemaster.net/loads with the TokenID in the headers. Here’s how to implement it in NetSuite:

1. Return to the script record created in Step 3 (Customization > Scripting > Scripts). Find your script (e.g., CubeMasterLoadBuilder) in the list and click its name to edit.
2. On the script detail page, under the “General” tab, click the Script File field’s “New” link next to the file dropdown. This opens the “File” creation page.
3. In the “File” form, set the Name field to something like CubeMasterLoadBuilder.js. In the File Type dropdown, select “JavaScript File.” Paste the following code into the Content text area (a large text box below):

define(['N/https', 'N/log'], function(https, log) {
    function sendLoadRequest() {
        var apiKey = 'your-api-key-here'; // Replace with your TokenID from Step 1
        var url = 'https://api.cubemaster.net/loads';
        var headers = {
            'Content-Type': 'application/json',
            'TokenID': apiKey
        };
        var requestBody = {
            "Title": "New Mixed Truck Load",
            "Description": "Hello Web API",
            "Cargoes": [
                {"Name": "ITEM001", "Length": 72, "Width": 30, "Height": 75, "Weight": 1002.45, "OrientationsAllowed": "OrientationsAll", "TurnAllowedOnFloor": false, "Qty": 16, "ColorKnownName": "Brown"},
                {"Name": "ITEM002", "Length": 27.31, "Width": 37.5, "Height": 76.67, "Weight": 521.45, "OrientationsAllowed": "OrientationsAll", "TurnAllowedOnFloor": false, "Qty": 28, "ColorKnownName": "Aqua"},
                {"Name": "SKU0005", "Length": 27.31, "Width": 9.5, "Height": 75.67, "Weight": 501.45, "OrientationsAllowed": "OrientationsAll", "TurnAllowedOnFloor": true, "Qty": 24, "ColorKnownName": "Beige"},
                {"Name": "SKU0005", "Qty": 23},
                {"Name": "SKU0008", "Qty": 34}
            ],
            "Containers": [
                {"VehicleType": "Dry", "Name": "53FT-Intermodal", "Length": 630, "Width": 98, "Height": 106, "ColorKnownName": "Blue"}
            ],
            "Rules": {
                "IsWeightLimited": true,
                "IsSequenceUsed": false,
                "FillDirection": "FrontToRear",
                "CalculationType": "MixLoad"
            }
        };

        try {
            var response = https.post({
                url: url,
                body: JSON.stringify(requestBody),
                headers: headers
            });
            log.debug('Response', response.body);
            return response.body;
        } catch (e) {
            log.error('Error', e.message);
            throw e;
        }
    }

    return {
        onRequest: sendLoadRequest
    };
});

4. Click the blue Save button at the bottom-right of the “File” form. Back on the script detail page, select this file from the Script File dropdown and click Save again.

UI Notes: The script file is stored in the File Cabinet (Documents > Files > File Cabinet), under the “SuiteScripts” folder by default. Replace 'your-api-key-here' with your actual TokenID from Step 1.

The CubeMaster API returns a JSON response detailing the load calculation. Below is the sample response (abridged for brevity):

{
    "status": "succeed",
    "message": "Engine created. 5 cargoes. 1 empty containers. Calculation started. Calculation ended. The load built successfully. The load saved to the cloud database.",
    "calculationError": "InvalidCargoSize",
    "document": {
        "title": "New Mixed Truck Load",
        "description": "Hello Web API",
        "isShared": true,
        "isAutoSaved": true,
        "isPending": false,
        "calculationTimeInSeconds": 0.6152743,
        "processId": "",
        "batchId": "",
        "createdBy": "CHANG@LOGEN.CO.KR",
        "createdAt": "2023-02-11T01:17:01.7392204+09:00",
        "updatedAt": "0001-01-01T00:00:00"
    },
    "loadSummary": {
        "cargoesLoaded": 68,
        "piecesLoaded": 68,
        "cargoesLeft": 0,
        "piecesLeft": 57,
        "unitloadsLoaded": 0,
        "volumeLoaded": 5261723.4606,
        "weightLoaded": 42674.59999999999,
        "priceLoaded": 0,
        "containersLoaded": 1
    },
    "filledContainers": [
        {
            "name": "#1 53FT-Intermodal",
            "sequence": 1,
            "loadSummary": {
                "cargoesLoaded": 68,
                "piecesLoaded": 68,
                "unitloadsLoaded": 0,
                "volumeLoaded": 5261723.4606,
                "volumeUtilization": 80.39990374424703,
                "vollumeUtilizationToLoadHeight": 81.03441853085657,
                "floorLoaded": 57090.75,
                "floorUtilization": 92.46963070942662,
                "weightLoaded": 42674.59999999999,
                "weightTotal": 42674.59999999999,
                "weightUtilization": 0,
                "dimWeight": 39424.33734939759,
                "priceLoaded": 0,
                "pricetUtilization": 0,
                "cargoesPerLayer": 14,
                "layersPerUnitload": 0
            }
        }
    ]
}

Handling in NetSuite:

• Parse the response in your SuiteScript with JSON.parse(response.body). Store key values (e.g., cargoesLoaded, volumeUtilization) in a custom record or transaction.
• To create a custom record for results, go to Customization > Lists, Records, & Fields > Record Types > New. Define fields like “Load Title” (text), “Cargoes Loaded” (integer), and “Volume Utilization” (float). Save and populate via N/record module.
• Check the Execution Log tab on the script detail page (Customization > Scripting > Scripts > [Your Script]) to view debug logs from log.debug. Filter logs by date or type using the dropdowns above the log table.
• If status isn’t "succeed", log the error via log.error and review under Customization > Scripting > Script Execution Logs. The log list shows columns like “Date,” “Type,” and “Details.”

After writing the script, test and deploy it in NetSuite:

1. Ensure the script file is uploaded (Step 5). Go to Customization > Scripting > Scripts, find your script, and verify the Script File field shows CubeMasterLoadBuilder.js.
2. Deploy the script as a Suitelet: On the script detail page, switch to the Deployments tab. Click the blue + New Deployment button above the empty table. In the “Script Deployment” form, set the ID field to customdeploy_cubemasterload, select Status as “Released” from the dropdown, and check the Execute as Role dropdown (default is “Administrator”). Click Save. Note the URL field (e.g., /app/site/hosting/scriptlet.nl?script=123&deploy=1) for testing.
3. Test the Suitelet: Open the deployment URL in a new browser tab. If successful, the response JSON appears in the browser (logged via log.debug). Check Customization > Scripting > Script Execution Logs for detailed output in the “Details” column.
4. For scheduled execution, change the script type: Edit the script, set Script Type to “Scheduled Script,” and redeploy under Deployments with Schedule options (e.g., “Daily” from the dropdown). Use the Schedule tab to set times.
5. Integrate into workflows: Add a button to a form (e.g., Sales Order) via Customization > Forms > Entry Forms. Edit a form, go to the “Custom Code” subtab, select your script in the Function field, and save. The button appears on the form’s toolbar.

UI Tip: Use the System Notes tab on the script or deployment record to track changes (e.g., “Field Changed” logs).