Pular para o conteúdo principal

Primeiros Passos

Bem-vindo à documentação da API XD Soba! Este guia vai ajudá-lo a começar com a nossa API, abordando autenticação, utilização básica e padrões comuns.

Introdução​

A API do XD Soba foi desenvolvida para facilitar a integração e o acesso programático aos principais serviços e dados da aplicação XD Soba.

Através desta API, é possível realizar operações como autenticação, consulta de dados, registo de acessos à base de dados e execução de outras tarefas essenciais, tudo de forma segura e eficiente.

Este guia destina-se a qualquer utilizador ou equipa técnica que pretenda configurar e utilizar a API do XD Soba, apresentando passo a passo o processo de obtenção de credenciais, configuração de acesso e execução de pedidos reais sobre a plataforma.

Pré-requisitos​

Antes de utilizar a API, é necessário ter uma conta XD Cloud ativa.

Criação de Conta XD Cloud através do XD Gestão Comercial​

Siga os passos abaixo para criar a sua conta XD Cloud:

Passo 1 – Aceder ao Menu Smart Connect​

Abra a aplicação XD Gestão Comercial, selecione o separador "Sistema" e clique no ícone "Smart Connect".

Menu Smart Connect

Passo 2 – Iniciar a Configuração de uma Nova Conta XD Cloud​

No separador Smart Connect, clique no botão correspondente ao XD Cloud (ícone da nuvem).

Botão XD Cloud

Passo 3 – Iniciar o Assistente​

Será aberto o Assistente para configurar o XD Cloud. Clique em "Seguinte" para avançar.

Iniciar Assistente

Passo 4 – Definir Opções da Conta​

  1. Selecione "Criar nova conta".
  2. Escolha a funcionalidade pretendida (por exemplo, "Resumo online").
  3. Marque a opção "Aceito instalar o serviço XD Web API" (se aplicável).
  4. Clique em "Seguinte".

Opções da Conta

Passo 5 – Inserir Credenciais da Conta​

  1. Introduza a senha da conta.
  2. Indique o nome da loja.
  3. Clique em "Processar".

Inserir Credenciais

Passo 6 – Processamento da Configuração​

Aguarde enquanto o sistema processa a configuração e instala os serviços necessários.

Processamento da Configuração

Passo 7 – Conclusão do Processo​

No final, verifique o relatório de sucesso e clique em "Terminar" para concluir.

Conclusão

Passo 8 – Confirmação da Conta Ativa​

Volte ao separador Smart Connect e confirme que a conta XD Cloud aparece como ativa.

Conta Ativa

Configurar a Ligação MySQL no Frontend do XD Soba​

Configurar a ligação da base de dados MySQL através do formulário de registo no frontend do XD Soba.

Fluxo de Configuração:​

  1. Aceder ao formulário de autenticação no frontend do XD Soba em https://xdsoba.com/ e preencher os dados de acesso.

Formulário de Login

Caso já tenha uma conta, mas a ligação ainda não esteja configurada, o sistema encaminhá-lo-á automaticamente para o formulário de registo da ligação, conforme ilustrado na imagem seguinte:

Formulário de Registo da Ligação

  1. Preencher os dados de ligação ao servidor no primeiro passo do registo:
    • Servidor: Endereço do servidor MySQL (ex: cloudserverxd0003.ddns.net ou IP do servidor)
    • Porta: Porta do MySQL (normalmente 3306)
    • Base de Dados: Nome da base de dados MySQL específica do tenant XDAO.5805
    • Utilizador: Nome de utilizador MySQL com permissões de acesso à base de dados
    • Password: Password do utilizador MySQL
    • Opções Extras: (opcional) Opções adicionais de ligação se necessário
  2. Submeter o formulário - O sistema:
    • Guardará automaticamente a cadeia de ligação no Azure Key Vault com a chave XDAO.5805
    • Avançará para o próximo passo (configuração de fuso horário)
    • Após completar o registo, a ligação estará configurada e o erro deixará de ocorrer
  3. Configuração Fuso Horário - Opcionalmente.

A configuração do fuso horário é um passo opcional que pode ser realizado após a configuração da ligação ou a qualquer momento posterior através do menu de Diversos.

Formulário de Registo da Ligação

Para definir o seu fuso horário manualmente, siga estes passos:

  1. Navegue até ao menu Diversos.
  2. Selecione a opção Geral.
  3. No menu superior da página, clique em Fuso Horário.
  4. Escolha o fuso horário desejado na lista e guarde a alteração.
info

Para configurar a ligação à base de dados, precisa de ter à mão:

  • Servidor MySQL: Endereço IP ou hostname do servidor MySQL
  • Porta: Porta de acesso ao MySQL (padrão: 3306)
  • Nome da Base de Dados: Nome da base de dados MySQL específica do tenant
  • Utilizador MySQL: Nome de utilizador com permissões de acesso à base de dados
  • Password MySQL: Password do utilizador

Autenticação e Obtenção do Token​

Após criar a conta XD Cloud, efetue o login para obter o token de autenticação que será utilizado no acesso aos endpoints do XD Soba.

Passos para efetuar o login:​

  1. Aceda ao endereço: https://api.xdsoba.com/swagger
  2. No menu da API, selecione o endpoint /gateway/auth/login.
  3. Preencha os campos no corpo do pedido (request body):
    • "user": Introduza a licença (conta XD Cloud).
    • "password": Introduza a sua palavra-passe.
  4. Clique em Execute para submeter o pedido.

Login no Swagger

Depois de executar o login com sucesso, irá receber uma resposta com o token.

Resposta com Token

info

Deve utilizar sempre a sua própria licença e password configurada no XD Gestão Comercial.

Como Utilizar o Token​

Em todos os pedidos aos endpoints da API, deverá incluir o token no cabeçalho da requisição:

Cabeçalho de Autorização

curl -X GET "https://api.xdsoba.com/gateway/item" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

Exemplos de Utilização dos Endpoints​

Depois de concluir todos os passos de configuração (criação da conta XD Cloud, login e configuração de acesso à base de dados), já pode utilizar os endpoints do XD Soba para aceder aos dados e funcionalidades disponíveis.

Exemplo 1: Consulta de Artigos (Items)​

Busca de Artigos

  1. No Swagger, selecione o endpoint GET /gateway/item.
  2. Preencha os parâmetros desejados (opcional):
    • skip: Número de registos a ignorar (útil para paginação).
    • pageSize: Quantidade de registos a retornar por página.
    • itemGroupId: Filtro por família.
  3. Clique em Execute para enviar o pedido.

Se tudo estiver correto (e o token de autenticação tiver sido colocado no cabeçalho Authorization), irá receber uma resposta com a lista de artigos disponíveis. Resposta de Artigos

Observações de Segurança​

  • Nunca partilhe os seus dados de acesso.
  • Não guarde credenciais em ficheiros partilhados.
  • Em caso de dúvida, contacte o suporte XD.

Autenticação​

Todos os pedidos à API requerem autenticação usando JWT (JSON Web Tokens). Para autenticar:

  1. Envie um pedido POST para /gateway/auth/login com as suas credenciais
  2. Use o token devolvido no cabeçalho Authorization para os pedidos subsequentes
curl -X POST "https://api.xdsoba.com/gateway/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"user": "seu_utilizador", "password": "sua_palavra_passe"}'

Inclua o token nos seus pedidos:

curl -X GET "https://api.xdsoba.com/gateway/item" \
     -H "Authorization: Bearer seu_token_aqui"

URL Base​

Todos os endpoints da API são relativos ao URL base:

https://api.xdsoba.com/gateway

Cabeçalhos Comuns​

Inclua estes cabeçalhos nos seus pedidos:

  • Authorization: Bearer <token> - Obrigatório para endpoints autenticados
  • Content-Type: application/json - Obrigatório para pedidos POST/PUT
  • Accept: application/json - Recomendado para todos os pedidos

Limitação de Pedidos​

Para garantir uma utilização justa e estabilidade do sistema, implementamos limitação de pedidos:

  • 100 pedidos por minuto por chave de API
  • Os cabeçalhos de limitação estão incluídos nas respostas:
    • X-RateLimit-Tier: Nome do Tier
    • X-RateLimit-Limit-PerMinute: Máximo de pedidos por janela
    • X-RateLimit-Window: Tempo até a limitação ser reiniciada

Tratamento de Erros​

A API usa códigos de estado HTTP padrão e devolve detalhes do erro no corpo da resposta:

{
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "errors": [
    {
      "code": "Item.NotFound",
      "description": "Item not found.",
      "type": 2,
      "furtherInformations": null
    }
  ]
}

Códigos de estado comuns:

  • 200 OK: Pedido bem-sucedido
  • 201 Created: Recurso criado com sucesso
  • 400 Bad Request: Parâmetros de pedido inválidos
  • 401 Unauthorized: Autenticação inválida ou em falta
  • 403 Forbidden: Permissões insuficientes
  • 404 Not Found: Recurso não encontrado
  • 429 Too Many Requests: Rate limit excedido
  • 500 Internal Server Error: Erro do lado do servidor

Próximos Passos​

Agora que compreende o básico, pode: