Histórico da Página
RESTWeb Service REST
Produto: | TOTVS Prestadores de Serviços Transporte de Passageiros |
Versões: | 12.1.23102410+ |
Este documento tem o objetivo de fornecer informações para utilização do Web Service REST de integração com oTOTVS Prestadores de Serviços Transporte de Passageiros
Para mais detalhes sobre o conceito de um serviços REST clique aqui.
Para mais detalhes sobre serviços REST na arquitetura Protheus clique aqui.
Definição do Serviço
Nome: WSCOLETOR
Objetivo: Permitir a Integração com o módulo SIGAGTP utilizando um WebService do Tipo REST.
Descrição: Integra os dados do coletor para gerar a prestação de contas.
Métodos: POST
Configurações do Serviço
A Configuração do serviço REST está documentada no link Configuração REST SERVER - Protheus.
Estas parametrizações estão localizadas fisicamente no arquivo appserver.ini da pasta de instalação "[...]\BIN\APP"
Nota | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||
Na seção HTTPURI, a chave PrepareIn deve ser comentada. Segue exemplo de configuração do WS REST para utilização no modulo GTP:
|
Definição dos métodos
POST
Descrição do Método: O método POST segue o conceito do próprio método em qualquer outro tipo de serviço REST, devendo seu conteúdo ser enviado no corpo da mensagem (body) no formato json.
O objetivo do método é enviar informações que devem ser gravadas nas tabelas do GTP, permitindo que os dados sejam submetidos aos processos de integração da filipetas
Estrutura da mensagem enviada no POST (Request):
Atributo | Pai | Nivel |
---|
Ocorrência | Formato |
---|
Cadastros Protheus | |||||
---|---|---|---|---|---|
layoutColetor | - | 1 | 1 | - | |
softwareColetor | layoutColetor | 1 | 1:1 | String( |
30) |
versaoColetor |
layoutColetor | 1 | 1: |
1 | String(30) | ||
cabecalho | - | 1 | 1 |
- |
empresa |
cabecalho |
1 | 1:1 | String( |
6) | De/Para de empresas no configurador (SIGACFG) ( Ambiente - Schedule - De/Para de Mensagem Única) | ||
matMotorista | cabecalho | 1 | 0: |
messageType
lote
2
TAFCODMSG
1 | String( |
15) |
messageSequential
lote
2
TAFSEQ
Matricula no cadastro de colaboradores | ||||
cartaoMotorista | cabecalho | 1 | 0:1 | String( |
50) |
matCobrador |
cabecalho |
1 |
TAFTPREG
0:1 | String( |
15) |
registryKey
lote
2
TAFKEY
Matricula no cadastro de colaboradores | ||||
cartaoCobrador | cabecalho | 1 | 0:1 | String( |
50) |
dataMovimento |
cabecalho |
1 |
TAFMSG
1:1 |
String - |
AAAAMMDD |
filipeta |
cabecalho |
1 |
TAFDATA
1:1 | String |
(30) | |
servicos | - |
integrationTime
2 |
TAFHORA
0:1 |
String - HH:MM:SS
Array | |
codServico | servicos |
2 |
0:1 | String( |
15) |
codVeiculo |
servicos | 2 |
0:1 | String( |
8) |
Prefixo no cadastro de frotas | |
prefixoLinha | servicos |
2 |
0:1 | String( |
5) |
registryPredecessor
Prefixo no cadastro de linhas | |
codigoLinha | servicos |
2 |
TAFREGPRED
0:1 | String( |
5) | Código no cadastro de linhas |
turno | servicos |
2 |
0:1 | String( |
1) | |||||
dataInicioViagem | servicos | 2 | 1:1 | String - AAAAMMDD | |
dataTerminoViagem | servicos | 2 | 1:1 | String - AAAAMMDD | |
hrInicio | servicos | 2 | 1 |
:1 | String( |
5) |
Obs: O XML pode ser enviado com a codificação UTF-8, neste caso é obrigatório o uso da declaração <?xml version="1.0" encoding="utf-8"?> no inicio do Xml.
hrFim | servicos | 2 | 1:1 | String(5) | |
dadosValidador | servicos | 2 | 1 | - | |
roletaInicioValidador | dadosValidador | 2 | 0:1 | String(10) | |
roletaFim | dadosValidador | 2 | 0:1 | String(10) | |
pagamentos | - | 3 | 1 | Array | |
tipoPagamento | pagamentos | 3 | 1:1 | String(6) | Tipo de pagamento no cadastro de Forma de pagamento |
quantidadePassageiros | pagamentos | 3 | 1:1 | Numerico | |
valorUnitario | pagamentos | 3 | 1:1 | Numerico | |
totalArrecadado | servicos | 2 | 0:1 | Numerico | |
totalGratuidades | servicos | 2 | 0:1 | Numerico | |
totalDinheiro | servicos | 2 | 0:1 | Numerico | |
diferenca | servicos | 2 | 0:1 | Numerico |
Aviso | ||
---|---|---|
| ||
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional. |
Aviso | ||
---|---|---|
| ||
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional. |
Estrutura da mensagem de retorno do POST (Response):
Atributo
Pai
Nivel
Ocorrência
Formato
status
-
1
0:1
String(7)
prestacaoContas
-
1
0:1
String(36)
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "layoutColetor":{ "softwareColetor": "Software coletor", "versaoColetor": "20" }, "cabecalho":{ "empresa": "02", "matMotorista": "000063", "cartaoMotorista":"7475975", "matCobrador": "919191", "cartaoCobrador":"7475976", "dataMovimento": "20240101", "filipeta":"000002582789610" }, "servicos":[ { "codServico": "02", "codVeiculo": "PREFIX", "prefixoLinha": "73859", "codigoLinha": "20", "turno": "1", "dataInicioViagem": "20240101", "dataTerminoViagem": "20240101", "hrInicio": "0200", "hrFim": "0300", "dadosValidador":{ "roletaInicioValidador": "0000001", "roletaFim": "0000002", "pagamentos":[{ "tipoPagamento": "000004", "quantidadePassageiros": 20, "valorUnitario": 20.02 }] }, "totalArrecadado": 200.00, "totalGratuidades": 12.30, "totalDinheiro": 32.50, "diferenca": 10.10 } ] } |
Estrutura da mensagem de retorno do POST (Response):
Atributo | Pai | Nivel | Ocorrência | Formato |
---|---|---|---|---|
status | - | 1 | 0:1 | String(7) |
prestacaoContas | - | 1 | 0:1 | String(6) |
message | - | 1 | 0:1 | String(36) |
- status – Informação de sucesso ou erro
- prestacaoContas – Código cadastrado da prestação de contas
- Message - Mensagem de sucesso ou de erro
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "ticketCodestatus": "WIO9753123654789789363655241452363sucess", "registryKeyprestacaoContas": [ { "key": "KEYIO7878874854545454998598525", "success": true }, { "key": "KEYYZE7878RE4854545454998598576", "success": true } ], "keyAmount": 2 } |
Códigos De Erros De Validação:
- 800 – Campo não informado na estrutura do arquivo.
- 801 – Campo obrigatório não enviado.
- 802 – Campo com valor inválido.
803 – TAFFIL não encontrado no complemento de empresas.
- 804 – Layout Inválido.
- 805 – Código de Prioridade inválido!
- 806 – Campo com erro na codificação ou criptografia
- 807 – Código de Fila inválido!
- 808 – Estrutura da tabela TAFST2 está desatualizada
- 809 - Não há configuração de empresas na chave PrepareIn seção TAF_CFGJOB
- 810 - Chave # de Identificação de filial não encontrada.
- 811 - Não foi possível identificar a filial # no corpo da mensagem.
- 812 - Código da Filial ERP # não pertence ao mesmo Grupo de Empresas no TAF considerando os registros integrados anteriormente neste lote.
- 813 - O TAFKEY # já existe na TAFST2 e encontra-se pendente de processamento ou em processamento.
- 814 - O Xml Contido no campo TAFMSG (integrationMessage) esta em desacordo com as versoes suportadas pelo TAF. Integracao da Versao 1.0 disponivel apenas para eventos SESMT
"000002",
"status": "Prestação de contas incluída com sucesso",
} |
Código De Erro De Validação:
- 400 – Cadastro não encontrado
Legenda:
# - valor variável.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "coderr "errorCode": 803400, "description "errorMessage": "OCadastro valorde do campo sourceBranch (TAFFIL) não está no cadastro no complemento de empresas.linha não encontrada" } |
RESTFAULT*
- 500 - Erro Interno no Servidor
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "ticketCodecode": "WIO9753123654789789363655241452363"500, "registryKey": [ { "key "detailedMessage": "KEYIO7878874854545454998598525", "success": false, "error": [ { "coderr": 801, "description": "Campo TAFFIL (sourceBranch) e Obrigatorio." }, { "coderr": 803, "description": "O valor do campo TAFFIL (sourceBranch) nao esta cadastro no complemento de empresas." } { "coderr": 805, "description": "Codigo de Prioridade invalido! Codigo enviado: '8'. Codigos validos: 0 - Urgente, 1 - Prioridade Critica, 2 - Prioridade Alta, 3 - Prioridade Media, 4 - Prioridade Baixa, 5 - Nao Prioritario" } ] }, { "key": "KEYYZE7878RE4854545454998598576", "success": true }, { "key": "KEYQWE7878RE4854545454998598571", "success": true }, { "key": "KEYQIU7878RE4854545454998598544", "success": true } ], "keyAmount": 4 } |
RESTFAULT*
500 - Erro Interno no Servidor "message": "Internal Server Error"
} |