# Integração de Telefonia Móvel - Surf (Class - Systems)

## Introdução

>[!TIP] Definição - Surf (Class - Systems):
>A MVNO Surf (Class - Systems) é uma plataforma que atua no mercado com soluções de tecnologia e conectvidade em **telefonia móvel**. Por meio da integração do sistema com a plataforma Surf (Class - Systems), é possível integrar de maneira eficaz sua operação de telefonia móvel, facilitando o gerenciamento ágil e eficiente de suas linhas.

- Este documento descreve o processo de integração entre o MVNO Surf (Class - Systems) e o Sistema IXC Soft.
- O objetivo é centralizar o gerenciamento de serviços de banda larga e telefonia móvel em uma única plataforma.
- A integração visa simplificar a gestão de clientes, contratos, inadimplência e processos de ativação/manutenção.

> [!NOTA] **Acesso à Configuração**
> **Caminho:** Configurações > Integrações > Integrações MVNO/telefonia móvel

### Requisitos de Uso
A contratação de um **módulo** é necessária para a liberação da integração no sistema IXC. Para realizar a contratação do módulo, entre em contato conosco mediante um atendimento direcionado ao departamento **Administrativo Financeiro**.

## Entrega de Valor
- Unificação do gerenciamento de banda larga e telefonia móvel;
- Simplificação de processos operacionais;
- Melhoria na gestão de inadimplência;
- Ampliação da oferta de serviços de telecomunicações.

## Configuração da Integração

### Passo 1: Cadastro da Integração
Neste passo, é efetuado o cadastro da integração. Este processo permite a comunicação e troca de dados entre o sistema e a plataforma **Surf (Class - Systems)**.

1. Acesse o formulário de [[integracoes mvno telefonia movel|Integrações MVNO Telefonia Móvel]] através do caminho: Configurações > Integrações > Integração MVNO/Telefonia Móvel;
2. Pressione o botão **Novo**;
3. Selecione **Surf (Class - Systems)** no campo **MVNA**;
4. Insira as informações fornecidas pela Surf (Class - Systems) nos campos:
	- **Token:** insira o token fornecido pela Surf. Esta informação serve como autenticador entre as plataformas, definindo a comunicação adequada entre ambas;
	  
5. Clique em **Salvar** para validar a criação da integração e concluir o cadastro;

>[!CAUTION] **Importante:**
>As credenciais são essenciais para estabelecer a conexão segura entre os sistemas e são fornecidas pela plataforma credenciada.

### Passo 2: Configuração do Produto de Telefonia Móvel (MVNO)
O cadastro do produto de MVNO é essencial para a gestão do produto no contrato, faturamento e também para permitir a ativação da linha MVNO, uma vez que o produto se relaciona com a integração pelos planos disponibilizados pela plataforma.

>[!INFO] **Importante:**
>O cadastro do produto no sistema é respectivo ao pacote disponível para a plataforma.

1. Acesse o formulário de [[cadastro de produtos|Cadastro de Produtos]] através do caminho: Sistema > Cadastros > Produtos;
2. Pressione o botão **Novo**;
3. Preencha os campos obrigatórios na aba **Produtos** e na aba **Planejamento**;
4. Acesse a aba **Telefonia Móvel**;
5. No campo **ID Integração:** Selecione a integração cadastrada anteriormente;  
	- **ID Plano integração:** Clique em **buscar plano integração** para buscar os planos da plataforma, selecione o plano respectivo ao produto que está sendo cadastrado;  
	- **ID Produto IXC:** O ID do produto criado no sistema para controle do plano de telefonia móvel;  
	- **Tipo referência:** Contrato.
	- **Ativo:** marque como **Sim**;
	  
>[!NOTA]  Atenção:
>O ID Plano integração é respectivo à descrição do pacote na plataforma.
>

6. Clique em **Salvar** para validar e finalizar o cadastro do produto.


### Passo 3: Produto no Contrato
Para realizar a gestão do contrato associado ao serviço de telefonia móvel, é necessário vincular o produto de MVNO ao contrato. Esta ação permite realizar a geração do faturamento, emitir notas fiscais e também efetuar ativação da linha associada à integração. Esta ativação pode ocorrer diretamente pelo contrato ou por [[formulario planos de venda|Formulário Planos de Venda]].

1. Acesse o [[formulario contrato do cliente|formulário Contrato do Cliente]] através do caminho: Sistema > Cadastros > Contratos;
2. Pressione o botão **Editar** para acessar o contrato;
3. Navegue até a aba **Produtos** e clique no botão **Novo**. Defina o tipo do produto como "MVNO/Telefonia Móvel" e no campo **Produto/Serviço**, clique na lupa e selecione o produto de MVNO cadastrado. Clique em **Salvar** para validar as configurações.

> [!Caution] Atenção:
> O campo **Tipo** precisa, **obrigatoriamente**, estar marcado como **MVNO/Telefonia móvel** para a usabilidade da integração não sofrer inconsistências e apresentar o funcionamento adequado.


### Passo 4: Cadastro e Ativação do linha MVNO
A ativação do da linha MVNO consiste em realizar a ativação de um novo numero ou solicitar a portabilidade de uma operadora para a Surf (Class - Systems).

>[!Caution] Atenção: 
>Somente é possível realizar o cadastro de uma linha MVNO em contratos que estão com status ativo.

>[!TIP] Validação cadastral
>A plataforma Surf valida os seguintes dados para a ativação de uma linha MVNO:
>- CPF/CNPJ;
>- Razão social/Nome;
>- Endereço (campos CEP, Endereço, Número, Complemento);
>- E-mail. 
>
>Atente-se ao cadastro do cliente para que todos estes dados estejam devidamente cadastrados.

###### **4.1: Ativação de número novo**
1. Ainda no contrato do cliente, navegue até a **Linha MVNO**;
2. Clique no botão **Novo** e preencha os campos apresentados:
	- **API:** Selecione a opção Alterar na API e no IXC;
		- **Alterar na API e no IXC:** ao utilizar essa opção, o sistema promoverá a comunicação entre o IXC Provedor e a plataforma. Toda requisição de alteração na linha MVNO será enviada para a plataforma Surf (Class - Systems), garantindo que os dados sejam sincronizados.
		 - **Ignorar API e alterar apenas no IXC:** ao utilizar essa opção, o sistema não utilizará a API da Surf (Class - Systems), resultando em nenhuma comunicação com ela. Todas as alterações feitas serão refletidas apenas no IXC Provedor, sem afetar a linha MVNO na plataforma MVNO.
		   
	- **Integração:** Clique na lupa e selecione o ID da integração da plataforma Surf (Class - Systems);
	- **Produto relacionado:** Deve inserir um produto IXC/MVNO, o qual foi cadastrado em **Produtos** e que esteja vinculado ao contrato do cliente;
	- **SIM card:** Número do cartão repassado pela integrada, deve conter 20 caracteres. Clique no botão **Buscar simcards disponíveis** e selecione o número do cartão que ficará relacionado à esta linha;
	- **Portabilidade:** Marque como **Não**;
	- **DDD**: Inserir DDD para que seja retornado o número do telefone equivalente ao DDD passado;
	- **Número do telefone:** Este é o número de telefone que ficará vinculado à linha, preenchido automaticamente ao salvar a linha MVNO.

3. Após informar todos os campos, clique em **Salvar**.
4. Campos preenchidos automaticamente:
	- **Número do telefone:** Este é o número de telefone que ficará vinculado à linha, preenchido automaticamente após salvar a linha;
	- **Status linha:** indica o status de uso da linha;

###### **4.2: Ativação de número existente (portabilidade)**
1. Ainda no contrato do cliente, navegue até a **Linha MVNO**;
2. Clique no botão **Novo** e preencha os campos apresentados:
	- **API:** Selecione a opção Alterar na API e no IXC;
		- **Alterar na API e no IXC:** ao utilizar essa opção, o sistema promoverá a comunicação entre o IXC Provedor e a plataforma. Toda requisição de alteração na linha MVNO será enviada para a plataforma Surf (Class - Systems), garantindo que os dados sejam sincronizados.
		 - **Ignorar API e alterar apenas no IXC:** ao utilizar essa opção, o sistema não utilizará a API da Surf (Class - Systems), resultando em nenhuma comunicação com ela. Todas as alterações feitas serão refletidas apenas no IXC Provedor, sem afetar a linha MVNO na plataforma MVNO.
		   
	- **Integração:** Clique na lupa e selecione o ID da integração da plataforma Surf (Class - Systems);
	- **Produto relacionado:** Deve inserir um produto IXC/MVNO, o qual foi cadastrado em **Produtos** e que esteja vinculado ao contrato do cliente;
	- **SIM card:** Número do cartão repassado pela integrada, deve conter 20 caracteres. Clique no botão **Buscar simcards disponíveis** e selecione o número do cartão que ficará relacionado à esta linha;
	- **Portabilidade:** Marque como **Sim**;
	- **DDD**: Inserir DDD para que seja retornado o número do telefone equivalente ao DDD passado;
	- **Número de Telefone:** Informar o número a ser portado;
	- **Operadora origem:** clique no botão **Buscar operadora** e selecione a operadora de origem do número de telefone que está sendo portado.
	  
3. Após informar todos os campos, clique em **Salvar**.
4. Campos preenchidos automaticamente:
	- **ID contrato integração:** ao cadastrar a linha MVNO no IXC, este campo é preenchido como um retorno da plataforma Surf (Class - Systems), indicando o ID do cadastro da linha na plataforma;
	- **Status linha:** indica o status de uso da linha;
	- **Status portabilidade:** ao ativar a linha como portabilidade, esta informação será preenchida como **Aguardando ativação.** Com a portabilidade concluída, o status é alterado para **Concluída.**	  

>[!SUCCESS] Finalização:
Após realizar a ação de todos os passos, a linha estará pronta para uso. Em casos de portabilidade a linha ficará com status **Aguardando ativação** até que o processo seja concluído. O status é alterado pela [[tarefa - consultar portabilidade|tarefa Consultar Portabilidades]] ou então a partir da [[consulta manual de portabilidade - mvno|Consulta manual de portabilidade - MVNO]]

>[!INFO] **Importante:**
>O controle de acesso é feito diretamente pelas ações do contrato ou manualmente nos botões de Status da linha (bloqueio e liberação).

## Casos de Uso

### 1. Controle de Acesso pelas Ações do Contrato
É possível realizar o gerenciamento do status da linha diretamente pelo sistema, mediante o status do contrato. Quando existe uma linha MVNO vinculada em um contrato, toda ação realizada no status do contrato e status de acesso irá refletir no status da linha, sendo esta alterada também e impactando no consumo do cliente final.  

>[!TIP] Dica:
>Os bloqueios estão estruturados em suspensão dos planos, isto é, o plano não será renovado na plataforma quando ocorrer o bloqueio no sistema.

#### Legenda - impacto do status do contrato na linha MVNO:

- **Ativo:** ao contrato que estiver com status de **ativo** e seu status de acesso também constar como **ativo**, a linha deve admitir o status de **Ativa**;
    
- **Bloqueio manual/automático:** ao contrato que for bloqueado por inadimplência de forma manual ou automática, assumindo o status de Bloqueio manual ou Bloqueio automático, a linha sofrerá bloqueio total, interrompendo totalmente o consumo do cliente;
    
- **Financeiro em atraso:** ao contrato que assumir o status de acesso do contrato para Financeiro em atraso, a linha sofrerá **bloqueio parcial**, interrompendo parcialmente o consumo do cliente;
    
- **Liberação manual ou automática:** é possível realizar o desbloqueio do contrato mediante o pagamento ou renegociação da mensalidade, por meio da liberação manual ou **automática** a partir do pagamento do título que ocasionou o bloqueio total ou parcial, ativando automaticamente o contrato ou manualmente;
    
- **Cancelamento:** ao cancelar/desativar o contrato, a linha irá respeitar o status do contrato e também será cancelada, admitindo o status de **Inativa**.


### 2. Controle de Acesso pelas Ações da Linha MVNO
É possível realizar o gerenciamento do status da linha diretamente pelo IXC, de modo que o sistema permite a alteração manual do status diretamente pela linha e não somente pelo contrato.  
Para alterar o status da linha, siga os passos a seguir:

1. Acesse o contrato do cliente;
2. Clique na aba Linha MVNO;
3. Selecione o botão de Editar;
4. Clique sobre o botão Status;
5. Selecione a opção de status que deseja aplicar à linha MVNO;  

#### Legenda - status:
  
- **Cancelar linha:** altera o status da linha para **Cancelada**, efetuando o cancelamento da linha. Uma linha cancelada pode ser reativada dentro de 90 dias através do botão **Liberar linha.**

>[!CAUTION] Atenção:
>Após **90** dias de cancelamento, a linha **não** poderá ser reativada.
  
- **Liberar linha:** realiza a liberação da linha quando estiver em bloqueio, retomando o consumo do cliente. A linha assume o status de **Ativa**;
  
- **Bloqueio parcial:** altera o status da linha para **Bloqueio parcial**, interrompendo parcialmente o consumo do cliente;

### 3. [[trocar titularidade - mvno|Trocar titularidade - MVNO]]
 O sistema permite a alteração da titularidade da linha, de modo que uma linha já cadastrada possa ser transferida para outro contrato.

>[!Caution] Critérios de transferência:
>- A linha deve estar com o status **Ativo**;
>- O status da portabilidade, caso a linha seja portada, deve estar como **Concluída**;
>- O contrato que receberá a linha deve estar com o status **Ativo**.
>- O contrato que receberá a linha deve ser do novo titular.

Para realizar uma troca de titularidade, siga os seguintes passos:
1. Acesse a linha MVNO que deseja realizar a alteração do contrato;
2. Selecione o botão **Trocar titularidade**;
3. No campo **ID contrato novo**, clique sobre a lupa e selecione o contrato que passará a ter vínculo com a linha MVNO.
4. Clique em confirmar para validar a troca de titularidade.

>[!TIP] Dica:
>A troca de titularidade ficará registrada no Histórico do  [[formulario contrato do cliente|Formulário Contrato do Cliente]].


### 4. Troca de SIM Card Linha MVNO Surf (Class-Systems)
A plataforma permite a alteração do SIM Card atrelado à linha MVNO. Para realizar a alteração do plano, siga os passos a seguir:

1. Acesse o [[formulario contrato do cliente|formulário de Contrato do Cliente]] através do caminho: Sistema > Cadastro > Contratos;
2. Selecione o contrato do cliente que deseja realizar a alteração do plano e clique em **Editar**;
3. Acesse a [[aba linha mvno - contrato do cliente|Aba Linha MVNO - Contrato do Cliente]] e localize o campo **SIM Card**;
4. Clique sobre o botão **Buscar simcards disponíveis** e selecione o novo número de simcard;
5. Clique em **Salvar** para atualizar os dados da linha.


### 5. Troca de plano da Linha MVNO Surf (Class-Systems)
A plataforma permite a alteração do plano atrelado à linha MVNO. Para realizar a alteração do plano, siga os passos a seguir:

1. Acesse o [[formulario contrato do cliente|formulário Contrato do Cliente]] através do caminho: Sistema > Cadastro > Contratos;
2. Selecione o contrato do cliente que deseja realizar a alteração do plano e clique em **Editar**;
3. Acesse a aba **Produtos** no [[formulario contrato do cliente|formulário Contrato do Cliente]] e clique em **Novo**;
4. No campo **Tipo**, indique a opção **MVNO/Telefonia Móvel** para habilitar a seleção de produtos desta classe;
5. No campo **Produto/Serviço**, selecione e vincule outro produto de telefonia móvel anteriormente cadastrado;
6. Após vincular o produto, acesse a [[aba linha mvno - contrato do cliente|Aba Linha MVNO - Contrato do Cliente]]. Selecione a linha MVNO cadastrada e clique em **Editar**;
7. No campo **Produto/Serviço**, clique na lupa e selecione o produto de MVNO anteriormente associado ao contrato;
8. Clique em **Salvar** para atualizar os dados da linha.


## Fluxo de Trabalho

```mermaid
flowchart TD
    A[Credenciamento com a plataforma] --> B[Cadastro da integração no sistema]
    B --> C[Cadastro do produto MVNO]
    C --> D[Incluir produto no contrato]
    D --> E[Ativar linha MVNO]

    E --> |Novo cadastro| F[Linha Ativa]
    E --> |Portabilidade| G[Consulta portabilidade]
    
    G --> |Concluída| F
    G --> |Recusada| H[Portabilidade Recusada]
    G --> |Cancelada| I[Portabilidade Cancelada]
    
    F --> J[Faturamento]
    
    J --> K[Trocar SIM Card]
    J --> L[Trocar Plano]
    J --> M[Trocar Titularidade]
    
    J --> N[Monitoramento do contrato e status de acesso]
    
    N --> O[Status de acesso baseado no financeiro do cliente]

```

## Considerações Finais
A integração entre a plataforma Surf (Class - Systems) e o sistema proporciona uma solução completa para o gerenciamento de serviços de telecomunicações. Esta integração resulta em operações mais eficientes e uma experiência aprimorada para o cliente. É fundamental estar a par das diretrizes de utilização e eventuais atualizações da plataforma integrada, garantindo assim o máximo aproveitamento das funcionalidades oferecidas.

## Etiquetas
#Integracoes #IntegracaoTelefoniaMovel #MVNO #SurfClassSystems
## Leia Também
-  [Surf (Class - Systems)](https://www.surf.com.br/site/)
- [[integracoes|Integrações]]
- [[trocar titularidade - mvno|Trocar titularidade - MVNO]]
- [[integracoes mvno telefonia movel|Integrações MVNO Telefonia Móvel]]
- [[dados adicionais mvno|Dados Adicionais MVNO]]
- [[tarefa - consultar portabilidade|Tarefa - Consultar Portabilidade]]
- [[consulta manual de portabilidade - mvno|Consulta manual de portabilidade - MVNO]]
- [[trocar titularidade - mvno|Trocar titularidade - MVNO]]
- [[como realizar a troca de plano para linhas mvno surf (class - systems)|Como realizar a troca de plano para Linhas MVNO Surf (Class - Systems)]]
- [[formulario contrato do cliente|Formulário Contrato do Cliente]]
- [[status de portabilidade de linhas mvno|Status de Portabilidade de Linhas MVNO]]