O que é a NS BP-e API
A NS BP-e API é uma aplicação de integração por onde outras aplicações podem realizar a emissão e gerenciamento de BP-es.
Diferentemente das aplicações tradicionais, onde os dados dos documentos são enviados para a aplicação de integração através de arquivos TXTs ou banco de dados, com a NS BP-e API os dados são enviados e recebidos através de requisições HTTPs que podem ser facilmente implementadas em qualquer linguagem de programação.
Veja em nossos exemplos de integração como implementar a comunicação.
Uma API é uma aplicação que possui métodos consumíveis por outras aplicações, ou seja, é uma aplicação que possui métodos que podem ser acessados diretamente através do código de outras aplicações.
Dá-se o nome de Consumidora ou Cliente à aplicação que consome os métodos de uma API.
Informações enviadas e recebidas nas requisições
Dados de envio
Os dados de envio variam de acordo com o método que está sendo consumido. Veja a documentação de consumo da API para informações detalhadas de quais dados são enviados para cada método.
O formato de dados enviados é JSON, mas em alguns casos é possível enviar os dados também em XML ou TXT.
Dados de recebidos
Toda requisição receberá como retorno algumas informações que podem ser classificadas em dois grupos: Status HTTP e Dados de Retorno.
Status HTTP
O status HTTP é enviado no cabeçalho da resposta e informa se a requisição foi realizada com sucesso ou se algum erro ocorreu. Este status é formado por um código e uma mensagem.
Por exemplo, se a requisição HTTP for realizada para o endereço errado o status HTTP terá código 404 e mensagem Não encontrado (Not Found). Se a requisição HTTP for realizada corretamente o status HTTP terá código 200 e mensagem OK.
As informações do Status HTTP não devem ser consideradas como dados de resposta do método consumido. Estas informações informam apenas se a requisição HTTP foi realizada com sucesso ou não.
Veja na tabela abaixo os códigos de Status HTTP que podem ser retornados pela API:
| Código | Descrição | Quando Ocorre | Possui dados de retorno |
|---|---|---|---|
| 200 | Ok | Sim | |
| 400 | Requisição mal formada | Quando a requisição está sendo realizada com dados montados de forma errada | Não |
| 401 | Não autorizado | Quando a aplicação consumidora tenta acessar algum recurso não autorizado | Não |
| 403 | Acesso negado | Quando o token de acesso informado é inválido | Não |
| 404 | Não encontrado | Quando a URL do método é inválida ou a informação requisitada não é encontrada | Sim (mas pode não conter caso o erro seja URL não existente) |
| 501 | Erro interno da API | Quando algum erro interno não previsto ocorre | Sim |
Dados de Retorno
Os dados de retorno são enviados no corpo da resposta e possuem as informações de resposta do método consumido. Estes dados variam de acordo com cada método consumido.
Dependendo de qual for o Status HTTP retornado, estas informações podem não existir. Por exemplo, se o status HTTP for 400 (Bad Request), o retorno conterá apenas o Status HTTP e não terá Dados de retorno. Por este motivo, é importante que a sua aplicação sempre valide o Status HTTP recebido antes de utilizar as informações dos Dados de Retorno para garantir que os mesmos existem.
Código e descrição do Retorno
Os dados de retorno possuem dois campos que indicam a situação do processamento realizado chamados status e motivo. Além destes campos, outros campos também estarão presentes e serão específicos para cada método da API. Veja a documentação de consumo da API para visualizar os campos retornados por cada método.
Os campos status e motivo informam o código de Status do Processamento e descrição literal do status de processamento, respectivamente.
O Status do Processamento é diferente do Status HTTP visto acima. Por exemplo, o consumo de um determinado método pode retorno Status HTTP 200, que indica que a comunicação com a API aconteceu de forma correta, e Status de Processamento -400, que indica que algum campo obrigatório não foi informado.
A tabela abaixo mostra os códigos de Status de Processamento que são comuns a todos os métodos. Demais códigos são específicos de cada método e estão documentados na página de consumo da API.
| Código | Descrição |
|---|---|
| -400 | Campos obrigatórios não preenchidas |
| -500 ou -999 | Erro interno da API |
| 200 | Ok |
| -401 | Usuário sem permissões para gerenciar documentos do contribuinte |
Layout dos dados de integração
O layout padrão de integração para troca de informações é o JSON. No entanto, no método de emissão de BP-e é possível realizar o envio dos dados também em XML considerando o mesmo layout definidos pelo Manual de Orientação do Contribuinte da Sefaz.
O JSON de integração deve ser montado seguindo o mesmo layout do XML de emissão.
Exemplo de geração de JSON
O quadro abaixo mostra um trecho do XML montado de acordo com o layout da Sefaz:
<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>
No quadro abaixo é possível ver o JSON montado com as mesmas informações acima:
{
"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"
}
}
}