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.

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

• N/https Module Members

• SecureString Object Members

• ClientResponse Object Members

• ServerResponse Object Members

• ServerRequest Object Members

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