Padrões de Resposta e Schemas

Os endpoints do módulo CVV partilham um conjunto de schemas (modelos de objetos) estruturados como heranças de uma base comum. Conhecer essa arquitetura facilita o reaproveitamento de DTOs (Data Transfer Objects) no código da sua aplicação .

Padrões de Resposta (Envelopes)

Todas as respostas do módulo seguem um envelope unificado. A validação do sucesso de uma chamada deve sempre analisar primeiro o campo retCode (onde 0 significa sucesso e qualquer outro valor indica um código de erro proveniente do HSM).

ReturnSingle

Utilizado pelos endpoints GenerateCV, ValidateCV e VerifyDynCV (quando o retorno esperado é apenas um valor único).

Campo	Tipo	Descrição
retCode	integer	Código de retorno. 0 = sucesso; outros valores indicam erro.
retValue	string	Valor de retorno simples (o CVV gerado ou uma descrição como "CVV Validated").
retMultiValue	any	Sempre null nestes endpoints.
retValid	boolean	Indica se a operação global foi bem-sucedida.
retDesc	string	Descrição textual do resultado (ex.: "OK" ou "CVV failed verification").

ReturnMultiValue

Utilizado exclusivamente pelo endpoint SuperGenerateCV (quando o retorno é uma matriz de múltiplos valores).

Campo	Tipo	Descrição
retCode	integer	Código de retorno. 0 = sucesso.
retValue	string	Sempre null neste schema.
retMultiValue	string[]	Array de strings contendo os CVVs gerados, apresentados exatamente na mesma ordem do array enviado na requisição.
retValid	boolean	Indica se a operação foi bem-sucedida.
retDesc	string	Descrição textual do resultado.

ReturnError

Ocorre em respostas HTTP 400, 404 e 500. Mantém o mesmo formato do ReturnSingle, mas com retValid igual a false, retCode preenchido com o código de falha do HSM e retDesc detalhando o erro .

Schemas de Entrada (Requisição)

CvvInputBase (Campos Comuns)

Schema base que é herdado pelas operações de geração e validação estática.

Campo	Tipo	Obrigatório	Descrição Técnica
client_id	integer	Sim	Identificador numérico do cliente.
keyId	string	Sim	Alias da chave CVK no banco.
pan	string	Sim	PAN do cartão (1 a 19 dígitos numéricos).
expDate	string	Sim	Data de expiração no formato YYMM ou MMYY.
serviceCode	string	Sim	Service code do cartão.

Extensões por Endpoint

GenerateCvInput: Idêntico ao CvvInputBase. Não exige campos adicionais.

SuperGenerateCvInput: Estende o CvvInputBase, mas substitui o campo de string serviceCode pelo array serviceCodeArray.

• serviceCodeArray (string[]): Array de service codes. Gera um CVV distinto por cada elemento.

ValidateCvInput: Estende o CvvInputBase adicionando o código que será submetido a validação.

• cv (string): O CVV/CVC a ser validado. Exige exatamente 3 dígitos numéricos (Regex: ^[0-9]+$).

• dynCv (string): Usado apenas se o serviceCode for "999".

VerifyDynCvInput (Validação Dinâmica): Este schema é completamente autónomo (não herda do base). Utiliza a chave MKAC e possui campos exclusivos para mapear a perspetiva dinâmica da bandeira e versão. Os campos detalhados estarão descritos na secção dedicada à validação dinâmica.