Introdução às Vendas na API

A API de vendas permite registrar transações envolvendo prospects (clientes potenciais) e membros (clientes registrados), abrangendo a aquisição de serviços, contratos de adesão e aulas experimentais. Ela foi desenvolvida para oferecer flexibilidade e precisão no controle comercial, integrando processos como aplicação de descontos, definição de forma de pagamento (à vista ou parcelado), uso de vouchers e vinculação à filial responsável pela venda.

Cada tipo de venda possui um fluxo específico, determinado pelo status do cliente (prospect ou membro) e pelo tipo de produto adquirido (serviço ou contrato). Este guia apresenta os principais casos de uso, com exemplos práticos e estrutura de payloads, para facilitar a integração correta com a API.

O uso adequado dos campos obrigatórios e opcionais garante que as informações sejam processadas corretamente pelo sistema, otimizando o registro das vendas e a conversão de prospects em membros ativos.

Casos de Uso

Caso 1: Prospect + Serviço

Descrição:
Um prospect (potencial cliente) realiza uma compra de um serviço específico. O sistema registra o prospect e o serviço adquirido.

Campos Obrigatórios:

idProspect: Identificação do prospect.
idService: Identificação do serviço adquirido.
payment: Tipo de pagamento (1 para à vista, 5 para parcelado).
idMember: 0 (indica que ainda não é membro).

Exemplo:

{
  "memberData": {
    "idMember": 0
  },
  "idProspect": 27473,
  "idService": 481,
  "payment": 5
}

Fluxo:

Prospect identificado por idProspect.
Serviço associado por idService.
Pagamento registrado em payment.
Se parcelado, usar totalInstallments.
O campo serviceValue pode ser ajustado.

Caso 2: Membro + Serviço

Descrição:
Um membro registrado realiza a compra de um serviço. O sistema associa o serviço ao membro.

Campos Obrigatórios:

idMember: Identificação do membro.
idService: Identificação do serviço adquirido.
payment: Tipo de pagamento.

Exemplo:

{
  "memberData": {
    "idMember": 12345
  },
  "idService": 481,
  "payment": 6
}

Fluxo:

Membro identificado por idMember.
Serviço identificado por idService.
Pagamento registrado.
Parcelamento com totalInstallments, se aplicável.
serviceValue ajustável.

Caso 3: Venda de Contrato para Prospect

Descrição:
Um prospect adquire um contrato de adesão. O sistema registra a venda para o prospect.

Campos Obrigatórios:

idProspect: Identificação do prospect.
idMembership: ID do contrato adquirido.
payment: Tipo de pagamento.
idMember: 0 (não é membro ainda).

Exemplo:

{
  "memberData": {
    "idMember": 0
  },
  "idProspect": 27473,
  "idMembership": 789,
  "payment": 6
}

Fluxo:

Prospect identificado por idProspect.
Contrato identificado por idMembership.
Tipo de pagamento informado.
Parcelamento com totalInstallments, se necessário.
Valor ajustável (serviceValue), possível uso de voucher.
Após compra, prospect se torna membro (idMember atribuído).

Caso 4: Venda de Contrato para Membro

Descrição:
Um membro adquire um contrato de adesão. O sistema associa a venda ao membro.

Campos Obrigatórios:

idMember: Identificação do membro.
idMembership: ID do contrato.
payment: Tipo de pagamento.

Exemplo:

{
  "memberData": {
    "idMember": 12345
  },
  "idMembership": 789,
  "payment": 6
}

Caso 5: Aula Experimental para Prospect

Descrição:
O prospect deseja realizar a inscrição em uma aula experimental, onde o valor é zerado para promover o serviço e gerar interesse. A transação é registrada com um pagamento de valor zero, mas é tratada como uma transação válida no sistema, com o payment definido para 5 (indicando que é um serviço, mesmo sem valor de pagamento).

Campos Obrigatórios:

idProspect: Identificação do prospect.
idService: ID da aula experimental.
payment: 5 (indica serviço gratuito).
idMember: 0.

Campos Opcionais:

idBranch: Se houver múltiplas filiais.

Exemplo:

{
  "memberData": {
    "idMember": 0
  },
  "idProspect": 27473,
  "idService": 101,
  "payment": 5
}

Fluxo:

Prospect realiza inscrição (campo idProspect).
Aula experimental identificada pelo idService.
Pagamento marcado como 5 (zerado).
Venda registrada com idMember: 0.

Recursos Adicionais

1. Adicionando Parcelamento

Se a venda for parcelada, preencha o campo totalInstallments com o número de parcelas.
Por exemplo, para 12 parcelas:

"totalInstallments": 12

Se for pagamento à vista, o campo pode ser:

"totalInstallments": 0

"totalInstallments": 1

2. Adicionando Voucher de Desconto

Se o cliente utilizar um voucher para obter um desconto, insira o código do voucher no campo voucher.
O sistema aplicará o desconto automaticamente ao valor do contrato ou serviço.

"voucher": "MEUDESCONTO123"

3. Alterando o Valor do Serviço (Apenas para serviços)

O campo serviceValue pode ser ajustado caso haja algum desconto, modificação ou outra alteração no valor do serviço.
Se não for informado, o sistema utilizará o valor padrão cadastrado.

"serviceValue": 199.90

4. Escolhendo a Filial da Venda (Token Multifilial)

Se o sistema operar com múltiplas filiais, utilize o campo idBranch para indicar a filial responsável pela venda.
Caso o token de autenticação seja multifilial:

Se idBranch for informado, a venda será registrada na filial correspondente.
Se idBranch não for informado, o sistema usará o valor de idBranch do próprio token.

"idBranch": 12

Evo Pay

Este tutorial descreve como integrar o Evo Pay para tokenização de cartões de crédito e realizar vendas via API. O processo inclui a configuração do Evo Pay no frontend, a captura do token do cartão e a realização da venda através da API de vendas.

Passo 1: Configuração do Evo Pay

Antes de começar, carregue o script do Evo Pay para permitir a tokenização de cartões.

Adicione o script do Evo Pay no seu HTML:
Inclua a tag <script> no <head> do seu HTML para carregar o script do Evo Pay.
```
<head>
  <script src="https://w12evopay.com/evocartao/evo-pay.js"></script>
</head>
```
Criando o componente para capturar os dados do cartão:
Adicione o componente <evo-cartao> no corpo da página. Esse componente será responsável pela captura dos dados do cartão.

<body>
  <div>
    <h1>Teste de Pagamento</h1>
    <evo-cartao></evo-cartao>
    <button onclick="salvar()">Salvar</button>
    <textarea id="retorno" readonly placeholder="Retorno do EVO PAY aparecerá aqui..."></textarea>
  </div>
</body>

Configuração do Componente no JS:
Defina o componente evo-cartao e configure os dados necessários (gateway, bandeiras de cartões, traduções) para que ele funcione corretamente.

var evoCartao;

setTimeout(() => {
  evoCartao = document.querySelector('evo-cartao');
  evoCartao.classes = 'form-no-style';

  // Configuração do Gateway (dados do EVO Pay)
  evoCartao.gateway = {
    //Obter dados através da API https://evo-integracao.w12app.com.br/api/v1/configuration/gateway
  };

  // Configuração das bandeiras de cartões aceitas
  evoCartao.bandeiras = [
    //Obter os dados através da API https://evo-integracao.w12app.com.br/api/v1/configuration/card-flags
  ];

  // Traduções (se necessário)
  evoCartao.traducoes = {
    //Obter os dados através da API https://evo-integracao.w12app.com.br/api/v1/configuration/card-translation
  };

  // Eventos de sucesso ou erro na tokenização do cartão
  evoCartao.addEventListener('eventoTokenGerado', (event) => {
    console.log(event.detail);
    document.getElementById('retorno').value = JSON.stringify(event.detail, null, 2);
  });

  evoCartao.addEventListener('eventoOcorreuErro', (event) => {
    console.error(event.detail);
    alert(event.detail);
    document.getElementById('retorno').value = `Erro: ${JSON.stringify(event.detail, null, 2)}`;
  });
}, 500);

function salvar() {
  evoCartao.dispatchEvent(new CustomEvent('salvar'));
}

Configuração do Gateway (evoCartao.gateway)
1. Este código configura o gateway de pagamento do Evo Pay. Ele utiliza dados fornecidos pela API do Evo, que pode incluir informações sobre a chave pública (publicKey), configurações de antifraude, e outras propriedades necessárias para o processamento do pagamento.
2. Fonte dos Dados: A URL mencionada (https://evo-integracao-api.w12app.com.br/api/v1/configuration/gateway) fornece essas informações.
```
evoCartao.gateway = {  
  // Obter dados através da API  
  // https://evo-integracao-api.w12app.com.br/api/v1/configuration/gateway
};
```
Configuração das Bandeiras de Cartões Aceitas (evoCartao.bandeiras)
1. Essa parte configura quais bandeiras de cartões são aceitas pelo sistema. As bandeiras podem incluir cartões como VISA, Mastercard, Amex, entre outros.
2. Fonte dos Dados: A URL fornecida (https://evo-integracao-api.w12app.com.br/api/v1/configuration/card-flags) é responsável por fornecer a lista de bandeiras suportadas, que será utilizada para exibir opções para o usuário no frontend.
```
evoCartao.bandeiras = [  
  // Obter dados através da API  
  // https://evo-integracao-api.w12app.com.br/api/v1/configuration/card-flags 
];
```
Configuração das Traduções (evoCartao.traducoes)
1. Esta configuração é usada para traduzir os campos do formulário de pagamento, como "Número do Cartão", "Nome do Titular", etc. Isso garante que os labels do formulário sejam apresentados no idioma correto para o usuário final.
2. Fonte dos Dados: Os dados de tradução são obtidos de uma API específica (https://evo-integracao-api.w12app.com.br/api/v1/configuration/card-translation), onde são fornecidas as traduções para cada campo do cartão de pagamento.
```
evoCartao.traducoes = {  
  // Obter dados através da API  
  // https://evo-integracao-api.w12app.com.br/api/v1/configuration/card-translation
};
```

Passo 2: Usar o Token Gerado

Quando o cartão for tokenizado com sucesso, o evento 'eventoTokenGerado' será disparado, e você receberá um objeto com o token gerado. Esse token será utilizado para realizar a venda no Evo.

Passo 3: Realizar a Venda

Com o token gerado pelo Evo Pay, você pode realizar a venda via a API de vendas.

Exemplo de chamada POST para o endpoint de vendas:

const vendaData = {
  "idBranch": 1, // ID da filial de venda
  "idMembership": 0, // Se for um serviço, passe 0
  "idService": 123, // ID do serviço
  "memberData": {
    "idMember": 12345, // ID do membro ou prospect
    "document": "12345678900",
    "zipCode": "12345000",
    "address": "Rua Exemplo",
    "number": "123",
    "complement": "Apto 101",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "idState": 35
  },
  "cardData": {
    "token": "TOKEN_GERADO_PELO_EVO", // Substitua com o token gerado
    "temporaryToken": "TEMP_TOKEN", // Se necessário
    "branchToken": "BRANCH_TOKEN", // Token da filial
    "totalInstallments": 1, // Número de parcelas para a opção 1 (Cartão de credito)
    "truncatedCardNumber": "1234", // Últimos 4 dígitos do cartão
    "brand": "VISA", // Bandeira do cartão
    "cardHolderName": "Nome do Titular",
    "cardExpirationYear": 2025,
    "cardExpirationMonth": 12
  },
  "idProspect": 0, // ID do Prospect
  "idMember": 0, // ID do Cliente
  "voucher": "DESCONTO123", // Se houver um voucher de desconto
  "idCardMember": 0, // ID do cartão se já houver
  "totalInstallments": 1, // Não funciona na opção 1 (Cartão de Credito)
  "payment": 1 // Tipo de pagamento: 1 para Cartão de Crédito
};

// Chamada para API de vendas
fetch("https://evo-integracao.w12app.com.br/api/v1/sales", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(vendaData)
})
  .then(response => response.json())
  .then(data => {
    console.log("Venda realizada com sucesso:", data);
  })
  .catch(error => {
    console.error("Erro na venda:", error);
  });

Passo 4: Resumo dos Fluxos de Trabalho

Tokenização do Cartão: Use o Evo Pay para capturar os dados do cartão e gerar um token. Isso ocorre ao clicar no botão "Salvar".
Realização da Venda: Após obter o token, use a API de vendas para registrar a venda, passando os dados do cliente, do serviço e do pagamento, incluindo o token gerado.
Respostas: O retorno do evento 'eventoTokenGerado' ou 'eventoOcorreuErro' informará se a tokenização foi bem-sucedida ou se houve erro.

Esse fluxo garante que você possa realizar vendas com segurança e facilidade, usando o Evo Pay para tokenizar os cartões e registrar transações.

Introdução às Vendas na API

Casos de Uso

Caso 1: Prospect + Serviço

Caso 2: Membro + Serviço

Caso 3: Venda de Contrato para Prospect

Caso 4: Venda de Contrato para Membro

Caso 5: Aula Experimental para Prospect

Recursos Adicionais

1. Adicionando Parcelamento

2. Adicionando Voucher de Desconto

3. Alterando o Valor do Serviço (Apenas para serviços)

4. Escolhendo a Filial da Venda (Token Multifilial)

Evo Pay

Passo 1: Configuração do Evo Pay

Configuração do Componente no JS:

Configuração do Gateway (evoCartao.gateway)

Configuração das Bandeiras de Cartões Aceitas (evoCartao.bandeiras)

Passo 2: Usar o Token Gerado

Passo 3: Realizar a Venda

Passo 4: Resumo dos Fluxos de Trabalho