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 | Cadastros Protheus | |||
---|---|---|---|---|---|---|---|---|---|
layoutColetor | - | 1 | 1 ticketCode | - | |||||
softwareColetor | layoutColetor | 1 | 1 | String(36) | |||||
loteversaoColetor | -layoutColetor | 1 | 1:N | - | |||||
sourceBranch | lote | 2 | TAFFIL | 1 | String(40) | ||||
String(36) | |||||||||
cabecalho | - | 1 | 1 | - | |||||
empresa | cabecalho | 1 | 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 | TAFREGPRED0:1 | String(100) | |||||
transferBranch | lote | 2 | TAFFILTRAN0:1 | String(40) | |||||
complement | lote | 2 | TAFCOMP0:1 | String(100) |
- ticketCode – layoutColetor – 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.
- cabecalho - atributo raiz
- servicos - atributo raizcomplement - 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. |
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(36) |
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 | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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.
- 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*
- 500 - Erro Interno no Servidor
...