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 |
---|
TAFST2
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 |
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 |
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.
- 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 |
Aviso | ||
---|---|---|
| ||
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional. |
Aviso | ||
---|---|---|
| ||
Para a utilização de caracteres especiais nos conteúdos dos atributos, é necessário a definição do encode correto no Header das mensagens de todos os métodos. Authorization : Basic ****** Content-Type : application/json;charset=UTF-8 |
Estrutura da mensagem de retorno do POST (Response):
Atributo
Pai
Nivel
Ocorrência
Formato
ticketCode
-
0:1 | String( |
10) |
roletaFim |
dadosValidador |
2 | 0: |
-
1 | String(10) | ||
pagamentos | - | 3 | 1 |
Array | |||
tipoPagamento | pagamentos | 3 | 1 |
:1 | String( |
6) |
key
registryKey
2
1
String(100)
success
registryKey
2
1
boolean(true : false)
Tipo de pagamento no cadastro de Forma de pagamento | |||||
quantidadePassageiros | pagamentos | 3 | 1:1 | Numerico | |
valorUnitario | pagamentos | 3 | 1:1 | Numerico | |
totalArrecadado | servicos |
error
2 | 0: |
1 |
Numerico |
totalGratuidades |
servicos |
2 | 0:1 |
Int(3)
description
error
3
1
String(100)
Numerico | |||||
totalDinheiro | servicos | 2 | 0:1 | Numerico | |
diferenca | servicos | 2 |
keyAmount
registryKey
0:1 |
Int(9999)
Numerico |
Aviso | ||
---|---|---|
| ||
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional. |
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{"ticketCode" : "WIO9753123654789789363655241452363", "lotelayoutColetor":{ [ { "sourceBranchsoftwareColetor" : "0100Software coletor", "messageTypeversaoColetor" : "220" }, "cabecalho":{ "messageSequentialempresa" : "00102", "registryTypematMotorista" : "S-1010000063", "registryKeycartaoMotorista" : "KEYIO78788748545454549985985257475975", "integrationMessagematCobrador": "PGVTb2NpYWw+PGV2dFRhYlJ1YnJpY2EgaWQ9J1MtMTAxMDEzMDUyMDE2MTU0MDE2JyB2ZXJzYW89JzEuMSc+PGlkZUV2ZW50bz48dHBBbWI+MzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz48L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTAwMDEyMjwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGFsdGVyYWNhbz48aWRlUnVicmljYT48Y29kUnVicj45OTg8L2NvZFJ1YnI+PGluaVZhbGlkPjIwMTYtMDM8L2luaVZhbGlkPjwvaWRlUnVicmljYT48ZGFkb3NSdWJyaWNhPjxkc2NSdWJyPkJBU0UgUEVOU0FPIFBHVE88L2RzY1J1YnI+PG5hdFJ1YnI+OTk4OTwvbmF0UnVicj48dHBSdWJyPjM8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjxyZXBEU1I+TjwvcmVwRFNSPjxyZXAxMz5OPC9yZXAxMz48cmVwRmVyaWFzPk48L3JlcEZlcmlhcz48cmVwUmVzYz5OPC9yZXBSZXNjPjwvZGFkb3NSdWJyaWNhPjwvYWx0ZXJhY2FvPjwvaW5mb1J1YnJpY2E+PC9ldnRUYWJSdWJyaWNhPjwvZVNvY2lhbD4=", "integrationDate" : "20161210", "integrationTime": "14:15:22919191", "cartaoCobrador":"7475976", "dataMovimento": "20240101", "erpownerfilipeta" : "DATASUL000002582789610" }, {"sourceBranch" : "0100servicos",:[ "messageType" : "2", { "messageSequentialcodServico" : "00102", "registryType" : "S-2200", "registryKeycodVeiculo" : "KEYYZE7878RE4854545454998598576PREFIX", "integrationMessage": "PGVTb2NpYWw+PGV2dENhZEluaWNpYWwgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNjEyMDkxNDU5NTQwMDAwMSc+PGlkZUV2ZW50bz48aW5kUmV0aWY+MTwvaW5kUmV0aWY+PG5yUmVjaWJvPjwvbnJSZWNpYm8+PHRwQW1iPjM8L3RwQW1iPjxwcm9jRW1pPjE8L3Byb2NFbWk+PHZlclByb2M+MS4wPC92ZXJQcm9jPjwvaWRlRXZlbnRvPjxpZGVFbXByZWdhZG9yPjx0cEluc2M+MTwvdHBJbnNjPjxuckluc2M+NTMxMTM3OTE8L25ySW5zYz48L2lkZUVtcHJlZ2Fkb3I+PHRyYWJhbGhhZG9yPjxjcGZUcmFiPjMyMDA5MDM3ODQ2PC9jcGZUcmFiPjxuaXNUcmFiPjEyMjAzNjcxODQ0PC9uaXNUcmFiPjxubVRyYWI+IEdUIFhNQlBFUkhVSlpOQ1FGU0lWTEFPRDwvbm1UcmFiPjxzZXhvPk08L3NleG8+PHJhY2FDb3I+MTwvcmFjYUNvcj48ZXN0Q2l2PjI8L2VzdENpdj48Z3JhdUluc3RyPjwvZ3JhdUluc3RyPjxuYXNjaW1lbnRvPjxkdE5hc2N0bz4xOTc2LTA0LTEzPC9kdE5hc2N0bz48Y29kTXVuaWM+MTIwMDEwNTwvY29kTXVuaWM+PHVmPlNQPC91Zj48cGFpc05hc2N0bz4wMTM8L3BhaXNOYXNjdG8+PHBhaXNOYWM+MDEzPC9wYWlzTmFjPjxubU1hZT5ORVVTQSBDQVJWQUxITyBORVZFUzwvbm1NYWU+PG5tUGFpPkpPU0UgUkVZTkFMRE8gQ1JFU1BPIE5FVkVTPC9ubVBhaT48L25hc2NpbWVudG8+PGRvY3VtZW50b3M+PENUUFM+PG5yQ3Rwcz4wMDAzNTgwMDwvbnJDdHBzPjxzZXJpZUN0cHM+MDAwNzM8L3NlcmllQ3Rwcz48dWZDdHBzPlNQPC91ZkN0cHM+PC9DVFBTPjxSRz48bnJSZz4xNi43MjEuMDMwPC9uclJnPjxvcmdhb0VtaXNzb3I+U1NQPC9vcmdhb0VtaXNzb3I+PGR0RXhwZWQ+MTk4Mi0wMy0wMjwvZHRFeHBlZD48L1JHPjxDTkg+PG5yUmVnQ25oPjAwMDAwMDAwMDA8L25yUmVnQ25oPjx1ZkNuaD48L3VmQ25oPjxkdFZhbGlkPjwvZHRWYWxpZD48Y2F0ZWdvcmlhQ25oPjwvY2F0ZWdvcmlhQ25oPjwvQ05IPjwvZG9jdW1lbnRvcz48ZW5kZXJlY28+PGV4dGVyaW9yPjxwYWlzUmVzaWQ+MDEzPC9wYWlzUmVzaWQ+PGRzY0xvZ3JhZD5BTEJBPC9kc2NMb2dyYWQ+PG5yTG9ncmFkPjE0NDQ8L25yTG9ncmFkPjxiYWlycm8+UFEuIEpBQkFRVUFSQTwvYmFpcnJvPjxubUNpZD5TQU4gTFVJWjwvbm1DaWQ+PGNvZFBvc3RhbD4wNDM0NjAwMDwvY29kUG9zdGFsPjwvZXh0ZXJpb3I+PC9lbmRlcmVjbz48aW5mb0RlZmljaWVuY2lhPjxkZWZGaXNpY2E+TjwvZGVmRmlzaWNhPjxkZWZWaXN1YWw+TjwvZGVmVmlzdWFsPjxkZWZBdWRpdGl2YT5OPC9kZWZBdWRpdGl2YT48ZGVmTWVudGFsPk48L2RlZk1lbnRhbD48ZGVmSW50ZWxlY3R1YWw+TjwvZGVmSW50ZWxlY3R1YWw+PHJlYWJSZWFkYXA+TjwvcmVhYlJlYWRhcD48L2luZm9EZWZpY2llbmNpYT48YXBvc2VudGFkb3JpYT48dHJhYkFwb3NlbnQ+TjwvdHJhYkFwb3NlbnQ+PC9hcG9zZW50YWRvcmlhPjxjb250YXRvPjxmb25lUHJpbmM+MDAxMzQ3MzU1NTUgLzwvZm9uZVByaW5jPjxmb25lQWx0ZXJuYXQ+MDExNzg5Nzk4Nzk4PC9mb25lQWx0ZXJuYXQ+PGVtYWlsQWx0ZXJuYXQ+UkVZTkFMRE9ASE9UTUFJTC5DT008L2VtYWlsQWx0ZXJuYXQ+PC9jb250YXRvPjwvdHJhYmFsaGFkb3I+PHZpbmN1bG8+PG1hdHJpY3VsYT4wMDAwMDAwMDAwMDAwMDAwMDAwNzwvbWF0cmljdWxhPjx0cFJlZ1RyYWI+MTwvdHBSZWdUcmFiPjx0cFJlZ1ByZXY+MTwvdHBSZWdQcmV2PjxpbmZvUmVnaW1lVHJhYj48L2luZm9SZWdpbWVUcmFiPjxpbmZvQ29udHJhdG8+PGNvZENhdGVnPjMwMjwvY29kQ2F0ZWc+PHJlbXVuZXJhY2FvPjx2clNhbEZ4PjEwMDAuMDA8L3ZyU2FsRng+PHVuZFNhbEZpeG8+NTwvdW5kU2FsRml4bz48L3JlbXVuZXJhY2FvPjxkdXJhY2FvPjx0cENvbnRyPjE8L3RwQ29udHI+PC9kdXJhY2FvPjxsb2NhbFRyYWJhbGhvPjwvbG9jYWxUcmFiYWxobz48L2luZm9Db250cmF0bz48L3ZpbmN1bG8+PC9ldnRDYWRJbmljaWFsPjwvZVNvY2lhbD4=", "integrationDate" : "", "integrationTimeprefixoLinha" : "73859", "registryPrioritycodigoLinha" : "020", "integrationQueueturno" : "1", "erpownerdataInicioViagem" : "DATASUL20240101", "registryPredecessordataTerminoViagem" : "KEYIO787887485454545499859852520240101", "transferBranch" : "0200" } ] } | ||||||
Bloco de código | ||||||
| ||||||
{ "ticketCode"hrInicio": "WIO97531236547897893636552414523630200", "registryKey": [ { "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.
Aviso title Atenção! No método POST caso o primeiro item do lote não esteja com o TAFFIL cadastrado no complemento de empresas o sistema irá rejeitar o lote inteiro, caso contrario é realizado uma avaliação item a item verificando se a filial é válida e se pertence ao mesmo grupo de empresas no TAF, neste caso é rejeitado somente os registros inválidos dentro do lote.
- 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
Legenda:
# - valor variável.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "coderrhrFim": 803"0300", "description": "O valor do campo sourceBranch (TAFFIL) não está no cadastro no complemento de empresas." } | ||||
Bloco de código | ||||
| ||||
{ "ticketCode": "WIO9753123654789789363655241452363", "registryKeydadosValidador": [ { { "key": "KEYIO7878874854545454998598525", "success": false, "errorroletaInicioValidador": ["0000001", { "coderrroletaFim": 801"0000002", "description": "Campo TAFFIL (sourceBranch) e Obrigatorio." "pagamentos":[{ }, { "coderrtipoPagamento": 803"000004", "description": "O valor do campo TAFFIL (sourceBranch) nao esta cadastro no complemento de empresas.""quantidadePassageiros": 20, } { "coderrvalorUnitario": 805, 20.02 "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", "successtotalArrecadado": true200.00, }, { "keytotalGratuidades": "KEYQWE7878RE4854545454998598571"12.30, "success "totalDinheiro": true 32.50, }, { "keydiferenca": "KEYQIU7878RE4854545454998598544",10.10 "success": true } ], "keyAmount": 4] } |
RESTFAULT*
- 701 - startRecno e ticketCode não informados no GET (é obrigatório que pelo menos 1 deles seja informado)
- 702 - Erro na criação/abertura da tabela TAFST2 ou TAFXERP
- 703 - O parâmetro searchMode deve ser preenchido com 1 ou 2.
- 704 - Arquivo vazio (Não foi enviado uma mensagem no body do POST)
- 705 - Erro ao realizar parser da mensagem (o arquivo enviado no Body não é um json válido)
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 | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"status": "sucess",
"prestacaoContas": "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 | ||||
---|---|---|---|---|
| ||||
{
"errorCode": 400,
"errorMessage": "Cadastro de linha não encontrada"
} |
RESTFAULT*
- 500 - Erro Interno no Servidor
Bloco de código | ||||
---|---|---|---|---|
| ||||
{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error"
} | ||||
Aviso | ||||
| ||||
Apesar do código de erro iniciar com 7 o status HTTP de um request que submetido a RestFault é 500 - Erro Interno no Servidor. |