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:
| Code | Description | When it occurs | Has return data |
|---|---|---|---|
| 200 | OK | Yes | |
| 400 | Bad request | When the request is being sent with wrongly assembled data | No |
| 401 | Unauthorized | When the consuming application tries to access some unauthorized resource | No |
| 403 | Forbidden | When the informed access token is invalid | No |
| 404 | Not Found | When the method URL is invalid or the requested information is not found | Yes (but may not contain it if the error is a non-existing URL) |
| 501 | API Internal Error | When some unforeseen internal error occurs | Yes |
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.
| Code | Description |
|---|---|
| 200 | OK |
| -400 | Mandatory fields not informed |
| -401 | User without permissions to manage documents |
| -500 or -999 | API 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
N02|0|00|1|1500.00|17.00|255.00|
Now see how the same data informed in JSON looks like:
// RETURN OF A NOTE
"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:
<ICMS00>
<orig>0</orig>
<CST>00</CST>
<modBC>1</modBC>
<vBC>1500.00</vBC>
<pICMS>17.00</pICMS>
<vICMS>255.00</vICMS>
</ICMS00>
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:
