Web Service REST

Produto:
TOTVS Automação Fiscal
Versões:
12.1.16+

Definição do Serviço

 

Nome: WSTAFST2

Objetivo: Permitir a Integração com o módulo SIGATAF utilizando um WebService do Tipo REST.

Descrição: Integra os produtos na tabela compartilhada TAFST2, permite a consulta do status de integração e cadastro dos registros através do TAFKEY ou TAFTICKET e permite a exclusão dos registros através do TAFTICKET.

Métodos: POST, GET e DELETE.

 

Definição dos métodos

POST

Descrição do Método: O método POST segue o conceito método devendo seu conteúdo ser enviado no corpo da mensagem (body).

 

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

Atenção: 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

ticketCode

-

1

1

String(36)

registryKey

-

1

1:N

-

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

2

1

Int(9999)

  • ticketCode – atributo raiz
  • registryKey – Array contendo os TAFKEY requisitados.
  • 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.

 

Exemplo de mensagem POST:

{"ticketCode" : "WIO9753123654789789363655241452363",
  "lote": [
    	{"sourceBranch" : "0100",
      	 "messageType" : "2",
      	 "messageSequential" : "001",
      	 "registryType" : "S-1010",
      	 "registryKey" : "KEYIO7878874854545454998598525",
      	 "integrationMessage": "PGVTb2NpYWw+PGV2dFRhYlJ1YnJpY2EgaWQ9J1MtMTAxMDEzMDUyMDE2MTU0MDE2JyB2ZXJzYW89JzEuMSc+PGlkZUV2ZW50bz48dHBBbWI+MzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz48L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTAwMDEyMjwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGFsdGVyYWNhbz48aWRlUnVicmljYT48Y29kUnVicj45OTg8L2NvZFJ1YnI+PGluaVZhbGlkPjIwMTYtMDM8L2luaVZhbGlkPjwvaWRlUnVicmljYT48ZGFkb3NSdWJyaWNhPjxkc2NSdWJyPkJBU0UgUEVOU0FPIFBHVE88L2RzY1J1YnI+PG5hdFJ1YnI+OTk4OTwvbmF0UnVicj48dHBSdWJyPjM8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjxyZXBEU1I+TjwvcmVwRFNSPjxyZXAxMz5OPC9yZXAxMz48cmVwRmVyaWFzPk48L3JlcEZlcmlhcz48cmVwUmVzYz5OPC9yZXBSZXNjPjwvZGFkb3NSdWJyaWNhPjwvYWx0ZXJhY2FvPjwvaW5mb1J1YnJpY2E+PC9ldnRUYWJSdWJyaWNhPjwvZVNvY2lhbD4=",
      	 "integrationDate" : "20161210",
	  	 "integrationTime": "14:15:22"
    	},
		{"sourceBranch" : "0100",
      	 "messageType" : "2",
      	 "messageSequential" : "001",
      	 "registryType" : "S-2100",
	  	 "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" :  ""
  		}
  	]
}

Retorno (Response):

{
"ticketCode": "WIO9753123654789789363655241452363",
"registryKey": [
	{
		"key": "KEYIO7878874854545454998598525",
		"success": true
	},
	{
		"key": "KEYYZE7878RE4854545454998598576",
		"success": true
	}
  ],
"keyAmount": 2
}

GET

Descrição do Método: O método GET retorna os status dos registros integrados de acordo com os parâmetros (atributos) enviados na URL.

A Consulta pode combinar parâmetros utilizando a sintaxe “Query String” conforme exemplo abaixo:

http://172.16.31.214:8085/rest/wstafst2?ticketCode=F95975312365478978936365524145236352®istryKey=KEYQWE7878RE4854545454998598571

 

Estrutura da requisição GET (Request):

Parâmetro

Descrição

Obrigatório

ticketCode

TAFTICKET

OC

registryKey

TAFKEY

OC

searchMode

Filtro para busca. .

N

 

  • ticketCode – Código do TAFTICKET, Obrigatório caso registryKey não seja informado.
  • registryKey – Código do TAFKEY, Obrigatório caso ticketCode não seja informado.
  • searchMode – Modo de pesquisa, quando não informado o response retorna todos os TAFKEYs relacionados a busca, quando igual a 1 retorna a última ocorrência do TAFKEY, quando igual a 2 retorna a última ocorrência válida do TAFKEY. Este parâmetro é útil quando o mesmo TAFKEY é enviado em vários TAFTICKET diferentes.

 

Estrutura da Resposta do método GET (Response):

 

Atributo

Pai

Nivel

Ocorrência

Formato

type

-

1

1

-

code

-

1

1:N

String(36-100)

Items

-

1

1

-

success

Items

2

1

boolean(true : false)

proccessed

Items

2

1

boolean(true : false)

description

Items

2

1

String(100)

registryKey

Items

2

0:1

String(100)

ticketCode

Items

2

0:1

String(36)

errorCode

Items

2

0:1

String(6)

errorDescription

Items

2

0:1

String(60)

errorDetail

Items

2

0:1

String(220)

statusCode

Items

2

0:1

String(1)

statusDescription

Items

2

0:1

String(25)

active

Items

2

0:1

boolean(true : false)

 

  • type – Determina o agrupamento do retorno que pode ser por ticketCode (TAFTICKET) ou registryKey (TAFKEY), o agrupamento depende dos parâmetros enviados no request, quando o registryKey é informado e o ticketCode omitido, o  retorno será por registryKey caso contrário por ticketCode.
  • code – Código do registro indicado no atributo type.
  • items – Itens do response.
  • success – informa que o envio do registro pelo método POST  foi realizado com sucesso.
  • proccessed – Informa se o registro foi processado (Job2) e integrado com sucesso no seu respectivo cadastro.
  • description – Descrição do status atual do registro.
  • registryKey – código do TAFKEY, esse atributo somente é exibido quando type for igual a ticketCode.
  • ticketCode – código do TAFTICKET, esse atributo somente é exibido quando type for igual a registryKey.
  • errorCode – Código do erro contido no campo TAFCODERR na tabela TAFXERP, atributo exibido somente quando proccessed for igual a false.
  • errorDescription – Descrição do errorCode, atributo exibido somente quando proccessed for igual a false.
  • errorDetail – Detalhes do erro, alguns tipos de erros possuem detalhes e são armazenados no campo TAFERR na tabela TAFXERP, atributo exibido somente quando proccessed for igual a false.
  • statusCode – Status do registro no TAF, atributo exibido somente quando proccessed for igual a true.
  • statusDescription – Descrição do status no TAF, atributo exibido somente quando proccessed for igual a true.
  • ative – Informa se o registro está ativo no TAF, atributo exibido somente quando proccessed for igual a true.

 

Exemplos de requisição utilizando o método GET:

 

  • Consulta pelo ticketCode:

Request:

http://172.16.31.214:8085/rest/wstafst2?ticketCode=WIO9753123654789789363655241452363

 

Response:

{
  "type": "ticketCode",
  "code": "WIO9753123654789789363655241452363",
  "items": [
    {
      "success": true,
      "proccessed": false,
      "description": "Aguardando Processamento.",
      "registryKey": "KEYIO7878874854545454998598525",
      "errorCode": "",
      "errorDescription": "",
      "errorDetail": ""
    },
    {
      "success": true,
      "proccessed": false,
      "description": "Aguardando Processamento.",
      "registryKey": "KEYYZE7878RE4854545454998598576",
      "errorCode": "",
      "errorDescription": "",
      "errorDetail": ""
    }
  ]
}


Response após a execução do processamento:
{
  "type": "ticketCode",
  "code": "WIO9753123654789789363655241452363",
  "items": [
    {
      "success": true,
      "proccessed": false,
      "description": "Registro Inconsistente.",
      "registryKey": "KEYIO7878874854545454998598525",
      "errorCode": "000007",
      "errorDescription": "A operacao solicitada no XML esta em desacordo com o cenario do registro na base do TAF",
      "errorDetail": ""
    },
    {
      "success": true,
      "proccessed": true,
      "description": "Registro Processado.",
      "registryKey": "KEYYZE7878RE4854545454998598576",
      "statusCode": " ",
      "statusDescription": "Registro Integrado",
      "active": true
    } 
 ]
}

Observação: O exemplo acima contem os 2 tipos de retorno possíveis para um TAFKEY, o atributo proccessed define se vão ser apresentados os atributos de Erro ou de Sucesso conforme descrito acima na tabela de estrutura da resposta do método GET.

 

DELETE

 

 

Exemplo de Consumo do Serviço

 

 

 

 

 

 

 

Códigos de Erro ( RESTFault )