What is the NS CT-e API
The NS CT-e API is an intregation application through which other application can issue and manage CT-es.
Unlike traditional applications, where the document data is sent to the integration application through TXTs or database files, with the NS CT-e API the data is sent and received through HTTPs requests that can be easily implemented in any programming language.
See in our integration examples how to implement the communication.
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.
Converting TXT file to JSON
Examples of service taker data informed in the TXT file:
Taker data in TXT
B02|4|07364617000135|0170108708|NEWS SYSTEMS LTDA|NEWS SYSTEMS||suporte@newssystems.eti.br|
Now see how the same data informed in JSON looks like:
{
"toma04": {
"toma": 4,
"CNPJ": "07364617000135",
"IE": "0170108708",
"xNome": "NEWS SYSTEMS LTDA",
"xFant": "NEWS SYSTEMS",
"email": "suporte@newssystems.eti.br"
}
}
The table below shows how the XML generated from this information will look like:
<toma4>
<toma>4</toma>
<CNPJ>07364617000135</CNPJ>
<IE>0170108708</IE>
<xNome>NEWS SYSTEMS LTDA</xNome>
<xFant>NEWS SYSTEMS</xFant>
<email>suporte@newssystems.eti.br</email>
</toma4>
Information validation
Before sending the information to Sefaz, the NS CT-e API performs a validation of the data received against the XSD schema provided by Sefaz to ensure that all mandatory fields have been filled in and the information is in the correct format. If there is any filling error, the CT-e will not be sent to Sefaz and the API return will contain one or more messages informing which information is incorrect.
The messages generated by a validation process against XSD are often difficult to understand and hinder the correction of information. Let’s look at an example:
Let’s say that the ide>cUF field, which must be filled with 2 numeric characters, was filled with the value 433. The normal message generated by the validation would be:
cvc-enumeration-valid: Value '433' is not facet-valid with respect to enumeration '[11, 12, 13, 14, 15, 16, 17, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 32, 33, 35, 41, 42, 43, 50, 51, 52, 53]'. It must be a value from the enumeration.
However, the NS CT-e API has a knowledge base of the CT-e layout fields and performs a treatment on the error messages generated by the validation process to facilitate the understanding of which information is wrong and how it should be corrected.
In the example above, the message returned by the API will be:
O campo 'cUF' foi preenchido incorretamente com o valor '433'. Este campo deve ser preenchido com um dos seguintes valores: 11, 12, 13, 14, 15, 16, 17, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 32, 33, 35, 41, 42, 43, 50, 51, 52, 53. (cvc-enumeration-valid: Value '433' is not facet-valid with respect to enumeration '[11, 12, 13, 14, 15, 16, 17, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 32, 33, 35, 41, 42, 43, 50, 51, 52, 53]'. It must be a value from the enumeration.)
See that now, translating the error message to English, “The ‘cUF’ field was incorrectly filled with the value ‘433. This field must ne filled in with one of the following values…”, the beggining has a more understandable information about which error happened and how it should be fixed. In addition, the original message was also kept at the end of the message in parentheses.