Referência da API - CRYPTO

Esta página detalha os endpoints responsáveis pela proteção (cifragem) e recuperação (decifragem) de dados, incluindo a operação de decifragem em lote (SuperDecryptData).

Autenticação

Todas as chamadas para os endpoints do módulo Crypto exigem o cabeçalho Authorization preenchido com um token Bearer JWT válido.

Exemplo de Cabeçalho:

HTTP
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...

Criptografar dados

post

Retorna os dados criptografados e o IV (se aplicável) em formato Hex. Em caso de erro, retorna os campos de erro (retCode e retDescription).

Retorna em retMultiValue:

retMultiValue[0] = msgRespEncrypted → Mensagem criptografada
retMultiValue[1] = ivResp → IV para a próxima chamada de descriptografia, apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 2

keyIdstringRequired

Alias/identificador da chave no banco de dados

Example: client-42-key-id-XXX-ZEK

modeEncFlagstringRequired

Modo de operação da cifra:

00: ECB (padrão se null ou valor não listado)
01: CBC (requer IV)
02: CFB8 (requer IV)
03: CFB64 (requer IV)

Example: 00

ksn_descstring · nullableOptional

Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)

ksnstring · nullableOptional

KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)

ivstring · nullableOptional

Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03

Example: 12345678123456781234567812345678

data_fmtstring · enumRequired

Formato dos dados de entrada:

H: Hexadecimal
T: Texto

Example: HPossible values:

p_ht_datastringRequired

Dados a serem criptografados em formato H (Hex) ou T (Texto)

Example: 1407C97819537CE2...

b_datastring · nullableOptional

Dados em formato binário (uso reservado)

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestringOptional

Valor de retorno simples (geralmente vazio em sucesso)

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

Descrição do resultado

Example: OK

400

Requisição inválida (campo obrigatório ausente ou formato incorreto)

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/demo/generate

POST /qseed/demo/generate HTTP/1.1
Host: api-research.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "client_id": 2,
  "keyId": "client-42-key-id-XXX-ZEK",
  "modeEncFlag": "14",
  "ksn_desc": null,
  "ksn": null,
  "iv": "12345678123456781234567812345678",
  "data_fmt": "H",
  "p_ht_data": "1407C97819537CE2E58B0D9AE808E39ABE20ACA2D371E469EE40B27B4F65281EF52C8B8725ABE119FBC47600E1C917F6F9EBDF2100554A007128BF9453325C6FE0FDA56F29C23E6642928480ACBFF08CC705ED3A99E48467839C038529C49C70EA16395E3EBF400934A1B0260B6FB4FD5D3A411479837481CC07BE244C853B40F3620150B462138D3A82AE63DA9A31FC717EBC4DBA1FE5A5CE415534B9FC968F8DB9A9CAADDA5953969AE581CF855B8844F983F270A9DA9331644282F607324DF48DB8227A71E2E374CF7AC6908268145B785D59ED548617606C0A6AD69A078F",
  "b_data": null
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "01C06115A1503D316C17A6DA7385D98E2CFB13745626704BC701710C2D82317ED01C7ECA0003AC8A4DC41E4366E9CCCA301C17F4D1F1C458D8DEEF256225447B573606BEC22D3064169A3E249807180C12B18A8CD3EA8E2906B6D0D279B9CB81072041AB71106850F528AE484336441FC7BDF1493162E30236DEDD62620924D3D0429089FE7E9EAC9C519AFAB825D216C3F9AE5272E16CABE8F47D21907F607CD43F67B151BCEE6C4C0334A0EE469771692FDC2661B07E0967F5BC9A4A4760B0DCB5EFFFDFF251ADC5A4D44C9AF8CEA96FC64A393F3D01A5168C45219FB8494F2802",
    null
  ],
  "retValid": true,
  "retDesc": "OK"
}

Descriptografar dados

post

Retorna os dados descriptografados e o IV (se aplicável) em formato Hex. Em caso de erro, retorna os campos de erro (retCode e retDescription).

Retorna em retMultiValue:

retMultiValue[0] = msgRespDecrypted → Mensagem descriptografada
retMultiValue[1] = ivResp → IV para a próxima chamada de criptografia, apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.

O campo data_fmt aceita apenas H (Hexadecimal) ou T (Texto). O formato B não é suportado.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 2

keyIdstringRequired

Alias/identificador da chave no banco de dados

Example: client-42-key-id-XXX-ZEK

modeEncFlagstringRequired

Modo de operação da cifra:

00: ECB (padrão se null ou valor não listado)
01: CBC (requer IV)
02: CFB8 (requer IV)
03: CFB64 (requer IV)

Example: 00

ksn_descstring · nullableOptional

Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)

ksnstring · nullableOptional

KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)

ivstring · nullableOptional

Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03

Example: 12345678123456781234567812345678

data_fmtstring · enumRequired

Formato dos dados de entrada:

H: Hexadecimal
T: Texto

Example: HPossible values:

p_h_datastringRequired

Dados criptografados a serem descriptografados em formato Hex

Example: 1407C97819537CE2...

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestringOptional

Valor de retorno simples (geralmente vazio em sucesso)

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

Descrição do resultado

Example: OK

400

Requisição inválida — formato de data_fmt incorreto ou campo obrigatório ausente

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldCrypto/DecryptData

POST /v4/PayShieldCrypto/DecryptData HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 613

{
  "client_id": 2,
  "keyId": "client-42-key-id-XXX-ZEK",
  "modeEncFlag": "14",
  "ksn_desc": null,
  "ksn": null,
  "iv": "12345678123456781234567812345678",
  "data_fmt": "H",
  "p_h_data": "1407C97819537CE2E58B0D9AE808E39ABE20ACA2D371E469EE40B27B4F65281EF52C8B8725ABE119FBC47600E1C917F6F9EBDF2100554A007128BF9453325C6FE0FDA56F29C23E6642928480ACBFF08CC705ED3A99E48467839C038529C49C70EA16395E3EBF400934A1B0260B6FB4FD5D3A411479837481CC07BE244C853B40F3620150B462138D3A82AE63DA9A31FC717EBC4DBA1FE5A5CE415534B9FC968F8DB9A9CAADDA5953969AE581CF855B8844F983F270A9DA9331644282F607324DF48DB8227A71E2E374CF7AC6908268145B785D59ED548617606C0A6AD69A078F"
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "01C01407C97859537CE2E58B0D9AE808E39ABE20ACA2D371E469EE40B27B4F65281EF52C8B8725ABE119FBC47600E1C917F6F9EBDF2100554A007128BF9453325C6FE0FDA56F29C23E6642928480ACBFF08CC705ED3A99E48467839C038529C49C70EA16395E3EBF400934A1B0260B6FB4FD5D3A411479837481CC07BE244C853B40F3620150B462138D3A82AE63DA9A31FC717EBC4DBA1FE5A5CE415534B9FC968F8DB9A9CAADDA5953969AE581CF855B8844F983F270A9DA9331644282F607324DF48DB8227A71E2E374CF7AC6908268145B785D59ED548617606C0A6AD69A078F",
    null
  ],
  "retValid": true,
  "retDesc": "OK"
}

PreviousModos de Operação e Retornos NextIntegração Prática e Casos de Uso

Last updated 2 months ago