## Introdução
A integração entre o Sistema e a plataforma de pagamentos Vindi visa automatizar fluxos financeiros e de vendas, oferecendo soluções de pagamento robustas e eficientes. Esta documentação detalha o processo de integração, seus benefícios e configurações necessárias.

> [!NOTA] Solução Oferecida
> Meio de pagamento para pagamentos via cartão de crédito de forma individual e recorrente.

## Acesso
> [!NOTA] Acesso ao Formulário
> Caminho: Sistema > Cadastros > Financeiro > Carteira de cobrança

### Benefícios da Integração

| Benefício                  | Descrição                                                         |
| -------------------------- | ----------------------------------------------------------------- |
| Automação                  | Redução de intervenção manual e aumento da eficiência operacional |
| Recorrência                | Pagamento de cartão de crédito na opção recorrente                |
| Receita Previsível         | Pagamentos recorrentes garantem fluxo de caixa mais estável       |
| Conveniência para Clientes | Pagamentos recorrentes reduzem atrasos e interrupções de serviço  |

## Estrutura 

## Como funciona a integração
1. Configuração
2. Acesso à Central do Assinante
3. Escolha da Opção de Pagamento
4. Preenchimento dos dados do Cartão de Crédito
5. Habilitação da Recorrência 

> [!WARNING] Atenção!
> Ao acessar as faturas na **Central do Assinante**, as cobranças **Vindi** também são listadas, permitindo um **pagamento alternativo via Pix** caso não estejam comunicadas. Independentemente do local de pagamento, se a fatura for quitada pela alternativa **Pix**, a **cobrança Vindi é cancelada**, e vice-versa.

### Etapas de configuração do módulo
* Configurações da integração com o cartão de crédito
* Juros/Multas/Desconto
* Configuração da tarefa que cobra as recorrências

## Campos obrigatórios
* **Descrição**: nome do cadastro de carteira de cobrança
* **Conta**: cadastro de conta vinculado a carteira
* **Tipo de recebimento**: modalidade da integração que gera as cobranças
* **Validar filial na venda**: se marcado como **Sim**, valida como necessário a filial do Contrato do Cliente ser igual à filial da carteira de cobrança
* **Ativo**: ativa ou inativa o cadastro da carteira de cobrança no Sistema

## Processo de Integração e Homologação
Para realizar a integração e homologação da **Integração de Cartão de Crédito Vindi** no Sistema, siga estes passos:

### Homologação
Para realizar a integração é necessário abrir um atendimento com o setor **Suporte Técnico** e você precisará dos seguintes dados:

> [!EXAMPLE] Dados Necessários
>
> **Vindi (API Cartão de Crédito)**
>
> * 1 - Número da agência com dígito?
> * 2 - Número da conta com dígito?
> * 3 - Chave (Merchant_Key)?
> * 4 - Plano na Vindi?

> [!TIP] Dica!
> Caso tenha dúvida sobre algum dos dados bancários, consulte o(a) Gerente de sua Conta Bancária.

### Passo a passo para obter as Credenciais da API

> [!info] Informação!
> Para a homologação da **Carteira de Cartão de Crédito Vindi**, você também precisa gerar a "Chave" e o "Plano na Vindi", sendo as credenciais da aplicação da API geradas no Internet Banking da Vindi.

1. Acesse o **Internet Banking Vindi**:
	- https://vindi.com.br/login/
2. Faça login com sua Conta
3. No menu lateral esquerdo, clique no menu **Configurações** e então em **Chaves de API**
4. Clique no botão **Nova Chave**
5. Depois, clique no botão **Criar Chave de acesso**
6. Copie a chave gerada e guarde essa informação

Agora você deve criar o Plano de Venda Vindi, para isso, siga os passos:
1. Ainda em sua conta Vindi, acesse o menu **Configurações** e clique em **Produtos**
2. Clique no botão **Novo Produto**
3. Depois, clique em **Criar Produto**
4. Feito isso, crie o plano, acessando "Menu Configurações > Planos > Novo Plano"
5. Insira o produto criado anteriormente e clique no botão **Criar Plano**
6. Com o plano criado, copie o ID do plano gerado

> [!SUCCESS] Credenciais API Finalizadas!
> Feito isso, com os seus outros dados bancários, o atendente da IXC Soft poderá prosseguir com a homologação da sua carteira de cobrança de Cartão de Crédito.

### Criando a Carteira
1. Acesse o menu **Sistema**
2. Pasta **Financeiro**
3. E clique em **Carteira de cobrança**
4. Clique em **Novo**

> [!WARNING] Aviso!
> Antes de qualquer configuração, dirija-se a aba **Impressão**, e no campo **Layout de Impressão** escolha o modelo: **Boleto + fatura detalhada**.
> 
> Como a integração de cartão não gera nenhum documento, com esta configuração, ao ser solicitada uma impressão será gerada uma fatura detalhada.

5. Na primeira aba chamada **Carteira de cobrança**, você fará as seguintes configurações:
	- **Descrição:** Aqui você irá definir a nomeação da carteira
	- **Conta:** Aqui você irá criar a conta, responsável por armazenar seus dados bancários. 
	- **Tipo de recebimento:** Neste campo você deve selecionar a opção **Cartão de crédito
	- **Enviar e-mail para cliente ao gerar:** Marcar como **Não**, pois torna obrigatório o e-mail de cadastro do cliente e envia automaticamente a fatura do cliente, fazendo assim o registro da mesma no banco (sendo assim, não é recomendado o uso)
	- **Validar filial na venda:** Marcar como **Não**
	- **Ativo:** Manter marcado como **Sim**
	- **Filial:** Remover o cadastro, clicando no botão **X** posicionado ao lado direito do campo
	- **Planejamento analítico:** utilize o padrão **240**, ou cadastre um novo

### Criando a Conta
- **Conta:** Defina o nome para a conta
- **Tipo da Conta:** Marque a opção **Banco**
- **Data de abertura:** Informe o dia em que está configurando a conta para esta carteira.
- **Planejamento analítico:** Para mais informações, acesse: [[formulario planejamento analitico|Formulário Planejamento Analítico]]
- **Filial:** Selecione o ID da filial para a qual será criada esta **Conta** e a **Carteira**

Na aba seguinte **Banco:**
- **Agência:** Número da sua agência bancária.
- **Dígito verificador da agência:** Insira o dígito verificador que fica após o número da agência.
- **Número da conta:** Número da sua conta bancária.
- **Dígito verificador da conta:** Informe o dígito verificador de sua conta bancária.

### Configurações Cartão de Crédito
- **Gateway:** Selecione o **Vindi**
- **Ambiente gateway:** Selecione **Produção**
- **Chave:** Insira o **Merchant_Key** das credenciais API gerado no site
- **Plano na Vindi:** Insira o ID de Plano Vindi criado no site
- **Máximo de parcelas:** Defina o valor padrão como 1, para permitir somente o valor integral da cobrança, caso desejar ofertar o parcelamento, aumente este valor conforme o necessário
- **Juro (% ao mês):** Valor percentual de juros para o parcelamento de cartão, considerado somente se o valor de **Máximo de parcelas** for maior que 1 (um)
- **Repassar taxa para o cliente:** Defina como "Sim" para que a taxa de transação cobrada pela integração de pagamento seja incluída no valor da fatura/cobrança do cliente, e se marcado como "Não", será cobrado somente o valor integral da venda que gerou a fatura. 

> [!WARNING] Aviso!
> Ao salvar a carteira, o campo **Webhook** será preenchido com o endereço para onde serão enviadas as notificações. Esse endereço precisará ser configurado também na plataforma da Vindi. <br>
> Veja como realizar esse processo no tópico abaixo.

### Configurando a URL de Notificações Webhook na Vindi
Para configurar a URL de Notificações Webhook na Vindi, siga os passos:
1. Logado em sua conta Vindi, acesse o menu **Configurações**
2. Clique na opção **Webhook**
3. Em seguida, clique em **Novo Webhook**
4. Insira a URL que foi gerada na carteira de cobrança, no Sistema
5. Marque a opção de **Fatura paga**
6. Finalize clicando em **Criar Webhook**

#### Redirecionar Taxas (Nova Função)
> [!TIP] Melhoria!
> Nas configurações de Carteiras de Cobrança para **Cartão de Crédito**, foi adicionada a opção de repassar as taxas transacionais ao cliente (seção "Redirecionar taxas"). Essa prática, prevista por lei, pode agora ser aplicada a pagamentos manuais e recorrentes.

Caso marque o parâmetro **Repassar taxa para o cliente** como "Sim", novos campos serão mostrados para a parametrização das taxas:
- **Será aplicada em pagamentos:** Individuais, Recorrentes ou Ambos
- **Porcentagem da taxa (%):** Informe o percentual que será calculado sobre o valor da venda e adicionado como acréscimo ao cliente no pagamento com Cartão de Crédito
- **Valor fixo da taxa (R$):** Informe o valor fixo em **Reais** que será acrescentado ao cliente no pagamento com Cartão de Crédito

> [!WARNING] Aviso!
> Ao selecionar a opção **Individuais**, a taxa será aplicada somente a pagamentos realizados pela Central do Assinante, onde será paga apenas uma parcela. <br>
> Na opção **Recorrentes**, a taxa será aplicada nas cobranças que possuem recorrência ativa. <br> 
> E selecionando **Ambos** a taxa será aplicada para as duas modalidades. No caso da Vindi, selecione a opção **Recorrentes.**

### Juros/Multas/Desconto
- **Juros %:** valor padrão (máximo permitido por lei, acima é caracterizado juro abusivo), configure 0.033%
- **Multa %:** valor padrão (máximo permitido por lei, acima é caracterizado multa abusiva), configure 2%
- **Desconto até o vencimento R$:** insira um valor em Reais para conceder desconto na fatura, se paga até a data do vencimento
- **Desconto até o vencimento %:** insira um valor em **Porcentagem** para conceder desconto na fatura, se paga até a data do vencimento

Para mais informações, acesse: [[juros, multas e desconto|Juros, Multas e Desconto]].

> [!NOTE] Dica!
> Por fim, finalize a configuração de sua carteira, clicando no botão **Salvar**.
> Agora é importante realizar a ativação de sua carteira no sistema, para que seus clientes tenham acesso a esta modalidade de pagamento, conforme instruções abaixo.

## Ativando a Carteira de Cobrança no Sistema 
Agora que sua carteira está configurada, você precisa fazer seu vínculo de duas formas possíveis: 

* **Hotsite (Central do Assinante):** Configurando a carteira nos parâmetros gerais do seu Sistema, no Hotsite, possibilitará que todos os clientes de sua base tenham acesso ao pagamento com esta carteira de cobrança através da **Central do Assinante**.
* **Alternativa de Pagamento:** Configurando e vinculando sua carteira de cartão a uma **Alternativa de Pagamento**, possibilitará que você insira esta alternativa dentro de outras carteiras de cobrança específicas. Isso abre possibilidades, como permitir que somente determinada cartela de clientes tenha acesso ao pagamento com cartão, ou até mesmo criar diferentes alternativas de pagamento, inserindo carteiras de cartão com diferentes valores de desconto até vencimento.

### Configurando a Carteira no Hotsite - Central do Assinante
1. Acesse o menu **Sistema**
2. Vá ao Submenu **Hotsite**
3. Pasta **Configurações**
4. Clique em **Configurações Geral**
5. Acesse a aba **Financeiro**
6. Configure os parâmetros de **Cartão de Crédito** e de **Recorrência com Cartão de Crédito**
7. Finalize clicando em **Salvar**

## Tarefa de Baixa de Títulos em Recorrência
Agora que sua carteira está configurada e ativa, é necessário que uma tarefa seja configurada, esta que será responsável por criar e enviar para a Integração a requisição de pagamento das cobranças recorrentes, que ocorre no dia do seu vencimento no sistema.

Para realizar a configuração, acesse:

1. Menu **Ferramentas**
2. Clique em **Ferramentas**
3. **Agenda de tarefas**
4. Botão **Novo**
5. **Tarefa:** Selecione **Baixar títulos cartão de crédito recorrente**
6. **Minuto (0-59):** Coloque o valor dos minutos, entre 0 e 59 min
7. **Hora (0-23):** Coloque o valor da hora, entre 0 e 23

> [!TIP] Dica!
> Recomenda-se que a tarefa seja configurada para executar somente **uma vez ao dia**, em um horário não conflitante com nenhuma outra tarefa.

## Fluxos e Processos

### Fluxo de Integração
```mermaid
sequenceDiagram
    participant S as Sistema
    participant API as API Vindi
    participant W as Webhook

    S->>API: Envia requisição (ex: gerar fatura)
    API->>S: Responde com dados da fatura
    Note over API,W: Evento ocorre (ex: pagamento)
    W->>S: Notifica sobre o evento
    S->>API: Confirma recebimento da notificação
```

## Considerações Finais
> [!SUCCESS] Concluído!
> A integração entre a Vindi e o IXC Provedor é um avanço significativo que visa melhorar o ambiente de negócios para provedores de serviço. <br>
> Com automação, redução de custos e suporte às demandas dos clientes, essa parceria é um passo importante para o futuro financeiro eficiente e simplificado.

## Etiquetas 
#IntegracaoFinanceira #Vindi #PagamentosOnline #CartaoDeCredito #APIVindi #Recorrencia 

## Leia Também
- [[como ativar a recorrencia na vindi|Como Ativar a Recorrência na Vindi]]
- [[como criar cobrancas para cliente na vindi|Como Criar Cobranças para Cliente na Vindi]]
- [[carteira de cobranca|Carteira de Cobrança]]
- [[financeiro|Financeiro]]
- [[integracoes bancarias - carteira de cobranca|Integrações Bancárias - Carteira de Cobrança]]
- [[recorrencia com cartao de credito|Recorrência com Cartão de Crédito]]
- [[como o cliente ativa a recorrencia|Como o Cliente Ativa a Recorrência]]
- [[como o cliente cancela a recorrencia|Como o Cliente Cancela a Recorrência]]
- [[verificar financeiro recorrente com cartao|Verificar Financeiro Recorrente com Cartão]]
- [[relatorio de contratos em recorrencia|Relatório de Contratos em Recorrência]]
- [[logs gateway|Logs Gateway]]
- [[como reprocessar logs gateway|Como Reprocessar Logs Gateway]]
- [[localizar pagamentos - logs gateway|Localizar Pagamentos - Logs Gateway]]
- [[logs de rotinas de cobranca gateway|Logs de Rotinas de Cobrança Gateway]]
- **Manual API Vindi:** https://atendimento.vindi.com.br/hc/pt-br/articles/203020644-Introdu%C3%A7%C3%A3o-%C3%A0-API-de-Recorr%C3%AAncia-da-Vindi