What is the NS BP-e API ?
The NS BP-e API is an integration application through which other applications can perform the issuance and management of BP-es.
Unlike traditional applications, where document data is sent to the integration application via TXT files or database, with NS BP-e API data is sent and received via HTTP requests that can be easily implemented in any application. programming language.
See in our integration examples how to implement the API communication.
An API is an application that has methods consumable by other applications. Those methods that can be accessed directly through the code of other applications. The application that consumes the methods of an API is given the name of Client.
Request and Responses data
Request data
Request data varies depending on the method being consumed. See the API consumption documentation for detailed information on what data is sent for each method.
The format of the data sent is JSON, but in some cases it is possible to send the data also in XML or TXT.
Response data
Every request will receive some information in the response, that can be classified into two groups: HTTP Status and Response 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 is formed by a code and a message.
For example, if the HTTP request is made to the wrong address, the HTTP status will have code 404 and message Not Found. If the HTTP request is carried out correctly, the HTTP status will have code 200 and OK message.
HTTP Status information should not be considered as response data for the consumed method. This information only tells you 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 | Occurrence | Does it return data? |
|---|---|---|---|
| 200 | Success | Yes | |
| 400 | Bad Request | When the request is being carried out with data mounted in the wrong way | No |
| 401 | Unauthorized | When the client app tries to access an unauthorized resource | No |
| 403 | Access denied | When the 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-existent URL) |
| 501 | Internal API error | When an unforeseen internal error occurs | Yes |
Return Data
The return data is sent in the response body and contains the response information for the method consumed. These data vary according to each method consumed.
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 contain only the HTTP Status and will have no return data. For this reason, it is important that your application always validates the HTTP Status received before using the information from the Return Data to ensure that it exists.
Returned code and description
The return data has two fields that indicate the status of the processing performed called status and reason. In addition to these fields, other fields will also be present and will be specific to each method of the API.
See the API consumption documentation to view the fields returned by each method.
The status and reason fields inform the Processing Status code and literal description of the processing status, respectively.
The Processing Status is different from the HTTP Status seen above.
For example, the consumption of a given method can return HTTP Status 200, which indicates that the communication with the API happened correctly, and Processing Status -400, which indicates that some 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 |
|---|---|
| -400 | Mandatory fields not filled |
| -500 or -999 | Internal API Error |
| 200 | Success |
| -401 | User without permissions to manage taxpayer documents |
Integration data layout
The standard integration layout for exchanging information is JSON.
However, in the BP-e issuing method, it is possible to send the data also in XML considering the same layout defined by the Sefaz Taxpayer Guidance Manual.
The integration JSON must be assembled following the same layout as the issuing XML.
JSON example:
The table below shows an excerpt of the XML assembled according to the Sefaz layout:
<infPassagem>
<cLocOrig>4314902</cLocOrig>
<xLocOrig>PORTO ALEGRE</xLocOrig>
<cLocDest>PR</cLocDest>
<xLocDest>CURITIBA</xLocDest>
<dhEmb>2018-01-31T15:00:00-02:00</dhEmb>
<infPassageiro>
<xNome>John Doe</xNome>
<CPF>12345678901</CPF>
<tpDoc>1</tpDoc>
<nDoc>1234567890</nDoc>
</infPassageiro>
</infPassagem>
Now, see the table below. It is possible to noteice that the JSON was assembled with the same information as above:
{
"infPassagem": {
"cLocOrig": "4314902",
"xLocOrig": "PORTO ALEGRE",
"cLocDest": "PR",
"xLocDest": "CURITIBA",
"dhEmb": "2018-01-31T15:00:00-02:00",
"infPassageiro": {
"CPF": "12345678901",
"nDoc": "1234567890",
"tpDoc": "1",
"xNome": "John Doe"
}
}
}