Depurar Problemas de Assinatura e Conectividade

A integração com a Get Smart API Cloud geralmente é direta, mas requisitos estritos de segurança e rede podem às vezes causar falhas nas requisições. Este guia aborda as duas categorias mais comuns de erros: Falhas de Validação de Assinatura e Problemas de Conectividade/Timeout.

Cenário 1: “Firma Incorrecta” (TPC0101)

O código de erro TPC0101 (“Firma Incorrecta”) é o problema mais frequente que os desenvolvedores encontram. Isso significa que o hash que você calculou no seu servidor não corresponde ao hash calculado pela API Cloud.

O Checklist de Diagnóstico

Se você receber este erro, verifique estas cinco armadilhas comuns:

1. Minimização de JSON

O Problema: Você está fazendo o hash de uma string JSON “formatada” (pretty-printed, com espaços e quebras de linha), mas enviando uma versão minimizada (ou vice-versa).

A Solução: A string que você faz o hash deve ser idêntica à string no campo info.

• Errado: Fazer o hash de {"amount": "10"} mas enviar {"amount": "10" } (note o espaço extra).
• Melhor Prática: Serialize seu objeto para uma string primeiro, faça o hash dessa string e, em seguida, coloque exatamente essa string no corpo da sua requisição.

2. Ordenação de Campos

O Problema: O JSON não é ordenado por padrão. Sua biblioteca JSON pode reordenar os campos (ex.: colocando terminal antes de comercio) ao serializar.

A Solução: Embora a API processe (parse) o JSON de forma flexível, a verificação da assinatura é uma comparação byte a byte. Certifique-se de que a string da qual você faz o hash tenha os campos exatamente na mesma ordem que a string que você envia pela rede.

3. Incompatibilidade de Chave de Ambiente

O Problema: Você está enviando uma requisição para a URL de Teste, mas assinando-a com sua Chave de Produção (ou vice-versa).

A Solução: Verifique suas variáveis de configuração.

• URL de Teste: https://tpvpc-i.redsys.es... requer o Segredo de Teste (frequentemente AAABBB na documentação, mas é exclusivo para você).
• URL de Produção: https://tpvpc.redsys.es... requer seu Segredo de produção (live).

4. Codificação de Caracteres

O Problema: Seu ID da Fatura (factura) contém caracteres especiais (ex.: “Café-001”) e está sendo submetido ao hash como ASCII em vez de UTF-8.

A Solução: Certifique-se de que as entradas da sua função de hash sejam explicitamente codificadas como UTF-8.

5. Caracteres de Escape

O Problema: Seu serializador JSON escapa barras normais (forward slashes) (ex.: https:\/\/).

A Solução: Se o seu serializador adicionar escapes à urlNotificacion, esses escapes farão parte da string e deverão ser incluídos no cálculo do hash.

Cenário 2: Timeouts de Conectividade

Se sua aplicação travar (hang) ou receber erros de conexão antes de obter uma resposta JSON, verifique sua configuração de rede.

1. Firewall e Portas

O Ambiente de Teste é executado em uma porta não padrão.

• Porta de Teste: 27443
• Porta de Produção: 443 (HTTPS Padrão)
• Ação: Certifique-se de que seu firewall de saída permita o tráfego para tpvpc-i.redsys.es na porta 27443.

2. Versão do TLS

A API requer TLS 1.2 ou superior.

• Sintoma: “Handshake Failure” ou “Connection Reset”.
• Ação: Se você estiver usando um servidor mais antigo (ex.: Java 7 antigo, .NET 4.5), pode ser necessário habilitar explicitamente o TLS 1.2 na configuração do seu cliente HTTP.

Cenário 3: “Bad Request” ou Erros Genéricos

Se a API retornar um erro HTTP padrão (400, 415, 500) sem um código de erro JSON específico:

Códigos de Erro Lógico Comuns

Uma vez que a conectividade e as assinaturas estejam funcionando, você pode enfrentar erros lógicos do terminal.

Próximos Passos

• Padrões Gerais da API e Cabeçalhos: Revise as regras estritas de formatação JSON.
• Catálogo de Códigos de Erro e Negação: Uma lista completa de códigos de erro TPVPC para depuração mais profunda.