O que é a NS ANTT API?
A NS ANTT API é uma aplicação de integração por onde outras aplicações podem realizar a emissão e gerenciamento dos métodos InserirLogVendaPassagem e InserirLogCancelarPassagem para com a ANTT.
Com a NS ANTT 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 a serem enviados é JSON.
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 na NS ANTT API.
Exemplo de geração de JSON
No quadro abaixo é possível ver um exemplo destes dados:
{
"chBPe":"43210808256988000126630060000023521000000012",
"tpAmb": 2,
"logEmissao": {
"codigoBilheteEmbarque": 1,
"codigoCategoriaTransporte": "02",
"identificacaoLinha": "1",
"codigoTipoServico": 1,
"dataViagem": "20210823",
"horaViagem": "173145",
"codigoTipoViagem": 1,
"..."
}
}