## Introdução
A integração entre o Sistema e a plataforma de pagamentos Cielo 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 |
| Flexibilidade de Pagamento | Pagamento de cartão de crédito na opção individual ou 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 

### 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 Cielo** 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
>
> **Cielo (API Cartão de Crédito)**
>
> * 1 - Número da agência com dígito?
> * 2 - Número da conta com dígito?
> * 3 - Merchant ID?
> * 4 - Merchant Key?

> [!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
O serviço da API E-commerce Cielo 3.0 funciona de maneira 100% digital sem o uso de máquinas, o seu cliente efetuará o pagamento pela central do assinante e a baixa será automática no sistema.

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

Em seguida, acompanhe o passo-a-passo de como ter acesso às suas Credenciais de API da Cielo E-commerce versão 3.0.
Para acessar, siga os passos indicados abaixo:
- 1. Acesse o **Site da Cielo**: 
	- https://www.cielo.com.br/
- 2. Faça login, caso for seu primeiro acesso, clique em Cadastre-se e siga os passos para criar sua conta.
- 3. Se você tem mais de um estabelecimento cadastrado, selecione-o no menu superior.
- 4. Em seguida, acesse a aba **E-commerce**, e selecione a **API E-commerce Cielo**.
- 5. Você será redirecionado para uma nova página no ambiente **Braspag**, que é uma empresa Cielo.
- 6. Na nova página clique na opção Cielo e selecione **Credenciais**.
- 7. Será enviado um **código de validação** para o e-mail cadastrado em sua conta. Para receber o e-mail, clique e Visualizar **Merchant Key**.
- 8. Confira se o e-mail está correto e clique em Confirmar.
- 9. Agora, acesse seu e-mail e copie o código de validação.
- 10. De volta a página da API E-commerce, informe o código de validação e clique em Confirmar.

Anote a Merchant ID e Merchant Key para o processo de homologação de carteira.
E pronto! Sempre que precisar acessar suas credenciais Merchant ID e Merchant Key, repita os passos acima.

> [!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 a **Cielo 3.0**
- **Ambiente gateway:** Selecione **Produção**
- **Merchant ID:** Insira o **Merchant ID** gerado em suas credenciais E-commerce da Cielo
- **Chave:** Insira o **Merchant Key** gerado em suas credenciais E-commerce da Cielo
- **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. 

#### 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.

### 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**

> [!TIP] Dica!
> Você pode conferir o Passo a Passo completo a seguir no documento sobre como [[configurar recorrencia com cartao de credito|Configurar Recorrência com Cartão de Crédito]].

### Configurando a Carteira como Alternativa de Pagamento
1. Primeiramente, crie seu cadastro de **Alternativa de Pagamento**, conforme as instruções presentes em [[configuracoes alternativas de pagamento|Configurações Alternativas de Pagamento]]
2. No menu **Sistema > Cadastros > Financeiro > Carteira de Cobrança**, localize o cadastro de carteira que deseja implementar a alternativa
3. Clique no botão **Editar**
4. No parâmetro **Configuração de alternativa de pagamento**, insira o **ID** ou busque pela **Lupa** o cadastro de Alternativa criado anteriormente
5. Finalize a configuração, clicando em **Salvar**

> [!SUCCESS] Concluído!
> Apenas clientes com a carteira padrão do contrato, que tenham a **Alternativa de Pagamento** com a opção de cartão de crédito vinculada, poderão pagar suas faturas por meio dessa forma.

## 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 Cielo
    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
```

> [!EXAMPLE] Tabela Erros de Retorno Cielo
> - [[erro no pagamento com cartao de credito cielo - tabela interna|Erro no Pagamento com Cartão de Crédito Cielo - Tabela Interna]]
> - [[erro no pagamento com cartao de credito cielo - tabela externa|Erro no Pagamento com Cartão de Crédito Cielo - Tabela Externa]]

## Considerações Finais
> [!SUCCESS] Concluído!
> A integração entre a Cielo 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 #Cielo #PagamentosOnline #CartaoDeCredito #APICielo #Recorrencia 

## Leia Também
- [[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 Cielo:** https://docs.cielo.com.br/ecommerce-cielo/reference/debito