Gerência de Tecnologia da Informação – GETIN

Nome do Projeto Vale pedágio

Responsável do Projeto / Área Wilton Costa Drumond Sousa / GERAR
E-mail Wilton.sousa@antt.gov.br
Telefone (61) 3410-1243

Responsável GETIN Fábio Querino Gonçalves/ GETIN

E-mail fabio.goncalves@antt.gov.br
Telefone (61) 3410-1357

Documento de Interface de software - DIS

Histórico de Mudanças
Data Autor Descrição Versão
06/06/2016 Paulo Henrique Criação do Documento 1.0
07/07/2016 Paulo Henrique Atualização do documento após 1.1
considerações encaminhadas pelas
operadoras.
23/09/2016 Paulo Henrique Inclusão de mensagem de validação de praça. 1.2
Inclusão de regra no método de inclusão de
registro de passagem.
11/10/2016 Paulo Henrique Alteração do campo “valorContrato” para 1.3
“ValorVP”.
19/10/2016 Paulo Henrique - Inclusão da regra de geração do identificador 1.4
da praça de pedágio.
- Atualização do fluxo
CancelarValePedagioPorPraca
- Correção da máscara do campo KM.
- Inclusão da mensagem de erro 220

14/11/2016 Antonio Paiva Atualização do artefato conforme 1.5

solicitação de mudança contida no jira
17901-109.
- Inclusão de uma caixa de texto Regras para
especificação de regras do DIS;
- Inclusão de uma caixa de texto Tabela de
exceção de nome de rodovia;
- Complementação da regra para criação de
ID da praça, inserido complemento para citar
composição de nome de rodovia quando for
exceção à regra.
22/11/2016 Paulo Henrique - Correção do atributo tipo de praça da Regra 1.6
01
- Alteração na nomenclatura do parâmetro
dataHoraEmissão para dataHoraEmissao no
método inserir vale pedágio.
- Inclusão da Regra 3 para tratamento do
parâmetro idVP.
Classificação da Informação: Comum, Não Monitorada, Não Crítica
 Gerência de Tecnologia da Informação – GETIN

30/12/2016 Antonio Paiva Atualização da tabela de praças que se 1.7

enquadram como exceção com relação ao
nome de rodovia.
20/06/2017 Antonio Paiva Atualização do artefato. 1.8
- Inclusão do parâmetro dataHoraEmissao no
método inserirRegistroPassagem.

Introdução

O objetivo deste documento é definir a forma de integração entre as empresas Fornecedoras do Vale-
Pedágio e a ANTT – Agência Nacional de Transportes Terrestres. As empresas deverão integrar com o
sistema da ANTT enviando as informações de emissão de Vale Pedágio. A ANTT irá concentrar as
informações de todas as empresas fornecedoras de Vale-Pedágio obrigatório.

Será apresentado os padrões de integração e as informações básicas que serão enviadas pelas empresas
a ANTT.

Arquitetura do serviço
Padrão de comunicação

O meio físico de comunicação utilizado será a Internet com o uso do protocolo SSL versão 3.0 e autenticação
mútua, que além de garantir um duto de comunicação seguro na Internet, permite a identificação do servidor
e do cliente através de certificados digitais, eliminando a necessidade de identificação do usuário através
de nome ou código de usuário e senha.

O modelo de comunicação segue o padrão de WebServices definido pelo WS-I Basic Profile. A troca de
mensagens entre os WebServices e o aplicativo da empresa fornecedoras de Vale-Pedágio obrigatório
interessada será realizada no padrão REST com o método POST.

O certificado digital utilizado no estabelecimento da conexão segura com autenticação mútua será emitido
por Autoridade Certificadora credenciada pela Infraestrutura de Chaves Públicas Brasileira ICP-Brasil, tipo
A1 ou A3, devendo conter o CNPJ da pessoa jurídica titular do certificado digital no campo otherName OID
=2.16.76.1.3.3 e ter a extensão Extended Key Usage com permissão de "Autenticação Cliente". A
identificação da Fornecedora de Vale-Pedágio obrigatório habilitada será feita através do CNPJ do
certificado digital.

A Tabela a seguir resume os principais padrões utilizados:

Características Descrição
WebServices Padrão definido pelo WS-I Basic Profile 1.1
(http://www.wsi.org/Profiles/BasicProfile-1.1-2004-
08-24.html).
Meio lógico de comunicação WebServices, disponibilizados pela ANTT

Meio físico de comunicação Internet

Protocolo Internet SSL versão 3.0, com autenticação mútua através de

certificados digitais.

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Padrão de troca de mensagens RESTFull - JSON

Padrão da mensagem Método POST

Padrão de certificado digital X.509 versão 3, emitido por Autoridade Certificadora

EndPoint de Homologação
EndPoint de Produção
credenciada pela Infraestrutura de Chaves Públicas
Brasileira – ICP-Brasil, do tipo A1 ou A3, devendo
conter o CNPJ do proprietário do certificado digital.
https://appservices-
hml.antt.gov.br/valePedagioServices/VPService.svc/
[metodo]
https://appservices.antt.gov.br/valePedagioServices/
VPService.svc/[metodo]

Métodos de integração previstos para o modelo de comunicação adotado:

 InserirValePedagio
 InserirRegistroPassagem
 ConsultarValePedagio
 CancelarValePegadio
 CancelarValePedagioPorPraca

Padrão de mensagens
Padrão de retorno

Os códigos de retorno devem possuir 3 tipos.

Código de retorno Tipo de mensagem

0 Erro de autenticação
1 Ação executada com sucesso.
2 Erro de validação
3 Erro não identificado.

Mensagens de autenticação (Cód. Retorno 0)

Identificador Mensagem
001 Certificado digital inválido.

Mensagens de sucesso (Cód. Retorno 1)

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Identificador Mensagem
101 [metodo] registrado com sucesso

Mensagens de erro (Cód. Retorno 2)

Código Restrição Mensagem

201 Dominio = [valor] O valor do campo [parâmetro] é inválido.
202 NumeroChar O valor do campo [parâmetro] é inválido.
[mínimo] e [máximo] É permitida a inclusão de valores entre
[mínimo] e [máximo].
203 ValidaVP Código do vale pedágio inválido.
204 ValidaCNPJCPF CNPJ/CPF inválido.
205 ValidaData Data inválida.
206 NumeroChar = [limite Número de caracteres do campo
de caracteres] [parâmetro] inválido.
207 ValidaHora Hora inválida.
208 ValidaPraca Id da praça de pedágio inválido.
209 ValidaStatusVP O vale pedágio já cancelado.
210 ValidaStatusVP Vale pedágio já utilizado.
211 ValidaStatusVP Vale pedágio vencido.
212 ValidaStatusVP Vale pedágio inexistente.
213 ValidadeVP Verifica se a data informada está dentro
do limite permitido.
214 ErroProtocolo Protocolo enviado não existe.
215 validaFornecedora Fornecedora não cadastrada.
216 validaOperadora Operadora não cadastrada.
217 validaSeVPExiste Vale pedágio já cadastrado.
218 localizaPraca Praça não encontrada.
219 pracaCancelada Não foi possível realizar o cancelamento.
O idPraca informado já está cancelado.
220 pracaUtilizada Não foi possível registrar passagem.
Vale já utilizado na praça/sentido
informado.

Mensagens de erros não identificados (Cód. Retorno 3)

Identificador Mensagem
301 Erro de comunicação. Favor entrar em contato com
sistemas.suporte@antt.gov.br

Autenticação
Fluxo de autenticação

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Valores e formatos
Parâmetro Descrição Obrigatório
possíveis
Certificado digital ICP-Brasil, Sim Não
do tipo A1 ou A3, devendo
conter o CNPJ do
codCertificado
proprietário do certificado
digital. Validação executada
pelo servidor de aplicação.

Métodos de integração
Método: InserirValePedagio

Definição

Este método permite o registro do vale pedágio emitido pela empresa desde que a Regra - 2 seja
atendida.

Fluxo

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Parâmetros

Ação: Insere Vale pedágio

Parâmetros de Entrada
Descrição do Tama Valor, Restrições e Obrigatório
Parâmetro Tipo
campo nho Validações
CNPJFornecedora Identificador da validaFornecedora()
empresa Numerovarchar2 =
14 Varchar2 Sim
fornecedora do 14
vale pedágio
CNPJOperadora Operadora do validaOperadora()
vale pedágio 14 Numerovarchar2 = Varchar2 Sim
14
CPFCNPJEmbarc Identificação do ValidarCNPJCPF()
ador embarcador da
carga. Possibilita 14 Varchar2 Sim
a inclusão de CPF
e CNPJ
IdVP Identificador do ValidaCodVP = 28
vale pedágio. 28 validaSeVPExiste(); String Sim
Aplicar Regra - 3
validadeVP Data de validade Padrão UTC
do vale pedágio AAAAMMDD;
8 DataValida(); String Sim
NumeroChar=8;
ValidadeVP ();
valorVP Valor do vale Min: 0;
pedágio emitido Max: 9999999; Decimal(
7 Sim
por praça e por 7,2)
sentido.
tipoVP Tipo do vale [01, 02, 03]
pedágio por praça 2 Ver tabela de Integer Sim
e por sentido. domínio
dataHoraEmissao Data e hora de aaaa-MM-
emissão do vale 14 ddTHH:mm:ss datetime Sim
pedágio. Hora deve
Classificação da Informação: Comum, Não Monitorada, Não Crítica
 Gerência de Tecnologia da Informação – GETIN

considerar padrão
UTC
placaVeiculo* Placa do veículo
para o qual o vale
7 NumeroChar = 7; String Sim
pedágio foi
emitido (mercosul)
categoriaVeiculo Categoria do [1, 2... 9]
veículo conforme Ver tabela de
2 Integer Sim
estabelecido domínio
neste documento
idPraca Identificador da
praça de pedágio
vinculados ao VP
emitido.
17 ValidaPraca( ); String Sim
A geração do id
será conforme
exposto na
Regra - 1.
*considerar placa do mercosul, como definida na resolução nº590 de 24 de maio de 2016

Parâmetros de saída
Parâmetro Descrição do campo Valores e formatos possíveis
Permite 14 dígitos.
Retorno do nº de protocolo gerado Sequencial com 12 dígitos + 2 dígitos
idProtocolo
após o registro do vale pedágio. do ano do tipo string
Ex: 99999999999999
codigo Código de retorno da inclusão.
Mensagem apresentada como saída
mensagem
do método.

Método: InserirRegistroPassagem

Definição

Este método permite o registro da passagem do veículo e utilização do vale pedágio. Deve impossibilitar a
inserção quando houver registro de passagem do vale para a mesma praça e sentido, com exceção de
praças bidirecionais que podem ser inseridas duas vezes.

Fluxo

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Parâmetros

Parâmetros de Entrada (nome classe “passagem”)

Descrição do Taman Valor, Restrições e Obrigatóri
Parâmetro Tipo
campo ho Validações o
idVP Identificador do ValidaCodVP = 28
vale pedágio. 28 validaSeVPExiste(); String Sim
Aplicar Regra - 3
dataHoraEmissao Data e hora de aaaa-MM-
emissão do vale ddTHH:mm:ss
dateti
pedágio. 14 Hora deve Sim
me
considerar padrão
UTC
idPraca Identificador da
praça.
ValidaPraca( );
A geração do id
17 localizaPraca( ); String Sim
será conforme
pracaUtilizada( );
exposto na
Regra - 1.
dataHoraPassage Data e hora de aaaa-MM-
m registro de ddTHH:mm:ss
dateti
passagem do 14 Hora deve Sim
me
veículo. considerar padrão
UTC

Parâmetros de saída
Parâmetro Descrição do campo Valores e formatos possíveis
codigo Código de retorno da inclusão.
Mensagem apresentada como saída
mensagem
do método.

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Método: ConsultarValePedagio

Definição

Permite a consulta de vale pedágio, retornando os dados da praça onde foi utilizado.

Fluxo

Parâmetros

Parâmetros de Entrada (nome classe “passagem”)

Descrição do Tama Valor, Restrições Obrigató
Parâmetro Tipo
campo nho e Validações rio
placaVeículo Placa do veículo
que utilizou o vale 7 NumeroChar=7; String Sim
pedágio.
idPraca ID da praça de
pedágio em que o
VP será utilizado.
A geração do id 17 ValidaPraca( ); String Não
será conforme
exposto na Regra
- 1.
dataInicioConsulta Data fim do aaaa-MM-dd
período que será
consultado para
identificar o vale
8 datetime Sim
pedágio, sendo
utilizado como
base a data de
emissão.
dataFimConsulta Data fim do aaaa-MM-dd
período que será
consultado para
identificar o vale
8 datetime Sim
pedágio, sendo
utilizado como
base a data de
emissão.
Classificação da Informação: Comum, Não Monitorada, Não Crítica
 Gerência de Tecnologia da Informação – GETIN

Parâmetros de saída
Parâmetro Descrição do campo Valores e formatos possíveis
Identificador do vale pedágio.
idVP 9999999999999999999999999999
Aplicar Regra - 3
nomePraca Nome da praça Não se aplica
nomeConcessionaria Nome da concessionária Não se aplica
Identificador do tipo de praça. [01,02]
Valores possíveis:
tpPraca 01 - Praça de Pedágio;
02 - Cabine de Bloqueio;
telefonePraca Telefone 99-999999999
Rodovia onde a praça está
rodoviaPraca 999
localizada.
kmPraca KM onde a praça está localizada. 999,999
Município onde a praça está
localizada.
municipioPraca Os dados de município são [01, 02, 03...99]
mantidos na base corporativa da
ANTT.
Estado onde a praça está
localizada. Os dados de UF são
ufPraca [01, 02, 03...53]
mantidos na base corporativa da
ANTT.
Status da praça. [01, 02, 03]
Valores possíveis:
statusPraca 01 = Operando
02 = Em construção
03 = Parada
Responsável pela concessão. [01,02,03...53]
responsavelConcessao Ver tabela de domínio;
latitude Latitude Max: 90,0;
Min: -90,0;
DATUM:
SIRGAS 2000
WGS 84
longitude Longitude Max: 180,0;
Min: -180,0;
DATUM:
SIRGAS 2000
WGS 84
dataVencimentoContrat Data vencimento contrato
aaaa-mm-dd;
o concessão
Protocolo de inclusão do vale
idProtocolo 99999999999999
pedágio
Valor do vale pedágio emitido por
valorVP 9999999,99
praça e por sentido.
Status do vale pedágio. [01,02,03,04]
Valores possíveis:

01 – Válido: VP para uma placa

dentro do prazo de validade

02 – Vencido: VP para uma placa

statusVP fora do prazo de validade. O Status
deve ser alterado de valido para
vencido quando o prazo findar

03 - Cancelado: VP cancelado antes

de findar seu prazo de validade. UM
VP não pode ser excluído fora de seu
prazo de validade.

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

04 – Utilizado: este status deve ser

enviado para cada praça de pedágio
em que o VP for consumido

Texto contendo informações

importantes acerca do vale
pedágio. Será utilizado
txMensagem Não se aplica
inicialmente para informar do
ambiente de homologação e do
período de fiscalização educativa.

Método: CancelarValePedagio

Definição

Realiza o cancelamento do vale pedágio emitido. Este método deve cancelar somente vales com status
tipo 1, válido. Caso não esteja deve emitir a mensagem adequada.

Fluxo

Parâmetros

Parâmetros de Entrada
Descrição do Tama Valor, Restrições e Obrigató
Parâmetro Tipo
campo nho Validações rio
idProtocolo Protocolo ValidaProtocolo( );
retornado após NumeroChar=14;
14 String Sim
inclusão do vale
pedágio.

Parâmetros de saída
Parâmetro Descrição do campo Valores e formatos possíveis
Permite 14 dígitos.
idProtocoloCanc Retorno do nº de protocolo de
Sequencial com 12 dígitos + 2
elamento cancelamento gerado.
dígitos do ano

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Ex: 999999999999
codigo Código de retorno da inclusão.
Mensagem apresentada como saída
mensagem
do método.

Método: CancelarValePedagioPorPraca

Definição

Realiza o cancelamento do vale pedágio emitido para uma praça específica

Fluxo

Parâmetros

Parâmetros de Entrada
Descrição do Tama Valor, Restrições e Obrigatóri
Parâmetro Tipo
campo nho Validações o
idProtocolo Protocolo do vale ValidaProtocolo( );
14 String Sim
pedágio. NumeroChar=14;
idPraca Identificador da ValidaPraca( );
praça. pracaCancelada( );
A geração do id
17 String Sim
será conforme
exposto na Regra
- 1.

Parâmetros de saída
Parâmetro Descrição do campo Valores e formatos possíveis
codigo Código de retorno da inclusão.
Mensagem apresentada como saída
mensagem
do método.

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Tabelas de domínio
Tabela que define o domínio do campo: TipoVP

TipoVP Uso
01 Tag
02 Cupom
03 Cartão

Tabela que define o domínio do campo: CategoriaVeiculo

CategoriaVeiculo Uso
1 Veículo de Passeio 2 eixos
2 Veículo Comercial 2 eixos
3 Veículo de Passeio 3 eixos
4 Veículo Comercial 3 eixos
5 Veículo de Passeio 4 eixos
6 Veículo Comercial 4 eixos
7 Veículo Comercial 5 eixos
8 Veículo Comercial 6 eixos
9 Motos
10 Veículo Comercial 7 eixos
11 Veículo Comercial 8 eixos
12 Veículo Comercial 9 eixos
13 Veículo Comercial 10 eixos
14 Veículo Comercial Acima de 10 eixos

Tabela que define o domínio do campo: responsavelConcessao*

responsavelConc Uso
essao
01 ANTT
02 AGEPAR
03 ARTESP
11 DER /RO
12 DER /AC
13 DER /AM
14 DER /RR
15 DER /PA
16 DER /AP
17 DER /TO
21 DER /MA
22 DER /PI
23 DER /CE

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

24 DER /RN
25 DER /PB
26 DER /PE
27 DER /AL
28 DER /SE
29 DER /BA
31 DER /MG
32 DER /ES
33 DER /RJ
35 DER /SP
41 DER /PR
42 DER /SC
43 DER /RS
50 DER /MS
51 DER /MT
52 DER /GO
53 DER /DF
54 ASPE
55 AGERBA
56 AGETRANSP
57 AGER
58 AGERGS
59 APEB

*Tabela utilizada no retorno da consulta de vale pedágio e será atualizada conforme novas praças forem cadastradas.

Tabela que define o domínio do campo: sentidoPraca

sentidoPraca Uso
01 Crescente
02 Decrescente
03 Bidirecional

Tabela de exceção de nome de rodovia

Representação Nome da rodovia

99001 VPE-052
99002 Ademar de Barros
99003 SPA 086/021
99004 Linha Amarela
99005 Transolimpica
99006 Pedágio de Elisário
99007 Cordeirópolis
99008 Bueno de Andrada
99009 Broa Norte - SPA-
149/215

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Regras

Regra - 1 Composição do idPraca

O idPraca é composto pela concatenação dos dados da praça de pedágio. Como descrito abaixo:
UF DA PRAÇA + NOME DA RODOVIA DA PRAÇA + KM DA PRAÇA + TIPO DA PRAÇA + SENTIDO
DA PRAÇA

Ex: idpraca = 35353304821380101

35 (35 - São Paulo/SP)

35330 (SP 330)
482138 (KM 482 MAIS 138 M)
01 (Praça de pedágio)
01 (Crescente)

Para nome de rodovia diferente de UFNNN (SP330) deverá ser considerado o prefixo 99 como código
da UF seguido de um sequencial composto por 3 caracteres numéricos.

Exemplo: Para o nome de rodovia VPE-052 será considerado o código 99001 conforme Tabela de
exceção de nome de rodovia.

Sendo que o tipo da praça possui os valores 01 – Praça de pedágio e 02 – Cabine de Bloqueio e o
sentido possui os valores 01 – Crescente, 02 – decrescente e 03 – bidirecional.

Regra - 2 Permissão para inserção de vale pedágio

Deve ser permitida a inclusão de vale pedágio que contenha validade inferior a 30 dias da data de
emissão do vale pedágio.

Regra - 3 Composição do IdVP

Para composição do IdVP que totaliza 28 dígitos de identificação, os 8 primeiros dígitos do

identificador deverão ser de acordo com os 8 primeiros dígitos do CNPJ do Fornecedor, sucedidos
por 20 dígitos de controle do fornecedor.

Sendo assim, um fornecedor com numeração de CNPJ igual a 12.345.678/0001-09 teria os IdVP´s na
seguinte forma:

1234567800000000000000000001
1234567800000000000000000002
1234567800000000000000000003

Referências

 RESOLUÇÃO N.º 590, DE 24 DE MAIO 2016.

 RESOLUÇÃO N.º 2885, DE 04 DE SETEMBRO 2008

Relação com outros projetos e sistemas

Classificação da Informação: Comum, Não Monitorada, Não Crítica

 Gerência de Tecnologia da Informação – GETIN

Não ( ) Sim ( ) Quais:

Aprovação do Documento
Preenchido por

E-mail

Assinaturas PATROCINADORES

Data: ____/____/____
Data: ____/____/____

Francisco José Marques

Tito Livio Pereira Queiroz e Silva
Gerente de Tecnologia
Superintendente SUROC
ANTT
ANTT

Assinaturas GESTORES

Data: ____/____/____ Data: ____/____/____

Wilton Costa Drumond Sousa José Aires Amaral Filho

Gerente GERAR Gerente Substituto GERAR
ANTT ANTT

Data: ____/____/____ Data: ____/____/____

Debora Vieira Tavares Andre Sousa Ramos

Gerente de projetos Especialista em Regulação / Coordenador
Squadra ANTT

Classificação da Informação: Comum, Não Monitorada, Não Crítica