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:1 | String(15) |
messageSequential
lote
2
Matricula no cadastro de colaboradores | |||||
cartaoMotorista | cabecalho | 1 | 0:1 | String(50) | |
matCobrador | cabecalho | 1 | 0:1 | String( |
15) |
registryType
lote
2
Matricula no cadastro de colaboradores | ||||
cartaoCobrador | cabecalho | 1 | 0:1 | String( |
50) |
registryKey
lote
2
dataMovimento | cabecalho | 1 | 1:1 | String - AAAAMMDD | |
filipeta | cabecalho | 1 | 1:1 | String( |
30) |
servicos |
- | 2 | 0:1 |
Array |
codServico |
servicos | 2 | 0:1 | String |
(15) | |
codVeiculo | servicos |
integrationTime
2 | 0:1 | String |
(8) | Prefixo no cadastro de frotas | ||||
prefixoLinha | servicos | 2 | 0:1 | String(5) | Prefixo no cadastro de linhas |
codigoLinha | servicos |
2 | 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) |
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. |
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", "registryKey": [ { "key"prestacaoContas": "KEYIO7878874854545454998598525000002", "successstatus": true }, { "key": "KEYYZE7878RE4854545454998598576", "success": true } ], "keyAmount": 2 } |
"Prestação de contas incluída com sucesso",
} |
Código De Erro De Validação:
- 800 400 – Campo não informado na estrutura do arquivo.
- 801 – Campo obrigatório não enviado.
- Cadastro não encontrado
Legenda:
# - valor variável.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "coderr "errorCode": 803400, "description "errorMessage": "OCadastro valor do campo sourceBranch (TAFFIL) de linha não está no cadastro no complemento de empresas.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"
} |