ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

🛒 API de Venda Loja

Este guia apresenta o passo a passo para integração com o serviço de vendas em estabelecimentos lojistas, permitindo realizar vendas com cartão, consultar limites e gerenciar transações.

🎯 Visão Geral

A API de Venda Loja permite que você:

• 🔐 Crie pré-autorizações para validar vendas
• 📱 Realize vendas com biometria para maior segurança
• ✅ Capture (efetive) vendas após a pré-autorização
• ❌ Desfaça vendas quando necessário
• 💳 Consulte limites e situação de cartões
• 📋 Cancele contratos de vendas
• 🔑 Obtenha working keys para criptografia

URL Base:

• Homologação: https://apihml.credsystem.com.br/venda-loja/api/v1

---

🔐 Autenticação

Todos os endpoints requerem autenticação via Bearer Token (JWT).

Header obrigatório:

Authorization: Bearer <seu_token_jwt>

Atenção

Tokens inválidos ou expirados retornarão erro 401 Unauthorized.

---

📚 Endpoints Disponíveis

1️⃣ Criar Pré-Autorização

Cria uma pré-autorização de venda antes de efetivar a transação. Este passo valida os dados do cartão, limite disponível e reserva o valor.

Endpoint: POST /pre-autorizacoes

Headers:

Header	Tipo	Obrigatório	Descrição
Authorization	string	✅ Sim	Bearer token JWT

Corpo da Requisição:

{
  "estabelecimento": "12345",
  "identificador": "PDV01",
  "codigoMaquina": "MAQ001",
  "usuario": "vendedor01",
  "nsu": "123456789012",
  "cartao": {
    "tarja": "1234567890123456",
    "cvv2": "123",
    "voucher": "VOUCHER123",
    "senhaCriptografada": "abc123xyz456"
  },
  "venda": {
    "valor": 150.00,
    "quantidadeParcelas": 3,
    "tipoParcelamento": "LOJA",
    "codigoPlano": "PLANO01"
  }
}

Campos da Requisição:

Campo	Tipo	Descrição
estabelecimento	string	Código do estabelecimento lojista
identificador	string	Identificador do ponto de venda (PDV)
codigoMaquina	string	Código da máquina/terminal
usuario	string	Usuário que está realizando a venda
nsu	string	Número Sequencial Único da transação
cartao.tarja	string	Número do cartão (tarja magnética)
cartao.cvv2	string	Código de segurança do cartão
cartao.voucher	string	Voucher do cartão digital (se aplicável)
cartao.senhaCriptografada	string	Senha do cartão criptografada
venda.valor	number	Valor total da venda
venda.quantidadeParcelas	integer	Quantidade de parcelas (1 para à vista)
venda.tipoParcelamento	string	Tipo de parcelamento (LOJA, ADMINISTRADORA)
venda.codigoPlano	string	Código do plano de parcelamento

Exemplo de Requisição:

curl -X POST "https://apihml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "12345",
    "identificador": "PDV01",
    "codigoMaquina": "MAQ001",
    "usuario": "vendedor01",
    "nsu": "123456789012",
    "cartao": {
      "tarja": "1234567890123456",
      "cvv2": "123",
      "senhaCriptografada": "abc123xyz456"
    },
    "venda": {
      "valor": 150.00,
      "quantidadeParcelas": 3,
      "tipoParcelamento": "LOJA",
      "codigoPlano": "PLANO01"
    }
  }'

Exemplo de Resposta (200 Success):

{
  "StatusCode": 200,
  "ReasonPhrase": "OK",
  "HttpVersion": "1.1",
  "Content": {
    "preAutorizacao": 789012,
    "mensagem": "Pré-autorização criada com sucesso",
    "status": "APROVADO"
  }
}

Dica

Guarde o número da preAutorizacao retornado - ele será necessário para capturar (efetivar) a venda.

---

2️⃣ Consultar Status da Pré-Autorização

Consulta o status de uma pré-autorização criada anteriormente.

Endpoint: GET /pre-autorizacoes/sonda/{preautorizacao}

Parâmetros:

Parâmetro	Tipo	Local	Obrigatório	Descrição
preautorizacao	string	Path	✅ Sim	Número da pré-autorização
Authorization	string	Header	✅ Sim	Bearer token JWT

Exemplo de Requisição:

curl -X GET "https://apihml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes/sonda/789012" \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

Exemplo de Resposta (200 Success):

{
  "StatusCode": 200,
  "ReasonPhrase": "OK",
  "HttpVersion": "1.1",
  "Content": {
    "preAutorizacao": 789012,
    "status": "APROVADO",
    "valor": 150.00,
    "dataHora": "2025-12-03T14:30:00.000Z",
    "situacao": "PENDENTE_CAPTURA"
  }
}

Possíveis Status:

Status	Descrição
APROVADO	Pré-autorização aprovada
NEGADO	Pré-autorização negada
PENDENTE_CAPTURA	Aguardando captura
CAPTURADO	Venda capturada (efetivada)
CANCELADO	Pré-autorização cancelada

---

3️⃣ Capturar (Efetivar) Venda

Efetiva a venda após a pré-autorização ser aprovada. Este passo confirma a transação e debita o valor do cliente.

Endpoint: POST /pre-autorizacoes/captura

Corpo da Requisição:

{
  "estabelecimento": "12345",
  "preAutorizacao": 789012,
  "numeroPedido": "PED-2025-001",
  "valor": 150.00
}

Campos da Requisição:

Campo	Tipo	Descrição
estabelecimento	string	Código do estabelecimento lojista
preAutorizacao	integer	Número da pré-autorização a ser capturada
numeroPedido	string	Número do pedido para referência
valor	number	Valor a ser capturado (deve corresponder ao valor pré-autorizado)

Exemplo de Requisição:

curl -X POST "https://apihml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes/captura" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "12345",
    "preAutorizacao": 789012,
    "numeroPedido": "PED-2025-001",
    "valor": 150.00
  }'

Exemplo de Resposta (200 Success):

{
  "StatusCode": 200,
  "ReasonPhrase": "OK",
  "HttpVersion": "1.1",
  "Content": {
    "mensagem": "Venda capturada com sucesso",
    "numeroContrato": 456789,
    "status": "APROVADO"
  }
}

Sucesso!

A venda foi efetivada. O cliente foi debitado e você receberá o valor conforme os termos acordados.

---

4️⃣ Desfazer Venda

Desfaz (estorna) uma venda previamente capturada.

Endpoint: POST /pre-autorizacoes/desfazimento

Atenção

O desfazimento geralmente deve ser realizado no mesmo dia da venda. Verifique as políticas da sua rede.

Corpo da Requisição:

{
  "estabelecimento": "12345",
  "tarja": "1234567890123456",
  "voucher": "VOUCHER123",
  "valor": 150.00,
  "nsu": "123456789012",
  "codigoMaquina": "MAQ001",
  "cpf": "12345678901",
  "cartao": "1234567890123456"
}

Campos da Requisição:

Campo	Tipo	Descrição
estabelecimento	string	Código do estabelecimento lojista
tarja	string	Número do cartão (tarja magnética)
voucher	string	Voucher do cartão digital (se aplicável)
valor	number	Valor a ser estornado
nsu	string	NSU da transação original
codigoMaquina	string	Código da máquina/terminal
cpf	string	CPF do cliente
cartao	string	Número do cartão

Exemplo de Requisição:

curl -X POST "https://apihml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes/desfazimento" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "12345",
    "tarja": "1234567890123456",
    "valor": 150.00,
    "nsu": "123456789012",
    "codigoMaquina": "MAQ001",
    "cpf": "12345678901",
    "cartao": "1234567890123456"
  }'

Exemplo de Resposta (200 Success):

{
  "mensagem": "Venda desfeita com sucesso",
  "status": "ESTORNADO",
  "dataHora": "2025-12-03T16:00:00.000Z"
}

---

5️⃣ Criar Pré-Autorização com Biometria

Cria uma pré-autorização utilizando biometria do cliente para maior segurança. Este método não requer a senha do cartão.

Endpoint: POST /pre-autorizacoes/biometria

Corpo da Requisição:

{
  "cpf": "12345678901",
  "estabelecimento": "12345",
  "nsu": "123456789012",
  "codigoMaquina": "MAQ001",
  "venda": {
    "valor": 150.00,
    "quantidadeParcelas": 3,
    "tipoParcelamento": "LOJA",
    "numeroPedido": "PED-2025-001",
    "codigoPlano": "PLANO01"
  },
  "identificador": "PDV01"
}

Campos da Requisição:

Campo	Tipo	Descrição
cpf	string	CPF do cliente
estabelecimento	string	Código do estabelecimento lojista
nsu	string	Número Sequencial Único da transação
codigoMaquina	string	Código da máquina/terminal
venda.valor	number	Valor total da venda
venda.quantidadeParcelas	integer	Quantidade de parcelas
venda.tipoParcelamento	string	Tipo de parcelamento
venda.numeroPedido	string	Número do pedido
venda.codigoPlano	string	Código do plano de parcelamento
identificador	string	Identificador do PDV

Exemplo de Requisição:

curl -X POST "https://apihml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes/biometria" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678901",
    "estabelecimento": "12345",
    "nsu": "123456789012",
    "codigoMaquina": "MAQ001",
    "venda": {
      "valor": 150.00,
      "quantidadeParcelas": 3,
      "tipoParcelamento": "LOJA",
      "numeroPedido": "PED-2025-001",
      "codigoPlano": "PLANO01"
    },
    "identificador": "PDV01"
  }'

Exemplo de Resposta (200 Success):

{
  "preAutorizacao": 789013,
  "mensagem": "Pré-autorização com biometria criada com sucesso",
  "status": "APROVADO",
  "urlBiometria": "https://biometria.credsystem.com.br/validate/xyz123"
}

Vantagens da Biometria

• ✅ Maior segurança na transação
• ✅ Não requer digitação de senha
• ✅ Reduz fraudes
• ✅ Melhor experiência do cliente

---

6️⃣ Consultar Limite e Situação do Cartão

Consulta o limite disponível e situação do cartão antes de realizar uma venda.

Endpoint: GET /limite-situacao

Parâmetros:

Parâmetro	Tipo	Local	Obrigatório	Descrição
Authorization	string	Header	✅ Sim	Bearer token JWT
cartao	string	Header	✅ Sim	Número do cartão
cpf	string	Header	✅ Sim	CPF do cliente
estabelecimento	integer	Query	✅ Sim	Código do estabelecimento
valorCompra	number	Query	✅ Sim	Valor da compra a ser validado
isInfoPlanos	boolean	Query	❌ Não	Se deve retornar informações dos planos (default: false)

Exemplo de Requisição:

curl -X GET "https://apihml.credsystem.com.br/venda-loja/api/v1/limite-situacao?estabelecimento=12345&valorCompra=150.00&isInfoPlanos=true" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cartao: 1234567890123456" \
  -H "cpf: 12345678901"

Exemplo de Resposta (200 Success):

{
  "limiteDisponivel": 5000.00,
  "limiteTotal": 10000.00,
  "limiteUtilizado": 5000.00,
  "situacaoCartao": "ATIVO",
  "podeComprar": true,
  "planos": [
    {
      "codigoPlano": "PLANO01",
      "descricao": "Parcelamento Loja - 3x sem juros",
      "quantidadeMaxParcelas": 3,
      "taxaJuros": 0.00
    },
    {
      "codigoPlano": "PLANO02",
      "descricao": "Parcelamento Loja - 6x",
      "quantidadeMaxParcelas": 6,
      "taxaJuros": 2.99
    }
  ]
}

Situações do Cartão:

Situação	Pode Comprar?	Descrição
ATIVO	✅ Sim	Cartão ativo e funcionando normalmente
BLOQUEADO	❌ Não	Cartão bloqueado temporariamente
CANCELADO	❌ Não	Cartão cancelado definitivamente
VENCIDO	❌ Não	Cartão com validade expirada
LIMITE_INSUFICIENTE	❌ Não	Sem limite disponível para a compra

Importante

Sempre consulte o limite antes de realizar uma venda para evitar transações negadas.

---

7️⃣ Cancelar Contrato

Cancela um contrato de venda já efetivado.

Endpoint: POST /contrato/cancelamento

Corpo da Requisição:

{
  "estabelecimento": "12345",
  "identificador": "PDV01",
  "contrato": "456789",
  "codigoMaquina": "MAQ001",
  "cartao": "1234567890123456",
  "tarja": "1234567890123456",
  "voucher": "VOUCHER123",
  "cpf": "12345678901"
}

Campos da Requisição:

Campo	Tipo	Descrição
estabelecimento	string	Código do estabelecimento lojista
identificador	string	Identificador do PDV
contrato	string	Número do contrato a ser cancelado
codigoMaquina	string	Código da máquina/terminal
cartao	string	Número do cartão
tarja	string	Número do cartão (tarja magnética)
voucher	string	Voucher do cartão digital (se aplicável)
cpf	string	CPF do cliente

Exemplo de Requisição:

curl -X POST "https://apihml.credsystem.com.br/venda-loja/api/v1/contrato/cancelamento" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "12345",
    "identificador": "PDV01",
    "contrato": "456789",
    "codigoMaquina": "MAQ001",
    "cartao": "1234567890123456",
    "cpf": "12345678901"
  }'

Exemplo de Resposta (200 Success):

{
  "mensagem": "Contrato cancelado com sucesso",
  "contrato": "456789",
  "status": "CANCELADO",
  "dataHora": "2025-12-03T16:30:00.000Z"
}

---

8️⃣ Obter Working Key

Obtém a chave de trabalho (working key) utilizada para criptografia de dados sensíveis como senhas de cartão.

Endpoint: GET /working-key

Headers:

Header	Tipo	Obrigatório	Descrição
Authorization	string	✅ Sim	Bearer token JWT

Exemplo de Requisição:

curl -X GET "https://apihml.credsystem.com.br/venda-loja/api/v1/working-key" \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

Exemplo de Resposta (200 Success):

{
  "workingKey": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6",
  "algoritmo": "AES256",
  "dataExpiracao": "2025-12-03T23:59:59.000Z"
}

Segurança

• A working key deve ser armazenada de forma segura
• Utilize a working key para criptografar senhas antes de enviar
• Renove a working key periodicamente
• Nunca exponha a working key em logs ou interfaces públicas

---

🔄 Fluxo Completo de Venda

Fluxo 1: Venda com Senha do Cartão

Fluxo 2: Venda com Biometria

---

📋 Exemplo Prático Completo

Aqui está um exemplo completo em JavaScript de como realizar uma venda:

const API_BASE = 'https://apihml.credsystem.com.br/venda-loja/api/v1';
const TOKEN = 'SEU_TOKEN_JWT';

async function realizarVenda() {
  try {
    // 1. Consultar limite do cartão
    const limiteResponse = await fetch(
      `${API_BASE}/limite-situacao?estabelecimento=12345&valorCompra=150.00&isInfoPlanos=true`,
      {
        headers: {
          'Authorization': `Bearer ${TOKEN}`,
          'cartao': '1234567890123456',
          'cpf': '12345678901'
        }
      }
    );
    
    const limite = await limiteResponse.json();
    console.log('💰 Limite disponível:', limite.limiteDisponivel);
    
    if (!limite.podeComprar) {
      throw new Error('Cliente sem limite disponível');
    }
    
    // 2. Obter working key para criptografar senha
    const keyResponse = await fetch(`${API_BASE}/working-key`, {
      headers: {
        'Authorization': `Bearer ${TOKEN}`
      }
    });
    
    const { workingKey } = await keyResponse.json();
    console.log('🔑 Working key obtida');
    
    // 3. Criptografar senha (implementar função de criptografia)
    const senhaCriptografada = criptografarSenha('1234', workingKey);
    
    // 4. Criar pré-autorização
    const preAuthResponse = await fetch(`${API_BASE}/pre-autorizacoes`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        estabelecimento: '12345',
        identificador: 'PDV01',
        codigoMaquina: 'MAQ001',
        usuario: 'vendedor01',
        nsu: '123456789012',
        cartao: {
          tarja: '1234567890123456',
          cvv2: '123',
          senhaCriptografada: senhaCriptografada
        },
        venda: {
          valor: 150.00,
          quantidadeParcelas: 3,
          tipoParcelamento: 'LOJA',
          codigoPlano: limite.planos[0].codigoPlano
        }
      })
    });
    
    const preAuth = await preAuthResponse.json();
    console.log('✅ Pré-autorização criada:', preAuth.Content.preAutorizacao);
    
    if (preAuth.Content.status !== 'APROVADO') {
      throw new Error('Pré-autorização negada');
    }
    
    // 5. Capturar (efetivar) a venda
    const capturaResponse = await fetch(`${API_BASE}/pre-autorizacoes/captura`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        estabelecimento: '12345',
        preAutorizacao: preAuth.Content.preAutorizacao,
        numeroPedido: 'PED-2025-001',
        valor: 150.00
      })
    });
    
    const captura = await capturaResponse.json();
    console.log('🎉 Venda capturada com sucesso!');
    console.log('Número do Contrato:', captura.Content.numeroContrato);
    
    return captura;
    
  } catch (error) {
    console.error('❌ Erro na venda:', error);
    throw error;
  }
}

// Função auxiliar de criptografia (exemplo simplificado)
function criptografarSenha(senha, workingKey) {
  // Implementar criptografia AES256 com a working key
  // Este é apenas um exemplo - use uma biblioteca de criptografia adequada
  return 'SENHA_CRIPTOGRAFADA';
}

// Executar
realizarVenda();

---

💡 Dicas e Boas Práticas

✅ Recomendações

1. Sempre consulte o limite - Verifique o limite disponível antes de criar a pré-autorização
2. Criptografe senhas corretamente - Use a working key e algoritmo AES256
3. Valide o NSU - Gere NSUs únicos para cada transação
4. Capture imediatamente - Não deixe pré-autorizações pendentes por muito tempo
5. Guarde o número do contrato - Necessário para cancelamentos futuros
6. Implemente timeout - Não deixe transações pendentes indefinidamente
7. Use biometria quando disponível - Aumenta a segurança e melhora a experiência

❌ Evite

1. ❌ Não armazene senhas de cartão sem criptografia
2. ❌ Não exponha a working key
3. ❌ Não reutilize NSUs
4. ❌ Não deixe pré-autorizações sem captura
5. ❌ Não ignore erros de limite insuficiente
6. ❌ Não faça desfazimento sem validação

---

⚠️ Tratamento de Erros

Principais Erros:

Status	Erro	Solução
400	Authorization é obrigatório	Incluir header Authorization com token válido
401	Token inválido ou expirado	Renovar o token de autenticação
403	Acesso negado	Verificar permissões do estabelecimento
404	Pré-autorização não encontrada	Verificar número da pré-autorização
422	Limite insuficiente	Cliente sem limite para a compra
422	Senha incorreta	Validar senha com o cliente
500	Erro interno	Tentar novamente ou contatar suporte

---

🔒 Segurança

Criptografia de Senha

// Exemplo de criptografia com working key
const CryptoJS = require('crypto-js');

function criptografarSenhaCartao(senha, workingKey) {
  // Converter working key de hex para WordArray
  const key = CryptoJS.enc.Hex.parse(workingKey);
  
  // Criptografar usando AES
  const encrypted = CryptoJS.AES.encrypt(senha, key, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  });
  
  // Retornar em formato Base64
  return encrypted.toString();
}

// Uso
const senhaCriptografada = criptografarSenhaCartao('1234', workingKey);

Proteção de Dados

• 🔐 PCI DSS Compliance - Siga as normas PCI para manipulação de dados de cartão
• 🔒 HTTPS Obrigatório - Todas as requisições devem usar HTTPS
• 🚫 Não armazene CVV - Nunca armazene o código de segurança
• 🔑 Renove tokens - Implemente renovação automática de tokens JWT
• 📝 Log seguro - Não registre dados sensíveis em logs

---

🆘 Suporte

Contato Técnico

Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.

Em Caso de Erro

1. Anote o NSU da transação
2. Capture os dados da requisição (sem informações sensíveis)
3. Verifique os logs de erro
4. Envie para o email de suporte com assunto: [API Venda Loja] - Descrição do Problema

---

Última atualização: 03 de Dezembro de 2025
Versão da API: 1.0