> 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/introducao-e-fundamentos.md).

# Introdução e Fundamentos

### Módulo Crypto

O módulo PayShield Crypto da plataforma Hop V4 oferece um conjunto de operações criptográficas simétricas executadas integralmente dentro do HSM (Hardware Security Module) gerenciado pela First Tech. A principal premissa deste serviço é garantir que o material de chave nunca deixe a fronteira segura do hardware.

Este documento fornece ao integrador a referência técnica completa, englobando fundamentos, modelos de dados, fluxo de integração, casos de uso práticos e taxonomia de erros.

### Público-Alvo e Pré-requisitos

Esta documentação é desenhada para:

* Desenvolvedores que integram aplicações ou *hosts* ao Hop V4.
* Arquitetos que avaliam o uso de criptografia gerenciada como serviço.
* Times de Segurança da Informação responsáveis por validar o desenho criptográfico da solução.

#### Pré-requisitos de Integração

Para consumir os endpoints descritos neste guia, certifique-se de que o seu ambiente cumpre os seguintes requisitos: 

1. Cliente provisionado na plataforma Hop V4, com um `client_id` atribuído. 
2. Pelo menos uma chave criptográfica cadastrada e associada ao seu `client_id`, com o respectivo alias (`keyId`) conhecido. 
3. Credenciais Auth0 (token JWT) válidas para o ambiente de destino.
4. Conectividade de rede autorizada para o endpoint `apivin.first-tech.net`.

### Fundamentos do PayShield Crypto

#### Operações Suportadas

O serviço expõe quatro famílias principais de operações criptográficas simétricas:

1. Cifragem de dados (`EncryptData`): Proteção de informações sensíveis para armazenamento seguro ou trânsito.
2. Decifragem de dados (`DecryptData` e `SuperDecryptData`): Recuperação do conteúdo original em texto claro (incluindo suporte a múltiplos blocos).
3. Geração de MAC (`GenerateMac`): Produção de um código de autenticação (Message Authentication Code) para garantir a integridade e autenticidade de mensagens.
4. Validação de MAC (`ValidateMac`): Verificação da integridade e autenticidade do código gerado.

#### Princípio Operacional e Algoritmos

Toda operação criptográfica atua sobre uma chave referenciada pelo seu `keyId`, que funciona como um alias armazenado no banco de dados gerenciado pela First Tech. O material criptográfico real nunca trafega pela API. A sua aplicação envia apenas o identificador da chave e os dados a serem processados; o HSM executa o cálculo e o resultado retorna em formato hexadecimal .

O algoritmo simétrico aplicado (como DES, 3DES ou AES) é determinado automaticamente pelo tipo da chave que foi provisionada. O integrador não precisa enviar o algoritmo no payload; o seu controle resume-se à escolha do modo de operação através do campo `modeEncFlag`

#### Modelo Padrão de Chamada

Para garantir consistência na integração, todos os endpoints do módulo Crypto seguem o mesmo contrato base:

* **Método HTTP:** `POST`.
* **Autenticação:** Bearer Token (JWT obtido via Auth0).
* **Content-Type:** `application/json`.
* **Identificação do Tenant:** Informada obrigatoriamente no campo `client_id` do corpo da requisição (*body*).
* **Identificação da Chave:** Informada no campo `keyId` do *body*.
* **Resposta Padronizada:** Os objetos de retorno sempre conterão os campos `retCode`, `retValue`, `retMultiValue`, `retValid` e `retDesc`.


---

# 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/introducao-e-fundamentos.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.