> 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/integracao-pratica-e-casos-de-uso.md). # Integração Prática e Casos de Uso Esta secção apresenta o roteiro recomendado para colocar o módulo Crypto em produção e detalha cenários reais de aplicação no ecossistema de pagamentos, ilustrando a sequência exata de chamadas de API . ### Fluxo de Integração Recomendado As cinco etapas abaixo cobrem o ciclo de vida completo da integração da sua aplicação cliente ao módulo PayShield Crypto, desde o setup até à monitorização em produção . #### 1. Provisionamento e Setup * Solicite à equipa da **First Tech** a criação do seu `client_id` e o cadastro das chaves criptográficas necessárias . * Armazene os `keyId` recebidos de forma segura nas configurações da sua aplicação. * Defina, em conjunto com o seu time de segurança, os modos de operação (`modeEncFlag`) adequados para cada caso de uso. #### 2. Gestão de Autenticação * Obtenha o token Bearer junto ao serviço Auth0 da First Tech . * Implemente cache do token: Respeite o *Time-To-Live* (TTL) fornecido. * Renovação proativa: Implemente a renovação do token antes da sua expiração para evitar picos de erros `401` em transações críticas. #### 3. Operação Padrão * Construa o payload da requisição com atenção redobrada aos campos de dados (lembre-se: `p_ht_data` para cifragem/MAC e `p_h_data` para decifragem) . * Configure *timeouts* HTTP adequados ao seu caso de uso (mais curtos para tráfego transacional online, mais longos para processamento *batch*). * Analise sempre o `retCode` no envelope de resposta antes de validar a flag `retValid`. #### 4. Tratamento de Erros e Resiliência * Erros `4xx`: Geralmente indicam problemas estruturais na requisição (ex.: payload inválido, chave incorreta). Não aplique *retry* cego sem corrigir a origem do problema . * Erros `5xx`: Podem representar falhas transitórias do serviço ou de rede. Implemente políticas de *retry* com *backoff* exponencial e *jitter* . * Regra de Segurança: Registe nos *logs* os campos `retCode` e `retDesc`, mas nunca imprima o conteúdo em claro de `p_ht_data` ou os retornos criptografados. #### 5. Observabilidade em Produção * Métricas Mínimas: Monitorize a taxa de chamadas por endpoint, a latência nos percentis `p50`/`p95`/`p99`, e a volumetria de erros agrupada por `retCode` . * Alertas: Configure alarmes para desvios de SLA (latência), incrementos súbitos do `retCode 155` (Chave não encontrada) ou respostas `401` persistentes. ### Casos de Uso Reais da Indústria #### Cenário 1: Tokenização de PAN para Armazenamento Desafio: Uma aplicação necessita de armazenar números de cartão (PAN) em base de dados própria, mantendo o dado cifrado em repouso e garantindo que as chaves não fiquem na posse da própria aplicação . **Sequência de Operações:** 1. Ingestão: A aplicação recebe o PAN em claro via canal seguro (TLS) . 2. Cifragem: A API do cliente consome o endpoint `EncryptData` (modo CBC ou ECB) . 3. Retorno Seguro: O Hop devolve o PAN cifrado e o IV utilizado. Imediatamente, a API descarta o PAN em claro da memória . 4. Persistência: O PAN cifrado, o IV e o `keyId` são armazenados na base de dados . 5. Recuperação: Ao necessitar do dado (ex.: autorização), a base de dados fornece a cifra e o IV à API . 6. Decifragem: A API consome o endpoint `DecryptData` . 7. Entrega: O Hop devolve o PAN em claro, que é entregue à aplicação final e descartado da memória após o uso . #### Cenário 2: Proteção de Campo Sensível em Mensagem ISO 8583 Desafio: Um *host* adquirente recebe mensagens transacionais (ISO 8583) de um POS contendo campos sensíveis cifrados com chave de sessão. O *host* precisa de os decifrar e re-cifrar com chave de zona antes de encaminhar à bandeira. **Sequência de Operações:** 1. Origem: O POS envia a mensagem ISO 8583 com o campo sensível cifrado . 2. Decifragem Transitória: O *host* adquirente extrai o campo e consome o `DecryptData` no Hop (modo CBC) . 3. Tratamento: O Hop devolve o dado em claro. O *host* valida o conteúdo (ex.: formato, expiração do cartão) . 4. Re-cifragem (Roteamento): O *host* consome novamente o `EncryptData`, desta vez aplicando a chave ZPK específica para a bandeira ou emissor . 5. Finalização: A autorização retorna do emissor e é devolvida ao POS . #### Cenário 3: Migração de Base com Rotação de Chaves Desafio: Troca programada da chave criptográfica de uma base inteira de dados para cumprir exigências de conformidade (PCI DSS). A operação é feita em *batch* . **Sequência de Operações:** 1. Leitura: O *Job* lê um lote de `N` registos cifrados e os seus respetivos IVs da base antiga . 2. Decifragem em Massa: O *Job* invoca o `SuperDecryptData` referenciando a chave antiga . 3. Memória Volátil: O Hop devolve a lista de dados em claro. Estes dados são mantidos apenas em memória e não são guardados em ficheiros intermediários . 4. Re-cifragem Individual: O *Job* itera sobre cada registo invocando `EncryptData` com o `keyId` da nova chave . 5. Recepção: O Hop devolve o novo conteúdo cifrado e o novo IV . 6. Persistência Atualizada: O *Job* grava o registo na base de dados utilizando o novo `keyId` e IV . #### Cenário 4: MAC Multi-bloco em Comunicação Host-to-Host Desafio: Envio de ficheiros de remessa ou mensagens muito longas entre dois *hosts* que precisam de ser autenticados com um único MAC, exigindo o particionamento do ficheiro em blocos suportáveis . **Sequência de Operações:** 1. Primeiro Bloco: O *Host* de origem invoca `GenerateMac` com `macModeFlag = 1` no primeiro segmento . 2. IV Intermediário: O Hop devolve um IV parcial para encadeamento . 3. Blocos Intermediários: O *Host* itera sobre o ficheiro invocando `GenerateMac` com `macModeFlag = 2`, alimentando-o com o IV recebido na etapa anterior . 4. Bloco Final: O *Host* invoca `GenerateMac` com `macModeFlag = 3` com o segmento final. O Hop devolve o MAC definitivo . 5. Transmissão: A mensagem completa e o MAC são enviados ao destino . 6. Validação Rigorosa: O *Host* de destino reproduz o particionamento exato e invoca o `ValidateMac` (com flags 1, 2 e 3). O Hop devolve `retValid: true` se o ficheiro estiver intacto . --- # 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/integracao-pratica-e-casos-de-uso.md?ask=&goal= ``` `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.