# Integração de Telefonia Móvel - Play Móvel (Beta)

## Introdução

>[!tip] Atenção!
>Este conteúdo está presente na **versão [[clientes beta ixc soft|Beta]]** do sistema.
>A disponibilidade desta integração na **versão Estável** será a partir de Abril de 2025.

---

>[!TIP] Definição - Play Móvel:
>A **Play Móvel** é uma operadora de telefonia móvel virtual (MVNO) que oferece planos de voz, dados e internet com foco em economia e praticidade. Com benefícios como redes sociais ilimitadas e gestão simplificada via aplicativo, é ideal para quem busca conectividade acessível e eficiente. Acesse: [Play Móvel](https://playmovel.com.br/).

>[!INFO] Importante:
>Antes de iniciar a integração da Play Móvel no sistema IXC, é necessário realizar a **contratação** do **módulo pós-pago** com a plataforma.
>
>**Fluxo:**
>Contratação com a Play Móvel > Ativação do módulo pós-pago na Play Móvel > Integração no IXC.

A funcionalidade **Integração de Telefonia Móvel/MVNO** é fundamental para provedores de internet que oferecem pacotes integrados de telefonia móvel e internet, utilizando a plataforma Play Móvel. Esta ferramenta permite configurar, manter e gerenciar de forma eficiente as conexões entre o Sistema IXC Soft e a plataforma de MVNO integrada.

Este documento descreve o processo de integração entre o MVNO Play Móvel e o Sistema IXC Soft, com o objetivo de 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

## 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 Play Móvel.

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 **Play Móvel** no campo **MVNA**;
4. Insira as informações fornecidas pela Play Móvel nos campos:
	- **Ambiente:** indique se ambiente de teste (Homologação) ou se estará em uso para fornecimento aos clientes (Produção);
	- **Identificador externo:** campo de texto, insira o identificador externo que utiliza na plataforma (identificador único para cada provedor);
	- **Token:** serve como uma chave de acesso (API Key), permitindo que ocorra a comunicação entre o sistema e a Play Móvel. Insira a senha informada pela plataforma. Após salvar, é encriptografado.
	  
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, pois o produto se relaciona com a integração pelos pacotes 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 plano integração adicional:** campo preenchido automaticamente como retorno da API;
	- **ID Produto IXC:** clique no botão **Buscar plano integração** e selecione o ID do produto criado no sistema para controle do plano de telefonia móvel;  
	- **Tipo referência:** Contrato.
	- **Ativo:** preenchido automaticamente.
	
>[!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 efetivamente, é 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: Tarefas Consultar Linha Ativa MVNO e Consultar Portabilidade

#### 4.1 [[tarefa - consulta ativacao linha mvno|Tarefa - Consulta Ativação Linha MVNO]]
Quando uma linha MVNO é cadastrada no sistema, a Play Móvel verifica se ela pode ser ativada. Enquanto essa ativação não é concluída, a linha permanece com o status de **Aguardando Ativação**. Nesse contexto, a tarefa **Consultar Linha Ativa MVNO** tem a função de validar, na plataforma, se a linha já está apta para ativação. Executada periodicamente, essa tarefa ativa as linhas automaticamente após o cadastro. Para garantir que o processo de ativação ocorra corretamente, é necessário cadastrar a tarefa no sistema. Siga as etapas abaixo:

1. Acesse o menu Ferramentas > Agenda de Tarefas > Novo.
2. No campo **Tarefa**, selecione a opção **Consulta ativação linha MVNO**.
3. Configure o horário de execução:
	  - No campo **Minuto**, indique o minuto em que a tarefa será executada. Marque a opção **Valor** e insira um número entre 0 e 59;
	   - No campo **Hora**, marque a opção **Valor** e insira um número entre 0 e 23;
	     
4. Nos campos **Dia do mês** e Mês, **selecione** a opção **Todos**.
5. No campo **Dia da semana**, defina o período em que as linhas poderão ser ativadas:
	  - Para execução diária, selecione **Todos**;
	   - Para definir um intervalo específico, insira os dias separados por traço; Por exemplo: 1-5 (segunda a sexta-feira);
	
6. Clique em **Salvar** para concluir o cadastro da tarefa.

> [!info] **Importante:**  
> Recomenda-se que o horário de execução seja definido de acordo com o volume e a frequência de cadastro de linhas. Por exemplo, se novas linhas forem cadastradas com frequência ao longo do dia, configure a tarefa para ser executada em intervalos regulares. Para isso, no campo **"Hora"**, utilize a estrutura `*/1` (para execução a cada 1 hora) ou ajuste conforme necessário.

#### 4.2 [[tarefa - consultar portabilidade|Tarefa - Consultar Portabilidade]]
A tarefa de **Consultar Portabilidade** é uma funcionalidade que permite acompanhar o processo de portabilidade de linhas MVNO no sistema. Esta tarefa verifica se a portabilidade foi concluída ou recusada, atualizando para o status correspondente. Cadastre-a conforme a orientação a seguir para manter atualizado o status de linhas do tipo **portabilidade:**

1. Acesse o menu **Ferramentas > Agenda de Tarefas > Novo**;
2. No campo **Tarefa**, selecione a opção **Consultar Portabilidade**;
3. Configure o horário de execução:
    - No campo **Minuto**, indique o minuto em que a tarefa será executada. Marque a opção **Valor** e insira um número entre **0 e 59**;
    - No campo **Hora**, marque a opção **Valor** e insira um número entre **0 e 23**;
    
4. Nos campos **Dia do mês** e **Mês**, selecione a opção **Todos**;
5. No campo **Dia da semana**, defina o período em que as linhas poderão ser ativadas:
    - Para execução diária, selecione **Todos**;
    - Para definir um intervalo específico, insira os dias separados por traço. Por exemplo: **1-5** (segunda a sexta-feira);
      
6. Clique em **"Salvar"** para concluir o cadastro da tarefa.

Além da tarefa de **Consultar Portabilidade**, também é possível atualizar o status das linhas através da funcionalidade da [[consulta manual de portabilidade - mvno|Consulta Manual de Portabilidades.]]

### Passo 5: Cadastro e Ativação da Linha MVNO
A ativação do da linha MVNO consiste em realizar a ativação de um novo número ou solicitar a portabilidade de uma operadora para a Play Móvel.

>[!INFO] Pós-pago:
>As ativação da linha no sistema funciona no modelo de consumo **pós-pago**, isto é, o cliente irá consumir e efetuar o pagamento em seguida. Se o status da linha for igual à **Ativa**, a recorrência será renovada.

>[!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 Play Móvel valida os seguintes dados para a ativação de uma linha MVNO:
>- Data de nascimento;
>- Data de fundação de CNPJ;
>- Nome/Razão social;
>- CPF/CNPJ;
>- E-mail;
>- Telefone celular (com DDD);
>- Endereço (campos CEP, Cidade, Endereço, Número, Complemento).
>  
>  Atente-se ao cadastro do cliente para que todos estes dados estejam devidamente cadastrados.

#### **5.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;
		- **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 Play Móvel, garantindo que os dados sejam sincronizados.
		 - **Apenas no IXC:** ao utilizar essa opção, o sistema não utilizará a API da Play Móvel, 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 Play Móvel;
	- **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 SIM Cards disponíveis** para vincular o SIM Card à linha ou insira manualmente;
	- **Portabilidade:** Marque como **Não**;
	- **DDD**: Inserir DDD para que seja retornado o número do telefone equivalente ao DDD inserido;
	
3. Após informar todos os campos, clique em **Salvar**. A linha assumirá o status de **Aguardando ativação**. Assim que a tarefa **Consultar Linha Ativa MVNO** executar e confirmar a ativação da linha, o status será alterado para **Ativa** e os seguintes campos serão 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;

#### **5.2: Ativação de número existente (portabilidade)**
1. Ainda no contrato do cliente, navegue até a aba **Linha MVNO**;
2. Clique no botão **Novo** e preencha os campos apresentados:
	- **API:** Selecione a opção Alterar na API e no IXC;
		- **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 Play Móvel, garantindo que os dados sejam sincronizados.
		 - **Apenas no IXC:** ao utilizar essa opção, o sistema não utilizará a API da Play Móvel, 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 Play Móvel;
	- **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 SIM Cards disponíveis** para vincular o SIM Card à linha ou insira manualmente;
	- **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 opção de operadora de origem disponível pela plataforma (o campo numero de telefone deve estar preenchido);
	  
3. Após informar todos os campos, clique em **Salvar**. É necessário que a tarefa **Consultar Linha Ativa MVNO** execute para validar um número de telefone. Se a ativação da portabilidade for confirmada, o campo **Número temporário** é preenchido, consiste em um número temporário a ser utilizado até a ativação da linha quando for portabilidade;
4. Os demais campos serão preenchidos automaticamente:
	- **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 Portabilidade]] 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).

>[!CAUTION] Atenção:
>A solicitação de uma portabilidade pode levar até 3 dias úteis para ser concluída.
>
>Se a portabilidade for negada, a linha assumirá o status de **Recusada** e **Aguardando Ativação**. Para reutilizar a linha, é necessário cadastrá-la novamente.

## 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.  
  
#### 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 permanecerá **ativa**;
- **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, admitindo o status de **Inativa** no sistema. A informação de **bloqueio** é enviada à Play Móvel, a linha ficará bloqueada até Play Móvel efetivamente cancelar a linha.

### 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, conforme as opções disponíveis;  
 
#### Legenda - status:

>[!CAUTION] Atenção:
>Os status de bloqueio e cancelamento descritos no sistema, funcionam na plataforma como um **pedido de bloqueio**, portanto, o **bloqueio ou cancelamento não são imediato**. O bloqueio ocorre através da recorrência, se solicitado o bloqueio, o cliente consome até finalizar o período de recorrência, tendo o consumo bloqueado após o período ser finalizado.

- **Bloqueio roubo:** altera o status da linha para **Bloqueio roubo**, interrompendo totalmente o consumo do cliente ao que diz respeito o consumo de dados, ligações e envios de SMS devido ao dispositivo/simcard ter sofrido roubo;
- **Cancelar linha:** altera o status da linha para **Cancelada**, solicitando o cancelamento da linha para a plataforma;
- **Liberar linha:** realiza a liberação da linha quando estiver em bloqueio, retomando o consumo do cliente. A linha assume o status de **Ativa**. Retorna a utilização imediatamente ao liberar;
 - **Bloqueio perda:** altera o status da linha para **Bloqueio perda**, interrompendo totalmente o consumo do cliente ao que diz respeito o consumo de dados, ligações e envios de SMS devido à perda do simcard/dispositivo;
- **Bloqueio parcial:** não possui bloqueio parcial;
- **Bloqueio total:** não possui bloqueio total, o bloqueio ocorre somente após o período de recorrência.

### 3. Troca de Plano da Linha MVNO Play Móvel
A plataforma permite a alteração do plano atrelado à linha MVNO. Para realizar a alteração do plano, siga os passos a seguir:

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

### 4. Troca de Titularidade

>[!CAUTION] Atenção!
>A integração com a Play Móvel não possui troca de titularidade.

## Fluxo de Trabalho

```mermaid
graph TD
    A[Início] --> B[Cadastro de Cliente]
    B --> C[Criação de Contrato]
    C --> D[Seleção de Plano Móvel]
    D --> E[Acesso à Aba MVNO]
    E --> F[Preenchimento de Dados da Linha]
    F --> G[Envio para Ativação]
    G --> H[Confirmação da Play Móvel]
    H --> I[Linha Ativa]
    I --> J[Monitoramento e gerenciamento]
```

## Considerações Finais
A integração entre a plataforma Play Móvel 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 #IntegracoesDeTelefoniaMovel #IntegracaoPlayMovel #PlayMovel #MVNO

## Leia Também
- [Play Móvel](https://playmovel.com.br/)
- [[integracoes|Integrações]]
- [[integracoes mvno telefonia movel|Integrações MVNO Telefonia Móvel]]
- [[tarefa - consultar portabilidade|Tarefa - Consultar Portabilidade]]
- [[consulta manual de portabilidade - mvno|Consulta manual de portabilidade - MVNO]]
- [[tarefa - consulta ativacao linha mvno|Tarefa - Consulta Ativação Linha MVNO]]
- [[aba linha mvno - contrato do cliente|Aba Linha MVNO - Contrato do Cliente]]
- [[produtos ixc - mvno|Produtos IXC - MVNO]]
- [[como realizar a troca de plano para linhas mvno play movel|Como Realizar a Troca de Plano para Linhas MVNO Play Móvel]]