> 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-key-manager/integracao-e-exemplos-praticos.md).

# Integração e Exemplos Práticos

## Integração e Exemplos Práticos

Para garantir uma implementação segura e fluida, esta secção detalha os três fluxos operacionais mais comuns na gestão de chaves criptográficas com parceiros, acompanhados de *snippets* de código nas linguagens mais utilizadas.

### Cenários de Integração (Fluxos)

#### Cenário 1: Onboarding Interno (Gerar Nova Chave)

Este é o cenário mais simples. O cliente integrador necessita de gerar uma nova chave para uso estritamente interno (ex.: uma ZPK que será usada no módulo PayShield PIN para validar PIN blocks recebidos do *front-end*) .

Sequência:

1. Obter o token JWT via Auth0.
2. Invocar o `GenerateKey` com `keyName = "ZPK"`, `keySizeType = "D"` (DES *double-length*, padrão em PIN) e `modeFlag = "0"` .
3. Capturar o `retValue` (`keyId`) retornado e registá-lo na base de dados do cliente, associado a este contexto de uso.
4. Capturar o `retMultiValue[0]` (KCV) e registá-lo para fins de auditoria e reconciliação futura.
5. A partir deste momento, o `keyId` pode ser consumido em chamadas aos restantes módulos da Hop V4.

***

#### Cenário 2: Receção de Chave de Parceiro

Cenário típico de integração: o cliente necessita de receber uma chave ZPK gerada por um adquirente parceiro. Esta chave é enviada encriptada sob uma ZMK que ambas as partes partilham .

Sequência:

1. Key Ceremony: Acordo prévio documentado com o parceiro para definir tipos de chave, tamanhos e esquema de troca.
2. Receber do parceiro a ZMK no formato Key Block Thales e o respetivo KCV.
3. Invocar o `ImportZMK` utilizando os dados do passo anterior. Registar o `keyId` retornado.
4. Receber do parceiro a ZPK (encriptada sob a ZMK partilhada).
5. Invocar o `ImportKey` passando a chave encriptada (`key_under_ZMK_to_import`) e o alias da ZMK (`ZMK_keyId`). Registar o novo `keyId` da ZPK .
6. Validação Crítica: Comparar o KCV retornado no `retMultiValue[0]` com o KCV informado pelo parceiro. Têm de coincidir obrigatoriamente; caso contrário, aborte a operação e investigue .

***

#### Cenário 3: Envio de Chave para Parceiro

Cenário inverso: o cliente necessita de enviar uma ZPK para um parceiro. Existem duas abordagens possíveis .

Abordagem A: Geração com Exportação Simultânea Ideal quando já se sabe de antemão qual o parceiro que vai receber a chave.

1. Importar a ZMK do parceiro via `ImportZMK` (se ainda não existir no banco).
2. Invocar o `GenerateKey` com `modeFlag = "1"`, apontando para a ZMK do parceiro no campo `zmk_TMK_keyId`. A API gera a chave e, na mesma chamada, devolve a chave já encriptada sob a ZMK de destino .
3. Enviar o resultado e o KCV para o parceiro através do canal seguro acordado.

Abordagem B: Geração e Exportação Separadas Ideal quando a ZPK é criada para uso interno primeiro, ou precisa de ser distribuída a múltiplos parceiros .

1. Invocar o `GenerateKey` com `modeFlag = "0"` para criar a ZPK no banco.
2. Para cada parceiro destino: invocar o `ExportKey` utilizando o `keyId` da ZPK e a `ZMK_keyId` do parceiro em questão. Recomenda-se selecionar `"TR31"` no `export_scheme` .
3. Enviar o `retMultiValue[0]` resultante a cada parceiro, acompanhado do KCV correspondente.

***

### Exemplos de Código (Snippets)

#### cURL — Gerar uma ZEK Efémera (`GenerateKey`)

Bash

```bash
curl -X POST \
  https://apivin.first-tech.net/v4/PayShieldKeyManager/GenerateKey \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "keyName": "ZEK",
    "keySizeType": "S",
    "modeFlag": "0",
    "is_ephemeral": true,
    "key_TTL_minutes": 1440
}'
```

#### Python — Pipeline de Onboarding de Parceiro

Este script demonstra a importação da ZMK e, de seguida, a importação da ZPK protegida por ela.

Python

```python
import requests

BASE = "https://apivin.first-tech.net/v4/PayShieldKeyManager"

def onboard_partner(token, client_id, partner_zmk, partner_zmk_kcv, partner_zpk_under_zmk):
    headers = {"Authorization": f"Bearer {token}"}

    # 1) Importa a ZMK
    r1 = requests.post(f"{BASE}/ImportZMK", headers=headers, json={
        "client_id": client_id,
        "kcv": partner_zmk_kcv,
        "keyZMK": partner_zmk,
    }, timeout=15)
    
    d1 = r1.json()
    if not d1.get("retValid"):
        raise RuntimeError(f"ImportZMK falhou: {d1}")
        
    zmk_alias = d1["retValue"]
    print(f"ZMK cadastrada: {zmk_alias} (KCV={d1['retMultiValue'][0]})")

    # 2) Importa a ZPK sob a ZMK
    r2 = requests.post(f"{BASE}/ImportKey", headers=headers, json={
        "client_id": client_id,
        "keyName": "ZPK",
        "keySizeType": "D",
        "key_under_ZMK_to_import": partner_zpk_under_zmk,
        "ZMK_keyId": zmk_alias,
    }, timeout=15)
    
    d2 = r2.json()
    if not d2.get("retValid"):
        raise RuntimeError(f"ImportKey falhou: {d2}")
        
    return {
        "zmk_keyId": zmk_alias,
        "zpk_keyId": d2["retValue"],
        "zpk_kcv": d2["retMultiValue"][0]
    }
```

#### Node.js — Geração com Exportação Simultânea (`modeFlag = 1`)

JavaScript

```javascript
const axios = require("axios");

async function generateAndExportZpkToPartner(token, clientId, partnerZmkAlias) {
  const url = "https://apivin.first-tech.net/v4/PayShieldKeyManager/GenerateKey";
  const payload = {
    client_id: clientId,
    keyName: "ZPK",
    keySizeType: "D",
    modeFlag: "1",
    zmk_TMK_flag: "ZMK",
    zmk_TMK_keyId: partnerZmkAlias,
  };

  const { data } = await axios.post(url, payload, {
    headers: { Authorization: `Bearer ${token}` },
    timeout: 15000,
  });

  if (!data.retValid) {
    throw new Error(`HSM retCode=${data.retCode}: ${data.retDescription}`);
  }

  return {
    keyId: data.retValue,
    kcv: data.retMultiValue[0],
    keyUnderZmk: data.retMultiValue[1] || null
  };
}
```


---

# 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-key-manager/integracao-e-exemplos-praticos.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.