Histórico da Página
RESTWeb Service REST
Produto: | TOTVS Prestadores de Serviços Transporte de Passageiros |
Versões: | 12.1.2310+ |
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 |
---|---|---|---|---|---|
ticketCode | - | 1 | 1 | String(36) | |
lote | - | 1 | 1:N | - | |
sourceBranch | lote | 2 | TAFFIL | 1 | String(40) |
messageType | lote | 2 | TAFCODMSG | 1 | String(01) |
messageSequential | lote | 2 | TAFSEQ | 1 | String(03) |
registryType | lote | 2 | TAFTPREG | 1 | String(10) |
registryKey | lote | 2 | TAFKEY | 1 | String(100) |
integrationMessage | lote | 2 | TAFMSG | 1 | Memo - Base64 |
integrationDate | lote | 2 | TAFDATA | 0:1 | String - AAAAMM01 |
integrationTime | lote | 2 | TAFHORA | 0:1 | String - HH:MM:SS |
registryPriority | lote | 2 | TAFPRIORIT | 0:1 | String(01) |
integrationQueue | lote | 2 | TAFSTQUEUE | 0:1 | String(01) |
erpowner | lote | 2 | TAFOWNER | 0:1 | String(40) |
registryPredecessor | lote | 2 | TAFREGPRED | 0:1 | String(100) |
transferBranch | lote | 2 | TAFFILTRAN | 0:1 | String(40) |
complement | lote | 2 | TAFCOMP | 0:1 | String(100) |
- ticketCode – atributo raiz
- lote - estrutura dos itens.
- sourceBranch - Código Identificador da filial do ERP emissor.
- messageType - Determina se o arquivo enviado em TAFMSG é .txt (1)ou .Xml(2).
- messageSequential - Sequência do arquivo; A Mensagem em TAFMSG pode ser enviada em mais de 1 registro, para isso deve-se repetir as informações dos demais campos e alterar a sequencia de acordo com a ordem das informações enviadas.
- registryType - Chave do Registro.
- integrationMessage - Arquivo/Evento a ser integrado, a mensagem deve ser enviada com criptografia BASE64.
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. - integrationDate - Data da Integração.
- integrationTime - Hora da Integração.
- registryPriority - Prioridade de processamento do registro.
- integrationQueue - Registro será considerado na fila de integração. '1' - Enable ou '0' - Disable.
- erpowner - Identificação do dono do XML a ser integrado
- registryPredecessor - Identificador com o TAFKEY do registro predecessor, caso exista algum registro que o preceda.
- transferBranch - Identificador da Filial original do trabalhador a ser transferido.
- complement - Campo aberto na TAFST2, onde para os eventos S-1200 e S-1210, quando informado o conteúdo MV será utilizado a regra de gravação de eventos de múltiplos vínculos (gravação aberta).
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 | ||||
---|---|---|---|---|---|---|---|---|
ticketCodestatus | - | 1 | 0:1 | String(367) | registryKey | - | ||
1 | 0:N prestacaoContas | - | coderr- | 1 | 0:1 | IntString( | 336) | |
message | - | 1 | 0:1 | String( | 100)||||
key | registryKey | 2 | 1 | String(100) | ||||
success | registryKey | 2 | 1 | boolean(true : false) | ||||
error | registryKey | 2 | 0:N | - | ||||
coderr | error | 3 | 1 | Int(3) | ||||
description | error | 3 | 1 | String(100) | ||||
keyAmount | registryKey | 1 | 0:1 | Int(9999) | ||||
36) |
- status – Informação de sucesso ou erro
- prestacaoContas – Código cadastrado da prestação de contas
- Message - Mensagem de sucesso ou de erro
- ticketCode – atributo raiz
- registryKey – Array contendo os TAFKEY requisitados.
- coderr - Código de erro que impediu a integração do lote
- description - Descrição do erro que impossibilitou a integração do lote.
- key – Código do TAFKEY
- success – Informa se o TAFKEY foi integrado ou não.
- error – Array contendo os erros que impediram a integração do registro. Atributo gerado somente quando success for igual a false.
- coderr – Código do erro que impossibilitou a integração.
- description – Descrição do erro que impossibilitou a integração.
- keyAmount – Número de registros enviados no POST.
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "ticketCode" layoutColetor":{ "softwareColetor": "WIO9753123654789789363655241452363Software coletor", "loteversaoColetor": ["20" }, {"sourceBranch" "cabecalho":{ "empresa": "010002", "matMotorista": "000063", "messageTypecartaoMotorista" : "27475975", "messageSequentialmatCobrador" : "001919191", "cartaoCobrador":"7475976", "registryTypedataMovimento" : "S-101020240101", "filipeta":"000002582789610" }, "registryKey" servicos":[ { "codServico": "KEYIO787887485454545499859852502", "integrationMessagecodVeiculo": "PGVTb2NpYWw+PGV2dFRhYlJ1YnJpY2EgaWQ9J1MtMTAxMDEzMDUyMDE2MTU0MDE2JyB2ZXJzYW89JzEuMSc+PGlkZUV2ZW50bz48dHBBbWI+MzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz48L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTAwMDEyMjwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGFsdGVyYWNhbz48aWRlUnVicmljYT48Y29kUnVicj45OTg8L2NvZFJ1YnI+PGluaVZhbGlkPjIwMTYtMDM8L2luaVZhbGlkPjwvaWRlUnVicmljYT48ZGFkb3NSdWJyaWNhPjxkc2NSdWJyPkJBU0UgUEVOU0FPIFBHVE88L2RzY1J1YnI+PG5hdFJ1YnI+OTk4OTwvbmF0UnVicj48dHBSdWJyPjM8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjxyZXBEU1I+TjwvcmVwRFNSPjxyZXAxMz5OPC9yZXAxMz48cmVwRmVyaWFzPk48L3JlcEZlcmlhcz48cmVwUmVzYz5OPC9yZXBSZXNjPjwvZGFkb3NSdWJyaWNhPjwvYWx0ZXJhY2FvPjwvaW5mb1J1YnJpY2E+PC9ldnRUYWJSdWJyaWNhPjwvZVNvY2lhbD4=PREFIX", "integrationDateprefixoLinha" : "2016121073859", "integrationTimecodigoLinha": "14:15:2220", "erpownerturno" : "DATASUL1", }, {"sourceBranch" "dataInicioViagem": "010020240101", "messageTypedataTerminoViagem" : "220240101", "messageSequentialhrInicio" : "0010200", "registryTypehrFim" : "S-22000300", "registryKey" : "KEYYZE7878RE4854545454998598576", "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" : "", "integrationTime" : "", "dadosValidador":{ "roletaInicioValidador": "0000001", "roletaFim": "0000002", "pagamentos":[{ "tipoPagamento": "000004", "quantidadePassageiros": 20, "registryPriority" : "0", valorUnitario": 20.02 }] }, "integrationQueuetotalArrecadado" : "1"200.00, "erpownertotalGratuidades" : "DATASUL"12.30, "registryPredecessortotalDinheiro" : "KEYIO7878874854545454998598525", 32.50, "transferBranch" : "0200" } diferenca": 10.10 } ] } |
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "ticketCode": "WIO9753123654789789363655241452363", "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 | ||||
---|---|---|---|---|
| ||||
{ "coderr": 803, "description": "O valor do campo sourceBranch (TAFFIL) não está no cadastro no complemento de empresas." } |
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "ticketCode": "WIO9753123654789789363655241452363", "registryKey": [ { "key": "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*
701 - startRecno e ticketCode não informados no GET (é obrigatório que pelo menos 1 deles seja informado)title | Status HTTP |
---|
- 500 - Erro Interno no Servidor