Pesquisar Artigos da Base de Dados

XML Servcice

XML Interface ÍNDICE
- Serviço ArtXMLServer
  - 1. Configuração do ArtXmlServer
  - 1. ArtXmlServer multiempresa
  - 1. Consola ‘XMLServices’
- Execução de serviços a partir do ARTSOFT
  - 1. Lista dos serviços disponíveis.
  - 1. Lista de funções ARTSOFT
  - 1. Lista de funções internas
- Parâmetros gerais dos Serviços WEB
  - 1. Retorno dos Serviços WEB
- Serviços Básicos
  - 1. ArtDB/_WSList
  - 1. ArtDB/_DBTables
  - 1. ArtDB/_tblDesc
  - 1. ArtDB/fnList
  - 1. ArtDB/Cambios..............................................................................
  - 1. ArtDB/CfgEnums
  - 1. ArtDB/SysTime
  - 1. ArtUsr/TestPsw
  - 1. Notify/SendMsg
- Serviços de Query
  - 1. Queries/Query
  - 1. Queries/SQLQuery
- Serviços relativos a Documentos
  - 1. DocFch/DocInsert
- 1. DocFch/DocUpdate
- 1. DocFch/DocSignature
- 1. DocFch/DocDelete
- 1. DocFch/DocRemove
- 1. DoFch/DocForceR
- 1. DocFch/GetImage
- 1. DocFch/SetImage
- 1. DocFch/DocPrices
- 1. DocFch/DocsByEnt
- 1. DocFch/DocStatus
- 1. DocFch/DocPrint............................................................................
- 1. DocFch/DocPrintEx
- 1. DocFch/DocPrintEtiqEx
- 1. DocFch/CfgDocum
Serviços relativos a Artigos
- 1. StkFch/Update
- 1. StkFch/Delete
- 1. Stkch/CfgGroups
- 1. StkFch/CfgEspec
- 1. StkFch/CfgMutac
Serviços relativos a Terceiros
- 1. TerFch/Login
- 1. TerFch/SetPass
- 1. TerFch/Update
- 1. TerFch/Delete
- 1. TerFch/UpdSug
Serviços relativos a Eventos de Terceiros
-
- 1. CRMHdr/GetTable
- 1. CRMHdr/GetQualif
- 1. CRMHdr/Insert
- 1. CRMHdr/Update
- 1. CRMHdr/Delete
- 1. CRMHdr/Status
- 1. CRMHdr/GetImage
- 1. CRMHdr/SetImage
Serviços relativos a Contabilidade e Contas Correntes
- 1. CtaLan/CurrAcc
- 1. CtaLan/OpenDoc
- 1. CtaLan/DocType
- 1. CtaLan/DocRecv
- 1. CtaLan/RecvDoc
- 1. CtaLan/GetImage
- 1. CtaLan/SetImage
- 1. CtaLan/LanDelete
- 1. CtaLan/LanUpdate
- 1. CtaFch/UpdateAccounts
- 1. CtaFch/DeleteAccounts
Serviços relativos a Recursos Humanos
- 1. GrhEmp/Login
- 1. GrhEmp/SetPass
- 1. GrhEmp/Update
- 1. GrhEmp/UpdSug
- 1. GrhEmp/UpdEvent
- 1. GrhEmp/DelEvent
- 1. GrhEmp/UpdEventCad
- 1. GrhEmp/DelEventCad
- 1. GrhInd/Login
- 1. GrhInd/SetPass
- 1. GrhInd/Update
- 1. GrhInd/UpdSug
- 1. GrhInd/UpdEvent
Apêndice A – XMLReports
Apêndice B – XMLQuery
Funções internas de XMLQuery e XMLReports
Lista de variáveis globais ARTSOFT
Apêndice C - Lista de funções base ARTSOFT
Apêndice D – Lista de Funções
Apêndice E - Formulários HTML
Variáveis e fórmulas
Formatação de campos
- Numéricos
- Alfanuméricos:
- Datas
- Exemplo de formulário HTML.................................................................
Apêndice F - Informação adicional sobre chaves de tabelas ARTSOFT
Apêndice G - Autenticação no servidor
- Modo produção
- Modo debug
- Teste de comunicação.........................................................................
- Algoritmos de validação de clientes.........................................................
Apêndice H – Comunicação Segura
-
- Comunicação de dados em formato compactado
Apêndice I - Configuração do servidor
- Lista de DLL’s, serviços e dependências
Apêndice J – Serviço XML de integração com plataformas B2C
Apêndice K – Validação de Logins
Apêndice L – Status WinSock

(^)

XML Interface

Objetivo
Disponibilização de serviços XML específicos, podendo ser chamados diretamente no
ARTSOFT, via plugins, ou executados a partir de um servidor sobre protocolo HTTP.

Modo de funcionamento
Cada função recebe uma string XML, e retorna o resultado do seu trabalho também
numa string XML, e, em alguns casos, numa string HTML.

Carateres ‘escape’ do XML
A sintaxe do XML utiliza os caracteres ‘<’, ‘>’, ‘&’ ‘’’ e ‘”’ (menor, maior, &,
apóstrofo e aspa), pelo que não é possível utilizá-los nos comandos. Quando forem
necessários, devem ser ‘codificados’ com as sequências ‘<’, ‘>’, ‘&’, ‘'’
e ‘"’, encarregando-se o ‘parser’ de XML de os descodificar. Aos caracteres
substitutos costuma chamar-se ‘sequências de escape^1 ’.
Em termos práticos, e partindo do pressuposto que seria necessário escrever este
‘statment’ SQL :

SELECT * from tableX where coluna1 > 10 AND coluna1 < 20 AND nome1 like ‘%nome’

deveria ser escrito desta forma^2 :

SELECT * from tableX where coluna1 > 10 AND coluna1 < 20 AND nome1 like '%nome'

(^1) O legado da informática sempre usou sequências de escape para controlo de posicionamento de cursores no ecrã, controlo do tip^ o
de letra em impressoras, etc, em que todas essas sequências começavam com o caracter ‘Escape’ (decimal 27 ou 0x01B), e uma tepara isso, a tecla ‘Esc’. cla específica
(^2) No caso dos statment SQL, veremos na respectiva secção que existe uma alternativa mais elegante para esta sintaxe.

(^)
Serviço ArtXMLServer
Este serviço está implementado para funcionar na plataforma ArtExec (serviço
Windows) e permite executar serviços ARTSOFT recebidos numa porta TCP.
Sendo um serviço do ArtExec, recomenda-se que seja consultada também a
documentação deste, pois a sua configuração e funcionamento afetam profundamente a
segurança e performance deste serviço. Esta documentação está no manual de instalação
de Serviços ARTSOFT.
Quando este serviço (e outros que estejam também instalados no mesmo servidor
ARTEXEC) representarem um consumo de CPU considerável que possa prejudicar a
performance do servidor de bases de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais) ou em alternativa, o serviço ArtExec
deve ser colocado noutro servidor específico para o efeito^3.

1. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no ficheiro de configuração do servidor
ArtExec, descrita no manual de Serviços ARTSOFT. Os campos a preencher estão
documentados na consola Artexecmanager.

Na seção [Config], tem que constar na lista de ‘Plugins’ instalados o módulo deste
serviço, o ‘ArtXMLServer’.
Para executar a sua função, este serviço entrega pedidos e recebe respostas dos
serviços que cada biblioteca ARTSOFT disponibiliza. Dependendo das bibliotecas instaladas,
poderão estar mais ou menos serviços disponíveis. Para indicar a lista de bibliotecas a usar,
deve colocar-se esta no parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos de contas, extratos de contas e de
diários, etc.).
ARTDB_S - Serviços de recursos humanos.
...

3
A mesma recomendação é aplicável quando forem usados servidores de aplicações desktop, tais como o remote desktop.

(^)

2. ArtXmlServer multiempresa

Este serviço é muito específico, e normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o serviço passa a ter um comportamento
diferente, adaptando-se às exigências da função.
Um software cliente que se conecte a um servidor multiempresa passa a ter que
indicar em cada ligação qual a base de dados pretendida e a respetiva data de trabalho,
adicionando um cabeçalho ‘DBName=Base De dados’, e ‘workDate=AAAA-MM-DD’, sem os
quais os pedidos passam a ser rejeitados com o status ‘ 406 - Not Acceptable’ e uma
mensagem ‘missing DBName’ ou ‘missing workDate’.
Quando o servidor recebe um pedido, verifica a ‘base de dados’ atual é a pedida. Se
sim, está tudo OK e processa o pedido. Senão, vai tentar comutar para a base de dados
pedida. Mas isso só pode acontecer se não existir mais nenhuma ligação em curso, pois essa
ainda está a usar a atual base de dados. Caso contrário, informa o cliente que o pedido, de
momento não pode ser satisfeito, devolvendo o status ‘423-media locked’ e uma pequena
mensagem. Quando isso acontecer, o cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços (até ao máximo dos que estiverem
instalados).
Como este serviço pode comutar de base de dados durante o seu funcionamento, não
pode ter nenhum outro serviço instalado no mesmo servidor ArtExec, pois a comutação
poderá ocorrer a qualquer momento, para além de tornar imprevisível qual a base de dados
sob a qual esse outro serviço iria efetuar o seu trabalho. Desta forma, quando o servidor
ArtXMLServer estiver configurado como ‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor^4 e recusa-se a arrancar se algum serviço já
estiver instalado no mesmo ArtExec.

3. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos manuais e apresentar a resposta numa
consola, permitindo assim criar um comando ou ficheiro XML, enviá-lo ao serviço e verificar
a resposta obtida, antes de a codificar na aplicação cliente, bem como efetuar pedidos de

4
A terminologia chama a este modo ‘greedy’ ou ‘ganancioso’.

(^)
informação sobre o sistema ou testar a performance dos canais de comunicação e / ou do
sistema.
Parâmetros da consola:
▪ Server – ‘IP:porta’ ou ‘nome_do_servidor:porta’ do servidor ArtXMLServer.
▪ Login – Normal, Debug, Teste, MultiDB e Plugin:
 Normal – Ligação ‘normal’ a um servidor ArtXMLServer exclusivo de uma
empresa;
 Debug –
 Teste – Usados para testar o cálculo do ‘digest’ para quem não possa usar um
dos conectores disponibilizados (.NET, PHP, C/C++, Android)^5.
 MultiDB - Ligação ‘normal’ a um servidor ArtXMLServer multiempresa. Este
modo tem especificidades que serão tratadas mais adiante;

5

A informação necessária a esse cálculo é fornecida pela ARTSOFT mediante pedido.

(^)
 Plugin – usar apenas quando a documentação do ‘plugin’ específico de
determinada empresa ou setor o indicarem. Como este modo utiliza
algoritmos diferentes do standard, o uso indevido deste modo vai ser banido
e registado no ficheiro de log como ‘tentativa de invasão’.
▪ Hash – O algoritmo a usar para calcular o ‘digest’ que o servidor espera. Este
parâmetro deve estar conforme o parâmetro ‘digest’ do servidor. Se isso não se
verificar, não é possível efetuar login, ficando registado no ficheiro de log como
‘tentativa de invasão’.
▪ User – O nome do utilizador, um dos nomes configurados no servidor em ‘UsersList’.
▪ Palavra-passe – a ‘password’ (não encriptada)^6 colocada a seguir ao ‘nome’
configurado no servidor em ‘UsersList’.
▪ Base de dados – (apenas se ‘Login=MultiDB’) – Permite indicar o nome da base de
dados / empresa de trabalho onde devem ser efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) – Permite indicar a data de trabalho a
que se referem os pedidos.
▪ XMLIndent – a indentação que o servidor deve usar na formatação do XML no envio
das respostas. Como este parâmetro passa a ser sempre enviado em todas as
ligações, faz com que seja ignorado o parâmetro de igual nome configurado no
servidor.
▪ Compressão – nenhuma^7 , ‘gZip’ ou ‘deflat’ – permite indicar o algoritmo de
compressão a usar nos pedidos ao servidor e que este usa também para as respostas.
Se forem usados canais de comunicação exteriores ou em que a largura de banda
seja reduzida, deve usar-se sempre compressão, reduzindo drasticamente o tamanho
das mensagens e aumentando muito a velocidade com que o cliente obtém os dados,
à custa de uma penalização de carga no servidor. O formato ‘gZip’ contém um
cabeçalho que informa dados adicionais sobre o texto compactado, pelo que, se não
existir outro motivo, deve ser este o formato a escolher.
▪ Config – Permite selecionar um ficheiro de configuração alternativo, permitindo
assim ter vários ficheiros de configuração e selecionar um deles para uso no
momento.
(^6) Esta palavra-passe é normalmente mostrada como ‘ password^ ’ (****), mas é guardada em pleno-texto no ficheiro de configuração da consola, e
pode ser visualizada como texto, ligando a ‘caixa de seleção/check (^7) ‘Identity’ na terminologia da RFC2616. - box) situada ao lado do botão ‘Config’.

(^)
(^)
▪ Segurança – Se esta opção estiver ligada, a transferência de dados é efetuada de
forma encriptada, mantendo a confidencialidade dos dados (os dados abrangidos
pelo R.G.P.D. só podem circular nesta forma).
▪ Params – Esta opção permite especificar os parâmetros necessários aos serviços de
teste (performance e eco), permitindo definir o nº de envios a efetuar. A descrição
desses serviços descreve o uso deste parâmetro.
▪ TimeOut – permite definir o tempo máximo que a consola espera pela resposta do
servidor, com um mínimo de 5 segundos e por omissão 15 segundos. Para pedidos
com respostas mais ‘volumosas’ poderá ser necessário aumentar este tempo.
O botão ‘ Lista de serviços ’ é um atalho para o serviço ‘ArtDB/_WSList’ e permite
visualizar todos os serviços disponibilizados pelo servidor ArtXMLServer. Se determinado
serviço não estiver disponível nesta lista, significa que a respetiva biblioteca ARTSOFT que
o executa não foi configurada ou carregada.
A caixa de seleção abaixo desse botão apresenta a mesma lista de serviços e permite
selecionar um deles. Estando um dos serviços selecionados, ao carregar no botão, este
funciona como um atalho para o serviço ‘ArtDB/_WSList’, com os parâmetros , que irá apresentar um texto com os parâmetros de
input , output e eventuais comentários específicos desse serviço.
O botão ‘ Lista de funções ’ é um atalho para o serviço ‘ArtDB/_fnList’, e apresenta
uma lista de funções disponibilizadas pelas bibliotecas instaladas. Essas funções podem ser
usadas em fórmulas que os serviços possam disponibilizar, para fórmulas de mapas,
relatórios e outros no próprio ARTSOFT bem como para uso no conector ‘Excel’.
A caixa de seleção abaixo desse botão apresenta a mesma lista de funções e permite
selecionar uma delas. Estando uma delas selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_fnList’ com os parâmetros e irá
apresentar um texto com os parâmetros de input dessa função e o respetivo tipo de retorno
(N-numérico, A=alfanum ou ‘|’=Array com elementos separados por ‘|’).
O botão ‘ Lista de tabelas ’ é um atalho para o serviço ‘ArtDB/_DbTables’, e apresenta
uma lista de tabelas disponibilizadas pelas bibliotecas instaladas.
A caixa de seleção abaixo desse botão apresenta a mesma lista de tabelas e permite
selecionar uma delas. Estando uma delas selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_TblDesc’ com os parâmetros e irá

(^)
(^)
apresentar uma seção ‘’ com a lista dos indexes utilizáveis do ficheiro/tabela, e uma
seção ‘’ com a lista das colunas dessa tabela, contendo o nome da coluna, o tipo,
tamanho e a descrição da mesma. Esta lista permite fornecer os dados necessários aos
serviços que permitem configurar a lista de colunas/campos que fornecem, bem como os
dados necessários para efetuar queries ‘ad-hoc’.
A opção lateral ‘Tipo’ permite selecionar que tipos de campos se pretendem - todos,
apenas os ‘reportáveis’ ou apenas aqueles que permitem ‘inputs’, e se ordenados ou não.
As linhas ‘Comandos/Ficheiros XML’ permitem definir os parâmetros em formato XML
simples (que caiba todo numa linha) ou complexos, através de um ficheiro XML que será lido
para envio. Se a linha começar com ‘<’ é interpretada como um XML simples, caso contrário,
como um ficheiro a ler. O botão ‘...’ a seguir ao campo permite navegar no sistema para
localizar o ficheiro a colocar na linha. Se este já estiver configurado, carregando em ‘CTRL’
e clicando no mesmo botão, chama o editor de texto para editar o respetivo ficheiro. O
editor por omissão é o ‘notepad’, mas pode ser configurado outro, editando o ficheiro de
configuração (por omissão o ‘XMLClient.ini’) e colocando o caminho e nome do editor, como
no exemplo:
EDITOR="C:\Program Files (x86)\Notepad++\notepad++.exe"
As linhas ‘Serviço’ permitem definir os nomes dos serviços a efetuar, podendo os
mesmos serem selecionados na respetiva lista de seleção. Porém, estes só serão enviados
ao servidor se a respetiva ‘check’ estiver ligada. Quando várias linhas estiverem
selecionadas, os pedidos serão enviados em lote e pela mesma ordem.
O botão ‘Performance’ necessita que a caixa ‘Params’ contenha um valor, que será
utilizado para indicar o nº de pedidos que irá efetuar ao servidor. Estes pedidos têm
tamanhos aleatórios até 1 megabyte, são recebidos pelo servidor e simplesmente
descartados, não havendo assim qualquer tipo de processamento dos mesmos. Desta forma
este teste permite medir a performance do canal de comunicações no sentido da receção
de pedidos (sendo a resposta muito curta, a velocidade de resposta passa a ser
estatisticamente irrelevante). Por fim, é apresentada a lista de mensagens enviadas e os
respetivos tempos, e no fim, um resumo estatístico: ‘tempo médio: xxx.x ms; tempo total:
xxx.xxx seg; MB: yyy; MB/s: zzzz.zzz’, em que o tempo médio é obtido pela média simples
dos tempos de cada pedido, o tempo total obtido pela soma do tempo gasto por cada pedido,

(^)
(^)
‘MB’ é o somatório dos Mega Bytes de dados enviados e ‘MB/s’ a média de Mega Bytes por
segundo de todos os pedidos, ou seja, a largura de banda do momento.
O botão ‘Eco’ necessita que a caixa ‘Params’ contenha um valor, que será utilizado
para indicar o nº de pedidos que irá efetuar ao servidor. Este serviço tem um funcionamento
totalmente idêntico ao anterior, com a especialização de enviar de volta ao cliente o
conteúdo recebido. Desta forma, o tempo de resposta já é totalmente relevante, permitindo
medir a largura de banda de envio e receção.
Poderá se muito útil efetuar estes testes e guardar os respetivos resultados na altura
da instalação de um servidor ArtXMLServer, para os comparar posteriormente em caso de
degradação da performance do serviço, permitindo aferir se essa degradação se deve ou não
à perda de largura de banda do canal de comunicações.
Execução de serviços a partir do ARTSOFT
É possível executar a maior parte dos serviços para testes e inclusivamente obter os
protótipos associados.
‘Empresa -> Funções de supervisão -> Configurações’:
Tem também acesso às listas de funções da API ARTSOFT que são usadas em XML e
no Excel, e também a lista de funções internas que podem ser usadas.

(^)
(^)

4. Lista dos serviços disponíveis.

Exemplo de protótipo.

(^)
(^)

**5. Lista de funções ARTSOFT

Lista de funções internas**

(^)
(^)
Parâmetros gerais dos Serviços WEB
O primeiro node XML (a root) pode conter um conjunto de atributos que indiquem
como se pretende que o serviço seja feito, ou obter a resposta do serviço:
Todos os serviços
status='[N]|S'
Solicita que seja enviada a descrição textual do erro, em complemento ao
enumerador já devolvido (rc=’xxxxxxxx’), sempre que haja qualquer erro.
Serve para ajudar um developper a perceber melhor o que aconteceu, mas
poderá não ser suficientemente explícita para mostrar ao utilizador, em
determinados contextos.
retid ='[N]|S'
Solicita que seja devolvido o ID dos registos processados (Auto incremento de
artigo, terceiro, documento, nº do evento, etc)
Serviços de inserção de dados
id='xxx'
Em funções que envolvam terceiros, esta propriedade indica qual o nº de
registo destino. Se esta propriedade for enviada e entityID também, irão ser
confrontadas para verificar se pertencem à mesma entidade. Se não for o
caso, será devolvido o erro ‘ErrInvEntityID’. Esta propriedade pode ser
‘injetada’ por um servidor que tenha validado o terceiro, assegurando-se
assim de que não houve adulteração ou injeção de um ‘entityID’ falso. No
caso de fichas adicionais (MoreInfo id=’xx’), esta propriedade pode também
referir o nº de registo de artigo, vendedor, conta, empregado ou
independente, que será validada com o campo ‘RegID’ do registo ‘FDUxxx’.
entityID='C|F|N|[R]:xxxx'
Em funções que envolvam terceiros, esta propriedade especifica uma
entidade destinatária deste comando. Se forem especificados outros
parâmetros relativos a uma entidade (ex: nº de cliente num cabeçalho de
fatura ou evento) e diferirem deste, o comando será rejeitado por razões de
segurança.
C:xxx – Cliente x, F:xxx – Fornecedor x, N:xxx – NIF de terceiro, R:xxx - nº de
registo (Auto incremento) da ficha de terceiro, sem prefixo – nº de registo.
contact=’xx.yy’
Em funções que envolvam terceiros e realizadas a partir de login de um
contacto, esta propriedade indica qual o nº de contacto que efetuou o login.
Esta propriedade pode ser ‘injetada/modificada’ por um servidor de
validação do contacto do terceiro.
Permite especificar que a inserção de dados deve ser feita sob uma
transação. É aplicável quando se pretende que, quando se verifica um erro,
o serviço elimine todas as operações feitas anteriormente, mantendo a
integridade da base de dados. A indicação da transação pode ser feita
parcialmente, ao nível de uma sub-tag, indicando que só as operações
ocorridas nesta devem ser transacionais. Ex. em clientes: <Contacts

(^)
(^)
trans=’Y|T|S|V|1|N|F|0’ trans=’S’> indicaria que apenas a lista de contactos deve ser transacional, ou
seja, insere os contactos todos, ou em caso de erro num deles, não insere
nenhum.
Na especificação de uma lista de campos (colunas), esta pode ser feita na forma de
nós XML (valor), o que permite que em qualquer registo se envie apenas os
campos disponíveis, mas permite também a especificação de uma lista de campos, a serem
enviados, e depois, estes possam ser enviados serializados, separados por um caracter
separador/delimitador. Exemplo:
<BaseAddrsep='|' fList='Ter.NrIdFisc,Ter.Nome,Ter.Morada,Ter.Localid,Ter.CPPais’>
500862273|Clube de Campismo de Lisboa|Rua Nova nº15|Alcântara|1375-111 LISBOA
500862284|Clube Caravanistas do Porto|Rua Seis nº33|Ribeira|4101-231 PORTO
500862145|Clube de Motars do Alentejo|Rua de Évora nº31|Beja|7001-911 BEJA

O separador ‘sep’ permite indicar qual o caracter usado para a separação de campos,
que, por omissão, é assumido ‘,’.
Caso se usem caracteres especiais, estes podem ser especificados como sequencias
de escape do tipo ‘C/C++, C#, Java, ex: \a \b \r \n, ou em hexadecimal: \xHH.

7. Retorno dos Serviços WEB

Um serviço devolve o resultado do seu trabalho numa string XML, que pode ter várias
formas, consoante o tipo de serviço, e o tipo de retorno:
Erro Parâmetros Exemplo de retorno
Sem erros retID=’N’
status='?'

<Entity/>

Registo
inexistente

retID=’?’
status='N'

<Entity rc='RecordNotExist'/>
Registo
inexistente

retID='?'
status='S'

<Entity rc='RecordNotExist'>Nº de registo não existe</Entity>

(^)
(^)
Erro de
inserção /
update /
delete,
na
base de
dados
retID=’N’
status='N'
 nº de erros totais
 nº de erros deste nó

 nº de erros deste nó

Erro de
inserção /
update /
delete,
na
base de
dados
retID=’N’
status='S'
trans=’S’

chave duplicada

Operação cancelada devido a transacção
abortada
Operação cancelada devido a transacção
abortada
Operação cancelada devido a transacção
abortada

Operação
com
sucesso
retID=’S’
status='?'

<BaseAddr fList='Ter.NrIdFisc,Ter.Nome’>
501848487,Clube de Campismo
Lisboa

1,Rua de São Bento
5,Rua de Santa Apolónia
9,Praça de Santo António

1,1,António Almeida
1,2,Joaquim Jeremias

25,Texto 1 para ficha adicional
25,Texto 2 para ficha adicional
25,Texto 3 para ficha adicional

Operação
com

<BaseAddr fList='Ter.NrIdFisc,Ter.Nome’>
501848487,Clube de Campismo
Lisboa

(^)
(^)
alguns erros
retID=’N’
status='S'

1,Rua de São Bento
5,Rua de Santa Apolónia
9,Praça de Santo António

1,1,António Almeida
1,2,Joaquim Jeremias

25,Texto 1 para ficha adicional
25,Texto 2 para ficha adicional
25,Texto 3 para ficha adicional

chave duplicada

chave duplicada

chave duplicada

Operação
com
alguns erros
retID=’S’
status='N'

<BaseAddr fList='Ter.NrIdFisc,Ter.Nome’>
501848487,Clube de Campismo
Lisboa

1,Rua de São Bento
5,Rua de Santa Apolónia
9,Praça de Santo António

1,1,António Almeida
1,2,Joaquim Jeremias

25,Texto 1 para ficha adicional
25,Texto 2 para ficha adicional
25,Texto 3 para ficha adicional

Na informação de retorno alguns serviços poderão ainda incluir o atributo ‘IDEx’ que
conterá informação adicional sobre um determinado erro, como, por exemplo, o conteúdo
de um determinado parâmetro errado. A documentação do serviço referirá quando isso
ocorrer.

(^)
(^)
Serviços Básicos
É possível inquirir quais os recursos disponíveis no servidor, através de um conjunto
de serviços:

8. ArtDB/_WSList

Informa quais os serviços disponíveis no serviço onde se conectou, ou se for indicado
um determinado serviço, qual o protótipo de string XML necessário como input.

Parâmetro Resultado

<wslist />

<wsList ttl="44">  ttl=nº de serviços disponíveis
<ArtDB>  Namespace ArtDB
<_DBTables/>  serviços do namespace ArtDB
<_FnList/>  (neste caso, ‘ArtDB/_FnList’)
<_TblDesc/> ...
<_WSList/> ...
</ArtDB>  fim do namespace ArtDB
<ArtFDU>  Namespace ArtFDU

...  serviços do namespace ArtFDU
 fim do namespace ArtFDU
... 
...  Outros namespaces
... 

<wsList service='TerUpdate' />

<!-- TerUpdate -->  nome do serviço
<Entity>  Terceiro
<BaseAddr>  Morada principal
<!-- fields -->  Campos da morada principal
</BaseAddr>
<OtherAddr>  Moradas adicionais
<Rec ID='1'>  Morada 1
<!-- fields -->  Campos da morada 1
</Rec>
<Rec ID='2'>  Morada 2
<!-- fields -->  campos da morada 2
</Rec>
</OtherAddr>
<Contacts>  Contactos do terceiro
<Rec ID='1.2'>  Contacto 1.2
<!-- fields -->  Campos do contacto 1.2

(^)
(^)

 Contacto 1.3

 Campos do contacto 1.3  Informação adicional (FDU)  Informação adicional x  Campos da informação adicional  Informação adicional y  Campos da informação adicional

9. ArtDB/_DBTables

Informa a lista de tabelas disponíveis no serviço onde se conectou.
Parâmetro Resultado

<DBTables />

<DBTables ttl="5">
<TerFch nr="14" key="7" ver="31" log="0">Terceiros</TerFch>
<TerCon nr="15" key="2" ver="20" log="0">Terceiros/Contactos</TerCon>
<VndFch nr="23" key="3" ver="1" log="0">Vendedores</VndFch>
<CrmHdr nr="83" key="9" ver="21" log="0">Eventos de Terceiros</CrmHdr>
<CrmDet nr="84" key="1" ver="0" log="0">Eventos de Terceiros-Detalhe</CrmDet>
</DBTables>

O atributo ‘nr’ informa qual o nº interno da tabela no ARTSOFT, que poderá ser
necessário como chave em tabelas que usem esta como ‘foreign key’.
O atributo ‘key’ informa o nº de chaves logicas existentes nessa tabela. Nota:
Poderão existir mais ou menos chaves lógicas que físicas, consoante a tabela.
O atributo ‘ver’ indica a versão da tabela, e é meramente informativo (apenas para
debug).
O atributo ‘log’ informa se a tabela está marcada como rastreável nas operações
feitas sobre ela, na tabela ‘Artlog’.
O texto do nó é o nome comum da tabela.

(^)
(^)

10. ArtDB/_tblDesc

Informa a lista de chaves e campos da tabela especificada. Para o caso de tabelas de
configuração presentes no ficheiro ArtTBE (um ‘tablespace’ que agrega centenas de
tabelas), é necessário especificar num atributo “enum=’xxx’” qual a tabela pretendida (de
momento apenas está disponível a tabela de configuração de documentos, com o enum
‘tblDoc’, devendo o pedido ser feito assim: .

Parâmetro Resultado

<tblDesc
table='TerCon'
[enum=’... ... ...’]
/>

<TerCon>
<keys>  Lista de chaves
<AutoInc name="Contactos/AutoIncremento">TerCon|AutoInc=1234</AutoInc>
<Contact name="Terceiros/Contactos" >TerCon|Contact|NrTerc=1234|TpCont=1</Contact>
<DataAniv name="Data de Aniversário">TerCon|DataAniv=20010101:20091231</DataAniv>
</keys>
<fields ttl="20">  Lista de campos (colunas)
<NrCli type="UInt" size="4">Nº de Cliente</NrCli>
<NrFor type="UInt" size="4">Nº de Fornecedor</NrFor>
<Filial type="UInt" size="2">Nº de Filial</Filial>
<TpContacto type="UInt" size="1">Tipo de Contacto</TpContacto>

...

<tblDesc
table='CtaLan'/>

<CtaLan>
<keys>  Lista de chaves
<AutoInc name="Nº de lançamento de contas">CtaLan|AutoInc=1:9999</AutoInc>
<ExtrDiar name="Lançamentos de um diário">CtaLan|ExtrDiar|Mes=5|Diario=21</ExtrDiar>

...
CtaLan|Links|Link=xxxxxx|NrLanc=1234

 Lista de campos (colunas)
<Cta.CtaEd type="Str" size="31">Nº de Conta Editado</Cta.CtaEd>
<Data.Lanc type="Date" size="4">Data de Lançamento</Data.Lanc>
<Flag.LcPend type="UInt" size="1">Lançamento pendente</Flag.LcPend>
<Flag.NaoSald type="Bool" size="1">Flag de Documento não Saldado</Flag.NaoSald>
<Lan.Flags type="Hexa" size="4">Flags Lançamento/Hexadec</Lan.Flags>
<Val.ValorDb type="Num" size="8" Dec="2">Valor a Débito</Val.ValorDb>
<Val.ValorCr type="Num" size="8" Dec="2">Valor a Crédito</Val.ValorCr>
<C_C.Imposto type="Num" size="8" Dec="2">Valor do Imposto</C_C.Imposto>
<C_C.NrVend type="UInt" size="4" >Nº de Vendedor</C_C.NrVend>
<Lan.Obs type="Str" size="1000">Observações</Lan.Obs>
<CDU.01 type="*Str" size="1000" array="31">Campo de utilizador 01</CDU.01>

(^)
(^)

Na lista de chaves (keys), o nome do nó informa qual o nome interno da chave (a
usar nos queries) e o atributo ‘name=’ informa qual o nome comum. O valor do nó contém
um exemplo de utilização da chave em queries.
Na lista de campos (fields), o nome do nó informa qual o nome do campo, o atributo
‘type’ informa qual o seu tipo, ‘size’ informa qual o seu tamanho e ‘dec’ se presente,
informa o nº de decimais que suporta, e ‘array’, se presente, indica que o campo é um
conjunto de campos da mesma natureza, que se repetem ‘x’ vezes, e cujo nome varia entre
o valor base indicado e o valor superior (no caso de CDU.01, são 31 campos que variam entre
CDU.01 e CDU.31).
Se o tipo de campo for precedido de ‘*’ este campo não existe fisicamente nessa
tabela, logo, não disponível em queries SQL. O valor do nó informa o nome comum do
campo.
Tipos de campo:
Tipo Descrição Tamanho (size=’xx’)
Str String alfanumérica xx=nº máximo de caracteres
Image String com o caminho de um ficheiro de imagem xx= nº máximo de caracteres
Sound String com o caminho de um ficheiro de som xx=nº máximo de caracteres
Date Data xx=4 -> AAAAMMDD, xx=2 -> MMDD
Hour Hora xx=4 –> HHMMSS, xx=2 –> HHMM
Int
Inteiro positivo ou negativo
xx=1 -> -128 a +127
xx=2 -> -32678 a +32767
xx=4 -> - 2147483648 a 2147483647
UInt
Inteiro positivo
xx=1 -> 0 a +255
xx=2 -> 0 a +65535
xx=4 -> 0 a 4294967295
Num Numérico de virgula flutuante, ‘dec’ informa a precisão em nº de
decimais,
xx=4 -> float
xx=8 -> double
Hexa Campo flags em formato hexadecimal. Ex: ‘C1A2F3E4’ xx=1 -> 8 bits, xx=2 -> 16 bits, ...
Bin Campo flags em formato binário, com o bit menos significativo em
primeiro. Ex. para 0x17: ‘10001110’
xx=1 -> 8 bits,
xx=2 -> 16 bits, ...
Bool Campo flag xx=1

(^)
(^)

11. ArtDB/fnList

Este serviço fornece uma lista das funções disponibilizadas pelo servidor.
Parâmetro Resultado

<fnList
[param=’T|F’] a)
/>

<fnList ttl="14">  ttl=nº total de funções existentes
<Contab ttl="6">  Namespace e nº de funções deste
<Conta/>  Nome da função

...  Outras funções do namespace

...  Namespace e nº de funções deste
...  Namespace e nº de funções deste

<fnList
function='Conta'
/>

<fnList ttl="1">
<CtaFch>  Namespace e nº de funções deste
<Conta type="N">  Nome da função e tipo de retorno
<Cta_CCu type="A">51:59/23:26</Cta_CCu>  b)
<TpSaldo type="|" def="Saldo">Saldo|DebMes|CredMes|SldMes|  c)
SldDeb|SldCred|DebAcm|CredAcm</TpSaldo>
<TipoMes type="|" def="MesAct">MesAct|MesAnt|Reab|Jan|Fev|Mar|Abr|Mai|Jun|Jul|  c)
Ago|Set|Out|Nov|Dez|Enc|Reg</TipoMes>
<TipoAno type="|" def="AnoAct">AnoAct|Ano-1|Ano-2|Ano-3|Ano-4|Ano-5</TipoAno>  c)
<TpMoeda type="A" def="EUR" len="3"/>  d)
</Conta>
</CtaFch>
</fnList>

a) se indicado param=’T’, serão incluídas todas as funções disponíveis e respetivos
parâmetros.
b), c) e d): Parâmetros de entrada e saída das funções:
Nome Descrição Valores possíveis
Type=’x’ Tipo de retorno, ou tipo de parâmetro

‘N’=Numérico
‘A’=Alfanumérico
‘|’=Enum / lista
Def=’x’ Valor por omissão (default), se o não for indicado. parâmetro

Len=’x-y:z’ Tamanho do campo

‘3’ – três dígitos exactos
‘3.2’ - três numéricos e 2 decimais
‘1-9’ – de um a nove dígitos
‘1-9.2’–de um a nove numéricos, com 2 decimais

(^)
(^)

12. ArtDB/Cambios

Fornece os câmbios da tabela de países/moedas na data do pedido, ou à data
especificada. Se não for especificada uma lista de moedas, serão enviados os câmbios para
todas as moedas, exceto para a moeda base (exemplo: se moeda base é ‘EUR’, nenhuma
cotação de ‘EUR’ será enviada).

Input Output
<cambios
[curr='USD;JPY;ABC;...']
[date='currency_date']
/>

<cambios date='aaaammdd'>
<curr ID='USD' buy='1.333' sell='1.222' />
<curr ID='JPY' buy='99.12' sell='99.55' />
<curr ID='ABC' rc='NotFound' />  se moeda não existir
</cambios>

13. ArtDB/CfgEnums

Fornece os dados da tabela de campos tipo lista (enums).
Input Output

<table type='xx' />

<table name="xxx">
<rec nr="1" id="01">Internet</rec>
<rec nr="2" id="02">Rádio</rec>
<rec nr="3" dtBeg="19000101" dtEnd="20060131" id="03">Jornais</rec>
<rec nr="4" id="04">Revistas</rec>
<rec nr="5" id="15">Outdoors</rec>
</table>
...
<table err="InvalidTable"/> ou
<table err="InvalidType"/>  se type não existir

14. ArtDB/SysTime

Fornece a data e hora locais ou UTC do sistema servidor.
Input Output
<systime [UTC='T|F']/> <systime>2080- 10 - 12T19:00:00</systime>

(^)
(^)

15. ArtUsr/TestPsw

Este serviço testa uma palavra-passe indicando se é forte suficiente para garantir o
mínimo de segurança contra-ataques de dicionário e conjunções de palavras de dicionário.
Com este serviço as aplicações podem testar uma palavra-passe de chamarem um
serviço de mudança de palavra-passe, ficando a saber o mesmo resultado, mas ocupando
muito menos recursos.
O teste do tamanho da palavra-passe é muito fácil, e cada aplicação pode contar o
nº de caracteres e decidir se é muito pequena ou não. No entanto, este serviço exige que
tenha pelo menos 4 caracteres de comprimento.
As palavras-passe não devem ter menos de 8 dígitos, não devem ser simétricas (ex.:
ABCDABCD), invertidas (ex.: ABCDEDCBA) ou exclusivamente numéricas, exclusivamente
maiúsculas, exclusivamente minúsculas, exclusivamente vogais, nem combinações destes
tipos (ex.: 123ABC), recomendando-se que contenha mistura de números, maiúsculas,
minúsculas e símbolos.
Input Output

<root psw='xxx' />

<root rc='OK|PswTooShort| Symetric|Mirrored|
OnlyNumbers|OnlyUppers|OnlyLowers|OnlyVowels|SequenceOfOnly' />
OK=A palavra passe é considerada forte (para o nº de dígitos fornecido)
PswTooShort=... tem menos de 4 caracteres;
Symetric=... é composta por dois segmentos iguais, ex.: ABCDabcd
Mirrored=... é composta por dois segmentos simétricos, ex: ABCDdcba
OnlyNumbers=... é composta apenas por números
OnlyUppers=... é composta apenas por maiúsculas
OnlyLowers=... é composta apenas por minúsculas
OnlyVowels=... é composta apenas por vogais
SequenceOfOnly=... contém dois segmentos de numeros, maiúsculas, minúsculas ou vogais.

16. Notify/SendMsg

Este serviço permite adicionar uma mensagem ao ficheiro de notificações do
ARTSOFT, que, para além de ficar registada na tabela, poderá ser enviada através dos
meios de notificação de ARTSOFT instalados na empresa (no ARTSOFT, via HTTP, via
email, via SMS, etc.)
Input Output
<message [FileID='StkFch|TerFch|...' RecID='xxx']>
+3519988776;addr@someurl.com;Usr1;Usr2=M;Usr3=MT;#3=M
 mensagem registada

(^)
(^)
_subject
message

 não registada,
rc=‘xx’
Parâmetros:
FileID='StkFch|TerFch|...' (^) e ao qual esta vai ficar associada.O FileID refere-se ao ficheiro sobre o qual se quer enviar a notificação
RecID='xxx' (^) qual a notificação se refere e ao qual esta vai ficar associada.O RecID refere-se ao numero do registo (autoincremento) sobre o
Este serviço pode ser dirigido a um conjunto diversificado de destinatários:

Se for indicado um número (precedido ou não de ‘+’), será entendido como
destinatário um nº de telefone, e esta mensagem deve ser enviada por SMS.
Se for indicado um endereço no formato xxx@yyy.zz, será entendido como
destinatário um endereço de correio eletrónico, e esta mensagem deve ser enviada
por email.
Se for indicado um identificador de utilizador, será entendido como destinatário o
utilizador ‘x’ do ARTSOFT. Adicionalmente poderá indicar-se também
‘User=M|T|MT’, em que ‘M’ significa ‘notificar adicionalmente por email e ‘T’
significa ‘notificar adicionalmente por telefone/SMS. Porém, não sendo indicado
qual o email ou telefone, estes deverão constar na ficha de utilizador.
Se for indicado ‘#x=M|T|MT’, será entendido como destinatário o endereço de email
ou de telefone/SMS do primeiro contacto do tipo ‘x’ da ficha do terceiro cujo
RecID=’yyy’ (implica obrigatoriamente que FileID=’TerFch’).

Serviços de Query

17. Queries/Query

Este serviço permite obter dados de uma tabela ou conjuntos de tabelas, ou
informações disponibilizadas por qualquer função, que estejam acessíveis. Recebe como
parâmetro uma string XML, compatível com as regras do XMLReports, descritas no

(^)
(^)
Apêndice A – XMLReports (pág. 79 ). Das várias funcionalidades que o XMLReports
possui, este serviço utiliza as não interativas^8 , permitindo obter dados obtidos a partir de
funções que calculam valores, listas obtidas a partir de uma navegação por um conjunto de
registos, ou uma mistura de ambos.
Para verificar a lista das tabelas disponíveis, existe o serviço ‘ArtDB/_DBTables’ (pág.
22 ). Para verificar a lista de chaves (indexes) e campos (colunas) de determinada tabela,
existe o serviço ‘ArtDB/_tblDesc’ (pág. 23 ), e para verificar quais as funções disponíveis,
existe o serviço ‘ArtDB/fnList’ (pág. 25 ).
Para obtenção de dados de uma tabela, ou de várias tabelas relacionadas, o XML
deverá ter um nó do tipo ‘list’, com um atributo ‘query’. Este atributo deverá conter a
indicação da tabela / chave onde pretende obter os dados, e consoante esta, deverá
fornecer os limites de cada segmento dessa chave. Poderá conter ainda a posição onde
terminou um query anterior para continuação, bem como eventuais filtros.
Um primeiro e simples exemplo de um query:
<TBL type='list' name='SKU#1' end=’xx’ query='StkFch|Principal|Codigo=1:10199’>

Neste, podemos observar os seguintes elementos:

type=list : indica que se trata de uma ‘list’, ou ainda, uma tabela fornecida por um
query;
name=’xxx’ ou ‘xxx#yyy’, neste caso SKU#1. Cada linha dessa list irá chamar-se
ou ‘xxx000’ a ‘xxx999’, neste caso, a (deduzindo-se daqui que
a query só pode ter no máximo, 9 elementos).
end=’xx: permite indicar o nº exato de registos pretendido;

(^8) As funcionalidades interativas permitem ao utilizador interagir manualmente com os dados, o que neste caso não faz sentido, p^ or
ser um serviço.

(^)
(^)

query=’...’ : Os dados serão obtidos a partir da tabela ‘StkFch’, através da chave
‘Principal’ (que contém a lista dos códigos de artigo), no intervalo [1 a 10109].
DefCol : Secção obrigatória a seguir a uma ‘list’ que contém a definição de uma linha
protótipo.
Código : Primeira coluna da ‘list’. Esta pode ter qualquer nome (desde que seja legal
em XML).
Nome : Segunda coluna da ‘list’. Também pode ter qualquer nome.
Form=’StkFch.xxx’ : fórmula que permita obter o valor pretendido. A fórmula pode
referir variáveis (com prefixo ‘%’) de um espaço de nomes (namespace), neste caso
StkFch, expressões aritméticas (ex: %StkFch.Prc.Preco.0 * 1.05 ), ou funções (com
prefixo ‘$’) de manipulação / formatação de dados (ex: $Left(%StkFch.Nome.0, 20)
ou quaisquer outras disponíveis para obtenção de dados ou valores (ex:
$Conta(%CtaFch.NrConta,Saldo)). Neste caso, só fará sentido colocar uma função
que receba um parâmetro vindo de uma variável de uma linha do query, senão, a
função será chamada sempre com um parâmetro constante, produzindo obviamente
um resultado constante em todas as linhas.

Um resultado possível para o query anterior seria:

1
Produtos de grande consumo

1.0
Produtos Alimentares, Utilidades

1.0.10
Azeites, Óleos, Vinagres, Sal

1.0.10.01
Azeites

1.0.10.01.00001
Azeite dourado

<SKU6>
<Codigo>1.0.10.01.00002</Codigo>
<Nome>Azeites fio de ouro</Nome>
</SKU6>
<SKU7>
<Codigo>1.0.10.02</Codigo>
<Nome>Óleos</Nome>
</SKU7>
<SKU8>
<Codigo>1.0.10.02.00001</Codigo>
<Nome>Óleo de soja</Nome>
</SKU8>
<SKU9>
<Codigo>1.0.10.03</Codigo>
<Nome>Vinagres</Nome>
</SKU9>
</TBL>

(^)
(^)
Como se pode verificar, o serviço query percorreu os primeiros 9 registos da
seleção efectuada, e devolveu o resultado, com uma anotação ‘next=xx’ no nó onde tinha
sido efetuado o query. Isto significa que, se for pretendido obter mais registos, deve voltar
a repetir-se o query indicando o ponto onde este deve retomar. Para isso, o query deve ter
a indicação ‘|#’ seguido do valor devolvido em ‘next’:
<TBL type='list' ... query='StkFch|Principal|Codigo=1:10199 |#5457'> ...
No ‘query’ permite estabelecer os limites inferior e superior da zona onde se
pretendem extrair os dados, que será suficiente na maioria dos casos, mas frequentemente
serão devolvidos registos sem interesse, pelo que será necessário eliminá-los. Pode fazer-se
isso, acrescentando-lhe um filtro. No exemplo seguinte pretende-se a estrutura de 1º nível
da hierarquia do ficheiro de artigos:
<TBL type='list' ... query='StkFch|Principal|Codigo=1:10199 |? $IsEqual(%StkFch.Div.NivFam,1)'> ...
Resultado:

0
Produtos de grande consumo

1
Vestuário e Calçado

2
Artigos de Desporto

3
Material Eléctrico

4
Equipamentos Domésticos

5
Automóveis, Acessórios e Peças

6
Informática, e Telecomunicações

9
Serviços

Ao efetuar um query utiliza-se um valor, ou intervalo de valores para cada segmento
de chave, mas no caso especial do primeiro segmento, é possível especificar uma lista de
intervalos, ou de valores:

(^)
(^)
...
...
Um query pode ser usado para obter apenas informação relevante, como, por
exemplo, alguns valores contabilísticos, utilizando algumas funções:

Neste pedido, o serviço deve devolver o resultado de algumas funções, e que gere um ficheiro de log, onde as funções deverão registar os detalhes onde obtiveram os valores. Nota: Nem todas as funções fornecem logs detalhados.

18. Queries/SQLQuery

Este serviço permite executar um statment SQL ‘Select’. Obviamente, por razões de
segurança, apenas é permitido executar statments Select. Sendo o resultado de um query
sempre uma tabela retangular com um número fixo de colunas, e um query poder conter
um enorme volume de dados, optou-se por codificar o recordset resultante numa string
com uma lista sequencial de campos separados por um caracter especial (muito fácil de
descodificar), evitando assim a grande redundância do XML na definição dos valores de
colunas.
Exemplificando: a partir de “ xxxTexto da
designação ”, irá ser substituído por “xxx|designação”.
Para isso, é possível definir qual o caracter pretendido para o separador de registos,
que, por omissão, é o caracter ‘tab’ (0x09). Para manter a descodificação da string muito
simples, criou-se uma restrição ao caracter separador: se este aparecer no resultado do
query será substituído por um espaço (dai que, por omissão se use o ‘tab’).

(^)
(^)
Pode pedir-se também a lista de nomes das colunas do recordset, que por omissão,
não serão enviadas (pressupõe-se que quando se especifica a lista de colunas pretendida já
se sabe quais são os seus nomes). Porém, existem situações em que esta lista pode ser útil,
e assim, pode colocar-se o atributo ‘flist=’s’, sendo então devolvidos todos os nomes das
colunas.
Um query pode conter muitos milhares de registos, que poderia implicar o consumo
excessivo de carga do processador ou largura de banda da rede, se não fosse controlado.
Assim, o statment deve conter um delimitador do nº de registos (por ex.: Select TOP 1000),
a fim de prevenir estes problemas. Se este delimitador não existir, o servidor ‘injeta’
automaticamente “TOP 10000” no query. Se o valor indicado for superior a 10000, será
devolvido o erro “ TopXxxTooBig ”.
Se for necessário enviar credenciais para estabelecer a coneção à base de dados,
estas podem ser enviadas inserindo dois atributos “UID=’user’ e Pwd=’psw”.
Na resposta é sempre incluído o atributo ‘nrRecs’ que contêm o nº de registos
contidos na coleção.
Um exemplo de query simples:

SELECT DivNrFicha,TerNome,TerMorada,TerLocalid,TerCPPais,TerCAE FROM TerFch
where TerFch.DivNrFicha < 1000 order by TerCAE

Resposta (‘\t’ = ‘tab’ ou caracter 0x09):
Query com indicação do caracter separador, ‘flist’, UID, PWD e TOP X:
<root sep='|' flist='s’ UID=’Master’ PWD=’SouOMaior’ >
SELECT TOP 100 DivNrFicha,TerNome,TerMorada,TerLocalid,TerCPPais,TerCAE FROM TerFch
where TerFch.DivNrFicha < 1000 order by TerCAE

349\tSANTOS & COMPANHIA S.A.\tQta Da Boavista\tGolegã\t2987-678 GOLEGÃ\t1210
135\tSIMÕES & ROSA, LDA.\tRua da Azenha 13\tSintra\t2710-112 SINTRA\t1460
412\tCOMERCIO, IMPORT & EXPORT, LDA.\tDoca do Poço do Bispo\tLisboa\t1370-555 LISBOA\t3111
...

(^)
(^)
Resposta:
Query utilizando o elemento CData do XML:
O elemento CData é aqui muito útil porque permite introduzir a sintaxe SQL sem
qualquer modificação, evitando codificações ou erros de transcrição. No exemplo seguinte
podemos verificar que assim podem usar-se diretamente os caracteres > e <:

0 AND TerFch.CliNumero<1000 order by TerCAE ]]> **Serviços relativos a Documentos**

19. DocFch/DocInsert

Permite inserir um documento, e eventuais registos associados, como artigos,
terceiros e vendedores.
Este serviço permite a inserção de um simples documento, ou de um conjunto de
documentos, artigos, terceiros e vendedores necessários para que a lista de documentos
seja processada. Esta última opção existe como conveniência para inserções em batch, mas,
rapidamente se concluirá que o XML input poderá ter tamanhos muito grandes, não sendo
muito adequado para WEBServices, até porque o seu processamento poderá demorar mais
tempo que o ‘timeout’ permitido para cada pedido. Nestes casos, aconselha-se a invocar
repetidamente cada um dos serviços que processam cada parte da mensagem.

<root nrRecs="99" fList="DivNrFicha|TerNome|TerMorada|TerLocalid|TerCPPais|TerCAE">
<rec>349|SANTOS & COMPANHIA S.A.|Qta Da Boavista|Golegã|2987-678 GOLEGÃ|1210 </rec>
<rec>135|SIMÕES & ROSA, LDA.|Rua da Azenha 13|Sintra|2710-112 SINTRA|1460 </rec>
<rec>412|COMERCIO, IMPORT & EXPORT, LDA.|Doca do Poço do Bispo|Lisboa|1370-555 LISBOA|3111</rec>
...
</root>

(^)
(^)
Para inserção de um documento, a estrutura do XML deverá ser:
Seção do XML Obrig Descrição
<document atribx=’xx’ ... > (^) S Início da mensagem e eventuais atributos adicionais que sejam
necessários.

...

..

N
Seção opcional para a identificação de um cliente que não conste na
tabela de terceiros e não se pretende que não venha a constar. Para isso,
é necessário registar os dados da sua morada e da eventual morada de
entrega do pedido.
... (^) N Seção opcional para uma lista de follow-ups a serem associados ao
documento.
.. (^) N Seção opcional para uma lista de situações a serem associadas ao
documento.

...

N Permite enviar dados específicos do cabeçalho de um documento. Se este
não for enviado, estes serão deduzidos a partir dos elementos de
‘DocItems’, se estes estiverem presentes. Senão, serão assumidos valores
por omissão.
...
ou
...
S Permite enviar as várias linhas do documento (docItems), ou efetuar um
documento de regularização de outro (onAcc), por ex. faturar
encomendas ou guias de remessa.
.... (^) N Seção opcional para especificar uma lista de meios de pagamento.
(^)
Para inserção de um documento e simultaneamente inserir ou atualizar artigos,
terceiros e vendedores, a estrutura do XML deverá ser:
Seção do XML Obrig Descrição
<message atribx=’xx’ ... > (^) Início da mensagem e eventuais atributos adicionais que sejam necessários

...

N
Nesta seção pode incluir-se os dados necessários à criação ou atualização
de um terceiro, a fim de ser processada antes do processamento do
documento. Para especificação desta mensagem, consultar o serviço
‘TerFch/Update’.

...

N
Nesta seção pode incluir-se os dados necessários à criação ou atualização
de um ou vários artigos, a fim de ser processada antes do processamento
do documento. Para especificação desta mensagem, consultar o serviço ‘
StkFch/Update’

...

N
Nesta seção pode incluir-se os dados necessários à criação ou atualização
de um vendedor, a fim de ser processada antes do processamento do
documento. Para especificação desta mensagem, consultar o serviço ‘ Erro! A
origem da referência não foi encontrada. ’.

(^)
(^)
... (^) S Seção dedicada à mensagem documento, conforme descrita atrás.
(^)
Exemplo:

<Doc.Serie>V901</Doc.Serie>
<Doc.Pedido>12345678</Doc.Pedido>
<Data.Docum>20080405</Data.Docum>
<Ter.NrTerc>130</Ter.NrTerc>
<CPag.Cod>1</CPag.Cod>
<MExp.Cod>1</MExp.Cod>

<Cod.Codigo>00100100001</Cod.Codigo>
<Qtd.Real>1</Qtd.Real>
<Val.UnBru>1.55</Val.UnBru>
<Desc.LinS>3.00+1.50</Desc.LinS>
<Div.Obs>Observações</Div.Obs>

<Cod.Codigo>00100100002</Cod.Codigo>
<Qtd.Real>1</Qtd.Real>
<Val.UnBru>1.55</Val.UnBru>
<Desc.LinS>3.00+1.50</Desc.LinS>
<Div.Obs>Observações</Div.Obs>

20. DocFch/DocUpdate

Permite atualizar um documento de acordo com as regras existentes para alteração
de documentos.
Este serviço permite a atualização de um documento. Ao utilizar este serviço é
importante realçar que são seguidas as regras de alteração de documentos, assim sendo,
num documento assinado, pago ou já regularizado só irá ser possível alterar campos
estáticos.

(^)
(^)
Com este serviço é possível alterar o cabeçalho, inserir novos lançamentos, atualizar
lançamentos existentes, ou mesmo eliminar lançamentos, desde que essas operações sejam
possíveis para o documento sobre o qual se pretende efetuar essas mesmas operações.
É importante referir, que, no caso de se estar a alterar lançamentos com
agregações/espécies e mutações, os mesmos terão que ser enviados na sua totalidade, isto
é, caso o lançamento tenha agregações ou espécies/mutações e se queira alterar as
mesmas, deverão ser enviados quer os campos que se pretende alterar bem como os que se
pretende manter.
Para inserção de um documento, a estrutura do XML deverá ser:
Seção do XML Obrig Descrição
<document [trans='s' retid='s'
status='s']>
S Início da mensagem e eventuais atributos adicionais que sejam
necessários
<docheader ID='Ai_doc'|
docID='Txxx/NrDoc'>
... Lista de campos do
cabeçalho de documento.

S
Permite enviar dados específicos do cabeçalho de um
documento. Este campo é obrigatório, pois é necessário enviar a
identificação de qual o documento que se pretende alterar. Essa
indicação pode ser dada através do Auto Incremento do
documento, AI=’Ai_doc’ ou através da identificação do
documento por série/número do documento, docID=’Txxx/yyy’.
...
N Permite enviar as várias linhas do documento (docItems),
inserção de novos lançamentos, alteração de lançamentos
existentes ou eliminação de lançamentos.
(^) N Seção opcional para uma lista de situações a serem associadas ao
documento
.... (^) N Seção opcional para especificar uma lista de meios de pagamento

....

N Seção opcional para especificar imagens associadas ao
documento
(^)
Exemplo:

-1252"?> (^) (^) 020111208 (^) - > ============== Importante ================ 20111208 Ola teste 2 --> Apenas é permitido enviar dados que possam> ser alterados no cabeçalho. (^) Observações Teste - Provisório

(^)
(^)
(^)
(^) -> ===========================================
<Qtd.Real>10</Qtd.Real> <Div.Obs>Por número do lançamento</Div.Obs> --> Update do lançamento referente ao lançamento> número 1 do documento em causa. Só podem ser (^)
--> enviados campos que sejam passiveis de > alteração nos lançamentos.(aplica-se a todos (^)

os nós )

<Qtd.Real>10</Qtd.Real> --> ========================================== > Update ao lançamento, do documento em causa, (^)
<Div.Obs>Por autoincremento</Div.Obs> <CDU.01> 1234 <CDU.01> - > identificado com o autoincremento 28475

--> Eliminação do lançamento referente ao > lançamento número 2 do documento em causa (^)

21. DocFch/DocSignature

Permite assinar um documento, ou uma lista de documentos, que estejam como
provisórios e que se pretenda que sejam assinados.

<document docAI='xxxx;yyyy;zzzz'|
docID='TXXX/NNN;TXXX/NNN;TXXX/NNN' status='s'
retid='s' />

docAI='xxxx;yyyy;zzzz' é uma lista de autoincrementos dos
documentos que se pretende assinar.
docID='...' é uma lista de documentos a assinar, identificados por
tipo(TXXX) e número (NNN) de documento.

Input:

Output:

<document docAI='111;222;333' status='s' retid='s' />
... ou ...
<document docID='V003/ 260182900 ;V003/ 260182901 ;V003/34' status='s' retid='s' />

Output 1: Para o caso de se ter utilizado docAI
<document status='s' err='3'>
<sucess ID='111' IDEx='V003/40'/>
<errors rc='RecordNotExist' ID='222'>Nº de registo não existe</errors>
<errors rc='DocPrepareError' ID='333'>O documento não se encontra em modo de elaboração e como tal não pode ser
assinado</errors>
</document>
Output 2: Para o caso de se ter utilizado docID
<document status='s' err='2'>
<sucess ID='122' IDEx='V003/41'/>
<errors rc='RecordNotExist' IDEx='V003/260182901'>Nº de registo não existe</errors>

(^)
(^)

22. DocFch/DocDelete

Permite anular um documento. Se a série de documentos estiver configurada para
anulação de documentos, o documento será marcado como anulado, removendo os registos
de C/C, desintegrando stocks e todas as linhas do documento irão manter-se. Se a série não
estiver configurada para anulação de documentos, executará as mesmas operações, mas as
linhas do documento serão eliminadas.

<document ID=’XXXX’ | docID='TXXX/YYY'
MotDel='1' status='S' />

MotDel=um elemento da tabela de motivos de anulação
de documentos

23. DocFch/DocRemove

Permite eliminar um documento. Esta operação faz as mesmas operações que
DocFch/DocDelete, eliminando o registo do documento. Esta operação não é possível em
séries que têm configurado a anulação de documentos. O comando é idêntico, não sendo
necessário o atributo ‘MotDel’, não teria interesse em categorizá-lo, uma vez que o
documento vai ser eliminado.
<document ID=’XXXX’ | docID='TXXX/YYY' status='S' />

24. DoFch/DocForceR

Efetua a regularização forçada de documentos pendentes^9 na totalidade ou apenas
de algumas das suas linhas. Para efetuar uma regularização forçada, é necessário justificar
qual o motivo, que deverá ser um dos elementos da respetiva tabela.
Para regularizar todo o documento:

root Nome (pode usar-se qualquer um)
docID='xxx/yyyy' Qual o nº de documento pretendido (alternativa: id=’xxx’, xxx=autoincremento)

(^9) Propostas, Encomendas, etc.
Nº de registo não existe

(^)
(^)
force=’id_motivo’ Motivo da regularização (um elemento da tabela de motivos de regularização forçada)
Para regularizar apenas algumas linhas:

root Nome (pode usar-se qualquer um)
docID='xxx/yyyy' Qual o nº de documento pretendido (alternativa: id=’xxx’, xxx=autoincremento)
id=’x’ Nº da linha do documento a regularizar
force=’id_motivo’ Motivo da regularização (um elemento da tabela de motivos de regularização forçada)

25. DocFch/GetImage

Fornece a(s) imagem(s) associadas a um documento. Cada página contém um
elemento com os atributos: type – informa o tipo de imagem; descr – Texto descrição
(se existir) associada ao documento. O texto de contém a imagem formatada em
Base64.
Exemplos:
Input:

Output:

<doc docID='E999/123456'/>
ou
<doc id='123456'/>

Doc Nome do nó (pode usar-se qualquer nome)
docID='xxx/yyyy' Qual o nº de documento pretendido (alternativa: id=’xxx’)
id=’xxxx’ ID do documento, ou autoincremento (alternativa: docID=’xx/yy’)

<Doc>
<img type="jpg" descr="blabla">/9j/4AAQSkZJRgABAQEAeAB4AAD/2wBDAAgGBgcGBQgHBwcJCQQgHBwcJCQ
...
W9ZY0VtzKyEADP8AtFT+FFFFbQpxprljsdFOlCkuWCsjW9ZY0VtzKyEADP8AtFT+FFFFbW9ZY0VtzKyEADP8A/9k=
</img>
<img type="png" descr="blá-blá">iVBORw0KGgoAAAANSUhEUgAAAKUAAACoCAMAAAC2a942H2j5es0cvH2j5
...
uTJ50nyEnCLKT1n+H2j5es0cvUclAAAAAElFTkSuQmCCH2j5es0cvH2j5es0cvH2j5es0cvH2j5es0cvH2j5es0c=

(^)
(^)

26. DocFch/SetImage

Permite associar imagem(s) a um documento. Cada página deverá conter um
elemento com os atributos: type – informa o tipo de imagem; descr – Texto descrição
(se existir) associada ao documento. O texto de contém a imagem formatada em
Base64.
Doc Nome do nó (pode usar-se qualquer nome)
nrDoc='xxx/yyyy' Qual o nº de documento pretendido (alternativa: id=’xxx’)
id=’xxxx’ ID do documento, ou autoincremento (alternativa: nrDoc=’xx/yy’)
retid=’s|n’ Pretende-se que seja devolvido o autoincremento dos artigos processados
status='s' Solicita que seja enviada a descrição textual do erro

Exemplos:
Input:

Output:

</img>
</Doc>
Ou
<Doc err="ErrorID"/>
Erros:
DocImgInvalDocID,DocImgDocNoImage

<doc nrDoc='E999/999999' retid='s' stat='s'>
<img type="jpg" descr="Imagem 'smile'">/9j/4AAQSkZJRgABAQEAeAB4AAD/2wBDAAgGBgcGBQgHBw
...
WyXZf166nFWrc+i2LVFFFe6c4UUUUAUNV/49TWdo/wDrfxoooA6CiiigAooooA//2Q==
</img>
<img type="png" descr="Caricatura">iVBORw0KGgoAAAANSUhEUgAAAEcAAABGCAIAAAARjh7tAAAACXBI
...
fpCrJ7YAAAAASUVORK5CYII=
</img>
</doc>

<doc>
<img id="3"/>
<img id="4"/>
</doc>
Ou, caso haja erros:
<tag err="MissingImageData"/>
Ou

(^)
(^)

27. DocFch/DocPrices

Fornece uma lista de preços para os artigos pedidos, considerando um cliente e uma
série de documentos.
Input:
pricelist Nome do nó (não é obrigatório que tenha este nome, mas é recomendado)
doc='xxx' Especifica qual a série à qual os preços se referem, ex: S999, V1, V999
dsc='[N]|S|all' N: Preço líquido, S: Preço bruto e desconto composto, all=Preço Bruto, e lista de descontos separados por ‘+’
vattx='[N]|S' Indicar qual a taxa de IVA do artigo
vatinc='[N]|S' O preço deve incluir o valor do IVA
stk='[N]|S' Deve ser indicado o stock existente
obs='[N]|S' Deve ser incluído o campo ‘observações’ da ficha de negociações
entityID='C|F|N|[R]:nn' Identificação do cliente ao qual se pretendem os preços. Se não indicada, os preços fornecidos são os de cliente indiferenciado.
sku='xxxxxxx' Código Principal de Artigo
sku2='xxxxxxx' Código Opcional de Artigo
qty='nnn' Quantidade à qual se pretende cotação

Exemplo:

Tag/Atributo Obrig Descrição
<pricelist

entityID='N:501848487' N (^) Identificação do cliente (por omissão: indiferenciado)
doc='V1' S (^) Identificação da série de documentos

Erros:
DocImgInvalDocID,InvalidImageType,MissingImageData,ErrorSavingImage

(^)
(^)
vatinc='n' vattx='s' N (^) Pretende-se preços sem IVA, e a respetiva taxa
dsc='s' N Pretende-se obter preços brutos e desconto composto
obs='s' N (^) Pretende-se as observações da ficha de negociações.
stk='s' N (^) Pretende-se a existência em stock no armazém da série V1
retid='s' N (^) Pretende-se que seja devolvido o Auto incremento dos artigos
processados
status='s' S (^) Solicita que seja enviada a descrição textual do erro
<item sku='1019910001' S (^) Indicação do código principal de artigo (para o opcional usar sku2)
qty='4' /> N (^) Indicação da quantidade para a qual se pretende cotação

N (^) Indicação opcional de uma lista de artigos e respetiva quantidade

Output:
Item (^) Nome de cada elemento da lista
id='nn’ (^) Identidade/Auto incremento do artigo
price='nnnnnn.nn' (^) Preço do item
disc='nn.nn|xx.xx+yy.yy' (^) Desconto ou lista de descontos (consoante dsc=’S’ ou dsc=’all’)
vat=’nn’ Taxa de IVA
stock=’nn’ (^) Saldo real em stock no armazém correspondente à série de documentos
doc=’xxx’. Só se foi pedido, com stk=’S’. Se houver stock negativo, devolve
‘0’.
avail=’nn’ (^) Tal como o anterior, mas devolvendo o saldo disponível.
bonus=’nnn’ Quantidade bónus (resultante de uma promoção ou negociação)
skuT=’xxxxx’ Referência ou código de artigo do terceiro / cliente
qty=’4’ (^) Existe uma negociação com quantidade mínima e o pedido feito com a
quantidade ‘qty’ que é inferior á negociada. Este nó é marcado com
rc=‘WarnOnlyMinQty’.
minqty=’nnn’ (^) Quantidade mínima para o preço indicado
timetd=’nnn’ Tempo, em dias para entrega (time to delivery)
(valor do nó) (^) Observações existentes na ficha de negociações
Exemplo:

Observações da ficha de negociação

(^)
(^)

28. DocFch/DocsByEnt

Fornece uma lista de documentos de um terceiro de determinada série, completa,
ou apenas com documentos pendentes de regularização. A função ‘DocStatus’ faz o mesmo
que esta, mas é especializada apenas num documento, pelo que nesta, apenas serão
descritos os parâmetros que aquela não suporta.

Input:

doc='Txxx'/> (^) Tipo e série de documentos. Este parâmetro é obrigatório.
entityID='xxx' (^) Nº de terceiro, cliente, fornecedor, NIF, etc. Este parâmetro é
obrigatório.
div='S|[N]' (^) Obter os documentos do terceiro como indiferenciado. Mesmo que exista
um registo de cliente / fornecedor, podem ser elaborados documentos
para este como terceiro indiferenciado.
begDate (^) Opcional, e indica a data inicial em que o relatório deve começar.
endDate (^) Opcional, e indica a data inicial em que o relatório deve terminar.
Outputs:
Input Output

<report
doc='C1'

<report doc="Txxx" entityID='xxx' begDate='xxx' endDate='xxx' ... ... ... />

(^)
(^)
entityID='xxx'
fwup='s' />

Aprovação Encomenda

Os detalhes da função ‘DocStatus’ complementam a descrição desta função.

29. DocFch/DocStatus

Fornece informação sobre o estado de um documento, de forma abreviada, ou
detalhada por cada item, para todos os itens ou apenas para os que estão pendentes de
regularização. Esta função faz o mesmo que a anterior, mas é especializada apenas para um
documento, e pode ter utilidade quando foi pedida a anterior em modo reduzido, e se
pretende mais detalhes sobre um documento em particular.

Input:
<root docID="Txxx/yyyy" id=’xxx’ entityID='xxx' div='s' all='s' fwup='n' level='n' docitems='S' sku=’1’/>

(^)
(^)
id='xxx' Auto incremento do documento
docID='Txxx/yyyyy' Tipo, série e número de documento. Se enviados doc e DocID, serão validados
entityID='xxx' Nº de terceiro, cliente, fornecedor, NIF, etc. Se enviado entityID, será validado se o documento pertence a esta entidade.
div='S|[N]' Documentos de ‘entityID’ como terceiro diverso/indiferenciado
all='S|[N]' Todos os documentos ou só pendentes
fwup='S|[N]' Pretende-se que seja enviado o follow-up do documento
level='S|[N]' Pretende-se que seja enviado o estado atual do documento
docItems='S|[N]' Pretendedo documento.-se que seja enviado o estado de regularização de cada linha
sku='D|O|T' Pretende(opcional) ou do terceiro.-se que seja enviado o código principal (default), alternativo
retID / status (comportamento standard)
Outputs:
Input Output

 código opcional de artigo

(^)
(^)
 regularização forçada

Aprovação Financeira
Em negociação avançada

Decisão Suspensa

É de realçar que quando “ all=’s’ ” todos os itens do documento são apresentados,
mesmo aqueles que já não estão pendentes. No entanto, existem dois motivos para que um
item não esteja pendente: foi processado (encomendado, faturado, etc.) ou cancelado. Se
for necessária essa informação, com “ all=’s’ ” num item cancelado (com regularização
forçada), irá ser apresentada a quantidade processada antecedida de ‘*’ e adicionado o
atributo ‘reason’ que indica qual a causa da regularização. Se “ status=’s’ ”, será
apresentada também a informação textual do porquê.

30. DocFch/DocPrint

‘Imprime’ um documento em formato .HTML, mediante transformação das variáveis
existentes num formulário indicado no comando, ou parametrizado na série de documentos.
Retorna um ficheiro HTML com o resultado, ou uma string XML com a descrição do erro.
Para impressão de um documento através do gerador de relatórios, ver a descrição
do serviço DocFch/DocPrint (pág. 49 ).

Input:

status='s' Em caso de erros, pretende-se a descrição completa do mesmo

<docum doc='23693' docID='V1/12666' id='9130' entityID='C:14997' form='fileName.html' status='s' />

(^)
(^)
doc='xxx' Autoincremento do documento
docID='Txxx/yyyyy' Tipo, série e número de documento. Se enviados doc e DocID, serão validados
entityID='xxx' Nº de terceiro, cliente, fornecedor, NIF, etc. Se enviado entityID, será validado se o documento pertence a esta entidade.
form='htm/filename.html'
Por omissão, é usado o primeiro nome parametrizado na série de
documentos, alterando-se a extensão para .HTM, e que deve residir na
diretoria de formulários. Este atributo ignora o que está parametrizado
e permite especificar o nome do formulário a usar, e eventualmente um
subdiretório do diretório de formulários.
Output:
O resultado desta função é uma string HTML, com o formato desejado, bastando para
isso efetuar o respetivo desenho em .HTML. Como se pode ver, as figuras seguintes
representam uma fatura e dois talões com designs diferentes, resultantes da transformação
desse formulário.

(^)
(^)

O

Apêndice E - Formulários HTML
descreve como formatar ficheiros .HTML de forma a serem transformados pelos
serviços do ARTSOFT.

31. DocFch/DocPrintEx

Este serviço imprime um documento através do gerador de relatórios. Para que este
serviço esteja disponível, é necessário carregar o ‘DocPrintCmd.DLL’ ou ‘DocPrintSvc.DLL’
(no ficheiro de configuração, na linha ‘ListaDLL’ (ver
Apêndice I - Configuração do servidor, na pág. 115 ).
Este serviço (bem como o DocFch/DocPrintEtiqEx ), poderá ter muita utilidade se
for usado através do ArtCMD (versão DocPrintCmd), replicando as mesmas funcionalidades
apresentadas pela impressão de documentos do ARTSOFT (seleção de opções de impressão,
pré-visualização do documento, etc.). No entanto esta versão não deve ser utilizada através
do servidor XML, pois este, normalmente estará a ser executado num servidor de aplicações,

(^)
(^)
não podendo interagir com o utilizador, nem podendo aceder facilmente às impressoras que
este disponha no seu posto de trabalho ou remotamente.
Se for necessária a impressão de documentos através do servidor XML, deve usar-se
a versão DocPrintSvc.DLL. No entanto, este serviço requer alguma atenção extra...

A configuração de impressão de da(s) série(s) a imprimir deve ser feita através do
ARTSOFT, e no na configuração do projeto não pode ser usada a opção ‘visualizar’;
O serviço só terá disponíveis as impressoras instaladas no servidor.
Deverão ser tidas em conta as restrições de licenciamento do List & Label para estes
casos.
32. DocFch/DocPrintEtiqEx

Este serviço imprime etiquetas referentes a lançamentos de um documento através
do gerador de relatórios. Tal como para o serviço DocFch/DocPrintEx , é necessário carregar
os mesmos DLL, de acordo com as instruções já referidas para esse serviço.
Exemplo de utilização:

33. DocFch/CfgDocum

Fornece dados da tabela de configuração de documentos. Os nomes a incluir no
atributo ‘Fields’ podem ser obtidos a partir de _ArtDB/tblDesc (pág. 23 ), com a tabela
‘ArtTbe’ e enum ‘tblDoc’.
Input Output

<table type=’V1:V999’
fields='xx,yy,zz'
name=’T|F’
/>

<table>
<rec id="E901" arm="11" flags="11110000000000000000000000000000">
Guias Remessa de Fornecedor
</rec>
<rec id="E903" arm="11" flags="11110000111100001111000000001111">
Faturas de Fornecedor
</rec>
<rec id="E904" arm="11">Vendas Dinheiro Fornecedor</rec>
<rec id="E909" arm="11">Devoluções a Fornecedor</rec>
</table>
ou

<docum id='ai_doc' | docID='Txxx/yyyy-zzz'
[form='etiqueta.lsx']
/>

form='xxx' - Imprimir com o formulário especificado, que por
omissão é o parametrizado na série de documentos

(^)
(^)

G.R.FornecedorFacturas FornecedorDevol. Fornecedor

ou ou

 se group não for 1,2 ou 3 **Serviços relativos a Artigos**

34. StkFch/Update

Permite inserir um artigo, e eventuais registos associados, como redefinições de
armazéns, negociações com terceiros, unidades logísticas, equivalências, composições e
registos de fichas adicionais.
Para inserção de um artigo, a estrutura do XML deverá ser:
Secção do XML Obrig Descrição
<sku rec=’xx’ ... > S Início da mensagem e eventuais atributos adicionais que sejam necessários

<Cod.Codigo>...</Cod.Codigo>

</ MainRec >

N
Secção opcional para a identificação de um artigo que não conste na tabela de
artigos. Se esta secção não existir, o atributo rec=’RecIDxxx’ tem que estar
presente no nó SKU.
<Warehouses>
<rec id=’nrArm’>
(redefined sku fields)
</rec>
<rec nr=’nrArm’>
(redefined sku fields)
</rec>
</Warehouses>

Secção opcional para a lista de campos do artigo redefinidos no armazém. Se
não estiver presente no nó ‘rec’ o atributo id=’nrArm’, o campo ‘Logis.NrArm’
tem de ser válido. Se estiverem os dois presentes, serão validados quanto à sua
consistência. Os campos a colocar no espaço fields deverão ser os que tiverem
disponíveis na tabela StkArm, que pode ser consultada através do serviço
ArtDB/_TblDesc.
<EntityNeg>
<Client id='xx.y'>
(fields ...)
</Client>
<Supplier id='xx.y'>
(fields ...)
</Supplier>
</EntityNeg>

Secção opcional para uma lista de negociações com clientes ou fornecedores.
Se no nó ‘Client’ ou ‘Supplier’ o atributo id=’xxx.y’ não estiver presente, os
campos ‘Ter.Cli’ ou ‘Ter.Forn’ têm que ser válidos. Se ambos estiverem
presentes, serão validados quanto à sua consistência. Os campos a colocar no
espaço fields deverão ser os que tiverem disponíveis na tabela StkRft, que pode
ser consultada através do serviço ArtDB/_TblDesc.

(^)
(^)

(fields ...)

N
Secção opcional para uma lista de Unidades logísticas de artigo. No campo
id=’xx’ deverá ser passado o número de identificação da unidade logística que
se está a criar (1,2,8, etc). Os campos a colocar no espaço fields, os que
fizerem sentido, poderão ser consultados na tabela StkUnl através do serviço
ArtDB/_TblDesc.

(fields ...)

(fields ...)

N
Secção opcional para uma lista de artigos equivalentes associadas ao registo de
artigo. No campo id=’xx’ deverá ser passado o número de identificação do
artigo equivalente que se está a criar ou a alterar. De notar que a numeração
da identificação do artigo equivalente é inicia a 0. Os campos a colocar no
espaço fields deverão ser os que tiverem disponíveis na tabela StkEqu, que
pode ser consultada através do serviço ArtDB/_TblDesc.

(fields ...)
(fields ...)

N
Seção opcional para uma lista de artigos de produção associados ao registo de
artigo. Os campos a colocar no espaço fields deverão ser os que tiverem
disponíveis na tabela CmpFch, que pode ser consultada através do serviço
ArtDB/_TblDesc.

(fields ...)
(fields ...)

N
Seção opcional para uma lista de fichas adicionais que se queira associar ao
registo de artigo. Os Campos que devem constar no nó Rec podem ser
consultados através do serviço ArtFDU/xxxxxx.

35. StkFch/Delete

Permite eliminar um registo de artigo, caso este registo não tenha lançamentos em
documentos pendentes.
Para eliminação de um artigo a estrutura do XML deve ser:
Seção do XML Obrig Descrição

Id=’xxx’ – identificação do registo de artigo (Auto incremento) que se pretende
eliminar.

36. Stkch/CfgGroups

Fornece os dados da tabela de grupos de artigos.
Input Output

<table group='1|2|3'/>

<table>
<rec fam="101">Equipamentos</rec>
<rec fam="102">Sistemas</rec>
<rec fam="201">Software pessoal</rec>

(^)
(^)
Software professional
Software Premium
Software Upgrades

... ou

 se group não for 1,2 ou 3

37. StkFch/CfgEspec

Fornece os dados da tabela de espécies passada como parâmetro no campo
type=”xxx”.
Input Output

<table type='xxx'/>

<table title="Calçado Bebé">
<rec id="1">Azul</rec>
<rec id="2">Cor Rosa</rec>
<rec id="3">Verde</rec>
<rec id="4">Laranja</rec>
<rec id="5">Amarelo</rec>
</table>

38. StkFch/CfgMutac

Fornece os dados da tabela de mutações passada como parâmetro no campo
type=”xxx”.
Input Output

151617181920

(^)
(^)
Serviços relativos a Terceiros

39. TerFch/Login

Permite a um serviço web usar o registo de contactos do ARTSOFT para controlar
contas e acessos de terceiros a partir da tabela de contactos, e validar o registo/password
sem que esta tenha de transitar na rede. Deve receber um XML formatado da seguinte
forma:

O atributo ‘ID’ deve conter o identificador do
registo de contacto do terceiro, fornecido pelo
ARTSOFT na respetiva ficha, a partir do botão
‘Acessos’ (ver imagem ao lado). Este parâmetro
serve para localizar qual o registo onde devem ser encontradas as credenciais (password
e respetivas permissões). Este parâmetro é calculado pelo ARTSOFT, de forma a ter
sempre 8 dígitos entre ‘0..9’ e ‘A..Z’ (não diferenciando entre maiúsculas e minúsculas),
e ser ‘pseudoaleatório’, de forma a não poder ser facilmente dedutível, numa empresa
cliente, qual o ID de um utilizador a partir de outro, a fim de aumentar a segurança do
sistema.
Os atributos ‘seed’ e ‘digest’ e a descrição do algoritmo de login estão descritos no
apêndice K – validação de logins.
O atributo ‘terAcc’ (opcional) informa que se pretende a lista das contas do terceiro que
este contacto tem acesso (como cliente, fornecedor ou ambas).

Output:

<Login id='LBW0XGXL' seed='0123456789012345' digest='FEDBD236CCC8D897947EC9B7B3AD46667947EC' terAcc=’x’/>

<Login rc="0" id="1" entityID="1" contact="1.1" flgCC="1000" flgEnc="10000" flgWeb="1111111111111111">
<Cli nr="21.1.1.1.00100">Clientes C/C, Gerais - MN</Cli>
<Cli nr="21.2.1.1.00100">Clientes títulos a receber</Cli>
<Cli nr="21.1.1.2.00100">Clientes C/C, Gerais - UE </Cli>
<Cli nr="21.1.1.3.00100">Clientes C/C, Gerais - OM</Cli>
<For nr="22.1.1.1.99988">Fornecedores gerais MN</For>
<For nr="22.1.1.2.99988">Fornecedores gerais UE</For>
<For nr="22.1.1.3.99988">Fornecedores gerais OM</For>

(parte da) janela que contém o ID do
contacto.

(^)
(^)
Em que:
rc='xx' Retorno do Erro. 0=Tudo OK, ou:
MissingXMLAttr=Faltam os atributos id, seed ou digest.
LoginInvalCont=O ID do contacto é inválido ou não existe.
LoginInvPasswd=A password do contacto não está correta.
id=’xx’ Devolve o ID do registo de contacto (Auto Incremento).
entityID='xxx' Devolve o ID do registo de terceiro (Auto Incremento).
contact='xx.yy' Devolve o tipo/nº de contacto.
flgCC='1111' Devolve as 4 flags relativas a C/C, em que o 1º bit representa a 1ª flag,... (janela acessos)
flgEnc='11111' Devolve as 5 flags relativas a Encomendas em que o 1º bit representa a 1ª flag, ...
flgWeb='0101 ... (16x)' Devolve as 16 flags específicas para WEB existentes no contacto, 1º bit=1ª flag, ...
Cli nr=’21.1...’ Nó que contém informação sobre o nº e tipo de conta do cliente
For nr=’22.1...’ Nó que contém informação sobre o nº e tipo de conta do fornecedor

40. TerFch/SetPass

Este serviço permite modificar a palavra-passe de um contacto de terceiro. Este só
pode ser chamado depois de efetuado o ‘TerFch/Login’ com sucesso. O input e output deste
serviço são iguais aos do serviço ‘

ArtUsr/TestPsw’ (pág. 27 ).
Este serviço exige que a palavra-passe tenha no mínimo 4 caracteres.

41. TerFch/Update

Permite atualizar um ou mais registos de terceiros, respetivas moradas extra,
contactos e fichas adicionais. Recebe como parâmetro um XML formatado da seguinte
forma:

<Entity>
<BaseAddr>
<!-- fields -->

<OtherAddr>
<Rec ID='1'>
<!-- fields -->

<Contacts>
<Rec ID='1.1'>
<!-- fields -->

<MoreInfo>
<Rec>
<!-- fields -->

<For nr="22.2.1.1.99988">Fornecedores Com Títulos</For>
<For nr="26.1.1.1.99988">Fornecedores Imobilizado MN</For>
</Login>

(^)
(^)

A zona ‘fields’ indica que se deve juntar a lista de campos necessários á criação / atualização de um registo, que pode ser consultada no ARTSOFT em Funções de Supervisão/Base de dados/Table Status, na tabela TerFch para ‘BaseAddr’ (endereço base) e na ‘TerCon’ para ‘Contacts’ (contactos). Os campos ‘OtherAddr’ (moradas extra) são um subconjunto de TerFch composto por: NrFilial, Nome, Morada, Localid, CPPais, NrTelef, NrFax, Email, EDICodEnt, LatitudeGPS, LongitudGPS. O campo ‘NrFilial’ é usado aqui para representar o nº da morada extra a usar, que pode ser expresso de forma alternativa como atributo de . Se por qualquer razão forem enviados os dois, estes deverão ser iguais, senão é devolvido o erro ‘RecordConfict’. Para ‘MoreInfo’, os campos disponíveis são: num num str: enum date hour num str date numstr date num str: enum bool str: subject str: filepath str str: DocID(C|F|E|S|Vxxx/yy) Se forem enviados o campo ‘RegID’ e o atributo ID=’xx’ , estes deverão ser iguais, senão é devolvido o erro ‘RecordConfict’.

42. TerFch/Delete

(^)
(^)
Permite eliminar um terceiro, ou informação associada a este, mais especificamente
informação de outras moradas, da lista de contactos ou das fichas adicionais.
Input:
Parâmetros:
id=’xx’ | EntityID=’T:xx’
id=’xx’ – autoincremento do terceiro a eliminar.
EntityID=’T:xx’ – tipo e número do terceiro a eliminar. No caso de cliente
seria na forma ‘C:899’, por exemplo, que significaria que seria para eliminar
o cliente com o número 899.

Se este campo for enviado, o terceiro será eliminado como cliente,
fornecedor ou no geral, dependendo do que vem no campo type=’...’. Se o
campo type=’..’ não for passado, é assumido o valor por defeito e o terceiro
é apagado totalmente (apaga o registo de terceiro). Caso o campo type tenha
o valor ‘C’ então apenas o registo de cliente do terceiro é eliminado,
mantendo o seu registo de terceiro e de fornecedor (caso o seja). Caso o
campo type tenha o valor ‘F’ então apenas o registo de fornecedor do
terceiro é eliminado, mantendo o seu registo de terceiro e de cliente (caso o
seja).
Por último, se no campo type for passado ‘All’ então o registo é eliminado na
sua totalidade, ou seja, o registo de terceiro é eliminado.

Permite eliminar outras moradas, que não a principal, associadas ao registo
de terceiro. No campo list=’..’ devemos passar as moradas que se pretende
eliminar. Por exemplo, para eliminar a morada 2 o campo list=’..’ deverá ser
list=’2’. Para eliminar todas as moradas extra, o campo list deverá ser
list=’All’.

Permite eliminar os registos de contactos associados a um terceiro. No caso
de o campo list conter list=’1.2’, significa que o contacto numero 2 do tipo
de contacto 1 será eliminado. Se apenas se colocar list=’1’, então serão
eliminados todos os contactos do tipo 1. Tal como noutros serviços o ‘;’ e o
‘:’ servem para passar um intervalo de registos em que será aplicada a
mesma operação a todos, neste caso a eliminação de registos.
<Entity id='xx' | EntityID='T:xx.yy'>

<MoreInfo ... />

(^)
(^)

Permite eliminar os registos de fichas adicionais associadas ao terceiro.
Deverá ser enviado no campo list os Auto incrementos das fichas adicionais a
eliminar. Se quisermos eliminar mais do que uma ficha adicional devemos
enviar uma lista de Auto incrementos de fichas adicionais a eliminar,
separados por ‘;’.

43. TerFch/UpdSug

Permite inserir um pedido de alteração a um registo de um terceiro. Este pedido será
entendido pelo ARTSOFT como uma sugestão de alteração, portanto, não a executando de
imediato, e deixando essa alteração ao cuidado de um operador que irá validar essas
alterações, que, no caso de estarem corretas, serão aceites, senão poderão ser modificadas
antes de serem atualizadas ou mesmo descartadas.
O formato da string XML é idêntico ao do TerFch/Update, suportando apenas os nós
‘BaseAddr’ e ‘OtherAddr’, exceto que é obrigatório indicar no nó entity qual o ‘ID’ do
terceiro (nº de registo) ou o ‘entityID’ a que as sugestões se referem.
Como apenas alguns campos são passiveis de receberem sugestões de alteração, o
protótipo do serviço indica a lista atualizada de campos aceites.

<Entity id=’xxx’>
<BaseAddr>
<!-- fields -->
</BaseAddr>
→

<OtherAddr>
<Rec ID='1'>
<!-- fields -->
</Rec>
<Rec ID='2'>
<!-- fields -->
</Rec>
</OtherAddr>
</Entity>

Outros serviços similares: ‘ GrhEmp/UpdSug ’ (pág. 74 ) e ‘
GrhInd/ UpdSug’ (pág. 77 ).

Serviços relativos a Eventos de Terceiros

44. CRMHdr/GetTable

Fornece uma lista de códigos de eventos, e os respetivos tempos de resposta.

(^)
(^)
Input:
event Nome do nó
codes
Lista/intervalo de códigos a obter, no
formato grupo.subgrupo (ex: 1.01:1.49) ou
grupo.grupo (ex: 3:5, que é uma abreviatura
de 3.00:5.99) ou apenas grupo (ex: 8, que é
uma abreviatura de 8.00 a 8.99).
Output:
Event Nome do nó enviado
nrRecs=’xx’ xx= Nº de nós presentes na lista que se segue
Code Nome do nó com a informação sobre um código de evento
id=’xx.yy’ Identificação numérica do código
limit=’xxx’ Tempo máximo, em minutos, de resposta do evento. Só presente se xxx>0.
delay=xxxM|H|D Tempo de espera em Minutos, Horas, Dias para que o evento comece a ser
atendido, e a partir do qual começa a ter efeito o tempo de resposta (limit).
Só presente se xxx>0.
Exemplo:

45. CRMHdr/GetQualif

Fornece uma lista de códigos de qualificadores, e os respetivos nomes de cada um
deles.
Input:

<event codes="2:2.59;3:7;8;9.11:9.19" retid='s' status='S'/>

<event nrRecs="6">
<code id="2.01">Evento A</code>
<code id="2.02" limit="240">Evento B</code>
<code id="2.03" limit="480">Evento C</code>
<code id="2.04" limit="720">Evento D</code>
<code id="2.05" limit="960" delay="2H">Evento E</code>
<code id="2.06" delay="7D">Evento F</code>
</event>

<root qualif=x:y;z;a:b retid='s' status='S'/>

(^)
(^)
root Nome do nó
qualif Lista / intervalo de códigos a obter, (ex: 1:2).
Output:
root (^) Nome do nó enviado
nrRecs=’xx’ (^) xx= Nº de nós presentes na lista que se segue
qualif (^) Nome do nó com a informação sobre um código de qualificador
id=’x’ (^) Identificação da tabela de qualificadores
name =’nome_Qualificador’ (^) Nome da tabela de qualificadores pedida
code=’xx.yy’ (^) Código do elemento da tabela de qualificadores respetiva.
Exemplo de output:

46. CRMHdr/Insert

Insere um novo evento.
Input:

event Nome do nó (não é obrigatório que tenha este nome, mas é recomendado)
entityID=’nn’
ID=’xx’
contact=’xx.yy’

Informação sobre o terceiro a que respeita o evento. Para mais detalhes, ver
informações sobre parâmetros gerais dos serviços WEB.

Peer=’peer_name’ Identificação do utilizador para quem é dirigido o evento. Se não for definido o evento
é enviado para o grupo de atendimento parametrizado na configuração do evento (No
ARTSOFT).

<root nrRecs='4'>
<qualif id='90' name='Versões'>
<rec code='90.01'>Versão 7.50</rec>
<rec code='90.02'>Versão 7.52</rec>
<rec code='90.03'>Versão 7.53</rec>
</qualif>
</root>

<event entityID="C:1" ID="2" contact="1.1" [peer='peer_name' ToUser='s|n'] eventlist='1:6'
code="2.99" class='1.01' startTime='2009- 12 - 31T12:30' tpInput='WEB' tpOutput='WEB'
retid='s' status='S'>
<subject>Evento de teste das classes XML de eventos</subject>
<message>Este evento serve apenas para teste destas classes</message>
<Qualif Q1='1.1' Q2='2.2' Q8='8.8' />
</event>

(^)
(^)
Para enviar para o utilizador aqui definido tem que se colocar o campo ToUser=’s’
senão é assumido o valor por defeito, que é ‘n’ (false), e o evento é enviado para o
grupo de atendimento.
ToUser=’s|n’ Indicação se é ou não para enviar diretamente para um utilizador, definido
previamente no campo peer=’peer_name’. Por defeito assume o valor ‘n’.
code=’xx.xx' Código de evento. Pode ser obtido por ‘EvtGetTbl’.
class=’xx.xx' Classificação do evento.
startTime='2009- 12 -
31T12:30'
Data em deve ser registado o inicio do evento. Por omissão, será assumida a data de
registo do evento (data de chegada do evento ao servidor de WEB services).
tpInput=’xxx’
Meio em que foi recebido o evento. Escolher um elemento da seguinte lista: “phone;
fax; mail; email; web; pers”. ‘pers’ deve ser usado para identificação de pedidos feitos
pessoalmente.
tpOutput=’xxx’ Idêntico ao anterior, mas identificando o meio usado para a resposta.
subject O valor deste nó deve conter o assunto.
message O valor deste nó deve conter a mensagem ou pedido do terceiro.
qualif Este nó deve conter os atributos de qualificação inicial do pedido, se existirem. Cada
qualificador é identificado pelo nome “Q1..Q8’, e conter um valor ‘xx.yy’.
Output:
event Nome do nó enviado
id=’xx’ Nº do evento inserido (só se foi pedido retid='S')
TLimit=’xxx’ Se foi definido um tempo limite para término de execução do evento, este atributo
informa a data e hora do término.
rc=’xx’ Código de erro ocorrido

47. CRMHdr/Update

Atualiza um evento já existente.
Input:

event Nome do nó (não é obrigatório que tenha este nome, mas é recomendado)
eventID=’nn’ Evento que vai ser atualizado, tem que existir.

<event rc="InvalidTercID" />
<event ID="12345" TLimit="2009- 04 - 06T00:09:04"/>

<event eventID='xxx' contact='x.y' class='x.yy'
[ tpInput='phone|fax|mail|email|web|pers']
[tpOutput='phone|fax|mail|email|web|pers']
<subject>subject updated text</subject>
<message>message text</message>
</event>

(^)
(^)
contact=’x.y' Contacto de terceiro no caso de se querer alterar o mesmo.
class=’xx.xx' Classificação do evento, caso se queira alterar a classificação do mesmo.
tpInput=’xxx’
Meio em que foi recebido o evento (se se quer atualizar ou alterar). Escolher um
elemento da seguinte lista: “phone; fax; mail; email; web; pers”. ‘pers’ deve ser usado
para identificação de pedidos feitos pessoalmente.
tpOutput=’xxx’ Idêntico ao anterior, mas identificando o meio usado para a resposta.
subject O valor deste nó deve conter o assunto que se pretende atualizar.
message O valor deste nó deve conter a mensagem ou pedido do terceiro que se pretende
atualizar.
Output:
event (^) Nome do nó enviado
id=’xx’ (^) Nº do evento alterado.
rc=’xx’ (^) Código de erro ocorrido.

48. CRMHdr/Delete

Permite eliminar um evento.
Input:

event (^) Nome do nó enviado
eventID=’xx’ (^) Nº do evento a eliminar. Se o evento já tiver tratamento, a operação
‘delete’ será registada como ‘update’, a não ser que se envie
forceDel=’s’.
forceDel='s' (^) Se forceDel=’s’ então força a eliminação do evento.
Output:
event (^) Nome do nó enviado
id=’xx’ (^) Nº do evento eliminado

// caso em que o evento já tinha tratamento.

(^)
(^)
action="U" (^) Operação que foi executada, ‘U’ update e ‘D’ delete.
rc=’xx’ (^) Código de erro ocorrido

49. CRMHdr/Status

Permite obter uma lista de eventos de determinado terceiro. Recebe como
parâmetro um XML formatado da seguinte forma:
Input:

Parâmetros:
event Nome do nó
entityID=’nn’
Informação sobre o terceiro a que respeita o evento. Para mais
detalhes, ver informações sobre parâmetros gerais dos serviços WEB.
contact=’ww:xx' Contacto de terceiro pretendido.

evtList=’ww:xx;yy:zz'

Lista de eventos pretendidos. Por omissão, todos.
Esta lista pode ser declarada a partir da ficha do contacto, colocando
‘[EVT=’xx.yy;xx.zz]’ no respectivo campo ‘Observações’, permitindo
assim definir por contacto, quais os tipos de eventos que costuma
ver, ou lhe são permitidos.
code=’xx.xx' Código de evento pretendido. Se existir evtList, code tem que ser um dos elementos dessa lista, senão é assinalado ‘NotAllowedEvt’;

table=’S|N' (^) Pretende-se que seja devolvida a tabela com os eventos usados.
detail=’F|P|A’ Se ‘F’ inclui apenas eventos já finalizados, se ‘P’ inclui apenas eventos pendentes, se ‘A’ inclui todos os eventos.
after='2009- 12 - 31T12:30'
Data em deve ser registado o inicio do evento. Por omissão, será
assumida a data de registo do evento (data de chegada do evento ao
servidor de WEB services).
maxrec=’xxx’ Indica que devem ser devolvidos apenas ‘xxx’ registos. Se não for especificado, assume por omissão 100.

(^)
(^)
start=’xx’ Apenas a partir do evento com ID=’xx’ (para continuação de query anterior que excedeu ‘maxrec’ registos.
Output:
event Nome do nó enviado
Table Nome do nó que contém a tabela de designações dos eventos
code id=’xx’ Código de Evento
records Nome do nó que contém a lista de eventos pedidos
evt id=’xxx’ Id do evento
code=’xx’ Código do evento
status=’x’ Estado do evento (pendente, finalizado)
date=’xx’ Data e hora de inicio do evento
limit=’xx’ Data limite de resolução do evento
subj=’xx’ Texto do assunto (se existir)
text=’xx’ Texto (se existir)
updates=’xx’ (^) Textos de alteração ao pedido original (se existir)
answer=’xx’ Resposta ao terceiro (se existir)
Exemplo:
 código de erro
ou
 Lista válida

Pedido de PropostaPedido de assistênciaReclamação

Proposta de Software Assistência para configuração de contas email Insatisfação total

(^)
(^)

50. CRMHdr/GetImage

Fornece a(s) imagem(s) associadas a um evento. O formato de chamada e retorno
são iguais aos de
DocFch/ GetImag, exceto a identificação do evento só pode ser feita por ‘id=’xx’,
uma vez que a opção ‘nrDoc=x/y’ aqui não faz sentido.

51. CRMHdr/SetImage

Permite associar imagem(s) a um evento. O formato de chamada e retorno são iguais
aos de DocFch/SetImag , exceto a identificação do evento só pode ser feita por ‘id=’xx’,
uma vez que a opção ‘nrDoc=x/y’ aqui não faz sentido.

Serviços relativos a Contabilidade e Contas Correntes

Estes serviços estão subdivididos em duas categorias: inserção / atualização da base
de dados e extratos especializados, com um conjunto de informação frequentemente
utilizada, que, se for pretendida de outra forma, ou com outros dados, poderá sempre ser
obtida via ‘Query’.

52. CtaLan/CurrAcc

Elabora um extrato de conta de todos os movimentos das contas solicitadas.
Input:
Parâmetro Descrição
accounts='xxx;yyy;zzz' Lista de contas ou lista de intervalos de contas (obrigatório)
code='A1:A999;B1:B999' Lista de tipos de documento ou lista de intervalos de tipos de documento
nrdoc='xxx' Nº do documento
all='s' True=Todos os lançamentos, False=Apenas documentos com saldo em aberto
after='date' Lançamentos com data igual ou superior a ‘date’
before='date' Lançamentos com data igual ou inferior a ‘date’
defs='s' Enviar tabela de definições de códigos
maxrecs='xx' Enviar no máximo, ‘xx’ registos. Este limite não pode ser superior a 100.

Exemplo:

(^)
(^)

Output:

N/Nota de DébitoAceite Letras BPIAceite Letras BCP

commentários

53. CtaLan/OpenDoc

Elabora um extrato de conta com os movimentos de documentos não saldados (ainda
em aberto).
Output:

O resultado deste extrato é idêntico ao do anterior, exceto que o nome ‘CurrAcc’
passa agora para ‘OpenDoc’.

54. CtaLan/DocType

Elabora um extrato de conta com os movimentos de documentos do(s) tipo(s)
indicados.

<OpenDoc>
...
</OpenDoc>

(^)
(^)
Output:

55. CtaLan/DocRecv

Elabora um extrato de conta com os movimentos de documentos do(s) tipo(s)
indicados, e respetivos pagamentos (a fornecedores) / recebimentos (de clientes).
Output:

56. CtaLan/RecvDoc

Elabora um extrato de conta com os movimentos de pagamentos de documentos do(s)
tipo(s) indicados, e os respetivos regularizados, ou seja, é o inverso do extrato ‘DocRecv’.
Output:

Descrição dos nós e atributos de output de todos os tipos de extratos:
Nó / Atributo Descrição
CurrAcc Nome do extrato
Table Solicitado por defs=’s’, contém o código e respetiva descrição

<DocType>
...
</DocType>

<DocRecv>
<Records NrAccs="1" TtRecs="2">
<Account Nr="211114777" NrRecs="2">
<Rec Code="A001" Docum="12153" Date="2008- 11 - 13" Value="800.75" Balance="400.75" Refer="V001/12153">
<OnAcc Code="B032" Docum="59" Date="2009- 01 - 28" Value="575.45" Remitt="200" Refer="TB"/>
<OnAcc Code="B032" Docum="91" Date="2009- 02 - 28" Value="255.15" Remitt="200" Refer="TB"/>
</Rec>
<Rec Code="A030" Docum="97" Date="2009- 02 - 27" Taxes="23.2" Value="13.2" Balance="9.2" Refer="V012/7"/>
</Account>
</Records>
</DocRecv>

<DocRecv>
...
</DocRecv>

(^)
(^)
Records Nó que contém a lista de contas
ttRecs /
nrRecs
Nº total de movimentos presentes de todas as contas (‘ttRecs’), ou só numa
conta (‘nrRecs’). Se seguido de ‘+’ o extrato está incompleto, porque
ultrapassa o nº de registos definidos por ‘maxrecs=xx’.
Account Nó que conterá o extrato da conta ‘nr’, com o total de ‘nrRecs’ movimentos
Rec Nó que representa um movimento de uma conta.
code Código deste movimento
docum Nº do documento
date Data-valor do movimento
dueDate (^) Data de vencimento do movimento, se existir
value Valor do movimento
balance Valor em aberto do movimento, ou o que ainda falta pagar / receber
refer Documento de referência, se existir
pend O movimento ainda está pendente de aprovação
currency Moeda em que foi feito o movimento
taxes Valor de impostos incluídos no valor total do movimento
delta Desconto deduzido ou agravamento incluído no total do movimento
remitts Num lançamento de débitos de clientes / créditos de fornecedores informa que existem ‘n’ pagamentos associados, que irão ser descritos a seguir
remitt Nos regularização do movimentoextratos^ ‘LanDocRecv’ e ‘LanRecvDoc’, informa qual o valor usado para
dbAnt Débito anterior á data do extrato
crAnt Crédito anterior á data do extrato
onAcc Nó que representa uma regularização do documento ao qual está dependente (On Account, por conta)

57. CtaLan/GetImage

Fornece a(s) imagem(s) associadas a um documento de C/Correntes. O formato de
chamada e retorno são iguais aos de
DocFch/ GetImag.

58. CtaLan/SetImage

(^)
(^)
Permite associar imagem(s) a um documento de C/Correntes. O formato de chamada
e retorno são iguais aos de DocFch/SetImag.

59. CtaLan/LanDelete

Permite eliminar lançamentos de documentos contabilísticos.
Para eliminar todos os lançamentos de um documento:
<docum DocID='xxx/NrDoc' [retID='Y|N'] [status='Y|N'] [trans='Y|N']/>

docum (^) Nome (pode usar-se qualquer um) do nó root.
DocID='xxx/yyyy' (^) Qual o tipo do documento (xxx) e qual o documento (yyyy)
a eliminar.
[retID='Y|N'][status='Y|N'] [trans='Y|N'] (^) Descrito em
Serviço ArtXMLServer
Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais)

(^)
(^)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

60. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos
a preencher estão documentados na consola
Artexecmanager.

Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.
...
61. ArtXmlServer multiempresa

(^)
(^)
Este serviço é muito específico, e
normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o
serviço passa a ter um comportamento diferente,
adaptando-se às exigências da função.
Um software cliente que se conecte a um
servidor multiempresa passa a ter que indicar em
cada ligação qual a base de dados pretendida e a
respetiva data de trabalho, adicionando um
cabeçalho ‘DBName=Base De dados’, e
‘workDate=AAAA-MM-DD’, sem os quais os pedidos
passam a ser rejeitados com o status ‘ 406 - Not
Acceptable’ e uma mensagem ‘missing DBName’ ou
‘missing workDate’.
Quando o servidor recebe um pedido, verifica
a ‘base de dados’ atual é a pedida. Se sim, está tudo
OK e processa o pedido. Senão, vai tentar comutar
para a base de dados pedida. Mas isso só pode
acontecer se não existir mais nenhuma ligação em
curso, pois essa ainda está a usar a atual base de
dados. Caso contrário, informa o cliente que o
pedido, de momento não pode ser satisfeito,
devolvendo o status ‘423-media locked’ e uma
pequena mensagem. Quando isso acontecer, o
cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços
(até ao máximo dos que estiverem instalados).
Como este serviço pode comutar de base de
dados durante o seu funcionamento, não pode ter
nenhum outro serviço instalado no mesmo servidor
ArtExec, pois a comutação poderá ocorrer a qualquer
momento, para além de tornar imprevisível qual a

(^)
(^)
base de dados sob a qual esse outro serviço iria
efetuar o seu trabalho. Desta forma, quando o
servidor ArtXMLServer estiver configurado como
‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor e
recusa-se a arrancar se algum serviço já estiver
instalado no mesmo ArtExec.

62. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.

(^)
(^)
Parâmetros da consola:
▪ Server – ‘IP:porta’ ou
‘nome_do_servidor:porta’ do servidor
ArtXMLServer.
▪ Login – Normal, Debug, Teste, MultiDB e
Plugin:
 Normal – Ligação ‘normal’ a um
servidor ArtXMLServer exclusivo de
uma empresa;
 Debug –
 Teste – Usados para testar o cálculo
do ‘digest’ para quem não possa usar
um dos conectores disponibilizados
(.NET, PHP, C/C++, Android).
 MultiDB - Ligação ‘normal’ a um
servidor ArtXMLServer multiempresa.
Este modo tem especificidades que
serão tratadas mais adiante;
 Plugin – usar apenas quando a
documentação do ‘plugin’ específico
de determinada empresa ou setor o
indicarem. Como este modo utiliza
algoritmos diferentes do standard, o
uso indevido deste modo vai ser
banido e registado no ficheiro de log
como ‘tentativa de invasão’.
▪ Hash – O algoritmo a usar para calcular o
‘digest’ que o servidor espera. Este
parâmetro deve estar conforme o parâmetro

(^)
(^)
‘digest’ do servidor. Se isso não se verificar,
não é possível efetuar login, ficando
registado no ficheiro de log como ‘tentativa
de invasão’.
▪ User – O nome do utilizador, um dos nomes
configurados no servidor em ‘UsersList’.
▪ Palavra-passe – a ‘password’ (não
encriptada) colocada a seguir ao ‘nome’
configurado no servidor em ‘UsersList’.
▪ Base de dados – (apenas se ‘Login=MultiDB’)

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das
respostas. Como este parâmetro passa a ser
sempre enviado em todas as ligações, faz
com que seja ignorado o parâmetro de igual
nome configurado no servidor.
▪ Compressão – nenhuma, ‘gZip’ ou ‘deflat’ –
permite indicar o algoritmo de compressão a
usar nos pedidos ao servidor e que este usa
também para as respostas. Se forem usados
canais de comunicação exteriores ou em que
a largura de banda seja reduzida, deve usar-
se sempre compressão, reduzindo
drasticamente o tamanho das mensagens e
aumentando muito a velocidade com que o
cliente obtém os dados, à custa de uma
penalização de carga no servidor. O formato

(^)
(^)
‘gZip’ contém um cabeçalho que informa
dados adicionais sobre o texto compactado,
pelo que, se não existir outro motivo, deve
ser este o formato a escolher.
▪ Config – Permite selecionar um ficheiro de
configuração alternativo, permitindo assim
ter vários ficheiros de configuração e
selecionar um deles para uso no momento.
▪ Segurança – Se esta opção estiver ligada, a
transferência de dados é efetuada de forma
encriptada, mantendo a confidencialidade
dos dados (os dados abrangidos pelo R.G.P.D.
só podem circular nesta forma).
▪ Params – Esta opção permite especificar os
parâmetros necessários aos serviços de teste
(performance e eco), permitindo definir o nº
de envios a efetuar. A descrição desses
serviços descreve o uso deste parâmetro.
▪ TimeOut – permite definir o tempo máximo
que a consola espera pela resposta do
servidor, com um mínimo de 5 segundos e por
omissão 15 segundos. Para pedidos com
respostas mais ‘volumosas’ poderá ser
necessário aumentar este tempo.
O botão ‘ Lista de serviços ’ é um atalho para
o serviço ‘ArtDB/_WSList’ e permite visualizar todos
os serviços disponibilizados pelo servidor
ArtXMLServer. Se determinado serviço não estiver
disponível nesta lista, significa que a respetiva
biblioteca ARTSOFT que o executa não foi
configurada ou carregada.

(^)
(^)
A caixa de seleção abaixo desse botão
apresenta a mesma lista de serviços e permite
selecionar um deles. Estando um dos serviços
selecionados, ao carregar no botão, este funciona
como um atalho para o serviço ‘ArtDB/_WSList’, com
os parâmetros , que irá apresentar um texto com os
parâmetros de input , output e eventuais
comentários específicos desse serviço.
O botão ‘ Lista de funções ’ é um atalho para
o serviço ‘ArtDB/_fnList’, e apresenta uma lista de
funções disponibilizadas pelas bibliotecas instaladas.
Essas funções podem ser usadas em fórmulas que os
serviços possam disponibilizar, para fórmulas de
mapas, relatórios e outros no próprio ARTSOFT bem
como para uso no conector ‘Excel’.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de funções e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_fnList’ com os parâmetros e irá apresentar
um texto com os parâmetros de input dessa função
e o respetivo tipo de retorno (N-numérico,
A=alfanum ou ‘|’=Array com elementos separados
por ‘|’).
O botão ‘ Lista de tabelas ’ é um atalho para
o serviço ‘ArtDB/_DbTables’, e apresenta uma lista
de tabelas disponibilizadas pelas bibliotecas
instaladas.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de tabelas e permite
selecionar uma delas. Estando uma delas

(^)
(^)
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_TblDesc’ com os parâmetros e irá apresentar uma
seção ‘’ com a lista dos indexes utilizáveis do
ficheiro/tabela, e uma seção ‘’ com a lista
das colunas dessa tabela, contendo o nome da
coluna, o tipo, tamanho e a descrição da mesma.
Esta lista permite fornecer os dados necessários aos
serviços que permitem configurar a lista de
colunas/campos que fornecem, bem como os dados
necessários para efetuar queries ‘ad-hoc’.
A opção lateral ‘Tipo’ permite selecionar que
tipos de campos se pretendem - todos, apenas os
‘reportáveis’ ou apenas aqueles que permitem
‘inputs’, e se ordenados ou não.
As linhas ‘Comandos/Ficheiros XML’
permitem definir os parâmetros em formato XML
simples (que caiba todo numa linha) ou complexos,
através de um ficheiro XML que será lido para envio.
Se a linha começar com ‘<’ é interpretada como um
XML simples, caso contrário, como um ficheiro a ler.
O botão ‘...’ a seguir ao campo permite navegar no
sistema para localizar o ficheiro a colocar na linha.
Se este já estiver configurado, carregando em ‘CTRL’
e clicando no mesmo botão, chama o editor de texto
para editar o respetivo ficheiro. O editor por omissão
é o ‘notepad’, mas pode ser configurado outro,
editando o ficheiro de configuração (por omissão o
‘XMLClient.ini’) e colocando o caminho e nome do
editor, como no exemplo:
EDITOR="C:\Program Files
(x86)\Notepad++\notepad++.exe"

(^)
(^)
As linhas ‘Serviço’ permitem definir os nomes
dos serviços a efetuar, podendo os mesmos serem
selecionados na respetiva lista de seleção. Porém,
estes só serão enviados ao servidor se a respetiva
‘check’ estiver ligada. Quando várias linhas
estiverem selecionadas, os pedidos serão enviados
em lote e pela mesma ordem.
O botão ‘Performance’ necessita que a caixa
‘Params’ contenha um valor, que será utilizado para
indicar o nº de pedidos que irá efetuar ao servidor.
Estes pedidos têm tamanhos aleatórios até 1
megabyte, são recebidos pelo servidor e
simplesmente descartados, não havendo assim
qualquer tipo de processamento dos mesmos. Desta
forma este teste permite medir a performance do
canal de comunicações no sentido da receção de
pedidos (sendo a resposta muito curta, a velocidade
de resposta passa a ser estatisticamente
irrelevante). Por fim, é apresentada a lista de
mensagens enviadas e os respetivos tempos, e no
fim, um resumo estatístico: ‘tempo médio: xxx.x ms;
tempo total: xxx.xxx seg; MB: yyy; MB/s: zzzz.zzz’,
em que o tempo médio é obtido pela média simples
dos tempos de cada pedido, o tempo total obtido
pela soma do tempo gasto por cada pedido, ‘MB’ é o
somatório dos Mega Bytes de dados enviados e ‘MB/s’
a média de Mega Bytes por segundo de todos os
pedidos, ou seja, a largura de banda do momento.
O botão ‘Eco’ necessita que a caixa ‘Params’
contenha um valor, que será utilizado para indicar o
nº de pedidos que irá efetuar ao servidor. Este
serviço tem um funcionamento totalmente idêntico
ao anterior, com a especialização de enviar de volta

(^)
(^)
ao cliente o conteúdo recebido. Desta forma, o
tempo de resposta já é totalmente relevante,
permitindo medir a largura de banda de envio e
receção.
Poderá se muito útil efetuar estes testes e
guardar os respetivos resultados na altura da
instalação de um servidor ArtXMLServer, para os
comparar posteriormente em caso de degradação da
performance do serviço, permitindo aferir se essa
degradação se deve ou não à perda de largura de
banda do canal de comunicações.
Execução de serviços a partir do
ARTSOFT
É possível executar a maior parte dos serviços
para testes e inclusivamente obter os protótipos
associados.
‘Empresa -> Funções de supervisão ->
Configurações’:

(^)
(^)
Tem também acesso às listas de funções da
API ARTSOFT que são usadas em XML e no Excel, e
também a lista de funções internas que podem ser
usadas.

63. Lista dos serviços disponíveis.

Exemplo de protótipo.

(^)
(^)

**64. Lista de funções ARTSOFT

Lista de funções internas**

(^)
(^)
Parâmetros gerais dos Serviços WEB
Para eliminar todos os lançamentos de vários documentos:
<docum TpDoc=’xxx’ NrDocI='y' NrDocF='z' [retID='Y|N'] [status='Y|N'] [trans='Y|N']>
docum Nome (pode usar-se qualquer um) do nó root.
TpDoc=’xxx’ Qual o tipo do documento (xxx) do qual se pretende eliminar vários documentos.
NrDocI='y'
Número do documento inicial (y) a ser eliminado. Por
exemplo se pretendermos apagar do documento 2 ao 10,
y será 2 e z será 10, sendo que serão eliminados todos os
documentos nesse intervalo.
NrDocF='z' Número do documento final (z) a ser eliminado.
[retID='Y|N'] [status='Y|N'] [trans='Y|N'] Descrito em

(^)
(^)
Serviço ArtXMLServer
Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

66. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos
a preencher estão documentados na consola
Artexecmanager.

Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.

(^)
(^)
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.
...
67. ArtXmlServer multiempresa

Este serviço é muito específico, e
normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o
serviço passa a ter um comportamento diferente,
adaptando-se às exigências da função.
Um software cliente que se conecte a um
servidor multiempresa passa a ter que indicar em
cada ligação qual a base de dados pretendida e a
respetiva data de trabalho, adicionando um
cabeçalho ‘DBName=Base De dados’, e
‘workDate=AAAA-MM-DD’, sem os quais os pedidos
passam a ser rejeitados com o status ‘ 406 - Not
Acceptable’ e uma mensagem ‘missing DBName’ ou
‘missing workDate’.

(^)
(^)
Quando o servidor recebe um pedido, verifica
a ‘base de dados’ atual é a pedida. Se sim, está tudo
OK e processa o pedido. Senão, vai tentar comutar
para a base de dados pedida. Mas isso só pode
acontecer se não existir mais nenhuma ligação em
curso, pois essa ainda está a usar a atual base de
dados. Caso contrário, informa o cliente que o
pedido, de momento não pode ser satisfeito,
devolvendo o status ‘423-media locked’ e uma
pequena mensagem. Quando isso acontecer, o
cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços
(até ao máximo dos que estiverem instalados).
Como este serviço pode comutar de base de
dados durante o seu funcionamento, não pode ter
nenhum outro serviço instalado no mesmo servidor
ArtExec, pois a comutação poderá ocorrer a qualquer
momento, para além de tornar imprevisível qual a
base de dados sob a qual esse outro serviço iria
efetuar o seu trabalho. Desta forma, quando o
servidor ArtXMLServer estiver configurado como
‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor e
recusa-se a arrancar se algum serviço já estiver
instalado no mesmo ArtExec.

68. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como

(^)
(^)
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.
Parâmetros da consola:
▪ Server – ‘IP:porta’ ou
‘nome_do_servidor:porta’ do servidor
ArtXMLServer.
▪ Login – Normal, Debug, Teste, MultiDB e
Plugin:
 Normal – Ligação ‘normal’ a um
servidor ArtXMLServer exclusivo de
uma empresa;
 Debug –

(^)
(^)
 Teste – Usados para testar o cálculo
do ‘digest’ para quem não possa usar
um dos conectores disponibilizados
(.NET, PHP, C/C++, Android).
 MultiDB - Ligação ‘normal’ a um
servidor ArtXMLServer multiempresa.
Este modo tem especificidades que
serão tratadas mais adiante;
 Plugin – usar apenas quando a
documentação do ‘plugin’ específico
de determinada empresa ou setor o
indicarem. Como este modo utiliza
algoritmos diferentes do standard, o
uso indevido deste modo vai ser
banido e registado no ficheiro de log
como ‘tentativa de invasão’.
▪ Hash – O algoritmo a usar para calcular o
‘digest’ que o servidor espera. Este
parâmetro deve estar conforme o parâmetro
‘digest’ do servidor. Se isso não se verificar,
não é possível efetuar login, ficando
registado no ficheiro de log como ‘tentativa
de invasão’.
▪ User – O nome do utilizador, um dos nomes
configurados no servidor em ‘UsersList’.
▪ Palavra-passe – a ‘password’ (não
encriptada) colocada a seguir ao ‘nome’
configurado no servidor em ‘UsersList’.
▪ Base de dados – (apenas se ‘Login=MultiDB’)

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.

(^)
(^)
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das
respostas. Como este parâmetro passa a ser
sempre enviado em todas as ligações, faz
com que seja ignorado o parâmetro de igual
nome configurado no servidor.
▪ Compressão – nenhuma, ‘gZip’ ou ‘deflat’ –
permite indicar o algoritmo de compressão a
usar nos pedidos ao servidor e que este usa
também para as respostas. Se forem usados
canais de comunicação exteriores ou em que
a largura de banda seja reduzida, deve usar-
se sempre compressão, reduzindo
drasticamente o tamanho das mensagens e
aumentando muito a velocidade com que o
cliente obtém os dados, à custa de uma
penalização de carga no servidor. O formato
‘gZip’ contém um cabeçalho que informa
dados adicionais sobre o texto compactado,
pelo que, se não existir outro motivo, deve
ser este o formato a escolher.
▪ Config – Permite selecionar um ficheiro de
configuração alternativo, permitindo assim
ter vários ficheiros de configuração e
selecionar um deles para uso no momento.
▪ Segurança – Se esta opção estiver ligada, a
transferência de dados é efetuada de forma
encriptada, mantendo a confidencialidade
dos dados (os dados abrangidos pelo R.G.P.D.
só podem circular nesta forma).

(^)
(^)
▪ Params – Esta opção permite especificar os
parâmetros necessários aos serviços de teste
(performance e eco), permitindo definir o nº
de envios a efetuar. A descrição desses
serviços descreve o uso deste parâmetro.
▪ TimeOut – permite definir o tempo máximo
que a consola espera pela resposta do
servidor, com um mínimo de 5 segundos e por
omissão 15 segundos. Para pedidos com
respostas mais ‘volumosas’ poderá ser
necessário aumentar este tempo.
O botão ‘ Lista de serviços ’ é um atalho para
o serviço ‘ArtDB/_WSList’ e permite visualizar todos
os serviços disponibilizados pelo servidor
ArtXMLServer. Se determinado serviço não estiver
disponível nesta lista, significa que a respetiva
biblioteca ARTSOFT que o executa não foi
configurada ou carregada.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de serviços e permite
selecionar um deles. Estando um dos serviços
selecionados, ao carregar no botão, este funciona
como um atalho para o serviço ‘ArtDB/_WSList’, com
os parâmetros , que irá apresentar um texto com os
parâmetros de input , output e eventuais
comentários específicos desse serviço.
O botão ‘ Lista de funções ’ é um atalho para
o serviço ‘ArtDB/_fnList’, e apresenta uma lista de
funções disponibilizadas pelas bibliotecas instaladas.
Essas funções podem ser usadas em fórmulas que os
serviços possam disponibilizar, para fórmulas de

(^)
(^)
mapas, relatórios e outros no próprio ARTSOFT bem
como para uso no conector ‘Excel’.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de funções e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_fnList’ com os parâmetros e irá apresentar
um texto com os parâmetros de input dessa função
e o respetivo tipo de retorno (N-numérico,
A=alfanum ou ‘|’=Array com elementos separados
por ‘|’).
O botão ‘ Lista de tabelas ’ é um atalho para
o serviço ‘ArtDB/_DbTables’, e apresenta uma lista
de tabelas disponibilizadas pelas bibliotecas
instaladas.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de tabelas e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_TblDesc’ com os parâmetros e irá apresentar uma
seção ‘’ com a lista dos indexes utilizáveis do
ficheiro/tabela, e uma seção ‘’ com a lista
das colunas dessa tabela, contendo o nome da
coluna, o tipo, tamanho e a descrição da mesma.
Esta lista permite fornecer os dados necessários aos
serviços que permitem configurar a lista de
colunas/campos que fornecem, bem como os dados
necessários para efetuar queries ‘ad-hoc’.
A opção lateral ‘Tipo’ permite selecionar que
tipos de campos se pretendem - todos, apenas os

(^)
(^)
‘reportáveis’ ou apenas aqueles que permitem
‘inputs’, e se ordenados ou não.
As linhas ‘Comandos/Ficheiros XML’
permitem definir os parâmetros em formato XML
simples (que caiba todo numa linha) ou complexos,
através de um ficheiro XML que será lido para envio.
Se a linha começar com ‘<’ é interpretada como um
XML simples, caso contrário, como um ficheiro a ler.
O botão ‘...’ a seguir ao campo permite navegar no
sistema para localizar o ficheiro a colocar na linha.
Se este já estiver configurado, carregando em ‘CTRL’
e clicando no mesmo botão, chama o editor de texto
para editar o respetivo ficheiro. O editor por omissão
é o ‘notepad’, mas pode ser configurado outro,
editando o ficheiro de configuração (por omissão o
‘XMLClient.ini’) e colocando o caminho e nome do
editor, como no exemplo:
EDITOR="C:\Program Files
(x86)\Notepad++\notepad++.exe"
As linhas ‘Serviço’ permitem definir os nomes
dos serviços a efetuar, podendo os mesmos serem
selecionados na respetiva lista de seleção. Porém,
estes só serão enviados ao servidor se a respetiva
‘check’ estiver ligada. Quando várias linhas
estiverem selecionadas, os pedidos serão enviados
em lote e pela mesma ordem.
O botão ‘Performance’ necessita que a caixa
‘Params’ contenha um valor, que será utilizado para
indicar o nº de pedidos que irá efetuar ao servidor.
Estes pedidos têm tamanhos aleatórios até 1
megabyte, são recebidos pelo servidor e
simplesmente descartados, não havendo assim

(^)
(^)
qualquer tipo de processamento dos mesmos. Desta
forma este teste permite medir a performance do
canal de comunicações no sentido da receção de
pedidos (sendo a resposta muito curta, a velocidade
de resposta passa a ser estatisticamente
irrelevante). Por fim, é apresentada a lista de
mensagens enviadas e os respetivos tempos, e no
fim, um resumo estatístico: ‘tempo médio: xxx.x ms;
tempo total: xxx.xxx seg; MB: yyy; MB/s: zzzz.zzz’,
em que o tempo médio é obtido pela média simples
dos tempos de cada pedido, o tempo total obtido
pela soma do tempo gasto por cada pedido, ‘MB’ é o
somatório dos Mega Bytes de dados enviados e ‘MB/s’
a média de Mega Bytes por segundo de todos os
pedidos, ou seja, a largura de banda do momento.
O botão ‘Eco’ necessita que a caixa ‘Params’
contenha um valor, que será utilizado para indicar o
nº de pedidos que irá efetuar ao servidor. Este
serviço tem um funcionamento totalmente idêntico
ao anterior, com a especialização de enviar de volta
ao cliente o conteúdo recebido. Desta forma, o
tempo de resposta já é totalmente relevante,
permitindo medir a largura de banda de envio e
receção.
Poderá se muito útil efetuar estes testes e
guardar os respetivos resultados na altura da
instalação de um servidor ArtXMLServer, para os
comparar posteriormente em caso de degradação da
performance do serviço, permitindo aferir se essa
degradação se deve ou não à perda de largura de
banda do canal de comunicações.

(^)
(^)
Execução de serviços a partir do
ARTSOFT
É possível executar a maior parte dos serviços
para testes e inclusivamente obter os protótipos
associados.
‘Empresa -> Funções de supervisão ->
Configurações’:
Tem também acesso às listas de funções da
API ARTSOFT que são usadas em XML e no Excel, e
também a lista de funções internas que podem ser
usadas.

69. Lista dos serviços disponíveis.

(^)
(^)
Exemplo de protótipo.

70. Lista de funções ARTSOFT

(^)
(^)

71. Lista de funções internas

Parâmetros gerais dos Serviços WEB

(^)
(^)

72. CtaLan/LanUpdate

Permite inserir lançamentos contabilísticos, e eventuais registos associados, como
por exemplo contas da contabilidade.
Para inserir lançamentos contabilísticos e contas associadas (opção 1):

fields - os mesmos elementos da mensagem 'CtaFch/UpdateAccounts' -
fields -

<journal id='x.y' [trans='x']>
<docum [docID='tpDoc/nrDoc'] date='xxx' refdate='xx' [trans='x']>
fields -
fields -

<docum [id='rec_nr' | docID='tpDoc/nrDoc'] [trans='x']>
...

<journal id='x.y' [trans='x']>
...

message Nome (pode usar-se qualquer um) do nó root.
retID='Y|N' status='Y|N' trans='Y|N' Descrito em

Serviço ArtXMLServer

Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.

(^)
(^)
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

73. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos
a preencher estão documentados na consola
Artexecmanager.

Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

(^)
(^)

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.
...
74. ArtXmlServer multiempresa

Este serviço é muito específico, e
normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o
serviço passa a ter um comportamento diferente,
adaptando-se às exigências da função.
Um software cliente que se conecte a um
servidor multiempresa passa a ter que indicar em
cada ligação qual a base de dados pretendida e a
respetiva data de trabalho, adicionando um
cabeçalho ‘DBName=Base De dados’, e
‘workDate=AAAA-MM-DD’, sem os quais os pedidos
passam a ser rejeitados com o status ‘ 406 - Not
Acceptable’ e uma mensagem ‘missing DBName’ ou
‘missing workDate’.
Quando o servidor recebe um pedido, verifica
a ‘base de dados’ atual é a pedida. Se sim, está tudo
OK e processa o pedido. Senão, vai tentar comutar
para a base de dados pedida. Mas isso só pode
acontecer se não existir mais nenhuma ligação em
curso, pois essa ainda está a usar a atual base de
dados. Caso contrário, informa o cliente que o

(^)
(^)
pedido, de momento não pode ser satisfeito,
devolvendo o status ‘423-media locked’ e uma
pequena mensagem. Quando isso acontecer, o
cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços
(até ao máximo dos que estiverem instalados).
Como este serviço pode comutar de base de
dados durante o seu funcionamento, não pode ter
nenhum outro serviço instalado no mesmo servidor
ArtExec, pois a comutação poderá ocorrer a qualquer
momento, para além de tornar imprevisível qual a
base de dados sob a qual esse outro serviço iria
efetuar o seu trabalho. Desta forma, quando o
servidor ArtXMLServer estiver configurado como
‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor e
recusa-se a arrancar se algum serviço já estiver
instalado no mesmo ArtExec.

75. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.

(^)
(^)
 MultiDB - Ligação ‘normal’ a um
servidor ArtXMLServer multiempresa.
Este modo tem especificidades que
serão tratadas mais adiante;
 Plugin – usar apenas quando a
documentação do ‘plugin’ específico
de determinada empresa ou setor o
indicarem. Como este modo utiliza
algoritmos diferentes do standard, o
uso indevido deste modo vai ser
banido e registado no ficheiro de log
como ‘tentativa de invasão’.
▪ Hash – O algoritmo a usar para calcular o
‘digest’ que o servidor espera. Este
parâmetro deve estar conforme o parâmetro
‘digest’ do servidor. Se isso não se verificar,
não é possível efetuar login, ficando
registado no ficheiro de log como ‘tentativa
de invasão’.
▪ User – O nome do utilizador, um dos nomes
configurados no servidor em ‘UsersList’.
▪ Palavra-passe – a ‘password’ (não
encriptada) colocada a seguir ao ‘nome’
configurado no servidor em ‘UsersList’.
▪ Base de dados – (apenas se ‘Login=MultiDB’)

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das

(^)
(^)
respostas. Como este parâmetro passa a ser
sempre enviado em todas as ligações, faz
com que seja ignorado o parâmetro de igual
nome configurado no servidor.
▪ Compressão – nenhuma, ‘gZip’ ou ‘deflat’ –
permite indicar o algoritmo de compressão a
usar nos pedidos ao servidor e que este usa
também para as respostas. Se forem usados
canais de comunicação exteriores ou em que
a largura de banda seja reduzida, deve usar-
se sempre compressão, reduzindo
drasticamente o tamanho das mensagens e
aumentando muito a velocidade com que o
cliente obtém os dados, à custa de uma
penalização de carga no servidor. O formato
‘gZip’ contém um cabeçalho que informa
dados adicionais sobre o texto compactado,
pelo que, se não existir outro motivo, deve
ser este o formato a escolher.
▪ Config – Permite selecionar um ficheiro de
configuração alternativo, permitindo assim
ter vários ficheiros de configuração e
selecionar um deles para uso no momento.
▪ Segurança – Se esta opção estiver ligada, a
transferência de dados é efetuada de forma
encriptada, mantendo a confidencialidade
dos dados (os dados abrangidos pelo R.G.P.D.
só podem circular nesta forma).
▪ Params – Esta opção permite especificar os
parâmetros necessários aos serviços de teste
(performance e eco), permitindo definir o nº
de envios a efetuar. A descrição desses
serviços descreve o uso deste parâmetro.

(^)
(^)
▪ TimeOut – permite definir o tempo máximo
que a consola espera pela resposta do
servidor, com um mínimo de 5 segundos e por
omissão 15 segundos. Para pedidos com
respostas mais ‘volumosas’ poderá ser
necessário aumentar este tempo.
O botão ‘ Lista de serviços ’ é um atalho para
o serviço ‘ArtDB/_WSList’ e permite visualizar todos
os serviços disponibilizados pelo servidor
ArtXMLServer. Se determinado serviço não estiver
disponível nesta lista, significa que a respetiva
biblioteca ARTSOFT que o executa não foi
configurada ou carregada.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de serviços e permite
selecionar um deles. Estando um dos serviços
selecionados, ao carregar no botão, este funciona
como um atalho para o serviço ‘ArtDB/_WSList’, com
os parâmetros , que irá apresentar um texto com os
parâmetros de input , output e eventuais
comentários específicos desse serviço.
O botão ‘ Lista de funções ’ é um atalho para
o serviço ‘ArtDB/_fnList’, e apresenta uma lista de
funções disponibilizadas pelas bibliotecas instaladas.
Essas funções podem ser usadas em fórmulas que os
serviços possam disponibilizar, para fórmulas de
mapas, relatórios e outros no próprio ARTSOFT bem
como para uso no conector ‘Excel’.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de funções e permite
selecionar uma delas. Estando uma delas

(^)
(^)
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_fnList’ com os parâmetros e irá apresentar
um texto com os parâmetros de input dessa função
e o respetivo tipo de retorno (N-numérico,
A=alfanum ou ‘|’=Array com elementos separados
por ‘|’).
O botão ‘ Lista de tabelas ’ é um atalho para
o serviço ‘ArtDB/_DbTables’, e apresenta uma lista
de tabelas disponibilizadas pelas bibliotecas
instaladas.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de tabelas e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_TblDesc’ com os parâmetros e irá apresentar uma
seção ‘’ com a lista dos indexes utilizáveis do
ficheiro/tabela, e uma seção ‘’ com a lista
das colunas dessa tabela, contendo o nome da
coluna, o tipo, tamanho e a descrição da mesma.
Esta lista permite fornecer os dados necessários aos
serviços que permitem configurar a lista de
colunas/campos que fornecem, bem como os dados
necessários para efetuar queries ‘ad-hoc’.
A opção lateral ‘Tipo’ permite selecionar que
tipos de campos se pretendem - todos, apenas os
‘reportáveis’ ou apenas aqueles que permitem
‘inputs’, e se ordenados ou não.
As linhas ‘Comandos/Ficheiros XML’
permitem definir os parâmetros em formato XML
simples (que caiba todo numa linha) ou complexos,
através de um ficheiro XML que será lido para envio.

(^)
(^)
Se a linha começar com ‘<’ é interpretada como um
XML simples, caso contrário, como um ficheiro a ler.
O botão ‘...’ a seguir ao campo permite navegar no
sistema para localizar o ficheiro a colocar na linha.
Se este já estiver configurado, carregando em ‘CTRL’
e clicando no mesmo botão, chama o editor de texto
para editar o respetivo ficheiro. O editor por omissão
é o ‘notepad’, mas pode ser configurado outro,
editando o ficheiro de configuração (por omissão o
‘XMLClient.ini’) e colocando o caminho e nome do
editor, como no exemplo:
EDITOR="C:\Program Files
(x86)\Notepad++\notepad++.exe"
As linhas ‘Serviço’ permitem definir os nomes
dos serviços a efetuar, podendo os mesmos serem
selecionados na respetiva lista de seleção. Porém,
estes só serão enviados ao servidor se a respetiva
‘check’ estiver ligada. Quando várias linhas
estiverem selecionadas, os pedidos serão enviados
em lote e pela mesma ordem.
O botão ‘Performance’ necessita que a caixa
‘Params’ contenha um valor, que será utilizado para
indicar o nº de pedidos que irá efetuar ao servidor.
Estes pedidos têm tamanhos aleatórios até 1
megabyte, são recebidos pelo servidor e
simplesmente descartados, não havendo assim
qualquer tipo de processamento dos mesmos. Desta
forma este teste permite medir a performance do
canal de comunicações no sentido da receção de
pedidos (sendo a resposta muito curta, a velocidade
de resposta passa a ser estatisticamente
irrelevante). Por fim, é apresentada a lista de

(^)
(^)
mensagens enviadas e os respetivos tempos, e no
fim, um resumo estatístico: ‘tempo médio: xxx.x ms;
tempo total: xxx.xxx seg; MB: yyy; MB/s: zzzz.zzz’,
em que o tempo médio é obtido pela média simples
dos tempos de cada pedido, o tempo total obtido
pela soma do tempo gasto por cada pedido, ‘MB’ é o
somatório dos Mega Bytes de dados enviados e ‘MB/s’
a média de Mega Bytes por segundo de todos os
pedidos, ou seja, a largura de banda do momento.
O botão ‘Eco’ necessita que a caixa ‘Params’
contenha um valor, que será utilizado para indicar o
nº de pedidos que irá efetuar ao servidor. Este
serviço tem um funcionamento totalmente idêntico
ao anterior, com a especialização de enviar de volta
ao cliente o conteúdo recebido. Desta forma, o
tempo de resposta já é totalmente relevante,
permitindo medir a largura de banda de envio e
receção.
Poderá se muito útil efetuar estes testes e
guardar os respetivos resultados na altura da
instalação de um servidor ArtXMLServer, para os
comparar posteriormente em caso de degradação da
performance do serviço, permitindo aferir se essa
degradação se deve ou não à perda de largura de
banda do canal de comunicações.
Execução de serviços a partir do
ARTSOFT

(^)
(^)
É possível executar a maior parte dos serviços
para testes e inclusivamente obter os protótipos
associados.
‘Empresa -> Funções de supervisão ->
Configurações’:
Tem também acesso às listas de funções da
API ARTSOFT que são usadas em XML e no Excel, e
também a lista de funções internas que podem ser
usadas.

76. Lista dos serviços disponíveis.

(^)
(^)
Exemplo de protótipo.

77. Lista de funções ARTSOFT

(^)
(^)

78. Lista de funções internas

Parâmetros gerais dos Serviços WEB
Os mesmos elementos da mensagem ‘ CtaFch/UpdateAccounts ‘

(^)
(^)

fields -

... Início da secção de lançamentos contabilísticos a inserir.
<journal id='x.y' [trans='x']> ... Secção respeitante ao diário a ser inserido. Id=’x.y’ refere-se ao número
do diário a inserir.
Podem ser inseridos vários diários, desde que estão dentro do nó
.
<docum [docID='tpDoc/nrDoc'] date='xxx'
refdate='xx' [trans='x']> ...

Documento a ser inserido dentro do diário. Para inserir é necessário
passar qual o tipo de e numero do documento a ser inserido
(docID='tpDoc/nrDoc'). Podem ser inseridos vários documentos, desde
que dentro de um nó .

fields -

Dados do lançamento de documento a ser inserido. Fields corresponde
a campos da tabela CtaLan.
Podem ser inseridos vários lançamentos, desde que dentro de um nó
<docum>.
Para inserir apenas lançamentos contabilísticos (opção 2):
<message trans='S' retid='S' status='S'>
<transactions>
...
</transactions>
</message>

message Nome (pode usar-se qualquer um) do nó root.
retID='Y|N' status='Y|N' trans='Y|N' Descrito em

Serviço ArtXMLServer

Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)

(^)
(^)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

79. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos
a preencher estão documentados na consola
Artexecmanager.

Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.

(^)
(^)

• ...

80. ArtXmlServer multiempresa

Este serviço é muito específico, e
normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o
serviço passa a ter um comportamento diferente,
adaptando-se às exigências da função.
Um software cliente que se conecte a um
servidor multiempresa passa a ter que indicar em
cada ligação qual a base de dados pretendida e a
respetiva data de trabalho, adicionando um
cabeçalho ‘DBName=Base De dados’, e
‘workDate=AAAA-MM-DD’, sem os quais os pedidos
passam a ser rejeitados com o status ‘ 406 - Not
Acceptable’ e uma mensagem ‘missing DBName’ ou
‘missing workDate’.
Quando o servidor recebe um pedido, verifica
a ‘base de dados’ atual é a pedida. Se sim, está tudo
OK e processa o pedido. Senão, vai tentar comutar
para a base de dados pedida. Mas isso só pode
acontecer se não existir mais nenhuma ligação em
curso, pois essa ainda está a usar a atual base de
dados. Caso contrário, informa o cliente que o
pedido, de momento não pode ser satisfeito,
devolvendo o status ‘423-media locked’ e uma
pequena mensagem. Quando isso acontecer, o
cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços
(até ao máximo dos que estiverem instalados).
Como este serviço pode comutar de base de
dados durante o seu funcionamento, não pode ter

(^)
(^)
nenhum outro serviço instalado no mesmo servidor
ArtExec, pois a comutação poderá ocorrer a qualquer
momento, para além de tornar imprevisível qual a
base de dados sob a qual esse outro serviço iria
efetuar o seu trabalho. Desta forma, quando o
servidor ArtXMLServer estiver configurado como
‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor e
recusa-se a arrancar se algum serviço já estiver
instalado no mesmo ArtExec.

81. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das

82. Lista dos serviços disponíveis.

(^)
(^)
Exemplo de protótipo.

83. Lista de funções ARTSOFT

(^)
(^)

84. Lista de funções internas

Parâmetros gerais dos Serviços WEB
Início da secção de lançamentos contabilísticos a inserir.

(^)
(^)
...

Terá que ter os mesmos nós “filhos” que foram descritos na “opção 1” ,
, e .

85. CtaFch/UpdateAccounts

Permite inserir ou atualizar contas no plano de contas.
Para inserir contas:
<account id='Ai' retid='S|N|T|F' trans='S|N|T|F' status='S|N|T|F'>

fields -

account Nome (pode usar-se qualquer um) do nó root.
id='Ai' Auto incremento da conta. Se este for passado irá fazer update a uma
conta já existente ou dar erro caso a conta não exista.
Se se pretende inserir uma conta nova, então este campo não deve ser
passado, sendo que no espaço fields devemos passar o campo NrConta
ou o campo NrContaEd obrigatoriamente.
retid='S|N|T|F'
trans='S|N|T|F'
status='S|N|T|F'>

Descrito em

Serviço ArtXMLServer

Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais

(^)
(^)
‘cores’ do processador (caso das máquinas virtuais)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

86. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos
a preencher estão documentados na consola
Artexecmanager.

Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.
...
87. ArtXmlServer multiempresa

88. Consola ‘XMLServices’

Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das
respostas. Como este parâmetro passa a ser
sempre enviado em todas as ligações, faz
com que seja ignorado o parâmetro de igual
nome configurado no servidor.
▪ Compressão – nenhuma, ‘gZip’ ou ‘deflat’ –
permite indicar o algoritmo de compressão a
usar nos pedidos ao servidor e que este usa
também para as respostas. Se forem usados
canais de comunicação exteriores ou em que
a largura de banda seja reduzida, deve usar-
se sempre compressão, reduzindo
drasticamente o tamanho das mensagens e
aumentando muito a velocidade com que o
cliente obtém os dados, à custa de uma
penalização de carga no servidor. O formato

(^)
(^)
Tem também acesso às listas de funções da
API ARTSOFT que são usadas em XML e no Excel, e
também a lista de funções internas que podem ser
usadas.

89. Lista dos serviços disponíveis.

Exemplo de protótipo.

(^)
(^)

**90. Lista de funções ARTSOFT

Lista de funções internas**

(^)
(^)
Parâmetros gerais dos Serviços WEB

fields - No espaço fields, devem ser passados, os campos da tabela CtaFch, que
se pretende inserir ou atualizar relativamente a uma conta.
Os campos TipoCta e (NrConta ou NrContaEd) pertencentes à tabela
CtaFch têm que obrigatoriamente ser passados quando se está a inserir
um nova conta.
No caso de se estar a realizar a atualização de uma conta e o id=’Ai’
tenha sido passado, então apenas o campo TipoCta tem obrigatoriedade
de ser passado.
92. CtaFch/DeleteAccounts

Permite eliminar contas do plano de contas.
No caso de contas de Terceiros, estas apenas podem ser apagados através da
eliminação do terceiro.
Para eliminar contas:

(^)
(^)
<account id='Ai' | account='12.1.1' retid='S|N|T|F' trans='S|N|T|F' status='S|N|T|F'/>
account Nome (pode usar-se qualquer um) do nó root.
id='Ai'
Auto incremento da conta a ser eliminada. Deve ser passado ou id=’Ai’
ou account=’xx.y.z’, caso sejam passados ambos, o serviço irá ter em
conta apena id=’Ai’.
account='12.1.1' Número da conta a ser eliminada.
retid='S|N|T|F'
trans='S|N|T|F'
status='S|N|T|F'
Descrito em
Serviço ArtXMLServer
Este serviço está implementado para funcionar na
plataforma ArtExec (serviço Windows) e permite
executar serviços ARTSOFT recebidos numa porta
TCP.
Sendo um serviço do ArtExec, recomenda-se
que seja consultada também a documentação deste,
pois a sua configuração e funcionamento afetam
profundamente a segurança e performance deste
serviço. Esta documentação está no manual de
instalação de Serviços ARTSOFT.
Quando este serviço (e outros que estejam
também instalados no mesmo servidor ARTEXEC)
representarem um consumo de CPU considerável que
possa prejudicar a performance do servidor de bases
de dados, o servidor deve ser escalado para ter mais
‘cores’ do processador (caso das máquinas virtuais)
ou em alternativa, o serviço ArtExec deve ser
colocado noutro servidor específico para o efeito.

93. Configuração do ArtXmlServer

A configuração deste serviço é efetuada no
ficheiro de configuração do servidor ArtExec,
descrita no manual de Serviços ARTSOFT. Os campos

(^)
(^)
a preencher estão documentados na consola
Artexecmanager.
Na seção [Config], tem que constar na lista
de ‘Plugins’ instalados o módulo deste serviço, o
‘ArtXMLServer’.
Para executar a sua função, este serviço
entrega pedidos e recebe respostas dos serviços que
cada biblioteca ARTSOFT disponibiliza. Dependendo
das bibliotecas instaladas, poderão estar mais ou
menos serviços disponíveis. Para indicar a lista de
bibliotecas a usar, deve colocar-se esta no
parâmetro ‘ LoadLibs ’:

ARTDB_D – Serviços de gestão comercial e
contabilidade (artigos, terceiros,
documentos, planos de contas, extratos de
contas e de diários, etc.).
ARTDB_P – Serviços de contabilidade (planos
de contas, extratos de contas e de diários,
etc.).
ARTDB_S - Serviços de recursos humanos.
...
94. ArtXmlServer multiempresa

Este serviço é muito específico, e
normalmente só é utilizado em integrações que
tenham o licenciamento específico multiempresa.
Quando configurado com ‘MultiEmpr=S’, o
serviço passa a ter um comportamento diferente,
adaptando-se às exigências da função.
Um software cliente que se conecte a um
servidor multiempresa passa a ter que indicar em
cada ligação qual a base de dados pretendida e a

(^)
(^)
respetiva data de trabalho, adicionando um
cabeçalho ‘DBName=Base De dados’, e
‘workDate=AAAA-MM-DD’, sem os quais os pedidos
passam a ser rejeitados com o status ‘ 406 - Not
Acceptable’ e uma mensagem ‘missing DBName’ ou
‘missing workDate’.
Quando o servidor recebe um pedido, verifica
a ‘base de dados’ atual é a pedida. Se sim, está tudo
OK e processa o pedido. Senão, vai tentar comutar
para a base de dados pedida. Mas isso só pode
acontecer se não existir mais nenhuma ligação em
curso, pois essa ainda está a usar a atual base de
dados. Caso contrário, informa o cliente que o
pedido, de momento não pode ser satisfeito,
devolvendo o status ‘423-media locked’ e uma
pequena mensagem. Quando isso acontecer, o
cliente tem duas opções: ou tenta novamente mais
tarde, ou tenta conectar-se a um dos outros serviços
(até ao máximo dos que estiverem instalados).
Como este serviço pode comutar de base de
dados durante o seu funcionamento, não pode ter
nenhum outro serviço instalado no mesmo servidor
ArtExec, pois a comutação poderá ocorrer a qualquer
momento, para além de tornar imprevisível qual a
base de dados sob a qual esse outro serviço iria
efetuar o seu trabalho. Desta forma, quando o
servidor ArtXMLServer estiver configurado como
‘Multiempresa’ passa a controlar que apenas ele
esteja em funcionamento no mesmo servidor e
recusa-se a arrancar se algum serviço já estiver
instalado no mesmo ArtExec.

95. Consola ‘XMLServices’

(^)
(^)
Esta aplicação permite enviar pedidos
manuais e apresentar a resposta numa consola,
permitindo assim criar um comando ou ficheiro XML,
enviá-lo ao serviço e verificar a resposta obtida,
antes de a codificar na aplicação cliente, bem como
efetuar pedidos de informação sobre o sistema ou
testar a performance dos canais de comunicação e /
ou do sistema.
Parâmetros da consola:
▪ Server – ‘IP:porta’ ou
‘nome_do_servidor:porta’ do servidor
ArtXMLServer.

(^)
(^)
▪ Login – Normal, Debug, Teste, MultiDB e
Plugin:
 Normal – Ligação ‘normal’ a um
servidor ArtXMLServer exclusivo de
uma empresa;
 Debug –
 Teste – Usados para testar o cálculo
do ‘digest’ para quem não possa usar
um dos conectores disponibilizados
(.NET, PHP, C/C++, Android).
 MultiDB - Ligação ‘normal’ a um
servidor ArtXMLServer multiempresa.
Este modo tem especificidades que
serão tratadas mais adiante;
 Plugin – usar apenas quando a
documentação do ‘plugin’ específico
de determinada empresa ou setor o
indicarem. Como este modo utiliza
algoritmos diferentes do standard, o
uso indevido deste modo vai ser
banido e registado no ficheiro de log
como ‘tentativa de invasão’.
▪ Hash – O algoritmo a usar para calcular o
‘digest’ que o servidor espera. Este
parâmetro deve estar conforme o parâmetro
‘digest’ do servidor. Se isso não se verificar,
não é possível efetuar login, ficando
registado no ficheiro de log como ‘tentativa
de invasão’.
▪ User – O nome do utilizador, um dos nomes
configurados no servidor em ‘UsersList’.

(^)
(^)
▪ Palavra-passe – a ‘password’ (não
encriptada) colocada a seguir ao ‘nome’
configurado no servidor em ‘UsersList’.
▪ Base de dados – (apenas se ‘Login=MultiDB’)

Permite indicar o nome da base de dados /
empresa de trabalho onde devem ser
efetuados os pedidos.
▪ Data trabalho - (apenas se ‘Login=MultiDB’) –
Permite indicar a data de trabalho a que se
referem os pedidos.
▪ XMLIndent – a indentação que o servidor
deve usar na formatação do XML no envio das
respostas. Como este parâmetro passa a ser
sempre enviado em todas as ligações, faz
com que seja ignorado o parâmetro de igual
nome configurado no servidor.
▪ Compressão – nenhuma, ‘gZip’ ou ‘deflat’ –
permite indicar o algoritmo de compressão a
usar nos pedidos ao servidor e que este usa
também para as respostas. Se forem usados
canais de comunicação exteriores ou em que
a largura de banda seja reduzida, deve usar-
se sempre compressão, reduzindo
drasticamente o tamanho das mensagens e
aumentando muito a velocidade com que o
cliente obtém os dados, à custa de uma
penalização de carga no servidor. O formato
‘gZip’ contém um cabeçalho que informa
dados adicionais sobre o texto compactado,
pelo que, se não existir outro motivo, deve
ser este o formato a escolher.
▪ Config – Permite selecionar um ficheiro de
configuração alternativo, permitindo assim

(^)
(^)
ter vários ficheiros de configuração e
selecionar um deles para uso no momento.
▪ Segurança – Se esta opção estiver ligada, a
transferência de dados é efetuada de forma
encriptada, mantendo a confidencialidade
dos dados (os dados abrangidos pelo R.G.P.D.
só podem circular nesta forma).
▪ Params – Esta opção permite especificar os
parâmetros necessários aos serviços de teste
(performance e eco), permitindo definir o nº
de envios a efetuar. A descrição desses
serviços descreve o uso deste parâmetro.
▪ TimeOut – permite definir o tempo máximo
que a consola espera pela resposta do
servidor, com um mínimo de 5 segundos e por
omissão 15 segundos. Para pedidos com
respostas mais ‘volumosas’ poderá ser
necessário aumentar este tempo.
O botão ‘ Lista de serviços ’ é um atalho para
o serviço ‘ArtDB/_WSList’ e permite visualizar todos
os serviços disponibilizados pelo servidor
ArtXMLServer. Se determinado serviço não estiver
disponível nesta lista, significa que a respetiva
biblioteca ARTSOFT que o executa não foi
configurada ou carregada.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de serviços e permite
selecionar um deles. Estando um dos serviços
selecionados, ao carregar no botão, este funciona
como um atalho para o serviço ‘ArtDB/_WSList’, com
os parâmetros , que irá apresentar um texto com os

(^)
(^)
parâmetros de input , output e eventuais
comentários específicos desse serviço.
O botão ‘ Lista de funções ’ é um atalho para
o serviço ‘ArtDB/_fnList’, e apresenta uma lista de
funções disponibilizadas pelas bibliotecas instaladas.
Essas funções podem ser usadas em fórmulas que os
serviços possam disponibilizar, para fórmulas de
mapas, relatórios e outros no próprio ARTSOFT bem
como para uso no conector ‘Excel’.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de funções e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_fnList’ com os parâmetros e irá apresentar
um texto com os parâmetros de input dessa função
e o respetivo tipo de retorno (N-numérico,
A=alfanum ou ‘|’=Array com elementos separados
por ‘|’).
O botão ‘ Lista de tabelas ’ é um atalho para
o serviço ‘ArtDB/_DbTables’, e apresenta uma lista
de tabelas disponibilizadas pelas bibliotecas
instaladas.
A caixa de seleção abaixo desse botão
apresenta a mesma lista de tabelas e permite
selecionar uma delas. Estando uma delas
selecionada, ao carregar no botão, este chama o
serviço ‘ArtDB/_TblDesc’ com os parâmetros e irá apresentar uma
seção ‘’ com a lista dos indexes utilizáveis do
ficheiro/tabela, e uma seção ‘’ com a lista
das colunas dessa tabela, contendo o nome da
coluna, o tipo, tamanho e a descrição da mesma.

(^)
(^)
Esta lista permite fornecer os dados necessários aos
serviços que permitem configurar a lista de
colunas/campos que fornecem, bem como os dados
necessários para efetuar queries ‘ad-hoc’.
A opção lateral ‘Tipo’ permite selecionar que
tipos de campos se pretendem - todos, apenas os
‘reportáveis’ ou apenas aqueles que permitem
‘inputs’, e se ordenados ou não.
As linhas ‘Comandos/Ficheiros XML’
permitem definir os parâmetros em formato XML
simples (que caiba todo numa linha) ou complexos,
através de um ficheiro XML que será lido para envio.
Se a linha começar com ‘<’ é interpretada como um
XML simples, caso contrário, como um ficheiro a ler.
O botão ‘...’ a seguir ao campo permite navegar no
sistema para localizar o ficheiro a colocar na linha.
Se este já estiver configurado, carregando em ‘CTRL’
e clicando no mesmo botão, chama o editor de texto
para editar o respetivo ficheiro. O editor por omissão
é o ‘notepad’, mas pode ser configurado outro,
editando o ficheiro de configuração (por omissão o
‘XMLClient.ini’) e colocando o caminho e nome do
editor, como no exemplo:
EDITOR="C:\Program Files
(x86)\Notepad++\notepad++.exe"
As linhas ‘Serviço’ permitem definir os nomes
dos serviços a efetuar, podendo os mesmos serem
selecionados na respetiva lista de seleção. Porém,
estes só serão enviados ao servidor se a respetiva
‘check’ estiver ligada. Quando várias linhas
estiverem selecionadas, os pedidos serão enviados
em lote e pela mesma ordem.

(^)
(^)
O botão ‘Performance’ necessita que a caixa
‘Params’ contenha um valor, que será utilizado para
indicar o nº de pedidos que irá efetuar ao servidor.
Estes pedidos têm tamanhos aleatórios até 1
megabyte, são recebidos pelo servidor e
simplesmente descartados, não havendo assim
qualquer tipo de processamento dos mesmos. Desta
forma este teste permite medir a performance do
canal de comunicações no sentido da receção de
pedidos (sendo a resposta muito curta, a velocidade
de resposta passa a ser estatisticamente
irrelevante). Por fim, é apresentada a lista de
mensagens enviadas e os respetivos tempos, e no
fim, um resumo estatístico: ‘tempo médio: xxx.x ms;
tempo total: xxx.xxx seg; MB: yyy; MB/s: zzzz.zzz’,
em que o tempo médio é obtido pela média simples
dos tempos de cada pedido, o tempo total obtido
pela soma do tempo gasto por cada pedido, ‘MB’ é o
somatório dos Mega Bytes de dados enviados e ‘MB/s’
a média de Mega Bytes por segundo de todos os
pedidos, ou seja, a largura de banda do momento.
O botão ‘Eco’ necessita que a caixa ‘Params’
contenha um valor, que será utilizado para indicar o
nº de pedidos que irá efetuar ao servidor. Este
serviço tem um funcionamento totalmente idêntico
ao anterior, com a especialização de enviar de volta
ao cliente o conteúdo recebido. Desta forma, o
tempo de resposta já é totalmente relevante,
permitindo medir a largura de banda de envio e
receção.
Poderá se muito útil efetuar estes testes e
guardar os respetivos resultados na altura da
instalação de um servidor ArtXMLServer, para os

(^)
(^)
comparar posteriormente em caso de degradação da
performance do serviço, permitindo aferir se essa
degradação se deve ou não à perda de largura de
banda do canal de comunicações.
Execução de serviços a partir do
ARTSOFT
É possível executar a maior parte dos serviços
para testes e inclusivamente obter os protótipos
associados.
‘Empresa -> Funções de supervisão ->
Configurações’:
Tem também acesso às listas de funções da
API ARTSOFT que são usadas em XML e no Excel, e
também a lista de funções internas que podem ser
usadas.

96. Lista dos serviços disponíveis.

(^)
(^)
Exemplo de protótipo.

97. Lista de funções ARTSOFT

(^)
(^)

98. Lista de funções internas

(^)
(^)
Parâmetros gerais dos Serviços WEB
Serviços relativos a Recursos Humanos

99. GrhEmp/Login

Efetua o login de um empregado no servidor XML ARTSOFT afim de poder obter acesso
aos seus dados como empregado. Para isso, o ARTSOFT apresenta o código de identificação
de cada empregado na respetiva ficha, onde, nesse mesmo sítio, permite atribuir uma
palavra-passe gerada aleatoriamente, que deverá depois ser alterada pelo próprio
empregado, já no interface externo (WEB ou outro).
Deve receber um XML formatado da seguinte forma:
Input:

O atributo ‘ID’ deve conter o identificador do registo de empregado, fornecido pelo
ARTSOFT na respetiva ficha, a partir do separador ‘diversos’. Este parâmetro serve para
localizar qual o seu registo de empregado, e é calculado pelo ARTSOFT, de forma a ter
sempre 8 dígitos entre ‘0..9’ e ‘A..Z’ (não diferenciando entre maiúsculas e minúsculas),
e ser ‘pseudoaleatório’, de forma a não poder ser facilmente dedutível qual o ID de um
empregado a partir do ID de outro, afim de aumentar a segurança do sistema.
Os atributos ‘seed’ e ‘digest’ e a descrição do algoritmo de login estão descritos no
apêndice K - Validação de logins.
Output:
100. GrhEmp/SetPass

Este serviço permite alterar a palavra-passe de empregado para acesso aos seus
dados de empregado no ARTSOFT. Para alterar a password é necessário ter login válido, pois
só assim é que se pode validar qual o empregado que está a mudar a password.

<Login rc='xx'>Nome do Empregado ou Independente</Login>

<Login id='LBW0XGXL' seed='0123456789012345' digest='FEDBD236CCC8D897947EC9B7B3AD46667947EC'/>

(^)
(^)
Deve receber um XML formatado da seguinte forma:
Input:

O atributo ‘psw’ deve conter a password que se pretende associar ao empregado.
**Output:

GrhEmp/Update**

Este serviço permite inserir ou atualizar os dados da ficha de um empregado, do seu
agregado familiar ou da sua ficha adicional.
Input:

Seção do XML Obrig Descrição
<employee id='nrEmp' .../>

S (^) Início da mensagem e eventuais atributos adicionais que sejam
necessários

fields -
</ MainRec >

N
Seção opcional para a identificação de um empregado que exista (no
caso de se estar a inserir) ou não (no caso de se tratar de uma
atualização). Se esta secção não existir, o atributo id=’nrEmp’ tem que
estar presente no nó employee.

//Quando o set da password não foi feito com sucesso //Quando o set da password foi feito com sucesso (^)

<employee id='nrEmp' .../>

fields -
fields -

...
fields -

...

(^)
(^)

fields -

...

N (^) Secão opcional para a informação relativa ao agregado familiar de um
empregado.

fields -

...

N (^) Seção opcional para a informação relativa às fichas adicionais de um
empregado.

102. GrhEmp/UpdSug

Permite inserir um pedido de alteração a um registo de um empregado. Este pedido
será entendido pelo ARTSOFT como uma sugestão de alteração, portanto, não a executando
de imediato, e deixando essa alteração ao cuidado de um operador da área de recursos
humanos que irá validar essas alterações eventualmente contra documentos a apresentar,
que, no caso de estarem corretas, serão aceites, senão poderão ser modificadas antes de
serem atualizadas ou mesmo descartadas. O seu funcionamento é idêntico ao de
‘TerFch/UpdSug’ (pág. 58 ), não existindo o nó ‘OtherAddr’, e aceitando uma lista de campos
diferente.
Input:

Secção do XML (^) Obrig Descrição
<employee id='x' .../>

fields: -

Início da mensagem e eventuais atributos adicionais que sejam necessários.
No espaço fields iremos colocar os campos do empregado que irão ser
sugeridos para alteração.

<employee id='x' .../>

fields: -

(^)
(^)

103. GrhEmp/UpdEvent

Este serviço permite inserir eventos para processamento de remunerações, horas
extra, férias, faltas ou abonos/descontos particulares para um empregado. Devido ao
polimorfismo desta tabela, descrevem-se detalhadamente as várias colunas.

Campo I/O Descrição
AI_Evp R Auto Incremento do registo
NrEmp R/W Nº do empregado
DataEf R/W Data a partir da qual se pode processar, ou data inicial das faltas
DataVal R/W Data a que respeita a remuneração (se respeitante ao mes corrente = 0) (Ex. retractivos, faltas de meses anteriores não processadas, etc)
DataReg R/W Data em que foi registado o evento (só para fins informativos)
DataProc R Data em que este evento foi processado.
Evento R/W Falta ou remuneração (vencimento, horas extra/trab.nocturno, em feriados, dias de descanço, etc)
NaoProc R Flag 'ainda não processado'
HrMinIni R/W Hora/Minuto inicio do evento

TipoUnid (^) R/W
Unidade base do evento:

Remunerações: 0=RemunMensal, 1=RemunUnitar, 2=RemunHoraria,
3=RemunEventual;
Faltas: 0=Falta ao Minuto, 1=FaltaAoDia
NrUnidad Nº de eventos repetidos (não podem ser interpolados que nesse caso, gera n registos)

Valor (^) R/W
Valor da remuneração ou Nº de Minutos físicos.

Horas extra: Não pode registar mais que o máximo legal por dia.
Faltas: O dia inicial+nº Horas não pode ultrapassar a data de processamento
da empresa, ou fim do ano.
LocTrab R/W Código do Local de Trabalho
AI_Cad R/W FK: Ligação a evento de cadastro
AI_Grupo R/W FK: naturezaAuto Incremento do Evento que agrupa um conjunto de eventos da mesma
RefRemFix R Referencias as remunerações fixas (usadas nos retractivos automáticos)
Obs[100] R/W Este texto será transportado para as observações do processamento

(^)
(^)

104. GrhEmp/DelEvent

Este serviço permite eliminar um evento de processamento de remunerações, horas
extra, férias, faltas ou abonos/descontos particulares de um empregado.
Input:

105. GrhEmp/UpdEventCad

Este serviço permite inserir eventos de cadastro de empregados.
Input:

106. GrhEmp/DelEventCad

Este serviço permite eliminar eventos de cadastro de empregados.
Input:

107. GrhInd/Login

Efetua o login de um colaborador independente no servidor XML ARTSOFT afim de
poder obter acesso aos seus dados como independente. Para isso, o ARTSOFT apresenta o
código de identificação de cada independente na respetiva ficha, onde, nesse mesmo sítio,
permite atribuir uma palavra-passe gerada aleatoriamente, que deverá depois ser alterada
pelo próprio empregado, já na interface externa (WEB ou outro). Os parâmetros que recebe
e os resultados que fornece são idênticos aos do serviço ‘
GrhEmp/Login’.

<employee id='nrEvent'/>

<employee id='1' retID='s' status='s' trans='s'
<rec>

fields (GrhCad) -

<employee id='nrEvent'/>

(^)
(^)

108. GrhInd/SetPass

Este serviço permite alterar a palavra-passe de um colaborador independente para
acesso aos seus dados no ARTSOFT. O input e output deste serviço são iguais aos do serviço
‘

ArtUsr/TestPsw’ (pág. 27 ). Este serviço exige que a palavra-passe tenha no mínimo
8 caracteres.

109. GrhInd/Update

Este serviço permite inserir ou atualizar os dados da ficha de independente, ou da
sua ficha adicional.

110. GrhInd/UpdSug

Permite inserir um pedido de alteração a um registo de um independente. Este
pedido será entendido pelo ARTSOFT como uma sugestão de alteração, portanto, não a
executando de imediato, e deixando essa alteração ao cuidado de um operador da área de
recursos humanos que irá validar essas alterações eventualmente contra documentos a
apresentar, que, no caso de estarem corretas, serão aceites, senão poderão ser modificadas
antes de serem atualizadas ou mesmo descartadas. O seu funcionamento é idêntico ao de
‘GrhEmp/UpdSug’ (pág. 74 ), diferindo apenas na lista de campos aceites.

111. GrhInd/UpdEvent

Este serviço permite inserir eventos para processamento de remunerações para
independentes. De seguida apresentam-se os nomes e a descrição de cada coluna desta
tabela.
Campo I/O Descrição
NrIndep R/W N.º de independente

(^)
(^)
CodRemum R/W Código de remuneração
NumSeq R/W Nº de Sequência (para permitir vários CodRemun para o mesma data)
DataEvt R/W Data do evento
DataVal R/W Data a que respeita o valor
DataPro R Data de processamento
Process R Flag ‘processado’
Local R/W Código de Local de trabalho
Quant R/W Quantidade
Valor R/W Valor
NrHoras R/W Nº de horas, quando a remuneração for utilizada para o anexo F do relatório
único
Obs[127] R/W Observações

(^)
(^)
Apêndice A – XMLReports
Um relatório do tipo ‘lista’ começa com o atributo type=’list’ , seguido do atributo
query que definirá que tipo de registos se pretende. É ainda possível definir que nomes
terão os nós que representam as linhas, com name=’nome#xxx’ , que, se não for definido,
assumirá ‘Row’. xx representa o nº de dígitos que completará o nome, e simultaneamente
define o nº máximo de registos devolvidos (10^xxx-1), ou seja, para xxx=3, será 10^3-1=999.
Este valor pode ainda ser definido pelo atributo max=’yyy’ , sendo ‘yyy’ o nº máximo
pretendido. Se definidos os dois, ‘yyy’ não deve ser superior a ‘xxx’.
A seguir, é necessário definir as colunas do relatório, através de ‘defcol’.
Exemplo 1

Output:

1.01.0123
Computador 99.0GHz, 2Tb RAM, 999TB Disco
1672
{ART}\Imagem1.png
iVBORw0KGgoAAAANSUhEUgAAAV8AAAFbCAIAAAD9RhrAAAAAB3RJTUUH1QEFFgQJgYJc3AAAHB1J
REFUeJztnbt1IzsShjF7ZNC8Aaw5Qawp4wYwQWwQMmSUMYaCuEEogDVkrDFBjHkDWJMGjTWaaoF4
...
WxzYAUyNPI/M38SOv7ldT9gBTIrvI1tTWmKBWTsLBnkHMCONIojE1r65FE4QOwAA3GBNagCAG9gB
AOAGdgAAuIEdAABu/g8etvGEfkhiXAAAAABJRU5ErkJggg==

(^)
(^)
1.01.0128
Computador 99.66GHz, 2Tb RAM 999TB
1912.5
{ART}\Imagem2.gif
R0lGODlhqgCmAPcAAB8aF0RAPkVBPkpGRFpWVGlmZOd5Gd+IPd+MQ96RTt2QTNuTVNyZXtiTWOKN
Q+SSS+yWS+yWTOyXTumUSeyYT+aRR+qZUeyZUe2aUu2dVu2cVeubVeSaWu2fWu2eWeqeXOaZVe6h
Xt2dZdWdbNicaOSfYtSgc9yjc9eme9aide6jYe6lZu2jYuSkbO6naemla++oau+qbemobuOgZvCr
...
BmqohmvQhm84h/d0B9UMnOb8USlJ8zzQswfRczt0OAdz+AbwM8ETbNMQ1IZt+AZzOAd0WId24FIM
9VIw3VNl+jy2I1N4wD7tcyvtwz54qAd7uIceFRw+bVRHtZSAAAA7

1.01.0145
Computador 99.99GHz, 2Tb RAM, 999TB
2102.15
{ART}\Imagem3.gif
R0lGODlhpQCoAPcAAB8aFzMuKzUwLjo1Mzs3NEI9O0RAPUlFQk9LSFFNS1RRTllVU1xYVl9bWVdT
UWJeXGRgXmViYGlmZG5raWxoZnFubHRxb3ZzcXl2dHt4dnx5d316eH57eX98eud5GYB9e4F/fYF+
...
0OVv/uconVJMZYcFRIdx8FRvN8VWhc7WbvCGcXBUdWCHSq0HOO7nXf7nnQ1oca6HeLDUTJXUSa3U
d4gHir6HbvZnjE5plR7IgAAAOw==

(^)
(^)
Apêndice B – XMLQuery
O serviço XMLQuery permite obter dados de ficheiros ARTSOFT a partir de um pedido
em formato XML com uma sintaxe o mais simples possível, com um conjunto de comandos e
funções que permitem validar e transformar os dados.
Esse documento poderá ter requisitos específicos que obriguem a ter atributos que
eventualmente colidam com atributos que sejam usados como comandos XMLQuery, e
portanto, eliminados na saída. Para evitar isso, podem criar-se comandos com o nome que
se pretenda, desde que estes sejam declarados antes de ser usados através de um
‘namespace XML’, no formato xmlns:NovoNome=’NomeOriginal’, conforme se pode verificar
no exemplo abaixo com ‘MyRead’.
Podem definir-se variáveis para efetuar somas, ou que contenham resultados de
operações, de valores de ‘nodes’. Para a criação destas variáveis pode usar-se o comando
‘defvar=’var1;var2;var3=$função(arg1,arg2)’. No exemplo abaixo, as variáveis TotBru,
TotLiq, TotVAT são variáveis de soma, e diasVenc uma variável que guarda o resultado do
cálculo usado na linha atributo ‘payDays’, substituindo a expressão usada na
linha atributo <payDays’. Este tipo de variável é muito útil em substituição de
fórmulas complexas, e sempre que seja necessário usar o resultado de uma fórmula mais
que uma vez.
Os comandos, funções e variáveis ignoram maiúsculas/minúsculas (case insensitive).
Lista de variáveis internas:

‘%this.value’ – devolve o valor do nó currente;
‘%this.nrChilds’ – Devolve o nº de filhos do nó corrente;
Lista de comandos:
Read - Permite ler um registo de uma tabela principal podendo sincronizar com
outras tabelas, que fornecerá os dados necessários ao processamento de todo o
documento. Se a operação de leitura falhar, é assinalado erro e o processamento é
abandonado. A ligação/sincronização entre ficheiros é feita através da
especificação dos comandos de leitura de cada tabela, separados por ‘^’, indicando
as variáveis de ligação entre a tabela principal e a dependente entre { e }.
Exemplo:
‘DOC@DocFch | Document|TpDoc=V3|NrDoc=52206 ^ CLI@TerFch|Cliente|
NrCli = {%DOC.Ter.EntidPag} | Filial={%DOC.Ter.FilialPg}’.

(^)
(^)
Neste exemplo pode verificar-se que é possível criar o ‘aliás’ ‘DOC’ para o nome da
tabela ‘DocFch’ e ‘CLI’ para a ‘TerFch’, facilitando a escrita e / ou leitura.

Query - Permite selecionar os registos que correspondam aos parâmetros
especificados. Os nós descendentes serão replicados para todos os registos
encontrados, e as variáveis disponibilizadas pelos registos do query só estarão
disponíveis para os descendentes. Este comando tem o mesmo formato que o já
descrito para ‘Read’, mas suportando os seguintes parâmetros: ‘|#xxx’ – permite
indicar que o próximo query deve iniciar a partir do registo com ID=xxx, devolvido
quando é especificado o atributo ‘MaxRec’ (ver abaixo); ‘|?filtro’ – permitem
especificar funções que incluam ou excluam registos, consoante o resultado seja
verdadeiro ou falso. Exemplo:
‘Query=DocLan|Document|TpDoc={%DOC.Doc.Serie}|NrDoc=
{%DOC.Doc.Numero} |#1234 |? $IsGreat(DocLan. Qtd.Movim,0)’. Este comando
pode conter no mesmo nó atributos adicionais que indiquem a forma como deve ser
processado:
▪ MaxRec – permite indicar o nº máximo de registos a processar. Se o query
contiver mais registos, será colocado no nó onde foi declarado o ‘Query’ o
atributo ‘next=xx’, permitindo que o próximo pedido possa indicar ‘xx’ como a
continuação do ‘Query’ anterior (ver acima |#1234).
▪ Desc - Indica que o query deve ser processado de forma descendente
▪ Output - Req|Opc|Sup:
▪ ‘Req’ (ou só ‘R’- É requirido/mandatório existirem registos. Se não existirem,
será assinalado erro.
▪ ‘Opc’ (ou só ‘O’) - É opcional existirem registos. Se não existirem, faz output
uma única vez do(s) filho(s) vazios e não assinala erro.
▪ ‘Sup’ (ou só ‘S’) - Se não existirem registos os filhos são suprimidos e não
assinala erro (parâmetro por omissão, se não existir 'output')
Enable - Indica que o nó e respetivos descendentes é condicional, e só será
processado se o valor de 'enable' for verdadeiro. Ex: enable='%DOC.IVA.Inc3'

(^)
(^)

Enum - lista de valores para substituição, separados por ';' , com valor por omissão
separado por '~'. Depois de obtido o valor do nó, este é verificado se consta na lista
de substituições. Se constar, o valor do nó será o que constar a seguir a '='. Se não
constar, será usado o valor por omissão (o que estiver a seguir a '~'). Exemplo:
enum='FT=Invoice;NC=Credit note;ND=Debit note~Others' (lista que permitem
substituir os tipos de document SAFT por uma outra designação necessária).
Form - O resultado da fórmula será colocado como o valor do nó (o que se situa
entre as tags de abertura e fecho do nó: valor). A fórmula pode conter
apenas variáveis-nomes que que comecem por % e funções-têm um nome que
começa por ‘$’ e argumentos entre ‘(‘ e ‘)’, podendo haver operações entre eles.
Um caso especial é uma função sem nome, que permite obter o conteúdo de um nó
já anteriormente processado, com um determinado caminho, e assume a sintaxe:
$(/root/trunk/trunk/node) no formato absoluto ou $(../trunk/node). A lista das
funções disponíveis está descrita abaixo. Exemplos:
- form='%DiasVenc' - variável interna declarada com DefVar;
- form='%CLI.Ter.Nome' - variável de uma coluna da base de dados, disponível após
  ‘Read’ ou ‘Query’;
- form='$DateDif(%DOC.Data.Limit,%DOC.Data.Docum)' - função que aceita dois
  argumentos e calcula a diferença em dias entre duas datas;
- form='$Date($DateAdd(%DOC.Data.Docum,7),AAAA-MM-DD)' - função que formata
  em ano-mês-dia uma data proveniente do resultado de uma função que adiciona
  ‘x’ dias a uma data;
- form='$abs(%DOC.IVA.Inc+ %DOC.IVA.Val)' - obter o valor absoluto da operação de
  soma de duas variáveis.
- form='$(/document/body/totals/payable)' – obter o valor do nó cujo caminho é o
  indicado.
- form='$(.../totals/payable)' – obter o valor do nó com caminho relativo ao nó onde
  se encontra, representando cada ‘.’ Um nó na direção ascendente em que o
  primeiro ‘.’ representa o nó atual, o seguinte o ascendente deste, e assim
  sucessivamente. Porque os caminhos relativos são sempre mais sujeitos a erros, se
  possível deve usar-se caminhos absolutos.

(^)
(^)

Valid - valida se o valor numérico do nó ou da expressão argumento é diferente de
zero. Se for '0' é assinalado erro de valor. Exemplos: valid='%DOC.Tot.Doc' (assinala
erro se o valor do documento for ‘0’) ou valid=' ' (assinala erro se o valor do nó for
‘0’).
ValidEx – após processar todos os filhos deste nó, valida se o valor da expressão
argumento é diferente de zero. Se for '0' é assinalado erro de valor. Exemplos:
ValidEx='%this.nrChilds' (assinala erro se o nº de filhos deste nó for ‘0’).
NrDec - As operações numéricas a efetuar (operações aritméticas ou resultado de
funções) devem ser arredondadas a 'nrdec' decimais.
Sum - Somar o valor numérico do nó às variáveis indicadas e previamente
definidas com 'defvar'. Exemplo: sum='subtotais;totais'. Nota: a soma é efetuada
em virgula flutuante (double). Se for usada em 'xlong' pode perder precisão, mas
estima-se que não deverá haver muitos casos de uso para isso.
Clear - Quando terminar o processamento do nó onde for declarado, limpa as
variáveis indicadas. Exemplo: clear='subtotal1;subtotal2'.

Exemplo completo:

(^) <document xmlns:myRead='read' xmlns:m=’nnnn’
myRdefvar='TotBru; TotLiq; ead='DOC@DocFch|Document... ^ CLI@TerFch|Cliente|NrCli={%DOC.Ter.EntidPag}|FTotVAT; diasVenc=$DateDif(%DOC.Data.Limit,%DOC.Data.Docum) >ilial={%DOC.Ter.FilialPg}'

(^) /> '$DateDif(%DOC.Data.Limit,%DOC.Data.Docum)' /> (^) (^)

(^) query='LINE@DocLan|Document|TpDoc={%DOC.Doc.Serie}|NrDoc={%DOC.Doc.Numero}' output='Required'> form='%LINE.Cod.Codigo'/> (^) (^) (^) )'/> (^) (^) **Output:**

(^) FT SV1/51111Fatura 29990111 Nome do comprador, Ldacomprador@servidor.pt (^) (^)

(^) Produto número um10107000801 1

(^)
(^)
11.423
2.6211.4 (^)

Serviço número dois 10107000800
129.4 (^)
236.76 (^)
(^) 29.4
...
(^)
6 (^)
103.223.74 (^)
(^) 126.94

(^)
(^)
Funções internas de XMLQuery e XMLReports
Estas funções podem ser encontradas na opção de lista de funções internas em ‘Funções de
Supervisão – Configurações – lista de funções internas’.
Ao dar um duplo clique em cada uma delas tem o protótipo e os parâmetros aceites.
De seguida apresentam-se algumas delas.
Retorno Nome da função Descrição
Funções de Tempos
str
$TimeNow (fmt)
Devolve a data e hora de sistema em formato (fmt):
(vazio): AAAA-MM-DD, HH:MM:SS;
EDI: AAAA-MM-DDTHH:MM:SS;
EDIms: AAAA-MM-DDTHH:MM:SS.MMM
(^)

(^)
(^)
Funções de Datas
num $Julian (string
source)
$Julian (enum
relativos)
Converte uma data gregoriana (normal) 'source' para uma data
juliana^10.

Subtraindo duas datas julianas, obtém-se o nº de dias entre as
duas datas;
Porque as datas julianas são lineares, é possível usar as
operações de adição e subtração com elas, convertendo-se
depois o resultado uma data gregoriana (normal).
Tendo uma data juliana, o resto da sua divisão por 7 (módulo
7), fornece o dia da semana (com Segunda=0 .. Domingo=6).
Ex: $Mod($Julian(2000- 01 - 01),7) = 5 (Sábado).
Para a alternativa ‘relativos’, ver tabela abaixo.
str $JulToDate (int
numero,
[fmtDatas
format])

Transforma ‘numero’ (uma data em formato Juliano) para o
formato usual, de acordo com 'format'. Se format não for
definido, assume ‘AAAAMMDD’.

str $Date (string source,
[fmtDatas
format])
$Date (enum
relativos,
[fmtDatas
format])

Transforma uma data 'source' num qualquer formato usual,
para o formato tipo 'format'. Se format não for definido,
assume ‘AAAAMMDD’.

Para a alternativa ‘relativos’, ver tabela abaixo.

str $DateAdd (string
date,
int dias,
[fmtDatas format]

Adiciona (se dias>0) ou subtrai (se dias<0) ‘x’ dias a uma data
e formata-a com o formato especificado.

str $DateDif (string
date1,
string date2)

Devolve o nº de dias entre duas datas. Se date1 for maior que
date2 o resultado será negativo. Se date1 ou date2 forem
vazias, o resultado será 0.

10
Uma data juliana é um número de dias sequencial, logo, possivel de ser utilizado para efectuar cálculos de datas. No
exemplofevereiro. Para obter o resultado em data usual (Gregoriana), é necessário convertê: Julian(20190101)+45, adiciona 45 dias ao dia 1 de Janeiro, sendo o resultado o equivalente juliano ao dia 15 de -la com JulDate. Ex:
$JulDate(Julian(20190101)+45).

(^)
(^)
bool $ValidDate (string
date,
[int tipo=0|1|2])
Devolve '1' se a data for válida ou '0' se inválida. Se tipo=0 ou
estiver ausente testa apenas mês e dia. Se 'tipo=1' testa acima
de 0001 - 01 - 01. Se 'tipo=2' testa entre 19000101 a 20991231.
Funções de Horas
str
num
$Hour (string source,
[fmtHoras format])
$Hour (enum relativos,
[fmtHoras format])
Transforma uma hora em formato 'source' para o formato 'format'. Tendo uma hora em
formato segundos (ou seja, um valor numérico simples), é possível fazer cálculos de
tempos expressos em segundos. Atenção: o formato ‘Miliseg’ não deve ser usado para
inputs de cálculos de tempos, a não ser que se divida o mesmo por 1000.
Se format não for definido, assume ‘HH:MM:SS’.
Se format='Seg' ou 'Miliseg' devolve ‘Num’ senão, devolve ‘Str’
A opção relativos só tem um parâmetro (’Now’), que devolve a hora do sistema.
Formatos de Datas: Formatos de Horas:
fmtDatas
fmtDat
as (alt) Resultado^^ fmtHoras^
fmtHor
as (alt) Resultado^
DD/MM/AAAA D/M/A 31/12/2999 HH:MM:SS H:M:S 23:59:59
AAAA/MM/DD A/M/D 2999/12/31 HH:MM H:M 23:59
DD.MM.AAAA D.M.A 31.12.2999 HH:MM:SS.MIL H:M:S.M 23:59:59.987
AAAA.MM.DD A.M.D 2999.12.31 HhMmSs HMS 23h 59m 59s
DD_MMM_AAAA D_M_A 31 Dez 2999 HhMm HM 23h 59m
AAAA_MMM_DD A_M_D 2999 Dez 31 HhMmSsMil HMSM 23h 59m 59s 987ms
DDMMMAAAA DMMMA 31Dez2999 DHhMmSs DHMS 65d 23h 59m 59s
AAAAMMMDD AMMMD 2009Dez31 DHhMm DHM 65d 23h 59m
DDMMAAAA DMA 31012999 Seg 99999999
AAAAMMDD AMD 29991231 Miliseg 99999999999
DATAEXT DX Sexta, 31 de Março de
2999
Parâmetros relativos de Datas Parâmetros relativos de Datas (Cont.)
relativos Resultado relativos Resultado
Today Data atual (de sistema) Minus2W Data atual menos 2 semanas
BegYear 1 de Janeiro do ano atual Minus1W Data atual menos 1 semana
EndYear 31 de Dezembro do ano atual Plus1Y Data atual mais 1 ano
BegMonth 1 do mês e ano atuais Plus6M Data atual mais 6 meses
EndMonth Último dia do mês e ano actuais Plus3M Data atual mais 3 meses
Minus1Y Data atual menos um ano Plus2M Data atual mais 2 meses
Minus6M Data atual menos 6 meses Plus1M Data atual mais 1 mês
Minus3M Data atual menos 3 meses Plus3W Data atual mais 3 semanas
Minus2M Data atual menos 2 meses Plus2W Data atual mais 2 semanas
Minus1M Data atual menos 1 mês Plus1W Data atual mais 1 semana
Minus3W Data atual menos 3 semanas

(^)
(^)
Funções Lógicas
bool $I sEqualundef expr2)^ (undef expr1, Verifica a igualdade entre ‘expr1’ e ‘expr2’, e devolve ‘1’ (true) se forem iguais, ou ‘0’ (false) no caso contrário.
bool $IsEqual (undef expr2) Verifica a como ‘expr1’) , e ‘expr2’. Devolve ‘1’ (true) se forem iguais, senão ‘0’ (false).igualdade entre o valor da célula onde se encontra a fórmula (que funciona
bool $I sNotEqundef expr2)^ (undef expr1, Verifica a desigualdade entre ‘expr1’ e ou ‘0’ (false) no caso contrário ‘expr2’, e devolve ‘1’ (true) se forem diferentes,
bool $IsNotEq (undef expr2) Verifica a desigualdade entre o valor da célula e ‘expr2’, e devolve ‘1’ (true) se forem diferentes, senão ‘0’ (false).
bool $I sGreatundef expr2)^ (undef expr1, Verifica se ‘expr1’ é maior que ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool $IsGreat (undef expr2) Verifica se o valor da célula é maior que ‘expr2’, e devolve ‘1’ (true) se for ‘0’ (false) no caso contrário. verdade, ou
bool $ IsGreatEqundef expr2)^ (undef expr1, Verifica se ‘expr1’ é maior ou igual a ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool $IsGreatEq (undef expr2) Verifica se o valor da célula é maior ou igual a ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool $ IsLessundef expr2)^ (undef expr1, Verifica se ‘expr1’ é menor que ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool $IsLess (undef expr2) Verifica se ‘expr1’ é menor que ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool $ IsLessEqundef expr2)^ (undef expr1, Verifica se ‘expr1’ é ‘0’ (false) no caso contrário.menor ou igual a ‘expr2’, e devolve ‘1’ (true) se for verdade, ou
bool $IsLessEq (undef expr2) Verifica se o valor da célula é menor ou igual a ‘expr2’, e devolve ‘1’ (true) se for verdade, ou ‘0’ (false) no caso contrário.
bool
$InRange (undef value,
undef limInf,
undef limSup)
Verifica se ‘value’ é maior ou igual a ‘limInf’ e menor ou igual a ‘limSup’, e devolve ‘1’
(true) se for verdade, ou ‘0’ (false) no caso contrário
bool
$OutRange (undef value,
undef limInf,
undef limSup)
Verifica se ‘value’ é menor que ‘limInf’ ou maior que ‘limSup’, e devolve ‘1’ (true) se
for verdade, ou ‘0’ (false) no caso contrário
bool
$IsTrue(string logicExpr)
Avalia uma expressão lógica, e devolve o resultado: 0/1 (true/false). ‘logicExpr’ pode
conter uma série de expressões ligadas por ‘^’ (AND) ou ‘|’ (OR), podendo ser
antecedidas por ‘~’ (NOT). Exemplo: “(~val1 ^ val2 | val3) | ~(val4 ^ val5)”
bool
$LogicalAND(uint32 flags,
string bitList,
char baseNum)
Verifica em ‘flags’ se a lista de bits (1..64) indicada em ‘bitList’ está toda ‘on’. ‘flags’
é um numérico em formato decimal ou hexadecimal; ‘bitList’ é uma lista de números
separada por ‘;’ e ‘baseNum’ é um carater ‘D’ (Decimal) ou ‘H’ (Hexadecimal) indicando
qual a base numérica utilizada. Devolve o resultado: 0/1.
bool
$LogicalAND (uint32 flags,
string bitList,
char baseNum)
Verifica em ‘flags’ se na lista de bits (1..64) indicada em ‘bitList’ pelo menos um deles
está ‘on’. ‘flags’ é um numérico em formato decimal ou hexadecimal; ‘bitList’ é uma
lista de números separada por ‘;’ e ‘baseNum’ é um carater ‘D’ (Decimal) ou ‘H’
(Hexadecimal) indicando qual a base numérica utilizada. Devolve o resultado: 0/1.

(^)
(^)
Funções Numéricas
num $Abs (double val) Devolve o valor absoluto de 'val' (quer o valor seja positivo ou negativo, devolve sempre o seu valor positivo).
num $Mod (int val,int divisor) Devolve o módulo (resto da divisão inteira) de 'val' por 'divisor'
num $R ounduint nrDig)^ (double valDecim, Arredonda um valor decimal a ‘nrDig’ de precisão.
num $Val (string exprNum) Calcula o valor numérico da expressão enviada (pode conter operações matemáticas)
num $Min (num val1,num val2) Devolve o menor dos valores val1 e val2
num $Max (num val1,num val2) Devolve o maior dos valores val1 e val2
str $FmtNum (num val, [string format])
Formata um valor numérico baseado no template ‘format’. Se ‘format’ não for
especificado, assume ‘###,###,###,###.##’ (separador de milhares=’,’ e de decimais ‘.’).
Se for usado o caracter '+' no inicio ou fim da formatação, é pedido explicitamente que
a formatação contenha sempre o sinal (+ ou -) no inicio ou fim do número. Se for
pretendido suprimir os zeros em valores '0' ou '0.00', deve substituir-se qualquer # por
'&'. Se o valor não couber na máscara de formatação, é apresentado ‘???????’.
Exemplos considerando a formatação do valor ‘123 45. 67 ’:
“+#,###,###.##” '+12, 345. 67 '
“+0######.##” '+0 012345. 67 '
“######.##+” ' 12345. 67 +'
“ 0 #######.##-” ' 00012345. 67 - '
“(###,###.##)” 12,345.67 se negativo: (12,345.67)
“*###,###.##-” **12,345.67 se negativo: *12,345.67-
“###.###,##” 12.345,67 separador de milhares='.' e de decimais '.'
“###.### ##” 12.345 67 separador decimal =' '.
“######.&&” 12345.67 se valor=0, a saída é vazia.
Nota importante: como o carater ‘,’ é um separador de argumentos, a máscara de
formatação tem que estar protegida com aspa simples ou dupla, consoante se usou a
dupla ou simples como delimitador de propriedade no xml. Exemplo:
ou
<DocAmount form=”$fmtNum($abs(%DOC.Tot.Doc)12345,'###.###,##-')”/>
Funções String
str $L eft (string origem,uint nrDigitos) Devolve os primeiros ‘nrDigitos’ de ‘origem’
str $ Rightuint nrDigitos)^ (string origem, Devolve os últimos ‘nrDigitos’ de ‘origem’
str
$Midle (string origem,
uint start,
uint nrDigitos)
Devolve a parte de ‘origem’ que começa em ‘start’, e não mais que ‘nrDigitos’
(1º caracter é numerado com a posição 1). Se start>tamanho de origem devolve uma
string vazia
str $Str(var|const|expr)^
Concatena um conjunto de valores resultantes de uma expressão contendo variáveis,
funções ou constantes alfa ou numéricos concatenados por ‘+’. Exemplo:
$str(1234+“-“+567+“ Lisboa” produz “1234-567 Lisboa”
str $ Casestring array)^ (uint nr,^ Devolve o elemento número 'nr' de 'array' (conjunto de strings separadas por ‘;’).Se nr=0 ou nr>nº de elementos da lista, devolve ""

(^)
(^)
bool
$Contains (string str,
string amostra)
$$Contains (...)
Verifica se ‘amostra’ está contido em ‘str’. A comparação será feita em modo case
sensitive, ou case insensitive, se for usada $$contains. Esta função é idêntica a $findStr,
mas devolvendo um resultado booleano.
str $ Switchstring lista, string defValue)^ (string value,^
Dada uma lista com key1=val1;key2=val2;key3=val3;... e value=keyX, Devolve o elemento
da lista cuja keyX seja igual ao valor keyX. Se não for encontrado nenhum valor, devolve
defValue, ou se não enviado, devolve “”
str $StrToken(string lista, uint nr[,char separ])^
Dada uma lista de valores separados pelo carater ‘separ’ (elem1;elem2;elem3), devolve
o elemento ‘nr’ dessa lista, se existir, senão devolve “”. Se ‘separ’ não for enviado, é
assumido ‘;’
num
$Find (string array,
string amostra)
$$Find (...)
Procura, em modo case sensitive, a posição de ‘amostra’ em ‘array’ (conjunto de strings
separadas por ‘;’), e devolve o nº do elemento do array onde encontrou, ou 0 se não foi
encontrada. Para uma procura em modo case insensitive, usar $$find.
num
FindStr (string origem,
String amostra)
$$FindStr (...)
Procura, em modo case sensitive, se ‘amostra’ se encontra em ‘origem’, e devolve a
posição de 'origem’ onde a encontrou, ou 0 se não foi encontrada.
Para uma procura em modo case insensitive, usar $$findStr.
str $ StrRemovstring chrList)^ (string source, Elimina todos os caracteres constantes de 'chrList' encontrados em 'source'.
Str $CRLF() Devolve os carateres CR e LF no texto
num $Length (string source) Devolve o nº de carateres da string ‘source’
Várias
undef
$If (string exprLogica,
undef resultTrue,
undef resultFalse)
Avalia exprLogica, e selecciona se o resultado for ‘true’ devolve ‘resultTrue’, caso
contrário, devolve resultFalse.
str $Extenso (double val,
[str uniSing,str uniPlur,
str decPlur, enum lang] )
Cria um texto que representa o extenso do número enviado. Se os parâmetros uniSing,
uniPlur,decPlur ou lang não forem indicados são usados or omissão os valores
“euro;euros;cêntimos” e ‘P’-Lingua portuguesa.
As línguas disponíveis são: P-Português standard, p=português ligeiro, E=English,
C=Castelhano; F=Francês; B=Belga.
$ValidMail (string source) Verifica se a expressão é um endereço de email bem formatado, devolvendo “1” se
estiver correta, “-1” se o estiver vazio, ou “0” se o email contiver erros, assinalando o
local do endereço com o primeiro carater inválido.
num $ValidVAT (string source,
[bool retISO])
Verifica se a expressão é um VAT europeu válido. Se iso_NS='0|F|N' devolve '0' se
inválido, ou '1' se válido. Se retISO for '1|S|T', devolve o código ISO dos pais se for
intracomunitário válido ou ‘0’ se form inválido, ou ‘ 999 ’ se não for reconhecido como
intracomunitário.

(^)
(^)
Lista de variáveis globais ARTSOFT
Nome Tipo Descrição
Licence Num Nº de licença ARTSOFT.
WorkDate Date Data de trabalho, que poderá ser diferente da data de sistema.
SkuLen Num Tamanho do código de artigo, entre 2 e 18
OpcLen Num Tamanho do código opcional, entre 2 e 18
SkuName AlfaN Nome do código de artigo, ex. ‘referência’
OpcName AlfaN Nome do código opcional, ex: ‘código de barras’
SkuIni AlfaN Limite lógico inicial do ficheiro de artigos, por omissão ‘0’
SkuEnd AlfaN Limite lógico final do ficheiro de artigos, por omissão = ‘ZZZZZZ’
RoundPrc Num Nº de dígitos para arredondamento de preços de venda
RoundVal Num Nº de dígitos para arredondamento de valores
RoundQty Num Nº de dígitos para arredondamento de quantidades
CliLen Num Nº máximo de dígitos para o nº de cliente
ForLen Num Nº máximo de dígitos para o nº de fornecedor
FilLen Num Nº máximo de dígitos para o nº de filial
CliMaxNr Num Valor máximo que um nº de cliente pode conter, ex: 99999.
ForMaxNr Num Valor máximo que um nº de fornecedor pode conter, ex: 99999.
FilMaxNr Num Valor máximo que um nº de filial pode conter, ex: 999.
NrCliInd Num O nº de cliente atribuído aos clientes indiferenciados.
NrForInd Num O nº de fornecedor atribuído aos fornecedores indiferenciados.
CliName Alfa Nome dado à entidade ‘cliente’, como por exemplo: ‘Associado’
ForName Alfa Nome dado à entidade ‘fornecedor’, como por exemplo: ‘Fabricante’
VndName Alfa Nome dado à entidade ‘vendedor’, como por exemplo: ‘Consultor’
UserNum Num Nº de utilizador actual com login no ARTSOFT.
UserID AlfaN ID do utilizador actual com login no ARTSOFT.
UserName Alfa Nome do utilizador actual com login no ARTSOFT.
GrhTpFam Array Lista de tipos de familiares definidos na respectiva tabela, separados por ‘|’
SkuMark Array Lista de marcas definidas para artigos, separadas por ‘|’
CliMark Array Lista de marcas definidas para clientes, separadas por ‘|’
ForMark Array Lista de marcas definidas para fornecedores, separadas por ‘|’
TerMark Array Lista de marcas definidas para terceiros, separadas por ‘|’
ImoMark Array Lista de marcas definidas para bens de imobilizado, separadas por ‘|’
EmpMark Array Lista de marcas definidas para empregados, separadas por ‘|’
IndMark Array Lista de marcas definidas para independentes, separadas por ‘|’

(^)
(^)
Apêndice B - Lista de funções base ARTSOFT
GlobalVar(enum
varName)
Devolve o conteúdo da variável global ‘varName’ cuja lista pode ser
consultada no Apêndice B -.
TabPaises() Devolve uma lista separada por ‘;’ com pares “nome do país : seu
código ISO”. Devolve apenas aqueles que estejam completos.
TabMoedas() (^) Idêntica à anterior, mas devolvendo o “nome : abreviatura da moeda”
DGEmprNum(RepFin
| CAE | PVOLNEG)
Consoante o parâmetro, esta função devolve o nº da repartição de
finanças a que a empresa pertence, o seu CAE, ou a percentagem do
volume de negócios afecta ao CAE.
DGEmprStr(NIF |
NIFRL | NIFTOC)
Consoante o parâmetro, esta função devolve o nº de contribuinte da
empresa, do seu representante legal ou do técnico de contas.
GetImage(ImageID
xxx)
Devolve uma string com os documentos digitalizados associados a um
documento ou evento, com a seguinte forma:
Um ‘header’ que contém o nº de páginas da imagem, seguido de
espaço e do tipo de imagem, outro espaço e a imagem digitalizada,
em formato Base64. Quando existir mais que uma página, estas estão
separadas por um espaço:
2 jpg /9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8
UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgy
IRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/w
...
PU+1P+3XPzfvOmP4RQsfTavZ/wBfMj63DszYorGF9c8/vOx/hHvUkd5OyAmTn6ChY6m3az/r5
lLEwfQ//9k= /9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLD
... ^

(^)
(^)
Apêndice D – Lista de Funções
Uma função executa um determinado ‘trabalho’ pré-determinado, fornecendo um
resultado em formato texto, Ex: o nome de um artigo ou de uma conta, ou em formato
numérico, Ex: o preço de venda de um artigo, ou o saldo de uma conta. As funções
assinaladas que retornam ‘*’ devolvem um texto com um conteúdo indeterminado, exemplo:
uma imagem em Base64.
A lista de todas as funções disponibilizadas pelo ARTSOFT^11 pode ser obtida a partir
do serviço ArtDB/fnList. Esta lista, tal como a lista de serviços disponibilizados depende da
configuração do ArtXMLServer, na secção ‘[XMLSERVER]’, chave ‘ListaDLL =x;y;z’
As funções não podem ser chamadas diretamente pelo XMServices, mas podem ser
chamadas dentro de um query. No exemplo ao lado, pretende-se obter o stock disponível
no armazém 1, dos artigos ‘x’, ‘y’, e ‘z’.
Se o resultado for do tipo numérico, a forma
abreviada form=’$função(parametros)’ é suficiente,
pois assume por omissão type=’num’. Já o pedido a
uma função do tipo alfanumérico deve ser
complementada com type=’text’. Se isso não for feito,
o query tentará converter o texto para número, e caso não consiga devolve
‘ErroInvalidNum’.
Estas funções podem ser encontradas na opção de lista de funções (API
Artsoft/Excel/ARTSOFTCOM) em Funções de Supervisão – Configurações – lista de funções
(API Artsoft/Excel/ARTSOFTCOM).

11

Poderão ser acrescentadas as que forem necessárias através de um serviço plugin.

<TBL>
<item form='$SkuValue(x,Avail,1)'/>
<item form='$SkuValue(y,Avail,1)'/>
<item form='$SkuValue(z,Avail,1)'/>
</TBL>

(^)
(^)
Em cada uma delas está o nome, uma breve explicação e os parâmetros a serem
passados para obter a informação pretendida.
De seguida está a descrição de algumas delas.

$Valor(Ativo, ...): Esta função devolve o valor do conjunto de contas configuradas no
elemento contabilístico de nome ‘Ativo’ (neste caso).
$SkuName(SKU,NameID,SkuType): Devolve o nome ‘NameID’ de um artigo com o
código ‘SKU’. Se o código é o da empresa, não é necessário indicar nada, ou em
alternativa ‘Def’ (default), ou ‘Opc’ (opcional). NameID varia de 0=Nome principal a
‘4’-Nome opcional 4.

(^)
(^)

$SkuPrice(SKU,PriceType,Wharehouse,SkuType) : Devolve um dos preços de
PriceType, do armazém ‘x’. Lista de preços disponíveis^12 :
o [0..9] – Preço de venda 0 .. 9. Se à data do pedido o preço for inválido (ter datas de
inicio e fim e a data do pedido estar fora desse intervalo) o preço devolvido será 0.
o LastCost – último preço de custo à entrada de armazém, na data do último recálculo
de preços médios;
o LastCNow - último preço de custo à entrada de armazém, na data do pedido;
o LCostExW - último preço de custo à saída do fornecedor, na data do último recálculo
de preços médios;
o LCExWNow - último preço de custo à saída do fornecedor, na data do pedido;
o MeanCost - preço médio de custo ponderado, na data do último recálculo de preços
médios;
o MeanCNow - preço médio de custo ponderado, na data do pedido.
$SkuValue(SKU,ValueType,Wharehouse,IniMonth,EndMonth,SkuType): Devolve os
valores acumulados do artigo ‘SKU’, do tipo ‘ValueType’, para a lista de armazéns
‘Wharehouse’, entre os meses ‘IniMonth’ e ‘EndMonth’. A lista de armazéns poderá
conter apenas ‘0’ para os acumulados de toda a empresa, um número de armazém, Ex:
‘1’, para os acumulados apenas desse armazém, ou uma lista de intervalos de
armazéns, Ex: 1 :5;9;10:30, em que se pretendem os valores dos armazéns 1 a 5, do
armazém 9, e dos armazéns 10 a 30. Lista de tipos de valor disponíveis:
o QtEnt – Quantidades entradas;
o QtOut – Quantidades saidas;
o QtVnd – Quantidades vendidas;
o Stock – Stock total em armazém;
o Avail – Stock disponível em armazém (Stock total em armazém – Quantidades já
cativadas);
o VlEnt – Valores Entrados;
o VlOut – Valores Saídos;
o VlVnd – Valores Vendidos;
o Profit – Lucro Bruto.

(^12) Nota: Os dados de LastCNow, LCExWNow e MeanCNow são de baixa qualidade uma vez que poderão ser actualizados por qualquer^
correcção, e os restantes só terão alguma qualidade se for feito um encerramento da data da gestão comercial na data em que frecálculos de preços médios, evitando assim que antes dessa data ainda haja alteração de valores. oram feitos os

(^)
(^)
Apêndice E - Formulários HTML
A ‘impressão’ de um documento deverá ser feita com o formato que o utilizador
pretender, e ainda, poder ter várias formas, de acordo com o fim a que se destina (fatura,
talão, etc.). Para conseguir esse objetivo, optou-se por efetuar a transformação de um
‘formulário template’ tendo como suporte um ficheiro HTML, que conterá todo o design do
documento, e indicações de como essa transformação ocorrerá.
Para colocar essas indicações, será usada a propriedade HTML ‘title’ que serve para
comentar determinada zona ou sugerir dicas quando se coloca o ponteiro do rato sobre ela,
muito útil quando este é usado para formatação Web, mas irrelevante na apresentação ou
impressão de formulário de documentos.
Assim, o atributo ‘title’ será usado para definir uma fórmula ou variável que irá ser
usada na próxima zona delimitada por ‘«...»’. Exemplo: «999,999.99».
Neste exemplo, seria procurada a variável ‘ DocFch.Tot.Doc’ , e o seu valor colocado
no lugar onde está agora um protótipo do valor «999,999.99», e removida a propriedade
‘title’, e, supondo que a variável tinha o valor de 123,456.50, resultaria em:
123,345.50.
A utilização da propriedade ‘title’ tem uma vantagem adicional para manutenção do
formulário: o facto de esta apresentar dicas quando o rato está sobre a sua zona de
influência, irá ser muito útil quando o formulário for apresentado num browser, pois irá
mostrar a fórmula o variável associadas a cada zona.
Para que essa transformação possa ocorrer, consideremos que o documento será
dividido em três partes: 1-um cabeçalho , que conterá tudo o que esteja antes da linha de
movimentos; 2-A(s) linha (s) de movimentos; 3- Fim do documento, que conterá tudo o que
esteja após a linha de movimentos.
O cabeçalho e o fim são transformados uma única vez. A linha de movimentos é
transformada tantas vezes quantas as linhas presentes no documento.

(^)
(^)
Torna-se assim necessário definir onde começa a linha de movimentos (uma ‘’
ou ‘table row’). Para isso, marca-se a linha de movimentos com a indicação: , em que a parte ‘*x’ só é necessária se forem necessárias ‘x’ linhas HTML
para cada linha de movimentos (por exemplo, em formulários tipo ‘talão’, ver o Erro! A o
rigem da referência não foi encontrada. , na pág. Erro! Marcador não definido. ).
Obviamente, existindo a indicação que são usadas ‘x’ linhas, deverão existir definidas de
seguida ‘x’ linhas ( ... ).
É também possível definir um ‘setup’ do documento, e um conjunto de constantes
de formatação, na tag :

Setup: permite definir três parâmetros importantes:
- LanObs=’[N]|S’: Indica se vai ser usada uma coluna específica para observações do
  lançamento. Se não for, o texto de observações irá ser concatenado ao da descrição do
  produto.
- Lingua=’ B|C|E|F|P|[p]’ (B=Francês/Belga, C=Castelhano, E=Inglês(English), F=Françês,
  P=Português, p=Português ligeiro): Permite definir a língua em que o extenso do documento
  deve ser produzido (se for necessário extenso).
- TextTab=’xx’: Indica o nº da tabela de personalização do formulário existente no ARTSOFT
  em ‘Configurações/Tabelas empresa/Listagens/Personalização de formulários’. Só será útil
  se o formulário utilizar as variáveis ‘IdEmp.Linha00 .. IdEmp.Linha19’, permitindo ao
  utilizador alterar facilmente o texto de identificação da empresa.
- Dec: Permite definir qual o caracter a ser usado para separador decimal, por omissão é ’.’,
  mas pode ser também ‘,’ e esta definição irá ser importante para interpretar as máscaras de
  formatação, do tipo “###,###.##”.
- V01, V02, ...Vxx: Variáveis que contém máscaras de formatação. A formatação de
  quantidades, taxas de IVA e valores irá ser usada em todo o documento, e as formulas
  irão contê-las, ou como constantes, ex: “DocFch.Tot.Doc@###,###.##” ou
  “DocFch.Tot.Doc@V01”. Torna-se evidente que, se for necessário alterar a
  formatação em todo o documento, será muito mais fácil fazê-lo apenas num local.

(^)
(^)
Variáveis e fórmulas
Uma variável ou campo é simplesmente o nome completo de uma variável, tal como
esta é usada nos queries, serviços, gerador de relatórios, etc^13. ‘title’ pode referir uma
variável, mas também pode ser usada uma formula algébrica com outras variáveis ou
constantes:
title=(DocFch.Tot.Bruto-DocFch.Tot.DescP)/1000@###,###
title=DocLan.Div.Descric + ' ' + Qtd.Med0 + 'x' + Qtd.Med1 + 'x' + Qtd.Med2 + Div.Obs
No caso a) subtotal com o total ilíquido menos o total de descontos de produto
expresso em milhares. No caso b) pretende-se concatenar a descrição com as três medidas
e juntar-lhe as observações do lançamento. Nota: nas formulas de concatenação não faz
sentido o uso de parêntesis para definirem regras de prioridade. Como aqui é necessário o
uso de plicas para delimitar texto constante, o conteúdo de ‘title=’ tem que ser delimitado
por aspas.
Formatação de campos
Numéricos
Formato Valor Resultado^14 Formato Valor Resultado
###,###
9.9
987654.32

6666.778

10
987,654

6,667

(###,###.##)

9.9
987654.32

6666.778

9.99)
987,654.32)
(6,666.78)
###,###.##

9.9
987654.32

6666.778

9.99
987,654.32

6,666.78

(*###,###.##)

9.9
987654.32

6666.778

*******9.99)
*987,654.32)
(***6,666.78)

###,###.##-

9.9
987654.32

6666.778

9.99-
987,654.32-
6,666.78-

(=###,###.##)

9.9
987654.32

6666.778

=======9.99)
=987,654.32)
(===6,666.78)

(^13) Nos cabeçalhos das exportações ASCII só é usado o nome do campo e não o nome completo da variável (Tabela.Campo), porque^
sendo a exportação/importação de uma determinada tabela, o contexto (namespace) de todas as variáveis já é conhecido: é o da própria tabela.
(^14) Apesar de as máscaras poderem definir espaços à esquerda de um número para o alinharem, este método não foi usado, devendo
usar-se o atributo align="right" para esse efeito, porque produz resultados mais estáveis em todos os browsers e impressoras, para além de
produzir ficheiros .HTML mais pequenos.

(^)
(^)
Alfanuméricos:
A formatação alfanumérica não tem qualquer sentido usada para ajustar textos à direita o
ao centro, pois em HTML, os atributos de ‘align’: ‘left’, ‘center’ e ‘right’ fazem isso de
forma mais eficiente. No entanto, poderá ser necessário alinhar determinado texto à
esquerda, ao centro ou à direita, e preencher determinado espaço com um determinado
caracter. Para isso incluiu-se um formato específico para esse efeito:
“tamanho, alinhamento, preenchimento”, em que:

tamanho: o tamanho em caracteres do resultado pretendido;
alinhamento: ‘L’=Left/Esquerda, ‘C’=Centrado, ‘R’=Right/Direita
carater de preenchimento. Se este caracter for ‘@’, deve usar-se ‘@@’

O formato “64,C,=” significa centrar uma string em 64 caracteres, cortando-a se for
maior, ou preenchê-la com ‘=’ à esquerda e/ou á direita, até perfazer o tamanho indicado.
Exemplos:
Formato Texto original ++++.++++1++++.++++2++++.++++3++^
32,L,= Boas Festas Boas Festas=====================
32,C,= Boas Festas ===========Boas Festas==========
32,R,= Boas Festas =====================Boas Festas
32,L|C|R,= Texto muito extenso que ultrapassa 32 caracteres Texto muito extenso que ultrapas

Datas
A formatação de datas é igual á descrita na pág. 81 em ‘Apêndice B – XMLQuery

O serviço XMLQuery permite obter dados de ficheiros ARTSOFT a partir de um pedido
em formato XML com uma sintaxe o mais simples possível, com um conjunto de comandos e
funções que permitem validar e transformar os dados.
Esse documento poderá ter requisitos específicos que obriguem a ter atributos que
eventualmente colidam com atributos que sejam usados como comandos XMLQuery, e
portanto, eliminados na saída. Para evitar isso, podem criar-se comandos com o nome que
se pretenda, desde que estes sejam declarados antes de ser usados através de um
‘namespace XML’, no formato xmlns:NovoNome=’NomeOriginal’, conforme se pode verificar
no exemplo abaixo com ‘MyRead’.

(^)
(^)
Podem definir-se variáveis para efetuar somas, ou que contenham resultados de
operações, de valores de ‘nodes’. Para a criação destas variáveis pode usar-se o comando
‘defvar=’var1;var2;var3=$função(arg1,arg2)’. No exemplo abaixo, as variáveis TotBru,
TotLiq, TotVAT são variáveis de soma, e diasVenc uma variável que guarda o resultado do
cálculo usado na linha atributo ‘payDays’, substituindo a expressão usada na
linha atributo <payDays’. Este tipo de variável é muito útil em substituição de
fórmulas complexas, e sempre que seja necessário usar o resultado de uma fórmula mais
que uma vez.
Os comandos, funções e variáveis ignoram maiúsculas/minúsculas (case insensitive).
Lista de variáveis internas:
‘%this.value’ – devolve o valor do nó currente;
‘%this.nrChilds’ – Devolve o nº de filhos do nó corrente;
Lista de comandos:
Read - Permite ler um registo de uma tabela principal podendo sincronizar com
outras tabelas, que fornecerá os dados necessários ao processamento de todo o documento.
Se a operação de leitura falhar, é assinalado erro e o processamento é abandonado. A
ligação/sincronização entre ficheiros é feita através da especificação dos comandos de
leitura de cada tabela, separados por ‘^’, indicando as variáveis de ligação entre a tabela
principal e a dependente entre { e }.
Exemplo:
‘DOC@DocFch | Document|TpDoc=V3|NrDoc=52206 ^ CLI @TerFch|Cliente| NrCli =
{%DOC.Ter.EntidPag} | Filial={%DOC.Ter.FilialPg}’.
Neste exemplo pode verificar-se que é possível criar o ‘aliás’ ‘DOC’ para o nome da
tabela ‘DocFch’ e ‘CLI’ para a ‘TerFch’, facilitando a escrita e / ou leitura.
Query - Permite selecionar os registos que correspondam aos parâmetros
especificados. Os nós descendentes serão replicados para todos os registos encontrados, e
as variáveis disponibilizadas pelos registos do query só estarão disponíveis para os
descendentes. Este comando tem o mesmo formato que o já descrito para ‘Read’, mas
suportando os seguintes parâmetros: ‘|#xxx’ – permite indicar que o próximo query deve
iniciar a partir do registo com ID=xxx, devolvido quando é especificado o atributo ‘MaxRec’
(ver abaixo); ‘|?filtro’ – permitem especificar funções que incluam ou excluam registos,
consoante o resultado seja verdadeiro ou falso. Exemplo:

(^)
(^)
‘Query=DocLan|Document|TpDoc={%DOC.Doc.Serie}|NrDoc= {%DOC.Doc.Numero}
|#1234 |? $IsGreat(DocLan. Qtd.Movim,0)’. Este comando pode conter no mesmo nó
atributos adicionais que indiquem a forma como deve ser processado:
MaxRec – permite indicar o nº máximo de registos a processar. Se o query contiver
mais registos, será colocado no nó onde foi declarado o ‘Query’ o atributo ‘next=xx’,
permitindo que o próximo pedido possa indicar ‘xx’ como a continuação do ‘Query’ anterior
(ver acima |#1234).
Desc - Indica que o query deve ser processado de forma descendente
Output- Req|Opc|Sup:
‘Req’ (ou só ‘R’- É requirido/mandatório existirem registos. Se não existirem, será
assinalado erro.
‘Opc’ (ou só ‘O’) - É opcional existirem registos. Se não existirem, faz output uma
única vez do(s) filho(s) vazios e não assinala erro.
‘Sup’ (ou só ‘S’) - Se não existirem registos os filhos são suprimidos e não assinala
erro (parâmetro por omissão, se não existir 'output')
Enable- Indica que o nó e respetivos descendentes é condicional, e só será
processado se o valor de 'enable' for verdadeiro. Ex: enable='%DOC.IVA .Inc3'
Enum - lista de valores para substituição, separados por ';' , com valor por omissão
separado por '~'. Depois de obtido o valor do nó, este é verificado se consta na lista de
substituições. Se constar, o valor do nó será o que constar a seguir a '='. Se não constar, será
usado o valor por omissão (o que estiver a seguir a '~'). Exemplo:
enum='FT=Invoice;NC=Credit note;ND=Debit note~Others' (lista que permitem substituir os
tipos de document SAFT por uma outra designação necessária).
Form - O resultado da fórmula será colocado como o valor do nó (o que se situa
entre as tags de abertura e fecho do nó: valor). A fórmula pode conter apenas
variáveis-nomes que que comecem por % e funções-têm um nome que começa por ‘$’ e
argumentos entre ‘(‘ e ‘)’, podendo haver operações entre eles. Um caso especial é uma
função sem nome, que permite obter o conteúdo de um nó já anteriormente processado,
com um determinado caminho, e assume a sintaxe: $(/root/trunk/trunk/node) no formato
absoluto ou $(../trunk/node). A lista das funções disponíveis está descrita abaixo. Exemplos:

(^)
(^)
form='%DiasVenc' - variável interna declarada com DefVar;
form='%CLI.Ter.Nome' - variável de uma coluna da base de dados, disponível após ‘Read’ ou
‘Query’;
form='$DateDif(%DOC.Data.Limit,%DOC.Data.Docum)' - função que aceita dois argumentos e
calcula a diferença em dias entre duas datas;
form='$Date($DateAdd(%DOC.Data.Docum,7),AAAA-MM-DD)' - função que formata em ano-
mês-dia uma data proveniente do resultado de uma função que adiciona ‘x’ dias a uma data;
form='$abs(%DOC.IVA.Inc+ %DOC.IVA.Val)' - obter o valor absoluto da operação de soma
de duas variáveis.
form='$(/document/body/totals/payable)' – obter o valor do nó cujo caminho é o
indicado.
form='$(.../totals/payable)' – obter o valor do nó com caminho relativo ao nó onde se
encontra, representando cada ‘.’ Um nó na direção ascendente em que o primeiro ‘.’
representa o nó atual, o seguinte o ascendente deste, e assim sucessivamente. Porque os
caminhos relativos são sempre mais sujeitos a erros, se possível deve usar-se caminhos
absolutos.
Valid - valida se o valor numérico do nó ou da expressão argumento é diferente de zero. Se
for '0' é assinalado erro de valor. Exemplos: valid='%DOC.Tot.Doc' (assinala erro se o valor
do documento for ‘0’) ou valid=' ' (assinala erro se o valor do nó for ‘0’).
ValidEx – após processar todos os filhos deste nó, valida se o valor da expressão
argumento é diferente de zero. Se for '0' é assinalado erro de valor. Exemplos:
ValidEx='%this.nrChilds' (assinala erro se o nº de filhos deste nó for ‘0’).
NrDec - As operações numéricas a efetuar (operações aritméticas ou resultado de
funções) devem ser arredondadas a 'nrdec' decimais.
Sum - Somar o valor numérico do nó às variáveis indicadas e previamente definidas
com 'defvar'. Exemplo: sum='subtotais;totais'. Nota: a soma é efetuada em virgula flutuante
(double). Se for usada em 'xlong' pode perder precisão, mas estima-se que não deverá haver
muitos casos de uso para isso.
Clear - Quando terminar o processamento do nó onde for declarado, limpa as
variáveis indicadas. Exemplo: clear='subtotal1;subtotal2'.
Exemplo completo:

(^)
(^)
(^) <document xmlns:myRead='read' xmlns:m=’nnnn’
myRdefvar='TotBru; TotLiq; ead='DOC@DocFch|Document... ^ CLI@TerFch|Cliente|NrCli={%DOC.Ter.EntidPag}|FTotVAT; diasVenc=$DateDif(%DOC.Data.Limit,%DOC.Data.Docum) >ilial={%DOC.Ter.FilialPg}'

(^) /> '$DateDif(%DOC.Data.Limit,%DOC.Data.Docum)' /> (^) (^)

(^) query='LINE@DocLan|Document|TpDoc={%DOC.Doc.Serie}|NrDoc={%DOC.Doc.Numero}' output='Required'> form='%LINE.Cod.Codigo'/> (^) (^) (^) )'/> (^) (^) **Output:**

(^) FT SV1/51111Fatura 29990111 Nome do comprador, Ldacomprador@servidor.pt (^) (^)

(^) Produto número um10107000801 111.4 (^) 232.62 (^) (^) 11.4 Serviço número dois (^) 10107000800129.423 6.7629.4 (^) ... (^) (^) 6

(^)
(^)
103.223.74 (^)
(^) 126.94

/ Formatos de Datas’, coluna ‘ fmtDatas’ , ou no formato reduzido, coluna ‘ fmtDatas (alt)’.
Exemplo de formulário HTML

... ...

«Empresa0»

«Empresa1»

«Empresa2»

«Empresa3»

«Codigo»

«Quant»

«iva»

«TtIliquido»

Totais

«Incid. tot.»

«Valor tot.IVA»

TOTAL DO DOCUMENTO

«TotalDocum.»

(^)
(^)
Apêndice F - Informação adicional sobre chaves de tabelas ARTSOFT
Indicada uma tabela válida, o serviço _ArtDB/tblDesc (pág. 23 ), informa quais as
chaves (indexes) e campos (colunas) da mesma.
Alguns tipos de segmentos de chave não ficam suficientemente explícitos na
informação sucinta dada pelo serviço. Neste caso, é necessário descrever estes aqui.
Lançamentos de Contabilidade (CtaLan)
Lançamentos por
Diários/Documentos ExtDiaDoc^
CtaLan|ExtDiaDoc|Mes=2:8|Diario=1:20|TpDoc=A1:A999|Data=20010101:2009
1231| SoCC =T
Lançamentos por Tipos de
documento TipoDoc^ CtaLan|TipoDoc|TpDoc=A1:A999|NrDoc=1:999999| SoCC =T^
Datas de Vencimento DataVenc CtaLan|DataVenc|AICta=1234|TpDoc=A1:A999|NrDoc=101:991231| Tipo =T
Lancamentos pendentes de
ligações PendLink^ CtaLan|PendLink|Link= xxxxxxxx |AICta=1234|Data=19990101:20991231^
Ligações entre lançamentos Links CtaLan|Links|Link= xxxxxxxx |NrLanc=1234
SoCC^15 1=Em lançamentos de C/C, apenas o lançamento de ordem 0 0=Todos os lançamentos do documento (custos, contrapartidas, etc.)
Tipo T=Todos os lançamentos, incluindo os já regularizados (por omissão)=Só lançamentos ainda não regularizados^
xxxxxx Significado xxxxxx Significado
Deposito Deposito LetraPagam Pagamento de Letra
Letra Letra LetraNPaga Letra Não Paga
Reforma Reforma LetraDevol Devolução de Letra
ReavActivo Reavaliações de Ativos LetraReforma1 Letra/Reforma1
LetraDevol Devolução de Letra LetraReforma2 Letra/Reforma2
LetraPagFact Letra/Pagamento de Fatura LetraRecambio Recambio de Letra
LetraDesconto Desconto de Letra LetraSubstit Substituição de Letra

15

Para especificar um valor lógico, pode usar-se a forma booleana: 0 ou 1, mas também: F=False, N=No/Não em vez
de ‘0’, ou T=True, V=Verdadeiro, Y=Yes, S=Sim em vez de ‘1’.

(^)
(^)
Apêndice G - Autenticação no servidor
Modo produção
Para manter um nível de segurança adequado, o servidor XML ARTSOFT necessita de
reconhecer quem está a efetuar os pedidos, afim de manter ‘fora’ do sistema eventuais
hackers capazes de provocarem algumas dores de cabeça ao administrador de sistema.
Para isso, foram criados os seguintes algoritmos:

Validação da lista de IP’s autorizados a comunicar (opcional): para isso deve criar-se
uma chave ‘HostsList’ no ficheiro de configuração. Esta deve conter a lista de IP’s
autorizados a efetuarem pedidos, separados pos ‘;’. Exemplo:
o HostsList=localhost;76.5.43.210;192.168.1.2;www.ARTSOFT.pt
Validação da lista de ‘utilizadores’ autorizados a comunicar com o servidor
(opcional): Todas as operações efetuadas por estes utilizadores irão aparecer no
ARTSOFT como efetuadas pelo utilizador ‘0’, ou seja, o sistema. Para isso é
necessário criar a chave ‘UsersList’ no ficheiro de configuração com a lista de
utilizadores e respetivas palavras-chave encriptadas, na forma ‘User1:Psw1; ...
UserN:PswN’. Exemplo:
o UsersList=Joaquim: 4fH6kC4Dim2V2UBfw; Manuel:C4Dim2V2UBfwi1SrASj
É possível juntar à lista de utilizadores válidos a lista de utilizadores normais
ARTSOFT, desde que tenha acionada a respetiva permissão. Todas as operações irão
aparecer no ARTSOFT como tendo sido feitas pelo utilizador correto. Para isso, basta
adicionar a chave ‘UseArtUsr=S’ no ficheiro de configuração. NOTA 1: para evitar
uma enorme confusão, não deverão existir nomes duplicados. Se isso acontecer,
serão usados em primeiro lugar os nomes constantes da ‘UsersList’. NOTA 2: a versão
do servidor multiempresa não suporta a lista de utilizadores ARTSOFT.

É de notar que ‘HostsList’ pode conter o IP em formato numérico, ou o nome do host,
mas esta é lida apenas quando o serviço é inicializado, mantendo-se estática durante o
funcionamento. Por essa razão, não devem ser incluídos na lista nomes de hosts com IP’s
dinâmicos, pois pode ocorrer uma mudança de IP, que não constará da lista.

(^)
(^)
Quando um cliente se conecta ao servidor, deve enviar-lhe um HTTP GET para o
recurso ‘login’, e no cabeçalho, deve ser adicionada uma chave ‘Name’ com o nome do
utilizador que se pretende ligar. Adicionalmente, pode juntar-se também uma chave
‘XmlIndent’ com o valor da indentação que os nós (nodes) dos streams XML devem ter, que
por omissão, é -1 (sem CR/LF e sem indentação de nós), podendo ser enviados valores
razoáveis de ‘0=Só com CR/LF’, ‘1...3=CR/LF seguido de 1..3 espaços por cada nível.
Em resposta, o servidor envia um status ‘200 OK’, uma chave no cabeçalho de nome
‘Digest’, contendo um desafio com 20 a 22 dígitos. Seguidamente, o cliente deverá colocar
no cabeçalho da sua primeira mensagem uma chave de nome ‘Digest’. O valor para esta
chave é formado por 16 ou 20 bytes codificados em hexadecimal (32 / 40 dígitos), e é
calculado, consoante o algoritmo escolhido, segundo o seguinte pseudocódigo:
MD5: efetuar o ‘digest’ com MD5 de “UserName”, “Password”, “Desafio” para as
posições 0, 16 e 32 de um ‘byte array’ com 48 bytes de tamanho, efetuar de novo o ‘digest’
desse buffer, e converter o resultado para hexadecimal:
char buffer[163], output[16],result[32+1]
MD5 (in UserName, out &buffer[00])
MD5 (in Password, out &buffer[16]) *
MD5 (in Desafio , out &buffer[32])
MD5 (in buffer , out output)
Hexa(in output , out result)
SHA1: efetuar o ‘digest’ com SHA1 de “UserName”, “Password”, “Desafio” para as
posições 0, 20 e 40 de um ‘byte array’ com 60 bytes de tamanho, efetuar de novo o ‘digest’
desse buffer, e converter o resultado para hexadecimal:
char buffer[203], output[20],result[40+1]
SHA1(in UserName, out &buffer[00])
SHA1(in Password, out &buffer[20]) *
SHA1(in Desafio , out &buffer[40])
SHA1(in buffer , out output)
Hexa(in output , out result)
Se for pretendido enviar vários comandos de seguida, deve colocar-se no cabeçalho
‘Keep-Alive=xx’, em que xx é o número de segundos que a ligação se deve manter (máx: 30
segundos). No último pedido o cabeçalho não deve conter este atributo, indicando que o

(^)
(^)
servidor após processar e responder a esse comando pode encerrar ‘graciosamente’ a
ligação.
Nota: ‘Name’ só pode ser enviado na 1ª mensagem (a da ligação), e ‘Digest’ só pode ser
enviado na 2ª mensagem, e apenas uma vez, senão, a ligação será encerrada!
Modo debug
No modo debug, o serviço não executa nenhuma função, mas permite testar os
algoritmos de login e digest, afim de verificar o seu bom funcionamento. Para isso, deve
enviar-se o pedido para ‘logdebug’ em vez de ‘login’, com um user ‘ART’ e password ‘SOFT’.
Neste modo, para que os valores possam ser comparáveis, o servidor envia um desafio
sempre constante “ABCDEFGHIJKLMNOPQRSTUV”. O resultado obtido deverá ser:

MD5: 7e cc a8 a4 00 07 9c 6a 31 88 44 3d 08 e3 6e 73
SHA1: 3d f2 5f 88 79 0d aa ea 81 f9 68 cd c1 a2 1f 15 65 df 64 32

Teste de comunicação
As aplicações utilizadoras poderão ter uma funcionalidade muito simpática para
quem está a configurar o sistema, colocando um botão ou opção de menu ‘Testar conecção’.
Para informar o utilizador qual o estado da ligação, pode fazer-se o login em modo debug,
e se a resposta for negativa, existe um problema com o endereço do host ou da porta em
que o serviço está instalado. Se a resposta for positiva, já é possível contactar o serviço,
mas ainda não se sabe se o ‘UserID’ e ‘Password’ estão corretos. Para isso, pode fazer-se
nova ligação para ‘logtest’ com o utilizador e password corretos. Neste modo, o serviço
também não executa nenhuma função, mas, por motivos de segurança, todos os pedidos de
‘logtest’ são enviados para o ficheiro de log e notificações.

Algoritmos de validação de clientes
O servidor permite a utilização dos algoritmos MD5 e SHA1 para validação de clientes,
devendo ser escolhido o SHA1, existindo o MD5 para suporte a aplicações e plataformas de
desenvolvimento mais antigas.

(^)
(^)
Um algoritmo de hash só tem uma via, ou seja, dado um texto ou documento, é
sempre possível gerar um hash para o mesmo, mas, dado um determinado hash não é
possível^16 determinar qual o texto que lhe deu origem.
Para ajudar nessa escolha, é necessário ter em atenção ao seguinte:

Se tiver acesso ao SHA1 na sua plataforma de desenvolvimento, use-o, porque é mais
seguro que o MD5.
No pseudocódigo, o passo assinalado com ‘*’ pode ser substituído por uma cópia do hash
da password previamente calculado, evitando que no código, ou na sua configuração,
exista a password em pleno texto (O utilitário ‘XMLwsClient.exe’ no botão ‘outros
logins’, contém uma secção para o cálculo de hashs).
Mesmo com a password ‘digerida’, é muito importante escolher uma password forte
(letras maiúsculas/minúsculas/números e símbolos), para evitar ataques do tipo
‘dicionário’^17.

16

Não deveria ser possível, mas como se irá mostrar de seguida, para pequenos textos como as passwords,
infelizmente existem formas de o fazer...

(^17) Percorre-se uma lista de números ou palavras habitualmente usadas, faz-se hash de cada elemento e compara-se
com o hash da digestão. Se for igual, a password foi localizada...

(^)
(^)
Apêndice H – Comunicação Segura
Para manter um nível de confidencialidade adequado, o servidor XML ARTSOFT
permite que todos os dados (o XML transportado no ‘body’ da mensagem HTTP) sejam
encriptados.
Pode ser configurado para que todas as mensagens devam ser encriptadas (com
Encript=S na configuração), ou a pedido do cliente (enviando no tipo de mensagem ‘bin/xml’
em vez de ‘text/xml’).
Independentemente da configuração, determinados serviços só podem ser
executados mediante uma comunicação segura, pois são demasiado perigosos para serem
expostos a escutas na rede, como os serviços de atribuição de palavas-passe e todos os
relacionados com recursos humanos.
Para efetuar as operações de cifra e decifra, é necessária uma chave com 20 bytes /
160 bits. Para a construir, deve fazer-se:

SHA1: Criar um array temporário de 40 bytes, e um array para a chave com 20 bytes.
Colocar nos primeiros 20 bytes do array temporário o hash SHA1 da password do
cliente^18 , (dado constante conhecido de ambos os lados, mas que nunca transitou na
rede), nos segundos 20 bytes o digest do desafio enviado pelo servidor (dado aleatório
variável por cada ligação), e por fim colocar no array chave o digest SHA1 do array
temporário.
MD5: Criar um array temporário de 32 bytes, e um array para a chave com 20 bytes.
Colocar nos primeiros 16 bytes do array temporário o hash MD5 da password do cliente,
(dado constante conhecido de ambos os lados, mas que nunca transitou na rede), nos
segundos 16 bytes o digest do desafio enviado pelo servidor (dado aleatório variável por
cada ligação), e por fim colocar nos primeiros 16 bytes do array chave o digest MD5 do

18

NOTA: Sendo a password um dado constante, esta operação pode já estar previamente feita, e assim a aplicação
cliente apenas coloca os bytes pré-digeridos nos primeiros 20 bytes do array temporário, evitando assim ter a password exposta
em pleno texto na aplicação (e portanto vulnerável a ataques) ou evitando o trabalho de a manter encriptada na aplicação,
que pode também estar vulnerável se o algoritmo de cifra for fraco. Mais sobre este assunto em ‘Algoritmos de validação de
clientes’, na pág. 45.

(^)
(^)
array temporário, e complementar os 4 bytes restantes com a cópia do 4º, 8, 12º e 16º
byte do mesmo array.
Para cifrar a mensagem do body deve efetuar-se a operação XOR de cada byte da
string XML com o respetivo byte da chave. Quando esgotada a chave, deve voltar-se ao início
desta. O resultado da encriptação deve ser enviado na mensagem HTTP com o ‘Content-
Type=bin/xml’.
Para decifrar a mensagem do body, depois de recebido o stream XML cifrado, deve
efetuar-se o mesmo procedimento descrito para a cifra (efetuando XOR de cada byte do
stream com o respetivo byte da chave). Depois desta operação, obtém-se o XML original.
A mensagem vai passar a circular em binário, e qualquer erro de cifra ou adulteração
da mensagem vai produzir um resultado imprevisível. Para evitar estar a fazer parsing de
um XML inválido, é adicionada uma chave no cabeçalho HTTP com o checksum simples de
32 bits (soma de todos os bytes da mensagem antes de cifrada módulo 0xFFFFFFFF). Essa
chave deve chamar-se ‘Checksum’ e conter o valor do checksum em hexadecimal, ex:
“checksum: 89abcdef”.
Assim, o cliente, ao receber uma mensagem cifrada deve decifrá-la, efetuar o
checksum do resultado e verificá-lo com o obtido no cabeçalho da mensagem. Se estiver
não estiver correto, deve fechar a ligação e mostrar um erro e / ou gerar um log, consoante
as circunstâncias. Quando enviar uma mensagem, deve calcular o checksum da mensagem,
cifrá-la, juntar a chave ‘Checksum’ e o respetivo valor e por fim enviar a mensagem.
Comunicação de dados em formato compactado
O servidor XML passou a suportar pedidos HTTP que tenham definido o tipo de
codificação da mensagem de resposta do servidor.
A implementação no servidor XML foi efetuada de acordo com a RFC 2616 Secc 14.3
e Secc 14.11.

(^)
(^)
De uma forma simplificada, o cliente ao efetuar um pedido HTTP ao servidor, pode
indicar qual ou quais os tipos de codificação que aceita^19 , e o servidor ao enviar a resposta
deverá compactar a mensagem e enviá-la desta forma, desde que devidamente identificado
o algoritmo de codificação.
De momento estão implementados os algoritmos gZip (RFC 1952), deflate (RFC
1950/1951) e identity (sem qualquer compactação).
Nos pedidos e mensagens de Login, não são usados quaisquer tipos de compactação.
Nos pedidos e mensagens cifradas também não são usados quaisquer tipos de
compactação.^20
Para o correto preenchimento dos atributos no Header da mensagem HTTP, deve
consultar a respetiva RFC 2616 Secc 11.3.
Aconselha-se a leitura da respetiva documentação técnica em
http://www.ietf.org/rfc/rfc2616.txt
O servidor XML também aceita pedidos HTTP efetuados pelos clientes, com conteúdo
compactado, desde que sejam seguidas as regras descritas na RFC 2616, relativamente ao
envio do BodyMessage de forma compactada.^21
É possível definir que o servidor XML nunca responde de forma compactada,
independentemente do pedido Request, efetuado pelo cliente, especificar que aceita dados
compactados. Para forçar este comportamento, é necessário inserir uma chave específica

19

De acordo com a RFC 2616 Secc 11.3 o pedido pode conter atributos que indicam os tipos de codificação aceites
na resposta do servidor. Por exemplo:
Accept-Encoding: compress, gzip
Accept-Encoding:
Accept-Encoding: *
Accept-Encoding: compress;q=0.5, gzip;q=1.0
Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
Aconselha-se a leitura da respetiva documentação técnica em http://www.ietf.org/rfc/rfc2616.txt

(^20) Nos pedidos ao servidor cifrados, caso fosse utilizada qualquer forma de compactação, o efeito seria o contrário
ao pretendido, uma vez que uma mensagem cifrada ao ser compactada iria ser expandida em vez de compatada.
(^21) Ao efetuar um pedido http ao servidor XML, se pretender enviar o conteudo da mensagem de forma compactada,
deverá ser inserido no Header da mensagem o atributo “Content-Encoding” com o respetivo algoritmo de compressão utilizado
na mensagem (exemplo: “Content-Encoding: gzip”).

(^)
(^)
(“ AcceptCompact ”)na secção “XMLSERVEREX” com o valor ‘N’ (ver a secção deste manual
referente à configuração do servidor XML).
Apêndice I - Configuração do servidor
No ficheiro de configuração do serviço ArtExec , devem ser preenchidos os campos
normais já descritos na formação de serviços ARTSOFT.
Se forem usados serviços que processem formulários, deverá existir na secção
[CONFIG]:
[CONFIG]
PathFrm=\ARTSOFT\Forms
Lista de DLL’s, serviços e dependências

ArtDB_A – Serviços relacionados com a gestão de artigos e stocks. Depende de ArtDB_B.
ArtDB_B – Queries. Serviços informativos. Serviços relacionados com tabelas de
configurações.
ArtDB_T - Serviços relacionados com a gestão de terceiros. Depende de ArtDB_B.
ArtDB_P - Serviços relacionados com a contabilidade. Depende de ArtDB_B e T
ArtDB_D - Serviços relacionados com documentos. Depende de ArtDB_A, B, T e P
ArtDB_S – Serviços relacionados com salários. Depende de ArtDB_T e P
ArtDB_V – Serviços relacionados com vendedores. Depende de ArtDB_T e S
DocPrintCmd - Impressão interativa de documentos de faturação. Depende de ArtDB_A,
B, T, P e D.
DocPrintSvc – Serviço de impressão de documentos de faturação. Depende de ArtDB_A,
B, T, P e D.
SqlQrySvc – Serviço de queries SQL.

Apêndice J – Serviço XML de integração com plataformas B2C

A ARTSOFT disponibilizou um serviço XML B2C que possibilita a implementação de
integração de plataforma B2C com o ARTSOFT.
Ao ativar este Serviço no licenciamento ficam disponíveis os seguintes serviços xml:

Queries/SQL Query

(^)
(^)

Queiries / Query
DocFch/DocInsert
DocFch/DocUpdate
DocFch/DocPrintEx
TerFch/Update
StkFch/Getimage

Estes serviços estão descritos neste manual, e são os que estarão disponíveis quando
a vossa licença tiver este licenciamento ativo.

Apêndice K – Validação de Logins

A fim de manter a confidencialidade da password de um contacto de terceiro,
utilizador ARTSOFT, empregado ou independente entre um servidor WEB e o browser, sem
ter que recorrer à encriptação da comunicação via SSL/TLS (evitando o uso de certificados
digitais^22 ), este serviço permite que a plataforma de internet da empresa delegue nele a
tarefa de acreditação do utilizador, tornando muito fácil a manutenção de utilizadores a
partir do próprio ERP, mantendo estes associados à ficha de terceiro.
Assim, a plataforma WEB deve apresentar algures uma entrada para a área
reservada, com pelo menos duas entradas: uma para a identificação do utilizador, e outra
para a password, e o correspondente botão ‘OK’ ou similar.

Ao enviar o formulário que contenha estes campos para o browser, deve incluir
também um valor invisível, que deverá ser gerado nesse momento, constituindo este o
‘seed’. Para que tenha a segurança desejada, este deverá ter pelo menos 16 dígitos gerados
aleatoriamente por ferramentas criptográficas. Deve ser também enviado ao browser o
código^23 que execute o algoritmo de ‘hash’ descrito a seguir.

(^22) Nota: Deve recorrer-se sempre à comunicação encriptada sempre que o tipo de informação transferida tenha carácter de^
confidencialidade e valor que o justifique. O processo aqui descrito é susceptível a ataques difíceis, mas possíveis, de um hacker construir uma
réplica da página WEB a atacar, conseguir desviar o utilizador para este site, e capturar-lhe o login. Porém este tipo de ataque é sempre possível
mesmo que a página use SSL/TLS, pois o utilizador médio nunca presta atenção se a página tem ou não um ‘cadeado’.
(^23) Em javascript por exemplo.

(^)
(^)
O browser deve então pedir ao utilizador o identificador e a sua password, formatá-
los da seguinte forma “ [UserID]~[Password] ”^24 , calcular o respetivo digest em SHA1 e
guardá-lo nos primeiros 20 bytes do array ‘Result’. Se seguida calcular o digest SHA1 do
‘seed’ (desafio) e colocá-lo nos segundos 20 bytes, efetuando depois o digest SHA1 do array
resultado sendo o resultado colocado no array buffer. Este resultado deve ser convertido
para hexadecimal (40 dígitos) e juntamente com o UserID, deve ser enviado pelo browser
ao servidor WEB. Este guardou em sessão o ‘seed’ que enviou ao browser, recebe o ‘UserID’
e o ‘digest’, e devolve estes três elementos ao servidor XML ARTSOFT. Pseudo-código:
char buffer[20],result[40+1]
SHA1(in [UserID]~[Passw], out &result[0])
SHA1(in Seed, out & result[20])
SHA1(in result, out buffer)
Hexa(in buffer, out result)
Nota 1 : Depois de enviar o pedido ao servidor XML ARTSOFT, deve limpar de imediato o
‘seed’, e agir de acordo com a resposta recebida. Deve ter em atenção que a receção de
um POST de login sem que o servidor tenha um ‘seed’ válido, pode tratar-se de um ataque
de reply (alguém, entre o servidor WEB e o browser) guardou uma resposta válida e está a
tentar obter um login ilegal.
Nota 2 : O uso da técnica de não guardar o ‘seed’ em sessão e enviá-lo num campo input do
tipo ‘hidden’ (mesmo que encriptado) para que o browser o devolva juntamente com os
restantes atributos, fica sujeito um ataque de reply sem hipótese de ser detetado...
Nota 3 : Estes pedidos de login do servidor Web ao XML Server devem ser encriptados para
evitar que alguém na rede interna intercepte estes pedidos e ganhe acesso aos dados que
estes protegem, que no caso de um ‘contacto de terceiro’ não é muito útil, mas em
Utilizadores ARTSOFT , Empregados e Independentes , seria muito apetecível (e com graves
consequências). Por essa razão, os serviços relativos a Empregados e Independentes e o
login de Utilizadores ARTSOFT só podem ser aceites se vierem encriptados.

Serviços relacionados: Erro! A origem da referência não foi encontrada.
TerFch/ Login
GrhEmp/ Login

24
A formatação é feita desta forma para evitar ataques de dicionário às palavras-passe mais ingénuas, que, mesmo
convertidas em hash, são possíveis de encontrar bases de dados destas na internet.

(^)
(^)

GrhInd/Login

Apêndice L – Status WinSock

A seguir são listados os status winsock que poderão ser devolvidos pelos serviços, que
poderão ser uma ajuda para determinar a causa de uma falha de operação.

Status ID do status Descrição
258 WAIT_TIMEOUT Tempo máximo de espera atingido
10013 WSAEACCES Não permitido acesso ao socket com as atuais permissões
10014 WSAEFAULT Detetado endereço de pointer inválido numa chamada ao WinSock
10022 WSAEINVAL An invalid argument was supplied
10024 WSAEMFILE Número de sockets em uso excedeu o limite do sistema operativo
10038 WSAENOTSOCK An operation was attempted on something that is not a socket
10049 WSAEADDRNOTAVAIL O endereço pedido não é válido

Achou este artigo útil?

Artsoft

Manual ARTSOFT Certified Specialist Gestão Comercial INDÍCE - Introdução ...

Pesquisar Artigos da Base de Dados

XML Servcice

XML Interface

5

O

• ...

11

15

16

18

19

Achou este artigo útil?

Artigos relacionados

Artsoft