Erros, Troubleshooting e Apêndices

Esta página consolida as diretrizes operacionais, o catálogo de resolução de falhas e o material de referência rápida para garantir uma integração segura, resiliente e de alta performance.

Boas Práticas de Integração

Segurança

• Proteção de Logs: Nunca registe dados em claro (como o conteúdo não-cifrado de p_ht_data, PINs ou PANs) em logs da aplicação, ferramentas de APM (Application Performance Monitoring) ou consolas.

• Gestão do Vetor de Inicialização (IV): Utilize sempre IVs aleatórios e únicos por cada operação quando utilizar os modos encadeados (01, 02 ou 03). Nunca reutilize um IV com a mesma chave.

• Preparação para Rotação de Chaves: Armazene sempre o keyId, os dados cifrados e o IV em conjunto na sua base de dados. Esta prática é essencial para suportar processos futuros de rotação de chave sem a necessidade de refazer a ingestão dos dados originais.

• Controlo de Acesso: Restrinja o acesso de rede ao endpoint apivin.first-tech.net através de uma allowlist de IPs, sempre que a arquitetura o permitir.

Performance

• Operações em Lote: Para cenários de alta volumetria, prefira utilizar o endpoint SuperDecryptData em vez de invocar o DecryptData individualmente para cada registo.

• Reutilização de Conexões: Reaproveite conexões HTTP (keep-alive). O serviço Hop V4 mantém uma conexão persistente e otimizada com o HSM.

• Gestão de Carga: Agende e distribua o processamento de batch jobs (lotes pesados) durante as janelas de menor movimento (off-peak), preservando assim a capacidade de processamento para as transações online de tempo real.

Códigos de Erro e Troubleshooting

O envelope de erro segue a mesma estrutura do envelope de sucesso. O campo retCode indica o tipo específico da falha, enquanto o retDesc carrega a descrição textual do problema .

Status HTTP e a Taxonomia de retCode

Status HTTP	Significado Padrão	retCode	Descrição do Erro Interno
200	Operação realizada com sucesso .	0	Sucesso absoluto.
400	Requisição inválida (campo ausente ou formato incorreto) .	-2	Formato inválido (ex.: data_fmt fora do enum esperado).
400	-	137	Malformação da requisição (estrutura comprometida).
401	Não autorizado (Token Bearer ausente ou inválido) .	-	Ocorre verificação antes de atingir o HSM.
404	Chave não encontrada no banco de dados.	155	O keyId fornecido não existe ou não pertence ao seu cliente.
400, 404, 500	Erro interno do servidor ou falha genérica .	-1	Erro interno.

Guia de Resolução Rápida (Troubleshooting)

A tabela abaixo cruza os sintomas mais comuns com as suas prováveis causas e ações corretivas recomendadas:

Sintoma Observado	Causa Provável	Ação Corretiva
HTTP 401 em todas as chamadas	Token expirado ou ausente.	Renovar o token no Auth0; verificar se o cabeçalho Authorization está bem formatado.
retCode 155	O keyId não está cadastrado para o client_id informado.	Conferir o provisionamento da chave com a equipa da First Tech.
retCode 137 (com payload "aparentemente" correto)	Campo obrigatório ausente, formato inválido ou erro de digitação (ex.: enviar p_h_data quando o endpoint exige p_ht_data).	Validar de forma rigorosa o JSON contra o dicionário de dados da API.
retCode -2 no DecryptData	O campo data_fmt é incompatível com o conteúdo fornecido.	Garantir que o data_fmt é igual a "H" para todo e qualquer dado cifrado enviado para decifragem.
iv retornando null em retMultiValue[1]	O modo de operação selecionado não consome nem gera IV (ex.: ECB).	Trata-se do comportamento normal e esperado para o modo 00.
Latência alta em SuperDecryptData	Tamanho do lote excede a capacidade ideal por requisição.	Reduzir a quantidade de itens no array p_h_data.
MAC inválido (retValid: false) no ValidateMac	A sequência multi-bloco executada no Host de destino está incorreta.	Validar que os valores de macModeFlag, a ordem das chamadas e o repasse do IV intermediário replicam exatamente o que foi feito na geração do MAC.
HTTP 400 sem retCode útil	O conteúdo (body) da requisição está malformado a nível do próprio JSON.	Validar o JSON antes do envio (usar um linter ou esquema validador).

---

Apêndice A. Glossário de Termos

Termo / Sigla	Definição
BDK	Base Derivation Key. Chave-mãe DUKPT a partir da qual as chaves de transação são derivadas.
CBC	Cipher Block Chaining. Modo de operação simétrico que encadeia os blocos via operação lógica XOR.
CFB	Cipher Feedback. Modo de operação que transforma uma cifra de bloco numa cifra de fluxo contínuo.
client_id	Identificador único do tenant (cliente) na plataforma Hop V4.
DUKPT	Derived Unique Key Per Transaction. Esquema criptográfico onde cada transação utiliza uma chave única que é derivada através do KSN.
ECB	Electronic Codebook. Modo de operação simétrico mais simples, que cifra cada bloco de forma independente.
HSM	Hardware Security Module. Dispositivo dedicado, de alta segurança, para a execução de operações criptográficas e gestão de chaves.
IV	Initialization Vector. Valor aleatório de partida utilizado nos modos encadeados (CBC, CFB).
JWT	JSON Web Token. Formato padrão do token de autenticação emitido pelo serviço Auth0.
keyId	Alias armazenado no banco de dados da plataforma que aponta para uma chave criptográfica física dentro do HSM.
KSN	Key Serial Number. Identificador necessário para realizar a derivação de chaves em transações DUKPT.
MAC	Message Authentication Code. Código gerado para garantir a integridade e a autenticidade de uma mensagem em trânsito.
p_ht_data	Campo do payload para enviar dados em formato Hexadecimal ou Texto (utilizado no Encrypt e MAC).
p_h_data	Campo do payload exclusivo para enviar dados em formato Hexadecimal (utilizado no Decrypt e SuperDecrypt).
PAN	Primary Account Number. Número principal impresso no cartão de pagamento.
TPK / ZPK	Terminal PIN Key e Zone PIN Key. Chaves que protegem o PIN entre o terminal/host e entre instituições, respetivamente.

Apêndice B. Referência Rápida de Endpoints

Consulte esta tabela para mapear rapidamente a operação que deseja realizar com o seu respetivo endpoint e campo de dados principal.

Operação	Endpoint da API	Campo de Entrada	Suporta Lote (Batch)?
Cifrar	/v4/PayShieldCrypto/EncryptData	p_ht_data	Não.
Decifrar	/v4/PayShieldCrypto/DecryptData	p_h_data	Não.
Decifrar Lote	/v4/PayShieldCrypto/SuperDecryptData	p_h_data[]	Sim.
Gerar MAC	/v4/PayShieldCrypto/GenerateMac	p_ht_data	Multi-bloco (via macModeFlag).
Validar MAC	/v4/PayShieldCrypto/ValidateMac	p_ht_data	Multi-bloco (via macModeFlag).