# 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ódigo HTTP | Causa Provável | Solução |
| :---- | :---- | :---- |
| **415 Unsupported Media Type** | Cabeçalhos Ausentes | Certifique-se de enviar `Content-Type: application/json`. |
| **400 Bad Request** | Sintaxe JSON | Você pode estar enviando valores `null` (proibido) ou JSON malformado. |
| **500 Internal Server Error** | Tipos de Dados Inválidos | Verifique se você está enviando uma String onde um Número é esperado (ou vice-versa). |

## 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.

| Código | Mensagem | Significado |
| :---- | :---- | :---- |
| **TPVPC0016** | *Comercio no posee terminal válido* | O número do terminal enviado (ex.: `1`) não está vinculado à sua conta de `comercio` nas configurações da nuvem. |
| **TPVPC0030** | *Sistema ocupado* | O terminal está ocupado processando outra requisição. Aguarde e tente novamente. |
| **TPVPC0060** | *No existe terminal apropiado* | Você solicitou uma bandeira de cartão (ex.: AMEX) que seu terminal não está configurado para aceitar. |

## Próximos Passos

* [**Padrões Gerais da API e Cabeçalhos**](/pt/get-smart/get-smart-api-cloud/reference/general-api-standards-and-headers)**:** Revise as regras estritas de formatação JSON.  
* [**Catálogo de Códigos de Erro e Negação**](/pt/get-smart/get-smart-api-cloud/reference/error-and-denial-code-catalog)**:** Uma lista completa de códigos de erro TPVPC para depuração mais profunda.