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 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 – SXBDicionário de regras de dependência – XXA
• 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

• Método: PUT, URI: table, 
• Método: PUT, URI: field
• Método: PUT, URI: folder
• Método: PUT, URI: question
• Método: PUT, URI: genericTable
• Método: PUT, URI: parameter
• Método: PUT, URI: programText
• Método: PUT, URI: lookup
• Método: PUT, URI: menu
• Método: PUT, URI: help

<Regra de negócio é o que define a forma de fazer o negócio, o processo definido e/ou as regras que devem ser contempladas. Devem ser descritas restrições, validações, condições e exceções do processo. Caso necessário, incluir neste capítulo também regras de integridade que devem ser observadas no momento do desenvolvimento>.

<Na tabela abaixo informe quais são as rotinas envolvidas, o tipo de operação, a opção de menu e se necessário uma breve descrição das regras de negócio relacionadas a rotina>.

Exemplo de Aplicação:

• Criar o campo “% Mínimo Espécie” (AAA_PERESP) onde o usuário informará o % que o aluno pagará em dinheiro. Esse % poderá ser alterado durante a negociação.
• Criar o campo “Referência Mínima para Cálculo” (AAA_REFCAL) onde o usuário informará um dos 4 valores disponíveis para pagamento das mensalidades  como a referência mínima para calcular o débito total do aluno.
• Criar o parâmetro MV_ACPARNE que definirá se as informações de “% Mínimo Espécie” e “Referência Mínima para Cálculo” serão obrigatórias.
• O parâmetro MV_ACPARNE deve ter as seguintes opções: 1=Obrigatório e 2=Opcional. Deve ser inicializado como opcional>.

Tabelas Utilizadas

• SE2 – Cadastro de Contas a Pagar
• FI9 – Controle de Emissão de DARF>.

Opcional

Protótipo de Tela

<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.

Protótipo 01

 Image Removed

Opcional

Fluxo do Processo

<Nesta etapa incluir representações gráficas que descrevam o problema a ser resolvido e o sistema a ser desenvolvido. Exemplo: Diagrama - Caso de Uso, Diagrama de Atividades, Diagrama de Classes, Diagrama de Entidade e Relacionamento e Diagrama de Sequência>. 

Opcional

Dicionário de Dados

Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/

(Opcional)

Grupo de Perguntas

<Informações utilizadas na linha Protheus>.

Nome: FINSRF2

(Opcional)

Consulta Padrão

<Informações utilizadas na linha Protheus>

Consulta: AMB

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

(Opcional)

Estrutura de Menu

<Informações utilizadas na linha Datasul>.

Procedimentos

Programas

Cadastro de Papéis

<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.

<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.