Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|
Especificação | |||
Produto |
| Módulo |
|
Segmento Executor |
| ||
Projeto1 |
| IRM1 |
|
Requisito1 |
| Subtarefa1 |
|
Chamado2 |
| ||
País | ( ) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( ) Outro _____________. | ||
Outros | <Caso necessário informe outras referências que sejam pertinentes a esta especificação. Exemplo: links de outros documentos ou subtarefas relacionadas>. |
Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos).
Disponibilizar uma API para para busca e inclusão de strings de tradução no AtuSX.
Para o correto desenvolvimento, utilização e configuração veja a documentação do REST antes de utilizar esta API: Doducmentação Documentação do REST no Protheus.
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:
As chamadas do REST deverão ser organizadas da seguinte forma
Método | URI | Metadado |
---|---|---|
PUT | /question | Dicionário de perguntas |
PUT | /table | Dicionário de tabelas |
PUT | /field | Dicionário de campos |
PUT | /genericTable | Tabelas genéricas |
PUT | /parameter | Dicionário de parâmetros |
PUT | /folder | Dicionário de pastas e agrupamentos |
PUT | /lookup | Dicionário de consultas padrão |
PUT | /fieldGroup | Dicionário de grupos de campos |
PUT | /help | Help de campo |
PUT | /programText | Strings de programas |
PUT | /menu | Menus do sistema |
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:
URI | Valores | Exemplo de preenchimento |
---|---|---|
/question | [Grupo de Perguntas, ID do filtro padrão, Ordem do Pergunte, País] | "key":["ABSENT","","01","BRA"] |
/table | [Alias da tabela, País] | "key":["SA1","BRA"] |
/field | [Nome do campo, País] | "key":["A1_NOME","BRA"] |
/genericTable | [Código da tabela, Chave da Tabela, País] | "key":["00","01","BRA"] |
/parameter | [Nome do parâmetro, País] | "key":["MV_1DUP","BRA"] |
/folder | [Alias da tabela, Ordem da Folder, Grupo da Folder] | "key":["SA1","1",""] |
/lookup | [Código da SXB, Tipo da consulta padrão, Sequencia, Coluna, País] | "key":["A2A","1","01","DB","BRA"] |
/fieldGroup | [Código do grupo, País] | "key":["001","BRA"] |
/help | [Nome do help, País] | "key":[".A014NOPR.","BRA"] |
/programText | [ ID da tabela de cabeçalho do Help (ZB0)Nome do fonte, Código da String, País] | "key":[1"FATA010.CH","STR0001","BRA"] |
/menu | [Módulo, Função, País] ou [Código do menu] | "key":["0000008203"]"02","MATA065","RUS"] ou "key":["0000000116"] |
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:
Código | Sigla | Descrição |
---|---|---|
1 | ALL | Todos |
2 | BRA | Brasil |
3 | ARG | Argentina |
4 | EUA | Estados Unidos |
5 | CHI | Chile |
6 | COL | Colômbia |
7 | VEN | Venezuela |
8 | MEX | México |
9 | POR | Porto Rico |
10 | PAR | Paraguai |
11 | URU | Uruguai |
12 | PER | Peru |
13 | COS | Costa Rica |
14 | DOM | Rep. Dominicana |
15 | EQU | Equador |
16 | PAN | Pana |
17 | BOL | Bolívia |
18 | SAL | El Salvador |
19 | PTG | Portugal |
20 | ANG | Angola |
21 | HAI | Haiti |
22 | TRI | Trinidad e Tobago |
23 | PAD | Padrão |
24 | AUS | Austrália |
25 | RUS | Russia |
Informações | ||
---|---|---|
| ||
Sempre opte por traduzir um campo usando um código de país diferente de ALL, internamente a API fará a busca usando o país especificado, caso não consiga localiza-lo fazemos uma segunda busca usando o país ALL. |
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 | descriptiondescription, definition1, definition2, definition3. definition4, definition5 |
/table | description |
/field | title, description, options |
/genericTable | description |
/parameter | description1description1, description2, description3 |
/folder | descriptiondescription |
/lookup | descriptiondescription |
/fieldGroup | description |
/help | problemtext, solutiontext |
/programText | text |
/menu | text, key |
O JSON deverá ser montado seguindo o seguinte modelo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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
Bloco de código | ||||
---|---|---|---|---|
| ||||
[ {"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.
A principio utilizaremos autenticação HTTP Basic.
A própria API deverá possuir tratamento para diversos erros nas requisições. Segue a lista dos principais erros tratados:
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.
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
Método | URI | Metadado |
---|---|---|
GET | /question | Dicionário de perguntas |
GET | /table | Dicionário de tabelas |
GET | /field | Dicionário de campos |
GET | /genericTable | Tabelas genéricas |
GET | /parameter | Dicionário de parâmetros |
GET | /folder | Dicionário de pastas e agrupamentos |
GET | /lookup | Dicionário de consultas padrão |
GET | /fieldGroup | Dicionário de grupos de campos |
GET | /help | Help de campo |
GET | /programText | Strings de programas |
GET | /menu | Menus do sistema |
A chamada dos Gets deverão ser complementadas com a seguinte query string:
Idiom=<Idioma a ser traduzido>&RefIdiom=<Idioma de referência>&Country=<País a ser traduzido>&RefCountry=<País de referência>&Filter={<Array com os filtros>}&Page=<Página a ser retornada>&MaxPerPage=<Número de registros por página>&AllRegs=<1=Retorna tudo, 0=Apenas pendente de tradução | Padrão=0> |
Os filtros terão as seguintes opções para cada Get:
URI | Valores | Exemplo de preenchimento |
---|---|---|
/question | {Grupo de Perguntas, ID do filtro padrão, Ordem do Pergunte} | Filter={"ABSENT","","01"} |
/table | {Alias da tabela} | Filter={"SA1"} |
/field | {Nome do campo} | Filter={"A1_NOME"} |
/genericTable | {Código da tabela, Chave da Tabela} | Filter={"00","01"} |
/parameter | {Nome do parâmetro} | Filter={"MV_1DUP"} |
/folder | {Alias da tabela, Ordem da Folder, Grupo da Folder} | Filter={"SA1","1",""} |
/lookup | {Código da SXB, Tipo da consulta padrão, Sequencia, Coluna} | Filter={"A2A","1","01","DB"} |
/fieldGroup | {Código do grupo} | Filter={"001"} |
/help | {Nome do help} | Filter={".A014NOPR."} |
/programText | {Módulo ao qual a string pertence, Programa ao qual a string pertence, Código da String} | Filter={"SIGAFAT","FATA010.CH","STR0001"} |
/menu | {Código do menu} | Filter={"0000008203SIGAFAT"} |
Exemplo de chamada:
Nesta chamada serão retornados apenas as strings a serem traduzidas, contidas no FATA010.CH
http://localhost:8090/rest/atusx/v1/programText?Idiom=ru&RefIdiom=pt-br&Country=rus&RefCountry=bra&Filter={,"FATA010.CH"}&Page=1&MaxPerPage=50 |
Retorno:
&AllRegs=0 |
O JSON de resposta contém os seguintes dados:
{ "values" [22] 0: { " TEXT": ""Processo de Venda" " } - " recno": 30795 " package": " " "project" : " " "key" : [3] 0: 982 1: "STR0001" 2: "ALL" " idiom": "POR" "version": "000001" } 1: { " values": { " TEXT": ""Pesquisar" " } - "recno": 30796 "package": " " " project": " " "key": [3] 0: 982 1: " STR0002" 2: "ALL" " idiom": "POR" " version": "000001" } . . . |
Informações | ||
---|---|---|
| ||
O número de registros por página pode impactar muito na velocidade de retorno da API, portanto, caso o tempo de resposta esteja muito alto, tente diminuir esse valor. |
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|