N/https Module

Use the N/https module to manage content sent to a third party using HTTPS calls. This module encapsulates all the functionality of the N/http Module, but does not allow the HTTP protocol. You can make HTTPS calls from client and server scripts.

                                   

You can use the N/https module to encode binary content or access a handle to the value in a NetSuite credential field.

You can use the N/https module to communicate between SuiteScript scripts, RESTlets, and SuiteTalk REST APIs without having to reauthenticate, using the https.requestRestlet(options) and https.requestSuiteTalkRest(options) methods.

Starting with NetSuite 2023.1, you can use the N/https module to communicate between SuiteScript scripts and Suitelets using the https.requestSuitelet(options) or https.requestSuitelet.promise(options) method.

When the N/https module is used, SuiteScript also loads the N/crypto Module and N/encode Module.

Important:

Use TLS 1.2 for HTTPS requests. SuiteScript 2.0 requests such https.delete(options), https.get(options), https.post(options), https.put(options), and https.request(options) usually go to third-party servers. Management of these servers is not within the control of your company. These HTTPS requests now fail the handshake when they attempt to connect to servers that do not support TLS 1.2. You should communicate with those who manage any third-party servers to which you connect, and ensure their servers support the TLS 1.2 protocol.

Important:

NetSuite supports the same list of trusted third-party certificate authorities (CAs) as the Mozilla Included CA Certificate List.

The target endpoint, domain, or server must use one of these trusted third–party CAs, or the connection cannot be established. Oracle NetSuite requires that the endpoints that you are connecting to from NetSuite provide a full certification chain, including intermediate certificates.

For a list of certificate authorities, see https://wiki.mozilla.org/CA/Included_Certificates.

Warning:

Using plain text or other unencrypted user credentials is unsafe and can pose a security threat. Whenever possible, use Token-based Authentication (TBA) or OAuth 2.0 to specify user credentials.

In This Help Topic

HTTPS Header Information

HTTPS headers can be used to pass additional information with an HTTPS request or response. Each HTTPS header consists of its case-insensitive name followed by a colon (:), then by its value (without line breaks). If you use custom headers, make sure the names of these headers do not contain underscores. For a general list of all HTTP headers (also applicable to HTTPS), visit http://developer.mozilla.org/en-US/docs/Web/HTTP/Headers.

Note that if you call https.post(options), passing in the header with a content type, NetSuite respects the following types:

  • all text media types (types starting with “text/”)

  • "application/json"

  • “application/vnd.maxmind.com-country+json”

  • “application/xml”

  • "application/soap+xml"

  • “application/xhtml+xml”

  • “application/atom+xml”

Otherwise, NetSuite overwrites the content type with the default type as if the type had not been specified. Default types are:

  • "text/xml; charset=UTF-8"

  • "application/x-www-form-urlencoded; charset=UTF-8"

If the body parameter is entered as an object, it is always encoded to the URL, and the headers are changed to "application/x-www-form-urlencoded; charset=UTF-8.”

When you use https.ServerResponse, textual responses are encoded in UTF-8 by default. If you want to return a file with an alternative character encoding, see Return a File with Alternative Character Encoding.

Some headers are not supported in NetSuite and are blocked. These are listed below as either general HTTPS headers or Suitelet response headers.

General Blocked HTTPS Headers

Be aware that certain headers cannot be set manually when using N/https module methods. If a script attempts to set values for any of the following headers, the values are discarded. These headers are listed in the following table.

  • Connection

  • Content-Length

  • Host

  • JSESSIONID

  • Trailer

  • Transfer-Encoding

  • Upgrade

  • Via

Suitelet Response HTTPS Header Blocklist

In addition to the headers described in General Blocked HTTPS Headers, certain headers cannot be set manually when interacting with the https.ServerResponse Objects sent by Suitelets. If a script attempts to set values for any of these headers, the system throws an SSS_INVALID_HEADER error. These headers are listed in the following table.

  • Allow

  • Content-Location

  • Content-MD5

  • Content-Range

  • Date

  • Location

  • Proxy-Authenticate

  • Public-Key-Pins

  • Public-Key-Pins-Report-Only

  • Retry-After

  • Server

  • Strict-Transport-Security

  • Upgrade-Insecure-Requests

  • Warning

  • WWW-Authenticate

N/https Module Members

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Object

https.SecureString

Object

Server scripts

Encapsulates data that may be sent to a third-party using an HTTPS call.

https.ClientResponse

Object (read-only)

Server scripts

Encapsulates the response to an HTTPS client request.

https.ServerRequest

Object (read-only)

Server scripts

Encapsulates the HTTPS request information sent to an HTTPS server. For example, a request received by a Suitelet or RESTlet.

https.ServerResponse

Object

Server scripts

Encapsulates the response from an HTTPS server to an HTTPS request. For example, a response from a Suitelet or RESTlet.

Method

https.createSecretKey(options)

Object

Server scripts

Creates a key for the contents of a credential field.

https.createSecureString(options)

Object

Server scripts

Creates an https.SecureString Object.

https.delete(options)

https.ClientResponse or https.ServerResponse

Client and server scripts

Sends an HTTPS DELETE request and returns the response.

https.delete.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS DELETE request asynchronously and returns the response.

https.get(options)

https.ClientResponse or https.ServerResponse

Client and server scripts

Sends an HTTPS GET request and returns the response.

https.get.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS GET request asynchronously and returns the response.

https.post(options)

https.ClientResponse or https.ServerResponse

Client and server scripts

Sends an HTTPS POST request and returns the response.

https.post.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS POST request asynchronously and returns the response.

https.put(options)

https.ClientResponse or https.ServerResponse

Client and server scripts

Sends an HTTPS PUT request and returns the response.

https.put.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS PUT asynchronously request and returns the response.

https.request(options)

https.ClientResponse or https.ServerResponse

Client and server scripts

Sends an HTTPS request and returns the response.

If a request fails, an error.SuiteScriptError is thrown.

https.request.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS request asynchronously and returns the response.

If a request fails, a Promise.reject is thrown with a parameter Error.

https.requestRestlet(options)

https.ClientResponse

Server scripts

Sends an HTTPS request to a RESTlet and returns the response. Authentication headers are automatically added.

The RESTlet will execute with the same privileges as the calling script.

https.requestRestlet.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS request to a Restlet and returns the response.

https.requestSuitelet(options)

https.ClientResponse

Client and server scripts

Sends an HTTPS request to a Suitelet and returns the response.

https.requestSuitelet.promise(options)

Promise Object

Client and server scripts

Sends an HTTPS request asynchronously to a Suitelet and returns the response.

https.requestSuiteTalkRest(options)

https.ClientResponse

Server scripts

Sends an HTTPS request to a SuiteTalk REST endpoint and returns the response. Authentication headers are automatically added.

Enum

https.CacheDuration

enum

Server scripts

Holds the string values for supported cache durations. Use this enum to set the value of the type parameter in ServerResponse.setCdnCacheable(options).

https.Encoding

enum

Server scripts

Holds the string values for supported encoding types. Use this enum to set the value of parameters in SecureString.appendString(options), SecureString.convertEncoding(options), https.createSecureString(options).

https.HashAlg

enum

Server scripts

Holds the string values for supported hashing algorithms. Use this enum to set the value of parameters in SecureString.hash(options) and SecureString.hmac(options).

https.Method

enum

Server scripts

Holds the string values for supported HTTPS requests. Use this enum to set the value of method parameter in https.request(options).

https.RedirectType

enum

Server scripts

Holds the string values for supported NetSuite resources that you can redirect to. Use this enum to set the value of the type parameter for ServerResponse.sendRedirect(options).

SecureString Object Members

SecureString functionality is supported only in server scripts.

The following members are called on the https.SecureString Object.

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Method

SecureString.appendSecureString(options)

https.SecureString

Server scripts

Appends one https.SecureString to another https.SecureString.

SecureString.appendString(options)

https.SecureString

Server scripts

Appends a string to a https.SecureString.

SecureString.convertEncoding(options)

https.SecureString

Server scripts

Converts the content of a https.SecureString between two encodings.

SecureString.hash(options)

https.SecureString

Server scripts

Creates a hash for a https.SecureString.

SecureString.hmac(options)

https.SecureString

Server scripts

Creates an hmac for a https.SecureString.

SecureString.replaceString(options)

https.SecureString

Server Scripts

Replaces all occurrences of a pattern string inside a https.SecureString with a replacement string.

ClientResponse Object Members

The following members are called on the https.ClientResponse Object.

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Property

ClientResponse.body

string (read-only)

Server scripts

The response body.

ClientResponse.code

number (read-only)

Server scripts

The response code.

ClientResponse.headers

Object (read-only)

Server scripts

The response body.

ServerRequest Object Members

The following members are called on the https.ServerRequest Object.

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Method

ServerRequest.getLineCount(options)

number

Server scripts

Returns the number of lines in a sublist.

ServerRequest.getSublistValue(options)

string

Server scripts

Returns the value of a sublist line item.

Property

ServerRequest.body

string (read-only)

Server scripts

The server request body

ServerRequest.files

Object (read-only)

Server scripts

The server request files represented as object in ID-file.File pair.

ServerRequest.headers

Object (read-only)

Server scripts

The server request headers.

ServerRequest.method

https.Method

Server scripts

The HTTPS method for the server request.

ServerRequest.parameters

Object (read-only)

Server scripts

The server request parameters.

ServerRequest.url

string (read-only)

Server scripts

The server request URL.

ServerResponse Object Members

The following members are called on the https.ServerResponse Object.

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Method

ServerResponse.addHeader(options)

void

Server scripts

Adds a header to the response.

ServerResponse.getHeader(options)

string | string[]

Server scripts

Returns the value of a response header.

ServerResponse.renderPdf(options)

void

Server scripts

Generates and renders a PDF directly to the response.

ServerResponse.sendRedirect(options)

void

Server scripts

Sets the redirect URL by resolving to a NetSuite resource.

ServerResponse.setCdnCacheable(options)

void

Server scripts

Sets CDN caching for a period of time.

ServerResponse.setHeader(options)

void

Server scripts

Sets the value of a response header.

ServerResponse.write(options)

void

Server scripts

Writes information (text/xml/html) to the response.

ServerResponse.writeFile(options)

void

Server scripts

Writes a file to the response.

ServerResponse.writeLine(options)

void

Server scripts

Writes line information (text/xml/html) to the response.

ServerResponse.writePage(options)

void

Server scripts

Generates a page.

Property

ServerResponse.headers

Object (read-only)

Server scripts

The server response headers.

Related Topics

SuiteScript 2.x Modules
SuiteScript 2.x

General Notices