> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-crypto/erros-troubleshooting-e-apendices.md).

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

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

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

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

***

### Apêndice A. Glossário de Termos

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

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Operação</th><th>Endpoint da API</th><th>Campo de Entrada</th><th>Suporta Lote (Batch)?</th></tr></thead><tbody><tr><td>Cifrar</td><td><code>/v4/PayShieldCrypto/EncryptData</code></td><td><code>p_ht_data</code></td><td>Não.</td></tr><tr><td>Decifrar</td><td><code>/v4/PayShieldCrypto/DecryptData</code></td><td><code>p_h_data</code></td><td>Não.</td></tr><tr><td>Decifrar Lote</td><td><code>/v4/PayShieldCrypto/SuperDecryptData</code></td><td><code>p_h_data[]</code></td><td>Sim.</td></tr><tr><td>Gerar MAC</td><td><code>/v4/PayShieldCrypto/GenerateMac</code></td><td><code>p_ht_data</code></td><td>Multi-bloco (via <code>macModeFlag</code>).</td></tr><tr><td>Validar MAC</td><td><code>/v4/PayShieldCrypto/ValidateMac</code></td><td><code>p_ht_data</code></td><td>Multi-bloco (via <code>macModeFlag</code>).</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ftcoders.first-tech.com/landing-page/modulo-crypto/erros-troubleshooting-e-apendices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.