1. Inicio
  2. Documentos
  3. NS NFe (English)
  4. First Steps

First Steps

What is the NS NF-e API?

The NS NF-e API is an integration application through which other applications can issue and manage NF-e.

Unlike traditional applications, where the document data is sent to the intregation application through database or TXT files, with the NS NF-e API the data is sent through HTTP requests that can be easily implemented in any programming language.

An API is an application that has methods used by other applications, that is, it’s an application that has methods which can be accessed directly through the code of other applications.
The name Consumer or Client is given to the application that consumes the methods of an API.

Information sent and received in requests
Shipping data

Shipping data varies depending on the method being consumed. See the API consumption document for detailed information on what data is sent to each method.

The sent data format is JSON, but in some cases its also possible to send the date in XML or TXT.

Received data

Every request will receive as a return some information that can be classified into two groups: HTTP Status and Return Data.

HTTP Status

The HTTP status is sent in the response header and informs if the request was successful or if an error occurred. This status consists of a code and a message.

For example, if the HTTP request is made to the wrong address, the HTTP status will have a 404 code and a Not Found message. If the HTTP request is performed correctly, the HTTP status will have code 200 and an OK message.

HTTP Status information should not be considered as consumed method response data. This information only informs if the HTTP request was successful or not.

See the table below for the HTTP Status codes that can be returned by the API:

CodeDescriptionWhen it occursHas return data
400Bad requestWhen the request is being sent with wrongly assembled dataNo
401UnauthorizedWhen the consuming application tries to access some unauthorized resourceNo
403ForbiddenWhen the informed access token is invalidNo
404Not FoundWhen the method URL is invalid or the requested information is not foundYes (but may not contain it if the error is a non-existing URL)
501API Internal ErrorWhen some unforeseen internal error occursYes
Return Data

The return data is sent in the response body and contains the response information of the consumed method. This data varies according to each method.

Depending on which HTTP Status is returned, this information may not exist. For example, if the HTTP Status is 400 (Bad Request), the return will only contain the HTTP Status and have no Return Data. For this reason, it’s important that your application always validates the HTTP Status received before using the Return Data information to ensure that it exists.

Return code and Description

The return data has two fields indicating the status of the carried out process, called “status” and “motivo”. In addition to these fields, other fields will also be present and will be specific to each API method. See the API consumer documentation to view the fields returned by each method.

The “status” and “motivo” fields inform the Processing Status code and literal description of the processing status, respectively.

The Processing Status is diferent from the HTTP Status seen above. For example, the consuption of a certain method can return HTTP Status 200, which indicates that the communication with the API happened correcly, and the Processing Status -400, which indicates that som mandatory field was not informed.

The table below shows the Processing Status codes that are common to all methods. Other codes are specific to each method and are documented on the API consumption page.

-400Mandatory fields not informed
-401User without permissions to manage documents
-500 or -999API internal error
Integration data layout

The default integration layout for exchanging information is JSON. However, in the NF-e issuance method. it’s possible to send the data IN XML or TXT considering the same layout used by the In House integration application of News Systems.

The integration JSON must be assembled following the same layout as the issuance TXT file. Click here to see the TXT file layout patterns.

Converting TXT file to JSON

Examples of service taker data informed in the TXT file:

ICMS data of CST 00


Now see how the same data informed in JSON looks like:

"ICMS00": {
  "orig": "0",
  "CST": "00",
  "modBC": "1",
  "vBC": "1500.00",
  "pICMS": "17.00",
  "vICMS": "255.00"

The table below shows how the XML generated from this information will look like:

Communication flowchart

The flowchart below shows the communication flow between the Client Application and the NS NF-e API in a complete NF-e issuance process, which starts with the generation of the NF-e data and sending it to the API until the obtaining of the DANFE for printing:

Como podemos ajudar?