> 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-cvv/integracao-e-exemplos-praticos.md). # Integração e Exemplos Práticos Esta secção detalha como os endpoints do módulo CVV se encaixam na arquitetura real de um emissor ou processador de cartões, apresentando os fluxos recomendados, boas práticas de segurança e exemplos de código prontos a utilizar. ### Fluxo Típico: Emissão de Cartão No momento da personalização e emissão de um novo cartão, o emissor necessita tipicamente de gerar os três valores de CVV de uma só vez . O fluxo recomendado é o seguinte: 1. Autenticação: Obter o token JWT via Auth0 (utilizando o *grant* `client_credentials`), que é válido tipicamente por 24 horas. 2. Geração em Lote: Invocar o endpoint `SuperGenerateCV` enviando o *array* `["", "000", "999"]` no campo `serviceCodeArray` para obter o CVV1, CVV2 e dCVV numa única chamada. 3. Persistência e Roteamento: Persistir os valores no sistema do emissor da seguinte forma: * O CVV1 segue para gravação na tarja/chip. * O CVV2 segue para a gráfica (impressão no plástico). * O dCVV é guardado apenas no servidor para validação em transações futuras. 4. Tratamento da Resposta: Verificar se `retCode = 0` e `retValid = true`. Em caso de falha, consultar o catálogo de erros para diagnóstico. ### Fluxo Típico: Autorização de Transação Para transações e-commerce/MOTO (Card-Not-Present) que exigem o CVV2: 1. Autenticação: Obter ou recuperar do cache o token JWT do Auth0 . 2. Validação Estática: Invocar o `ValidateCV` enviando `serviceCode = "000"` e o `cv` preenchido no checkout pelo portador. 3. Decisão de Negócio: Avaliar o campo `retValid`: * `true`: Seguir com a autorização da compra. * `false`: Recusar a transação ou solicitar nova digitação do código . Para transações presenciais (Chip/Contactless) com dCVV: * Substituir o passo 2 pelo uso do endpoint `VerifyDynCV`, preenchendo os campos dependentes da bandeira (como `brand`, `dynCvVers`, `atc`, etc.) recebidos no momento da aproximação. ### Boas Práticas de Integração Antes de colocar o código em produção, valide se a sua aplicação cumpre as seguintes diretrizes essenciais de segurança e resiliência:
CategoriaBoas Práticas
AutenticaçãoCache do JWT: Os tokens Auth0 possuem validade longa. Não solicite um novo token a cada chamada de CVV; isso introduz latência desnecessária e pode esgotar os rate limits do serviço de autenticação.
ResiliênciaIdempotência Nativa: Os endpoints GenerateCV e SuperGenerateCV são determinísticos. Para os mesmos inputs (PAN, expDate, serviceCode e chave), retornarão sempre o mesmo CVV. Isto permite o replay seguro de requisições em caso de timeout de rede .
SegurançaHigienização de Logs: Jamais registe o CVV em texto claro nos logs da sua aplicação. Registe apenas o client_id, keyId, retCode e retDesc para auditoria. Nunca guarde o PAN completo, o campo cv de entrada ou o retValue contendo a resposta .
Políticas de RetryComo tratar erros: Erros 500 e 504 podem sofrer tentativas repetidas (retry) com backoff exponencial. Erros 400 (input inválido), 401 e 404 (chave inexistente) não devem ser retentados sem que a aplicação corrija o dado de origem .
### Exemplos de Código Estes *snippets* demonstram a invocação prática dos endpoints. #### cURL — Gerar CVV2 (`GenerateCV`) ```bash Bash curl -X POST \ https://apivin.first-tech.net/v4/PayShieldCVV/GenerateCV \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "client_id": 42, "keyId": "client-42-XX-key-id-XXXX-CVK", "pan": "4234567890123456", "expDate": "825", "serviceCode": "000" }' ``` #### Python — Validar CVV2 no Checkout (`ValidateCV`) Python 
Python
import requests

url = "https://apivin.first-tech.net/v4/PayShieldCVV/ValidateCV"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
payload = {
    "client_id": 42,
    "keyId": "client-42-XX-key-id-XXXX-CVK",
    "pan": "4234567890123456",
    "expDate": "825",
    "serviceCode": "000",
    "cv": "515"
}

r = requests.post(url, json=payload, headers=headers, timeout=10)
data = r.json()

if data.get("retValid"):
    print("CVV válido - seguir com autorização")
else:
    print(f"CVV inválido - código {data.get('retCode')}: {data.get('retDesc')}")
#### Node.js — Gerar os 3 CVVs na Emissão (`SuperGenerateCV`) 
JavaScript
const axios = require("axios");

async function gerarCvvsEmissao(token, pan, expDate, trackServiceCode) {
  const url = "https://apivin.first-tech.net/v4/PayShieldCVV/SuperGenerateCV";
  const payload = {
    client_id: 42,
    keyId: "client-42-XX-key-id-XXXX-CVK",
    pan,
    expDate,
    serviceCodeArray: [trackServiceCode, "000", "999"],
  };

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

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

  const [cvv1, cvv2, dcvvSeed] = data.retMultiValue;
  return { cvv1, cvv2, dcvvSeed };
}
--- # 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-cvv/integracao-e-exemplos-praticos.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.