SmartAPI — SmartDigit

Centro do produto

Integração e API SmartDigit. Manuais na wiki SmartDigit.

5 versões 25 entradas Actualizado em 02/07/2026

Correcção

Reforço da segurança nas comunicações da API

Foram reforçadas as proteções de segurança nas respostas da API e deixou de ser possível aceder a funcionalidades protegidas sem autenticação ou sem licença válida em determinados cenários internos, aumentando a fiabilidade do controlo de acessos.

Nova funcionalidade

Impressão de documentos em fila para evitar conflitos

Os pedidos de impressão de documentos passam a ser processados em fila, um de cada vez, evitando problemas quando são pedidas várias impressões ao mesmo tempo.

Nova funcionalidade

Pasta de destino de PDFs configurável

É agora possível configurar a pasta onde os ficheiros PDF gerados são guardados, através de uma nova opção nas definições da aplicação.

Correcção

Tratamento correto de pastas de PDF vazias

Quando não existe nenhum ficheiro PDF na pasta de destino configurada, a aplicação deixa de gerar um erro inesperado e passa a devolver uma mensagem clara a indicar que não foi encontrado qualquer ficheiro.

Nova funcionalidade

Filtragem por vários documentos e séries na consulta de transações

A consulta de transações de artigos passa a permitir indicar mais do que um documento ou série em simultâneo, devolvendo os resultados correspondentes a todas as combinações pedidas.

Correcção

Correção na consulta de artigos e transações

Foram corrigidos vários erros na consulta e processamento de transações de artigos: a listagem de componentes de um artigo passa a respeitar a ordem correta, evita-se um erro ao processar clientes sem número de contribuinte definido e corrige-se um problema ocasional no registo de pagamentos com vale que podia impedir a conclusão do documento.

Nova funcionalidade

Opção para usar a licença do programa de faturação na instalação

No assistente de instalação passa a existir a opção "Usar licença Sage (se aplicável)". Ao ativar esta opção, deixa de ser necessário introduzir manualmente uma chave de licença, sendo esta obtida automaticamente a partir da licença já existente no programa de faturação.

Nova funcionalidade

Configuração de certificado de segurança na instalação

O processo de instalação passa a incluir uma ferramenta que cria e configura automaticamente um certificado de segurança, facilitando a disponibilização do serviço através de ligação encriptada sem passos manuais adicionais.

Nova funcionalidade

Início de sessão com autenticação por token

Passa a ser possível autenticar os pedidos através de um token de acesso, além da chave de API já existente. A chave de acesso pode agora ser enviada tanto no cabeçalho tradicional como no cabeçalho de Autorização, o que facilita a integração com sistemas que já usam este método padrão.

Nova funcionalidade

Suporte a múltiplas licenças em simultâneo

O serviço passa a poder ter mais do que uma licença ativa ao mesmo tempo. Assim, se a mesma instalação tiver, por exemplo, acesso ao módulo de pagamentos e ao módulo de expedições, ambos ficam disponíveis sem ser necessário escolher apenas um. O acesso a cada grupo de funcionalidades é agora controlado automaticamente consoante as licenças ativas, e a documentação da API apresentada apenas mostra os pedidos que a instalação está autorizada a usar.

Nova funcionalidade

Configuração de dependências do serviço na instalação

O processo de instalação passou a permitir definir de que outros serviços do Windows este serviço depende, para que arranque apenas depois desses serviços estarem disponíveis. As dependências são indicadas no ficheiro de configuração da instalação e aplicadas automaticamente ao serviço durante a instalação.

Nova funcionalidade

Novo serviço de expedições de encomendas

Foi adicionado um novo serviço para gerir expedições de encomendas, com consulta dos perfis de transportadora disponíveis e envio de pedidos de expedição diretamente a partir da aplicação. As mensagens de erro, como "Empresa não encontrada" ou "Perfil não encontrado", estão agora disponíveis em português e inglês.

Nova funcionalidade

Consulta de artigos com filtros e paginação

Foi disponibilizada uma nova forma de consultar artigos que permite aplicar filtros mais avançados e obter os resultados paginados, tornando mais eficiente a pesquisa de grandes quantidades de artigos.

Nova funcionalidade

Mais detalhe nas mensagens de erro ao validar documentos

As mensagens devolvidas quando a validação de um documento falha passaram a incluir mais informação de contexto, facilitando a identificação da causa do problema, nomeadamente em situações relacionadas com IVA em vendas eletrónicas.

Nova funcionalidade

Opção para imprimir o documento na impressora predefinida

Ao criar um documento através da integração, passou a ser possível indicar que o mesmo deve ser impresso automaticamente na impressora predefinida do sistema.

Correcção

Nome do cliente omitido corretamente em documentos de consumidor final

Em documentos de determinado tipo (fatura simplificada), quando o cliente identificado é o "Consumidor Final", o nome deixa de ser incluído no documento, respeitando a regra fiscal aplicável a este tipo de venda.

Nova funcionalidade

Desconto global do cliente aplicado automaticamente aos documentos

Quando um cliente tem configurado um desconto global e o documento não tem um desconto específico definido, esse desconto passa a ser aplicado automaticamente às transações desse cliente.

Correcção

Validação do valor total dos pagamentos aplicada antes da gravação do documento

A verificação de que o valor total dos pagamentos corresponde ao valor total do documento passou a ser feita no momento correto do processo, evitando que documentos com valores de pagamento incoerentes sejam gravados incorretamente.

Correcção

Aviso quando um artigo é enviado sem referência

Caso um documento inclua uma linha de artigo sem referência preenchida, é agora devolvida uma mensagem de erro específica a identificar a situação, em vez de o processamento falhar de forma pouco clara.

Nova funcionalidade

Aviso quando a quantidade indicada excede o máximo permitido

Ao processar um documento, se for indicada uma quantidade superior ao máximo configurado para um artigo, é agora devolvida uma mensagem clara a identificar os artigos em causa, em vez de o documento avançar com valores inválidos.

Correcção

Serviço deixa de reiniciar indevidamente quando a base de dados está indisponível

O serviço já não tenta reiniciar repetidamente quando não consegue estabelecer ligação à base de dados, evitando reinícios desnecessários e melhorando a estabilidade em situações de indisponibilidade temporária da base de dados.

Correcção

Registo de eventos corrigido ao usar um nome de serviço personalizado

Corrigido um problema em que os registos de eventos do serviço não eram gerados corretamente quando este era instalado com um nome diferente do habitual.

Nova funcionalidade

Nome do serviço personalizável na instalação

Passou a ser possível definir um nome próprio para o serviço instalado, em vez de este ser sempre gerado automaticamente a partir da empresa e do produto. Quando não é indicado um nome específico, mantém-se o comportamento habitual.

Nova funcionalidade

Novo ponto de verificação de disponibilidade do serviço

Foi adicionado um novo pedido de verificação de estado que permite confirmar rapidamente se o serviço está em funcionamento, sem necessidade de autenticação. Este ponto pode ser utilizado por ferramentas de monitorização para garantir que o serviço está sempre disponível.

API – Help document

How to see swagger to check json Struture – Access http://locahost:PORT/swagger

Go to endpoint v1/itemTransaction for example, and you can see example value to structure (this endpoint is used for Sales and Purchase documents):

Using QUERY Endpoint to get data:

Sage 50c Database Tables Structure: https://smartdigit.pt/SageDataDicionary.html

QUERY Endpoint: http://locahost:PORT/swagger/ui/index#!/Query/Query_V2Post

How to retrieve exception logs:

SELECT TOP(10) * FROM UX_SD_LOGS

How to filter by date

SELECT i.itemID, ItemNames.Description, i.ItemPictureName, i.FamilyID, f.Description
FROM Item I
INNER JOIN ItemNames ON i.itemID = ItemNames.ItemID
INNER JOIN Family f ON f.FamilyID = i.FamilyID
WHERE ItemNames.LanguageID = 'PTG' AND
CONCAT(CONVERT(VARCHAR(10), i.DtAlt, 120),' ', CAST(CONVERT(VARCHAR,DATEADD(SECOND, i.HrAlt*86400, 0),108) AS TIME)) > '2021-02-20 10:00:00'

SELECT        ItemID, BarCode, BarCodeType, ColorID, SizeID, PropertyID1, Description, UnitPrice, UnitOfSaleID, MaximumDecimals, Quantity, FindON, ItemType
FROM            (SELECT        i.ItemID, i.BarCode, i.BarCodeType, ISNULL(c.ColorID, 0) AS ColorID, ISNULL(s.SizeID, 0) AS SizeID, ISNULL(i.PropertyID1, NULL) AS PropertyID1, [in].Description,
                                                    CASE WHEN ispS.UnitPrice > 0 THEN ispS.UnitPrice ELSE isp.UnitPrice END AS UnitPrice, i.UnitOfSaleID, um.MaximumDecimals, NULL AS Quantity, 1 AS FindON, i.ItemType
                          FROM            dbo.Item AS i INNER JOIN
                                                    dbo.ItemNames AS [in] ON i.ItemID = [in].ItemID AND [in].LanguageID =
                                                        (SELECT        DefaultLanguageID
                                                          FROM            dbo.ConfSystem) INNER JOIN
                                                    dbo.UnitOfMeasure AS um ON um.UnitOfMeasureID = i.UnitOfSaleID INNER JOIN
                                                    dbo.ItemSellingPrices AS isp ON i.ItemID = isp.ItemID AND isp.PriceLineID = 1 AND isp.SizeID = 0 LEFT OUTER JOIN
                                                    dbo.ItemColor AS c ON i.ItemID = c.ItemID LEFT OUTER JOIN
                                                    dbo.ItemSize AS s ON i.ItemID = s.ItemID LEFT OUTER JOIN
                                                    dbo.ItemSellingPrices AS ispS ON i.ItemID = ispS.ItemID AND ispS.PriceLineID = 1 AND ispS.SizeID = s.SizeID
                          WHERE        (i.Discontinued = 0)
                          UNION
                          SELECT        POSi.ItemID, POSi.POSItemID, POSi.BarCodeType, ISNULL(POSi.ColorID, 0) AS ColorID, ISNULL(POSi.SizeID, 0) AS SizeID, ISNULL(i.PropertyID1, NULL) AS PropertyID1,
                                                   CASE WHEN POSi.Description <> '' THEN POSi.Description ELSE [in].Description END AS Description,
                                                   (CASE WHEN POSi.SalePrice > 0 THEN POSi.SalePrice ELSE (CASE WHEN ispS.UnitPrice > 0 THEN ispS.UnitPrice ELSE isp.UnitPrice END) END) AS UnitPrice, POSi.UnitOfMeasure, um.MaximumDecimals,
                                                   POSi.Quantity, 3 AS FindON, i.ItemType
                          FROM            dbo.POSIdentity AS POSi INNER JOIN
                                                   dbo.Item AS i ON POSi.ItemID = i.ItemID INNER JOIN
                                                   dbo.ItemNames AS [in] ON POSi.ItemID = [in].ItemID AND [in].LanguageID =
                                                       (SELECT        DefaultLanguageID
                                                         FROM            dbo.ConfSystem) INNER JOIN
                                                   dbo.UnitOfMeasure AS um ON um.UnitOfMeasureID = POSi.UnitOfMeasure INNER JOIN
                                                   dbo.ItemSellingPrices AS isp ON POSi.ItemID = isp.ItemID AND isp.PriceLineID = 1 AND isp.SizeID = POSi.SizeID LEFT OUTER JOIN
                                                   dbo.ItemSellingPrices AS ispS ON POSi.ItemID = ispS.ItemID AND ispS.PriceLineID = 1 AND ispS.SizeID = POSi.SizeID
                          WHERE        (POSi.POSItemID <> '') AND (i.Discontinued = 0)) AS T

CONCAT(CONVERT(VARCHAR(10), i.DtAlt, 120),' ', CAST(CONVERT(VARCHAR,DATEADD(SECOND, i.HrAlt*86400, 0),108) AS TIME)) > '2021-02-20 10:00:00'

Item list filtered by the language PTG and the date of the last change

dfsdf

SELECT i.itemID, ItemNames.Description, i.ItemPictureName, i.FamilyID, f.Description
FROM Item I
INNER JOIN ItemNames ON i.itemID = ItemNames.ItemID
INNER JOIN Family f ON f.FamilyID = i.FamilyID
WHERE ItemNames.LanguageID = 'PTG' AND
CONCAT(CONVERT(VARCHAR(10), i.DtAlt, 120),' ', CAST(CONVERT(VARCHAR,DATEADD(SECOND, i.HrAlt*86400, 0),108) AS TIME)) > '2021-02-20 10:00:00'

SELECT        ItemID, BarCode, BarCodeType, ColorID, SizeID, PropertyID1, Description, UnitPrice, UnitOfSaleID, MaximumDecimals, Quantity, FindON, ItemType
FROM            (SELECT        i.ItemID, i.BarCode, i.BarCodeType, ISNULL(c.ColorID, 0) AS ColorID, ISNULL(s.SizeID, 0) AS SizeID, ISNULL(i.PropertyID1, NULL) AS PropertyID1, [in].Description,
                                                    CASE WHEN ispS.UnitPrice > 0 THEN ispS.UnitPrice ELSE isp.UnitPrice END AS UnitPrice, i.UnitOfSaleID, um.MaximumDecimals, NULL AS Quantity, 1 AS FindON, i.ItemType
                          FROM            dbo.Item AS i INNER JOIN
                                                    dbo.ItemNames AS [in] ON i.ItemID = [in].ItemID AND [in].LanguageID =
                                                        (SELECT        DefaultLanguageID
                                                          FROM            dbo.ConfSystem) INNER JOIN
                                                    dbo.UnitOfMeasure AS um ON um.UnitOfMeasureID = i.UnitOfSaleID INNER JOIN
                                                    dbo.ItemSellingPrices AS isp ON i.ItemID = isp.ItemID AND isp.PriceLineID = 1 AND isp.SizeID = 0 LEFT OUTER JOIN
                                                    dbo.ItemColor AS c ON i.ItemID = c.ItemID LEFT OUTER JOIN
                                                    dbo.ItemSize AS s ON i.ItemID = s.ItemID LEFT OUTER JOIN
                                                    dbo.ItemSellingPrices AS ispS ON i.ItemID = ispS.ItemID AND ispS.PriceLineID = 1 AND ispS.SizeID = s.SizeID
                          WHERE        (i.Discontinued = 0)
                          UNION
                          SELECT        POSi.ItemID, POSi.POSItemID, POSi.BarCodeType, ISNULL(POSi.ColorID, 0) AS ColorID, ISNULL(POSi.SizeID, 0) AS SizeID, ISNULL(i.PropertyID1, NULL) AS PropertyID1,
                                                   CASE WHEN POSi.Description <> '' THEN POSi.Description ELSE [in].Description END AS Description,
                                                   (CASE WHEN POSi.SalePrice > 0 THEN POSi.SalePrice ELSE (CASE WHEN ispS.UnitPrice > 0 THEN ispS.UnitPrice ELSE isp.UnitPrice END) END) AS UnitPrice, POSi.UnitOfMeasure, um.MaximumDecimals,
                                                   POSi.Quantity, 3 AS FindON, i.ItemType
                          FROM            dbo.POSIdentity AS POSi INNER JOIN
                                                   dbo.Item AS i ON POSi.ItemID = i.ItemID INNER JOIN
                                                   dbo.ItemNames AS [in] ON POSi.ItemID = [in].ItemID AND [in].LanguageID =
                                                       (SELECT        DefaultLanguageID
                                                         FROM            dbo.ConfSystem) INNER JOIN
                                                   dbo.UnitOfMeasure AS um ON um.UnitOfMeasureID = POSi.UnitOfMeasure INNER JOIN
                                                   dbo.ItemSellingPrices AS isp ON POSi.ItemID = isp.ItemID AND isp.PriceLineID = 1 AND isp.SizeID = POSi.SizeID LEFT OUTER JOIN
                                                   dbo.ItemSellingPrices AS ispS ON POSi.ItemID = ispS.ItemID AND ispS.PriceLineID = 1 AND ispS.SizeID = POSi.SizeID
                          WHERE        (POSi.POSItemID <> '') AND (i.Discontinued = 0)) AS T

Get document identifiers and filter them by date

SELECT TransDocument, TransSerial, TransDocNumber, CONCAT(CONVERT(VARCHAR(10), DtAlt, 120),' ', CAST(CONVERT(VARCHAR,DATEADD(SECOND, HrAlt*86400, 0),108) AS TIME)) AS DtAlt FROM SaleTransaction 
WHERE CONCAT(CONVERT(VARCHAR(10), DtAlt, 120),' ', CAST(CONVERT(VARCHAR,DATEADD(SECOND, HrAlt*86400, 0),108) AS TIME)) > '2021-03-20 23:59:00'

Get list Open unpaid document of specific customer ordered by deferred payment date

SELECT CreateDate, DeferredPaymentDate, ContractReferenceNumber, TransSerial, TransDocument, TransDocNumber, TransInstallmentID, TotalAmount, TotalPendingAmount, DebitTotalAmount, CreditTotalAmount, PartyAccountTypeID, PartyAddressID
FROM CustomerLedgerAccount
  where TotalPendingAmount <> '0' and PartyID = '1'
  Order By DeferredPaymentDate

Manual (SmartAPI)

Minimum requirements:

.NET Framework 4.7.2
Database in SQL Server 2016 or above
Sage 2021 version or above

Introdução

A SmrtAPI é um produto que transforma toda a camada do sage numa WebAPI, conseguem com isso fazer qualquer operação que fazem em sage na SmartAPI.
Exemplos:
Criar/alterar/apagar Documentos
Criar/alterar/apagar Artigos
Criar/alterar/apagar qualquer tabela, documento
Comunicar guias á AT
Imprimir Documentos
Gerar Safts
e muito mais

Manual de instalação

O processo de instalação da extensibilidade é bastante simples.
Pedimos ao utilizador que siga os passos abaixo indicados para instalar o produto SmartAPI.
Para a utilização a base de dados deve correr numa versão SQL Server 2016 ou superior.

Passo 1 – Instalação

Executar o exe de instalação do produto como administrador.

Irá ser apresentado o quadro de configuração, que irá servir para fazermos a ligação ao Sage

Versao Sage: Devemos selecionar se estamos a usar o 50c faturação ou 50c Loja
Empresa: ID/Nome da empresa (a mesma definida na area de sistema do sage)
Chave de Licença: Chave de licenciamento da aplicação SmartAPI
ID da Máquina: Caso pretendamos que o serviço use um machideID diferente do servidor, devemos indicar qual o machineID definido na conf de postos do Sage. (opcional)
Nome do Serviço: Nome a dar ao serviço (opcional)

Uma vez instalada a SmartAPI com sucesso, podemos verificar que foi criado um serviço no windows de nome SmartAPI.Sage50cLoja

Esse serviço é responsável por colocar em funcionamento toda a SmartAPI, para verificarmos se a API está em fucnionamento depois de garantir que o serviço está a correr sem problemas, na maquina onde foi instalada a smartAPI devemos abrir o seguinte link no browser http://localhost:5581/swagger/ui/index

Irá ser mostrado o swagger da api onde têm ativos todos os endpoints que o licencimaneto pedido tem acesso.

NOTAS
Caso pretendam alterar a API_KEY ou a porta default (5581) da SmartAPI devem editar o seguinte ficheiro
C:\SmartApps\API\Service\SmartAPI.ini

nesse ficheiro encontramos as seguintes settings
X-API-KEYS=pass de acesso á api, caso coloquem varias senhas, devem separar as mesmas por ponto e virgula, ficando algo como A-API-KEYS=DEMO1;DEMO2;DEMO3
APIPort=porta usada pela SmartAPI

De notar que qualquer alteração que façam ao ficheiro em questão, devem reiniciar o serviço SmartAPI, para que as novas configurações sejam carregadas no arranque.

Downloads

Ficheiro	Tamanho	Data
API202302001.v21.05.05.exe	154 MB	10/07/2026	Descarregar
API202302001.v21.05.04.exe	154 MB	25/06/2026	Descarregar
API202302001.v21.05.03.exe	152 MB	29/04/2026	Descarregar

21.5.5

Reforço da segurança nas comunicações da API

Impressão de documentos em fila para evitar conflitos

Pasta de destino de PDFs configurável

Tratamento correto de pastas de PDF vazias

Filtragem por vários documentos e séries na consulta de transações

Correção na consulta de artigos e transações

21.5.4

Opção para usar a licença do programa de faturação na instalação

Configuração de certificado de segurança na instalação

Início de sessão com autenticação por token

Suporte a múltiplas licenças em simultâneo

21.5.2

Suporte a modo offline nas transações e fecho de período

21.5.1

Configuração de dependências do serviço na instalação

Novo serviço de expedições de encomendas

21.4.54

Consulta de artigos com filtros e paginação

Mais detalhe nas mensagens de erro ao validar documentos

Opção para imprimir o documento na impressora predefinida

Nome do cliente omitido corretamente em documentos de consumidor final

Desconto global do cliente aplicado automaticamente aos documentos

Validação do valor total dos pagamentos aplicada antes da gravação do documento

Aviso quando um artigo é enviado sem referência

Aviso quando a quantidade indicada excede o máximo permitido

Serviço deixa de reiniciar indevidamente quando a base de dados está indisponível

Registo de eventos corrigido ao usar um nome de serviço personalizado

Nome do serviço personalizável na instalação

Novo ponto de verificação de disponibilidade do serviço

Using QUERY Endpoint to get data:

Introdução

Manual de instalação

Passo 1 – Instalação

Instalação

Instalação