> 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/referencia-da-api-key-manager.md).
# Referência da API - KEY MANAGER
Esta secção detalha os três primeiros endpoints do módulo Key Manager, responsáveis por introduzir novas chaves no ambiente seguro do HSM: `GenerateKey` (criação do zero), `ImportKey` (receção de chaves de trabalho de parceiros) e `ImportZMK` (receção da chave-mestra de zona de um parceiro) .
## Gerar chave
> Gera uma nova chave criptográfica no HSM e a armazena no banco de dados.\
> Retorna o \`keyId\` gerado em \`retValue\` e o KCV (Key Check Value) em \`retMultiValue\[0]\`.\
> \
> Suporta geração simples (\`modeFlag: "0"\`) ou geração com exportação simultânea sob ZMK/TMK (\`modeFlag: "1"\`).\
> \
> Quando \`is\_ephemeral: true\`, a chave tem tempo de vida limitado definido por \`key\_TTL\_minutes\`.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GenerateKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","modeFlag"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser gerada (ex ZEK, ZPK, ZMK, TMK, BDK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES (64 bits)\n- D Double DES (128 bits)\n- T Triple DES (192 bits)\n- A AES-128\n- B AES-192\n- C AES-256\n"},"modeFlag":{"type":"string","enum":["0","1","A","B"],"description":"Modo de operacao:\n- 0 Gerar chave\n- 1 Gerar chave e exportar sob ZMK/TMK\n- A Derivar chave\n- B Derivar chave e exportar sob ZMK/TMK\n"},"zmk_TMK_flag":{"type":"string","nullable":true,"description":"Flag da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"zmk_TMK_keyId":{"type":"string","nullable":true,"description":"Alias da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}},"paths":{"/v4/PayShieldKeyManager/GenerateKey":{"post":{"tags":["Key Manager"],"summary":"Gerar chave","description":"Gera uma nova chave criptográfica no HSM e a armazena no banco de dados.\nRetorna o `keyId` gerado em `retValue` e o KCV (Key Check Value) em `retMultiValue[0]`.\n\nSuporta geração simples (`modeFlag: \"0\"`) ou geração com exportação simultânea sob ZMK/TMK (`modeFlag: \"1\"`).\n\nQuando `is_ephemeral: true`, a chave tem tempo de vida limitado definido por `key_TTL_minutes`.\n","operationId":"generateKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
> O papel crítico do KCV (Key Check Value) Observe que o valor `"6DA9EB"` é retornado no `retMultiValue[0]`. Este é o KCV: um *hash* curto de 6 dígitos hexadecimais que serve como impressão digital da chave. É utilizado para confirmar com a contraparte que ambos possuem exatamente a mesma chave, sem nunca revelar a chave em si . Registe sempre o KCV junto com o `keyId` nos seus logs de auditoria.
***
## Importar chave sob ZMK
> Importa uma chave criptográfica que está criptografada sob uma ZMK (Zone Master Key).\
> A chave é descriptografada pelo HSM e re-criptografada sob o LMK, sendo armazenada no banco de dados.\
> Retorna o \`keyId\` gerado em \`retValue\` e o KCV em \`retMultiValue\[0]\`.\
> \
> Quando \`is\_ephemeral: true\`, a chave tem tempo de vida limitado definido por \`key\_TTL\_minutes\`.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ImportKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","key_under_ZMK_to_import","ZMK_keyId"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser importada (ex ZEK, ZPK, TMK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES\n- D Double DES\n- T Triple DES\n- A AES-128\n- B AES-192\n- C AES-256\n"},"key_under_ZMK_to_import":{"type":"string","description":"Chave criptografada sob a ZMK a ser importada (formato Key Block ou X9.17)"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK no banco de dados"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}},"paths":{"/v4/PayShieldKeyManager/ImportKey":{"post":{"tags":["Key Manager"],"summary":"Importar chave sob ZMK","description":"Importa uma chave criptográfica que está criptografada sob uma ZMK (Zone Master Key).\nA chave é descriptografada pelo HSM e re-criptografada sob o LMK, sendo armazenada no banco de dados.\nRetorna o `keyId` gerado em `retValue` e o KCV em `retMultiValue[0]`.\n\nQuando `is_ephemeral: true`, a chave tem tempo de vida limitado definido por `key_TTL_minutes`.\n","operationId":"importKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Importar ZMK (Zone Master Key)
> Importa uma ZMK (Zone Master Key) em formato Key Block Thales para o HSM.\
> A ZMK é validada pelo KCV informado e armazenada no banco de dados.\
> Retorna o \`keyId\` gerado em \`retValue\` e o KCV em \`retMultiValue\[0]\`.\
> \
> O campo \`keyZMK\` deve estar no formato Key Block Thales (ex: \`S1009652TB00S0001...\`).\
> O campo \`kcv\` deve ter exatamente 6 caracteres hexadecimais.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ImportZMKInput":{"type":"object","required":["client_id","kcv","keyZMK"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"kcv":{"type":"string","minLength":6,"maxLength":6,"description":"Key Check Value da ZMK (exatamente 6 caracteres hexadecimais)"},"keyZMK":{"type":"string","description":"ZMK em formato Key Block Thales"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}},"paths":{"/v4/PayShieldKeyManager/ImportZMK":{"post":{"tags":["Key Manager"],"summary":"Importar ZMK (Zone Master Key)","description":"Importa uma ZMK (Zone Master Key) em formato Key Block Thales para o HSM.\nA ZMK é validada pelo KCV informado e armazenada no banco de dados.\nRetorna o `keyId` gerado em `retValue` e o KCV em `retMultiValue[0]`.\n\nO campo `keyZMK` deve estar no formato Key Block Thales (ex: `S1009652TB00S0001...`).\nO campo `kcv` deve ter exatamente 6 caracteres hexadecimais.\n","operationId":"importZMK","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportZMKInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
#### Por que o KCV é separado
O KCV não é extraído automaticamente do Key Block — ele precisa ser informado pela contraparte e validado contra o resultado da decifração interna no HSM. Se houver divergência, o HSM rejeita a importação (tipicamente com retCode 11). Isso protege contra adulterações da ZMK em trânsito ou erros de digitação.
#### O comportamento de expiração em ZMKs
Nas respostas de sucesso deste endpoint, observará que o campo `retKeyTTLmin` retorna sempre `0` (sem expiração). Motivo: As ZMKs tipicamente NÃO são efêmeras. São chaves-mestras de longa duração que garantem trocas contínuas com um parceiro. O endpoint não expõe a flag `is_ephemeral`; caso necessite de rotacionar a ZMK, o fluxo correto é importar uma nova (obtendo um novo `keyId`) e descontinuar a antiga .
***
## Exportar chave sob ZMK
> Exporta uma chave armazenada no HSM (criptografada sob LMK) para criptografia sob uma ZMK.\
> Retorna a chave exportada em \`retMultiValue\[0]\`.\
> \
> Suporta três esquemas de exportação:\
> \- X917: Formato X9.17 (DES/3DES apenas)\
> \- TR31: Formato TR-31 Key Block\
> \- TKBF: Thales Key Block Format
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","ZMK_keyId","export_scheme"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK sob a qual a chave sera exportada"},"export_scheme":{"type":"string","enum":["X917","TR31","TKBF"],"description":"Esquema de exportacao:\n- X917 Formato X9.17 (apenas DES/3DES)\n- TR31 Formato TR-31 Key Block\n- TKBF Thales Key Block Format\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operacao"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retDescription":{"type":"string","description":"Descricao do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}},"paths":{"/v4/PayShieldKeyManager/ExportKey":{"post":{"tags":["Key Manager"],"summary":"Exportar chave sob ZMK","description":"Exporta uma chave armazenada no HSM (criptografada sob LMK) para criptografia sob uma ZMK.\nRetorna a chave exportada em `retMultiValue[0]`.\n\nSuporta três esquemas de exportação:\n- X917: Formato X9.17 (DES/3DES apenas)\n- TR31: Formato TR-31 Key Block\n- TKBF: Thales Key Block Format\n","operationId":"exportKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Traduzir chave entre LMKs
> Traduz uma chave de criptografia sob um LMK antigo para criptografia sob o LMK atual.\
> Utilizado em processos de migração de LMK.\
> Retorna a chave re-criptografada sob o novo LMK em \`retValue\` (formato Key Block Thales).\
> \
> O campo \`OldKey\` deve estar no formato Key Block Thales criptografado sob o LMK antigo.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"TranslateLMKInput":{"type":"object","required":["client_id","OldKey"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"OldKey":{"type":"string","description":"Chave em formato Key Block Thales criptografada sob o LMK antigo"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}},"paths":{"/v4/PayShieldKeyManager/TranslateLMK":{"post":{"tags":["Key Manager"],"summary":"Traduzir chave entre LMKs","description":"Traduz uma chave de criptografia sob um LMK antigo para criptografia sob o LMK atual.\nUtilizado em processos de migração de LMK.\nRetorna a chave re-criptografada sob o novo LMK em `retValue` (formato Key Block Thales).\n\nO campo `OldKey` deve estar no formato Key Block Thales criptografado sob o LMK antigo.\n","operationId":"translateLMK","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateLMKInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## The GenerateKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"GenerateKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","modeFlag"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser gerada (ex ZEK, ZPK, ZMK, TMK, BDK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES (64 bits)\n- D Double DES (128 bits)\n- T Triple DES (192 bits)\n- A AES-128\n- B AES-192\n- C AES-256\n"},"modeFlag":{"type":"string","enum":["0","1","A","B"],"description":"Modo de operacao:\n- 0 Gerar chave\n- 1 Gerar chave e exportar sob ZMK/TMK\n- A Derivar chave\n- B Derivar chave e exportar sob ZMK/TMK\n"},"zmk_TMK_flag":{"type":"string","nullable":true,"description":"Flag da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"zmk_TMK_keyId":{"type":"string","nullable":true,"description":"Alias da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}}}}}
```
## The ImportKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ImportKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","key_under_ZMK_to_import","ZMK_keyId"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser importada (ex ZEK, ZPK, TMK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES\n- D Double DES\n- T Triple DES\n- A AES-128\n- B AES-192\n- C AES-256\n"},"key_under_ZMK_to_import":{"type":"string","description":"Chave criptografada sob a ZMK a ser importada (formato Key Block ou X9.17)"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK no banco de dados"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}}}}}
```
## The ImportZMKInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ImportZMKInput":{"type":"object","required":["client_id","kcv","keyZMK"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"kcv":{"type":"string","minLength":6,"maxLength":6,"description":"Key Check Value da ZMK (exatamente 6 caracteres hexadecimais)"},"keyZMK":{"type":"string","description":"ZMK em formato Key Block Thales"}}}}}}
```
## The ExportKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","ZMK_keyId","export_scheme"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK sob a qual a chave sera exportada"},"export_scheme":{"type":"string","enum":["X917","TR31","TKBF"],"description":"Esquema de exportacao:\n- X917 Formato X9.17 (apenas DES/3DES)\n- TR31 Formato TR-31 Key Block\n- TKBF Thales Key Block Format\n"}}}}}}
```
## The TranslateLMKInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"TranslateLMKInput":{"type":"object","required":["client_id","OldKey"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"OldKey":{"type":"string","description":"Chave em formato Key Block Thales criptografada sob o LMK antigo"}}}}}}
```
## The ReturnImpKey object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operacao"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retDescription":{"type":"string","description":"Descricao do resultado"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- -1 Erro interno\n- 01 Erro de paridade na chave (aviso)\n- 04 Tipo de chave invalido\n- 05 Flag de comprimento de chave invalido\n- 07 Tipo de ZKA Master Key invalido\n- 10 Erro de paridade na ZMK/TMK\n- 11 Erro de paridade na chave\n- 44 Migracao nao permitida (PCI HSM compliance)\n- 45 Tipo de chave de destino de migracao invalido\n- 68 Comando desabilitado\n- 137 Malformacao da requisicao\n- 155 Chave nao encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descricao do erro"}}}}}}
```
---
# 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/referencia-da-api-key-manager.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.