Nesse artigo ensinarei a utilizar as apis do SORGES para troca de informações. Elas permitem fazer consultas na base de dados do software, e também alterar ou inserir dados. Não é possível remover informações através de api.
Observe que esse artigo é destinado a desenvolvedores e usuários avançados, que desejam integrar seu sistema ou serviço ao SORGES. Se você apenas que exportar ou importar informações, tem outros artigos aqui na central de ajuda que ensinam a fazer isso de forma mais simples.
Como dito acima, o SORGES dispõe de apis que permitem consultar, alterar e incluir informações no banco de dados. Naturalmente, isso abre a segurança do sistema, pois o uso delas dispensa login de usuário. Devido a isso, existem duas configurações que precisam ser liberadas para poder usar a api. Essas configurações servem de mecanismo de segurança, e por padrão vem bloqueadas.
A primeira é a C0145, em AJUSTES GLOBAIS:
Altere e marque essa configuração.
A segunda fica na aba DIVERSOS, em AJUSTES LOCAIS:
Ali na seção segurança, marque a opção para permitir o uso de APIs.
O segundo passo é você conhecer a estrutura do sistema. Nosso sistema é capaz de gerar uma documentação dinâmica em cada módulo, que facilita entender a sua estrutura, algo que outros sistemas não possui.
Vamos pegar o controle de produtos como exemplo, se você clicar lá no canto superior esquerdo da tela, em MAIS, terá a opção para GERAR RELATÓRIO COM DOCUMENTAÇÃO DOS CAMPOS:
Esse relatório é o que você precisa para entender o módulo. Veja o exemplo:
Naquele primeiro quadro, LISTA DE CAMPOS – PRODUTO, temos TABELA/VISÃO – PRODUTO. Esse é o nome da tabela no banco de dados, e também é o id do módulo, que você vai precisar. Ou seja, se fizer um comando sql “SELECT * FROM PRODUTO” verá toda a tabela de produtos do sistema. Mas nem precisa disso, pois a lista mostra também todos os campos.
Veja que na imagem acima eu circulei o PRO_CODBARRAS, que é o código de barras do produto (tem a descrição logo na frente e embaixo também), e circulei o PRO_DESCRICAO, que é o nome ou descrição do produto. E na imagem abaixo:
Lá no final eu circulei o PRO_VAL_VENDA1, que é o preço dele. Veja que eu anotei o nome da tabela e os 3 campos no bloco de notas. Posso usar eles para fazer uma consulta:
O comando SELECT PRO_CODBARRAS, PRO_DESCRICAO, PRO_VAL_VENDA1 FROM PRODUTO vai me trazer a lista de todos os produtos, com código, descrição e preço.
Cada módulo tem seu relatório, e os sub cadastros do módulo aparecem no relatório. Por exemplo, no módulo de vendas verá os campos da venda, dos produtos vendidos, e das formas de pagamento usadas.
Uma vez que você conhece o básico da estrutura, pode começar a integrar a api. Para isso vá no atalho SORGES – Ferramentas:
Aí vai na aba SERVIÇOS, botão ADICIONAR, e na lista TIPO DE SERVIÇO terá duas opções:
- API DE EXPORTAÇÃO DE DADOS: usando essa API você passa um comando SQL para o sistema, e ele vai gerar um arquivo csv, xml, ou htm, com o resultado dessa consulta.
- API DE TRANSFERÊNCIA DE DADOS: essa trabalha usando as funções exportar e importar, que você encontra lá no botão MAIS no topo da tela dos módulos. Por isso ela suporta só os formatos csv e xml, sendo que caso precise importar cadastros com sub cadastros é necessário usar o formato xml. Essa api permite consultar e exportar informações do sistema, e permite também que você insira ou altere cadastros via arquivo.
Na primeira api, de exportação, você verá essa mensagem abaixo:
Ela instrui como deve ser criado o arquivo. É bem simples, é um arquivo de texto, sendo que na primeira linha tem o formato (CSV, XML ou HTM), na segunda tem o nome do arquivo que o sistema vai exportar, e da terceira em diante o comando SQL. Por exemplo:
XML
C:\meusarquivos\produtos.xml
SELECT PRO_CODBARRAS, PRO_DESCRICAO, PRO_VAL_VENDA1 FROM PRODUTONesse exemplo acima, vai ser gerado um arquivo xml, que será salvo na pasta C:\meusarquivos, com o nome produtos.xml, e o conteúdo será o resultado do comando sql indicado. É interessante evitar acentos ou caracteres especiais no caminho e no nome do arquivo. Além disso, procure gerar o arquivo com codificação UTF-8 para evitar erros na leitura de caracteres.
Quando você clicar em OK na mensagem, será solicitado que abra o arquivo de texto que contém o comando acima. Ou seja, você vai gerar um primeiro arquivo, e vai abrir ele manualmente para o programa processar. A partir daí o SORGES fica configurado para sempre ler esse arquivo, então basta você gravar ele de novo com o mesmo nome, no mesmo lugar.
O arquivo gerado será mais genérico, porém ele ainda leva o nome dos campos, o que facilita a leitura:
Agora vamos ver a segunda api, que permite fazer a troca de arquivos. Veja essa imagem:
A imagem acima mostra a mensagem que aparece ao configurar essa api. É quase a mesma lógica, porém o arquivo de texto que você vai gerar tem mais informações. Na primeira linha você deve indicar o que deseja, EXPORTAR ou IMPORTAR. Na segunda linha vai formato, que pode ser CSV ou XML. Na terceira deve indicar o id do módulo. Lembra lá encima quando você anotou o ID? Esse aqui:
Esse PRODUTO é o id, então é ele que usamos no arquivo. Aí a quarta linha é o nome do arquivo que o SORGES vai gravar ou vai ler, dependendo do comando que informou na primeira linha. E por fim, a partir da quinta linha vai o comando SQL, caso você esteja exportando informações. Porém, o comando aqui é diferente, você não pode usar a cláusula “SELECT FROM“, use só o “WHERE“. Por exemplo, você quer uma lista dos produtos que tem “COCA” na descrição, o arquivo com o SQL ficaria assim:
EXPORTAR
XML
PRODUTO
C:\meusarquivos\produtos.xml
WHERE PRO_DESCRICAO LIKE '%COCA%'O arquivo gerado nesse caso segue o mesmo padrão da exportação feita dentro do sistema, é um arquivo completo, com todos os campos:
Se você quiser importar esse arquivo, o comando seria esse:
IMPORTAR
XML
PRODUTO
C:\meusarquivos\produtos.xmlQuando você importa o arquivo, não é necessário que ele tenha todos os campos. Você pode colocar só os campos que você precisa mexer. Além disso, se ele não encontrar o registro, um novo registro será adicionado. Já se ele encontrar o registro cruzando pela chave primária, ele só atualiza os dados. A chave é sempre o primeiro campo, no caso do produto, o PRO_UUID. Recomendo muito assistir ao vídeo no começo do artigo, pois nele eu demonstro melhor vários exemplos de arquivos.