Guia de Solução de Problemas

Este guia ajuda-o a resolver problemas comuns ao trabalhar com a API do XD Soba.

Problemas Comuns

Erros de Autenticação

401 Não Autorizado

• Verifique se o seu token é válido e não expirou
• Confirme o formato do token: Bearer o_seu_token_aqui
• Certifique-se de que está a utilizar as credenciais corretas

403 Proibido

• Verifique se a sua conta possui as permissões necessárias
• Confirme se a sua chave de API está ativa
• Contacte o suporte se necessitar de acesso a endpoints específicos

Erros de Recurso

404 Recurso não encontrado

• Verifique se o URL do endpoint está correto
• Confirme se o ID do recurso existe
• Certifique-se de que o recurso não foi eliminado

Limitação de Pedidos

429 Demasiados Pedidos

• Verifique os cabeçalhos de limite de pedidos na resposta
• Implemente um recuo exponencial na sua lógica de tentativas
• Considere implementar cache para reduzir as chamadas à API

Erros de Validação

400 Pedido Inválido

• Verifique se todos os campos obrigatórios estão presentes
• Confirme os tipos de dados e formatos
• Certifique-se de que os formatos de data estão corretos (ISO 8601)
• Valide os comprimentos de texto e os intervalos numéricos

Erros de Servidor

500 Erro Interno do Servidor

• Este é um erro do lado do servidor — tente novamente após alguns segundos
• Se o erro persistir, contacte o suporte
• Inclua o valor do cabeçalho X-Request-ID ao reportar o problema

Códigos de Erro

Código	Descrição	Solução
Entity.Duplicated	Já existe uma entidade com este código.	Verifique o código da entidade e utilize um valor único
Entity.IsNotASupplier	A entidade requerida não é um fornecedor	Confirme se a entidade selecionada é do tipo fornecedor
Item.CanNotChangeSerialNumberType	Não é possível alterar o tipo de número de série, pois o item já possui documentos associados	O item já possui documentos associados, não sendo permitida a alteração
Item.InvalidPrinterNumber	O número da impressora deve estar entre 1 e 20.	Garanta que o número da impressora está dentro do intervalo permitido
ItemStock.NotFound	Registo de stock do item não encontrado.	Verifique se o item possui stock registado
PointsConfig.InvalidDateRange	A data de início não pode ser maior que a data de fim.	Garanta que a data de início é anterior ou igual à data de fim
Resource.ExceededFileSize	O tamanho do ficheiro excedeu o limite permitido.	Reduza o tamanho do ficheiro para dentro do limite permitido

Dicas de Depuração

Registo de Pedidos

Ative o registo de pedidos na sua aplicação:

// Exemplo em C#
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Debug", "true");

Cabeçalhos de Resposta

Verifique estes cabeçalhos para obter informações adicionais:

• X-Request-ID: Para rastreamento de pedidos
• X-RateLimit-*: Para informações sobre limites de pedidos
• X-Error-Code: Para códigos de erro detalhados

Soluções Comuns

1. Problemas com Tokens

   # Verificar o formato do token
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer o_seu_token_aqui" \
        -v

2. Limitação de Pedidos

   # Verificar os cabeçalhos de limite de pedidos
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer o_seu_token_aqui" \
        -I

3. Erros de Validação

   # Testar com payload mínimo
   curl -X POST "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Content-Type: application/json" \
        -d '{"campo_obrigatorio": "valor"}'

Obter Ajuda

Se continuar a ter problemas:

1. Consultar a Documentação
   • Reveja o Guia de Introdução
   • Leia o Guia de Utilização da API
   • Consulte a Referência da API