Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Disponibilizar uma API para busca e inclusão de strings de tradução no AtuSX.

Definição da Regra de Negócio

REST

Para o correto desenvolvimento, utilização e configuração veja a documentação do REST antes de utilizar esta API: Documentação do REST no Protheus.

API - Put

Deverá ser desenvolvida uma API de integração com o AtuSX para permitir a busca e inclusão de strings de tradução diretamente em sua base de dados.

O nome da rotina RESTFul deverá ser ATUSX.

A API deverá ser desenvolvida usando os fundamentos do RESTFul e deverá contemplar os seguintes metadados do AtuSX:

• Dicionário de perguntas – SX1
• Dicionário de tabelas – SX2
• Dicionário de campos – SX3
• Cadastro de tabelas genéricas – SX5
• Dicionário de Parâmetros – SX6
• Dicionário de Pastas e agrupamentos – SXA 
• Dicionário de consultas padrões – SXB
• Dicionário de grupo de campos – SXG
• Help e help de campos
• Tabela de strings de tradução de programas – arquivos .CH
• Menus do sistema

As chamadas do REST deverão ser organizadas da seguinte forma

Exemplo de como deverá ser composta uma URL: http://<servidor>:<porta>/rest/atusx/v1/<URI>

O v1 descrito na URL da API se refere a sua versão. Esta poderá mudar caso haja novas implementações na API.

 Todos os métodos REST deverão receber um JSON no corpo da mensagem que deverá conter as seguintes informações:

• version: Versão do dicionário no AtuSX (parâmetro não obrigatório)
• project: Código do projeto no AtuSX (parâmetro não obrigatório)
• package: Código do pacote no AtuSX (parâmetro não obrigatório)
  
  
• key: Array contendo os valores que representam a chave da tabela de destino no AtuSX.
  Esta opção poderá conter os seguinte valores:

Observação: Para o campo País do Menu, sempre é considero o país informado (para menus localizados) e caso não seja encontrado também o país * (para menus do tipo ALL).

 
Lista de possíveis países:

• property: Mnemônico que representa alguma coluna específica da tabela que será atualizada.
  Os valores possíveis para esse parâmetro são:

  URI	Valores
  /question	description, definition1, definition2, definition3. definition4, definition5
  /table	description
  /field	title, description, options
  /genericTable	description
  /parameter	description1, description2, description3
  /folder	description
  /lookup	description
  /fieldGroup	description
  /help	problemtext, solutiontext
  /programText	text
  /menu	text, key

• idiom: Idioma no qual se deseja incluir o temo traduzido. A lista de possíveis valores para esse parâmetro são: pt-br (português do Brasil), pt (português de Portugal), en (ingles), es (espanhol), ru (russo).
• value: Valor traduzido

O JSON deverá ser montado seguindo o seguinte modelo:

[
	{
		"version" : "<AtuSX version -non obligatory->",
		"project" : "<AtuSX project -non obligatory->",
		"package" : "<AtuSX package -non obligatory->",
		"key" : [
			<Index Keys separate by ",">
		],
		"property" : "<Field to update>",
		"idiom" : "<pt-br, pt, en, es, ru>",
		"value" : "<Tranlated term>"
	},
	...
]

Exemplo de JSON formatado com valores reais para alterações de registros de SX1:

URI: /atusx/v1/question

[
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"description","idiom":"ru","value":"?????? ????"},
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"definition1","idiom":"ru","value":"??"},
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"definition2","idiom":"ru","value":"???"}
]

De modo geral o JSON enviado deverá ser um array onde cada linha será correspondente a um UPDATE na tabela do AtuSX. Cada item do array deverá ter todas as informações necessárias para a localização do registro que será atualizado e o valor a ser incluído.

Autenticação

A principio utilizaremos autenticação HTTP Basic.

Erros e Validações

A própria API deverá possuir tratamento para diversos erros nas requisições. Segue a lista dos principais erros tratados:

• Problema na estrutura do JSON.
• Não preenchimento da tag Key.
• Não preenchimento da tag Property.
• Não preenchimento da tag Idiom.
• Não preenchimento da tag Value.
• Não preenchimento de um idioma válido (o conteúdo deve ser: pt-br, pt, en, es ou ru).
• Conteúdo da tag Property ser inválido.
• Tamanho do array passado na tag Key difere do tamanho da chave de índice correspondente.
• Registro não pode ser encontrado.

Casso seja passado mais de um JSON pra ser processado de uma só vez, o erro deverá retornar qual posição do array apresentou erro. Porém, neste caso, todos os JSONs anteriores terão sido processados e o processo será abortado ao localizar um erro.

API - Get

Criação da API para poder recuperar os valores que precisam ser traduzidos baseados em um idioma de referência, ou seja, a API deverá receber o idioma para o qual se deseja traduzir e o idioma de referencia, o JSON resultante da busca retornará o texto do idioma de referência para ser enviado para tradução.

As validações dos Gets deverão ser as mesmas do Put (descritas no item Erros e Validações) assim como a autenticação (descrita no item Autenticação).

As chamadas disponíveis para os Gets também serão as mesmas do Put

A chamada dos Gets deverão ser complementadas com a seguinte query string:

Os filtros terão as seguintes opções para cada Get:

Exemplo de chamada:

Nesta chamada serão retornados apenas as strings a serem traduzidas, contidas no FATA010.CH

O JSON de resposta contém os seguintes dados:

• Values = Valores a serem traduzidos, estes já são acompanhados de seus mnemonicos
• Recno = recno do registro
• Package = pacote do registro no AtuSX
• Project = projeto do registro no AtuSX
• Key = chave única do item
• Idiom = idioma de referência
• Version = versão do registro no AtuSX