> 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-pan/integracao-boas-praticas-e-apendices.md).

# Integração, Boas Práticas e Apêndices

### Fluxo de Integração Recomendado

As cinco etapas abaixo cobrem a integração ponta-a-ponta de uma aplicação cliente ao módulo PayShield Pan .

#### Provisionamento

* Solicite à First Tech a criação do `client_id` e o registo das chaves criptográficas necessárias (LMK do *tenant* e as ZPKs por canal: emissor, adquirente, terminais, gráfica) .
* Mapeie cada caso de uso a um par origem/destino e ao endpoint correspondente, conforme a matriz de operações (Secção 3).
* Documente internamente os `keyIds` e os seus algoritmos (AES vs 3DES), uma vez que o algoritmo não é exposto pela API e tem de ser conhecido pelo integrador.

#### Autenticação

* Obtenha o token Bearer junto ao Auth0 da First Tech .
* Implemente um sistema de *cache* do token, respeitando o TTL (*Time-To-Live*) fornecido pelo provedor.
* Implemente a renovação proativa antes da expiração para evitar erros `401` em transações críticas.

#### Operação

* Construa o *body* de acordo com o endpoint alvo. Tenha especial atenção às convenções de nome de campo (ex.: `zpkKeyIdSrc/Dst` em `PinEmbossing`/`PinInternalization`, versus `keyId` em `TranslatePin*`) .
* Valide a compatibilidade formato × algoritmo antes de enviar (Secção 4.3).
* Trate a resposta inspecionando primeiro o `retCode` antes de avaliar a flag `retValid`.

#### Tratamento de Erros

* O `retCode 01` no `ValidatePinIssuerKey` é a resposta esperada quando o PIN está incorreto; não se trata de um erro técnico .
* Os `retCode 10` ou `11` (paridade de chave) indicam que a chave está corrompida e precisa de ser reprovisionada (abra um chamado com a First Tech).
* O `retCode 17` indica que a tradução para o par origem/destino está bloqueada pelas políticas do HSM.
* O `retCode 69` (formato desabilitado) indica uma violação da matriz de compatibilidade (ex.: formato 48 em 3DES).
* Os erros `5xx` podem ser transitórios. Implemente um mecanismo de *retry* com *backoff* exponencial e *jitter*, mas NUNCA registe o PIN nos *logs* durante este processo.

#### Observabilidade

* Métricas Mínimas: Monitorize a taxa de chamadas por endpoint, a latência nos percentis `p50`/`p95`/`p99`, e a taxa de erro agrupada por `retCode` .
* Alertas: Configure alarmes em caso de desvio de SLA, num incremento súbito de `retCode 01` (que pode indicar um ataque de força bruta), em erros `401` persistentes, e em quaisquer `retCodes` de paridade.
* Regra de Ouro (Logs): É estritamente PROIBIDO registar em *log* os campos `pin`, `pinDb`, `pinBlockSrc`, `generatedPin` ou qualquer conteúdo do `retMultiValue`. Registe apenas o `client_id`, o endpoint, o `retCode` e a duração da chamada.

***

### Boas Práticas

#### Segurança

* O PIN em claro NUNCA deve ser visto pela aplicação. Toda a manipulação acontece sob cifragem (LMK, ZPK, TPK). Se o desenho arquitetural exigir o PIN em claro, o desenho está incorreto .
* Restrinja o acesso ao endpoint `apivin.first-tech.net` através de uma *allowlist* de IPs, sempre que possível.
* Implemente *rate limits* por `client_id` na sua infraestrutura para evitar enumeração de PINs (ex.: um máximo de `N` tentativas por PAN por hora).
* Em fluxos de `ValidatePinIssuerKey`, propague apenas o valor booleano do `retValid` para a camada de negócio; nunca exponha o `retDescription` ao cliente final.

#### Performance

* Reaproveite as conexões HTTP (*keep-alive*). O serviço Hop V4 já mantém uma conexão persistente e otimizada com o HSM .
* Em *jobs* de migração, dimensione lotes pequenos (50 a 200 registos) para não saturar a fila de processamento do HSM.
* Distribua os *jobs* de migração durante as janelas de menor movimento (*off-peak*) para preservar a capacidade de processamento das transações *online*.

#### Guia de Troubleshooting Rápido

<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 token no Auth0; verificar <em>header</em> <code>Authorization</code>.</td></tr><tr><td><code>retCode 17</code> em PinEmbossing</td><td>Tradução LMK → ZPK desabilitada para o par de chaves.</td><td>Verificar as políticas do HSM aplicadas ao seu <em>tenant</em>.</td></tr><tr><td><code>retCode 69</code> em PinEmbossing com formato 48</td><td>Formato 48 não suportado em ZPK 3DES (destino).</td><td>Usar formatos <code>01-47</code> no <code>pinBlockFmtDst</code>.</td></tr><tr><td><code>retCode 81</code> com pinLength informado</td><td>Tamanho real do PIN no PinBlock difere do declarado.</td><td>Validar a rotina de geração do PinBlock na origem.</td></tr><tr><td><code>retCode 88</code></td><td>PinBlock com PIN de tamanho zero (alerta).</td><td>Revisar processo de geração na origem.</td></tr><tr><td><code>retCode 10</code> ou <code>11</code></td><td>Erro de paridade na chave.</td><td>Solicitar reprovisionamento da chave à First Tech.</td></tr><tr><td><code>ValidatePinIssuerKey</code> sempre retorna <code>retValid false</code></td><td><code>formatCode</code> / <code>formatCodeDb</code> invertidos ou <code>keyIds</code> trocados.</td><td>Validar o <em>payload</em> rigorosamente contra o exemplo da Secção 15.3.</td></tr><tr><td><code>TranslatePan</code> retorna formato inesperado</td><td>AES Key Block LMK força nativamente o formato 48 no resultado.</td><td>Documentar esta regra nas integrações <em>downstream</em> que processam a resposta.</td></tr></tbody></table>

***

### Apêndices

#### Apêndice A - Glossário

| AES                    | *Advanced Encryption Standard*. Algoritmo simétrico padrão (128, 192 e 256 bits). |
| ---------------------- | --------------------------------------------------------------------------------- |
| AES Key Block LMK      | Modelo de armazenamento de chaves AES no HSM em formato Key Block (TR-31).        |
| 3DES Key Block LMK     | Modelo de armazenamento de chaves 3DES no HSM em formato Key Block.               |
| BDK                    | *Base Derivation Key*. Chave-mãe DUKPT.                                           |
| DUKPT                  | *Derived Unique Key Per Transaction*. Esquema de derivação por transação.         |
| formatCode             | Índice abreviado de formato de PinBlock (0/1/3/4).                                |
| ISO PIN Block Format 4 | Formato moderno de PinBlock (Thales 48), exclusivo para chaves AES.               |
| LMK                    | *Local Master Key*. Chave-mestra AES interna do HSM da First Tech.                |
| pinBlockFmt            | Código direto Thales de formato de PinBlock (01, 02... 48).                       |
| TPK / ZPK              | *Terminal PIN Key* / *Zone PIN Key*. Chaves partilhadas entre zonas ou terminais. |
| Variant LMK            | Modelo legado de armazenamento de chaves no HSM (anterior ao Key Block).          |

#### Apêndice B - Referência Rápida de Endpoints

| Gerar PIN sob LMK            | `/v4/PayShieldPan/GeneratePin`          | LMK                            |
| ---------------------------- | --------------------------------------- | ------------------------------ |
| Gerar PIN sob ZPK do emissor | `/v4/PayShieldPan/GeneratePinIssuerKey` | ZPK                            |
| LMK AES → ZPK 3DES           | `/v4/PayShieldPan/PinEmbossing`         | AES → 3DES                     |
| ZPK 3DES → LMK AES           | `/v4/PayShieldPan/PinInternalization`   | 3DES → AES                     |
| LMK AES → ZPK AES            | `/v4/PayShieldPan/TranslatePinLmkToZpk` | AES → AES                      |
| ZPK AES → LMK AES            | `/v4/PayShieldPan/TranslatePinZpkToLmk` | AES → AES                      |
| Trocar PAN preservando PIN   | `/v4/PayShieldPan/TranslatePan`         | LMK → LMK                      |
| Trocar PAN + traduzir PIN    | `/v4/PayShieldPan/TranslatePinPan`      | LMK → ZPK                      |
| Validar PIN recebido         | `/v4/PayShieldPan/ValidatePinIssuerKey` | ZPK 3DES → LMK AES (validação) |


---

# 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-pan/integracao-boas-praticas-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.