Central de Ajuda Quaza Provedores

SVA — Serviço de Valor Agregado (PT)

SVA — Serviço de Valor Agregado

SVA — Serviço de Valor Agregado — os serviços de parceiros que o provedor revende junto com a internet

Como cadastrar e operar o módulo SVA (Serviço de Valor Agregado) no Quaza — os serviços que você revende junto com a internet (TV por streaming, ebooks, telefonia, antivírus). Aqui você liga a plataforma do parceiro ao Quaza, importa os planos, provisiona o assinante e acompanha as chamadas de API. Voltado a quem trabalha com produtos e contratos no provedor.

SVA não é a nota fiscal. Esta wiki trata do cadastro e provisionamento do serviço. A nota fiscal do SVA (a NFeSVA, modelo fiscal de São Paulo) é assunto de outra wiki: veja NFe SVA .

Nesta wiki:

O que é SVA

SVA (Serviço de Valor Agregado) é tudo o que o provedor vende além do acesso à internet: TV por streaming, plataformas de ebook e audiolivro, telefonia, antivírus, monitoramento. No Quaza, um SVA é um serviço de um parceiro externo (a plataforma que entrega o conteúdo) que você revende ao seu cliente final e cobra dentro do contrato dele.

Para isso funcionar, o Quaza conversa com a plataforma do parceiro por uma API: quando você cadastra um assinante, o Quaza cria o acesso lá no parceiro automaticamente; quando o cliente fica inadimplente e o contrato é bloqueado, o Quaza bloqueia o acesso ao SVA também — em cascata. O módulo cobre hoje mais de 20 parceiros (Watch Brasil, PlayHub, Skeelo, Cariap, Now+, Olé TV, entre outros).

O SVA cuida de	O SVA NÃO cuida de
Ligar a plataforma do parceiro ao Quaza (Integrador)	Emitir a nota fiscal do serviço — isso é NFe SVA
Importar e cadastrar os planos revendidos	Vender internet pura — isso vai em NFCom
Criar o acesso do assinante no parceiro (provisionar)	Lançar a cobrança/boleto — isso é Cobrança
Bloquear/desbloquear o acesso conforme o contrato	O contrato em si — isso é Contrato

Quando usar (e quando NÃO)

Use o módulo SVA quando…	NÃO é aqui quando…
Você fechou parceria com uma plataforma (ex.: Watch Brasil) e quer revendê-la	Você só precisa emitir a nota fiscal de um SVA → NFe SVA
Quer dar acesso a um serviço de streaming/ebook a um cliente específico	Quer cobrar o cliente → Cobrança e Fatura
Precisa investigar por que o acesso de um cliente ao parceiro não funciona	Quer adicionar o serviço ao contrato → tela de Contrato (aba Serviços)

Passo a passo — do parceiro ao assinante

1	Cadastre o Integrador. Em SVA → Integrador, clique em Adicionar integrador SVA, escolha o Gateway (o parceiro: Watch Brasil, PlayHub…) e preencha as credenciais de API que o parceiro forneceu. Os campos que aparecem mudam conforme o gateway.
2	Teste a conexão. Abra o integrador salvo e clique em Testar conexão API. Se aparecer "Conexão estabelecida com sucesso", as credenciais estão certas.
3	Cadastre/Importe os Planos. Em SVA → Plano, use Importar planos para puxar os planos direto do parceiro (quando o gateway suporta) ou cadastre manualmente. Cada plano guarda o código do integrador que será enviado ao parceiro.
4	Provisione o assinante. Em SVA → Usuário, clique em Adicionar usuário, escolha o Cliente/Contrato, o Integrador e o Plano, e preencha os dados exigidos pelo parceiro (usuário, senha, CPF, telefone — varia por gateway). Ao salvar, o Quaza cria o acesso na plataforma do parceiro.
5	Vincule ao contrato (cobrança). Para o serviço entrar na fatura e seguir o bloqueio por inadimplência, ele precisa estar como serviço do tipo SVA no Contrato do cliente.
6	Acompanhe. Em SVA → Log Request você vê cada chamada que o Quaza fez ao parceiro (criação, bloqueio, desbloqueio) — útil para descobrir por que algo falhou.

Fluxo — provisionamento e bloqueio em cascata

Do cadastro do parceiro ao provisionamento do assinante; abaixo da linha tracejada, o bloqueio/desbloqueio em cascata disparado pela situação do contrato.

Glossário

Termo	O que significa
SVA	Serviço de Valor Agregado: serviço de um parceiro (streaming, ebook, telefonia, antivírus) que o provedor revende junto com a internet.
Integrador	O cadastro que liga uma plataforma parceira ao Quaza, com as credenciais de API. Um integrador = uma conta sua em um parceiro.
Gateway	Qual parceiro o integrador representa (Watch Brasil, PlayHub, Skeelo…). Define quais campos e qual API o Quaza vai usar.
Plano	O pacote do parceiro que você revende (ex.: "Paramount+HBO", "Ebook Premium"). Guarda o código que o parceiro reconhece.
Usuário SVA	O assinante provisionado: a ligação Cliente → Contrato → Integrador → Plano com o acesso criado no parceiro.
Código de integração	O identificador que o parceiro devolve/reconhece para aquele plano ou assinante; é o que o Quaza envia nas chamadas de API.
Provisionar	Criar o acesso do assinante na plataforma do parceiro (acontece ao salvar o Usuário SVA).
Homologação / Produção	Ambiente da API do parceiro: homologação é teste; produção é o ambiente real que cria acessos de verdade.
Log Request	Registro de cada chamada que o Quaza fez à API do parceiro (URL, método, código de resposta, data) — a trilha de auditoria.
Bloqueio em cascata	Quando o contrato do cliente é bloqueado por inadimplência, o Quaza pede ao parceiro para suspender também o acesso ao SVA.

Configuração / pré-requisitos

Credenciais do parceiroSVA → Integrador

Antes de tudo, você precisa de uma conta na plataforma do parceiro e das credenciais de API que ele fornece (usuário/senha, token, client id/secret — varia). Sem isso o teste de conexão falha.

Planos cadastradosSVA → Plano

Você só consegue provisionar um assinante se o plano dele já existir. Use Importar planos para puxar do parceiro quando possível.

Cliente com contratoCliente → Contrato

O assinante SVA é sempre amarrado a um contrato de um cliente. É por esse vínculo que a cobrança e o bloqueio por inadimplência funcionam.

Tela — Integrador

SVA → Integrador

É onde você liga cada plataforma parceira ao Quaza. A listagem mostra os integradores cadastrados; clique no lápis para abrir o detalhe.

Listagem de integradores (Listar integradores SVAs) — colunas Código, Descrição, Gateway, Alteração e Alterador; o botão "Adicionar integrador SVA" fica no topo à direita.

No detalhe você dá uma Descrição (um nome seu para reconhecer o integrador), escolhe o Gateway e define a Situação (habilitado/desabilitado) e o ambiente (Homologação ou Produção). Conforme o gateway escolhido, o Quaza mostra só os campos de credencial que aquele parceiro exige: usuário e senha de API, token, instância, client id/secret. Use o botão Testar conexão API para confirmar antes de operar.

Tela — Plano

SVA → Plano

Os pacotes que você revende. Cada plano pertence a um integrador e guarda o código do integrador — o identificador que o parceiro reconhece.

Listagem de planos (Listar planos) — colunas Código, Descrição, Integrador, Código Integrador, Situação, Alteração e Alterador; à direita ficam "Adicionar plano" e "Importar planos".

Use Importar planos para escolher um integrador e puxar o catálogo direto do parceiro (quando o gateway suporta) — assim você não digita código por código. Planos importados já vêm com o código de integração preenchido.

Tela — Usuário

SVA → Usuário

O coração da operação: cada linha é um assinante provisionado. A listagem mostra o caminho completo Cliente → Contrato → Integrador → Usuário → Plano, com a situação.

Listagem de usuários (Listar usuários) — colunas Código, Cliente, Contrato, Integrador, Usuário, Plano, Situação, Alteração e Alterador; Cliente e Contrato são links para a ficha do cliente.

Ao adicionar, você escolhe Cliente/Contrato, Integrador e Plano. Os campos seguintes (usuário, senha, CPF, telefone, MAC, modelo de equipamento) aparecem conforme o que o parceiro exige. Ao salvar um usuário novo, o Quaza chama a API do parceiro e cria o acesso na hora — por isso o cadastro pode dar erro de validação vindo do parceiro (ex.: usuário já em uso). No detalhe de um usuário já criado, alguns gateways oferecem ações extras (ex.: consultar pacotes/assinaturas disponíveis).

Tela — Log Request

SVA → Log Request

A trilha de auditoria das chamadas de API. Cada linha é uma requisição que o Quaza fez ao parceiro. É somente leitura — você não cria nem apaga nada aqui, só consulta.

Listagem do Log Request (Listar logs Request) — colunas Código, URL, Método, Código da Requisição e Criação; repare nas chamadas de oauth/token e authenticate ao parceiro.

É o primeiro lugar para olhar quando "o SVA do cliente não funciona": abra o log, ache a chamada do cliente, veja o código da requisição (200 = ok; 4xx/5xx = erro) e o conteúdo da resposta. As URLs costumam mostrar a ação (ex.: subscribe, BloquearLogin, DesbloquearLogin).

Tarefas automáticas

Além das ações que você dispara na tela, o módulo SVA roda algumas tarefas automáticas em segundo plano. Quem liga, desliga e agenda essas tarefas é o administrador do servidor (via crontab) — o operador não controla isso pela tela.

Tarefa	O que faz	Quando
Renovação de token (Watch Brasil)	Renova periodicamente o token de acesso à API do parceiro, para as chamadas não expirarem.	Automática (tarefa periódica)
Criação de usuários (Digilivro)	Cria em lote os acessos pendentes na plataforma do parceiro.	Automática (tarefa periódica)
Bloqueio / desbloqueio por contrato	Quando o contrato é bloqueado ou desbloqueado (manual ou via tarefa de cobrança), suspende/reativa o acesso ao SVA no parceiro.	Manual ou automático (segue o contrato)

As tarefas variam conforme os parceiros que você usa. Se uma renovação de token ou criação em lote parar de rodar, fale com o suporte — a programação dessas tarefas é feita no servidor, não na tela.

Barra de ações

#	Botão	Onde aparece	O que faz
1	Testar conexão API	Detalhe do Integrador	Faz uma chamada de teste com as credenciais e confirma se a conexão funciona.
2	Importar planos	Listagem de Plano	Escolhe um integrador e puxa o catálogo de planos direto do parceiro.
3	Consultar pacotes disponíveis	Detalhe do Usuário (gateways que suportam)	Lista, vindo do parceiro, os pacotes que podem ser atribuídos àquele assinante.
4	Consultar assinaturas	Detalhe do Usuário (gateways que suportam)	Mostra, vindo do parceiro, as assinaturas já ativas do assinante.

Quando dá errado

Sintoma	Causa provável	O que fazer
"Conexão não estabelecida" ao testar	Credenciais erradas ou ambiente trocado (Homologação x Produção)	Confira usuário/senha/token e o ambiente no Integrador; revise no painel do parceiro.
"Integrador: X, não cadastrado como gateway"	O integrador foi criado sem um gateway válido selecionado	Edite o Integrador e selecione o Gateway correto.
"Usuário já em uso" / "CPF já em uso" / "Telefone já em uso"	Já existe um assinante ativo com esse dado	Verifique em SVA → Usuário se o assinante já não está provisionado.
Importar planos falha	Aquele parceiro não tem importação automática implementada	Cadastre os planos manualmente com o código de integração.
Cliente diz que o SVA parou	Contrato bloqueado por inadimplência (bloqueio em cascata) ou erro de API	Cheque a situação do contrato; depois veja o Log Request (código de resposta da última chamada).

Pegadinhas frequentes

SVA não é a nota fiscal. Provisionar o serviço aqui não emite documento fiscal. A nota (NFeSVA) é gerada na tela própria — veja NFe SVA .

Salvar um usuário novo já cria o acesso no parceiro. Não é um rascunho: ao salvar, o Quaza chama a API e provisiona de verdade. Confira os dados antes.

Ambiente importa. Um integrador em Homologação não cria acessos reais. Antes de operar com clientes, garanta que está em Produção.

O bloqueio do SVA segue o contrato. Se o serviço não estiver vinculado ao contrato como tipo SVA, o bloqueio por inadimplência não atinge o acesso — o cliente continua usando mesmo devendo.

Cada gateway pede campos diferentes. Uns exigem usuário+senha, outros CPF, outros telefone ou MAC. Os campos aparecem sozinhos conforme o gateway; não invente dados.

Apagar um usuário tenta remover o acesso no parceiro. A exclusão não é só local: o Quaza pede ao parceiro para remover o assinante e desvincula o serviço do contrato.

Plano sem código de integração não funciona. O código é o que o parceiro reconhece; sem ele, o provisionamento falha. Preferir importar a digitar.

O Log Request é só leitura. Ele registra o que aconteceu; não dá para "refazer" uma chamada por ali. Para reprovisionar, volte ao Usuário.

De onde vêm os dados

Informação enviada ao parceiro	Onde é cadastrada no Quaza
Credenciais de API (usuário, token, etc.)	SVA → Integrador
Código do plano/pacote	SVA → Plano (campo Código de integração)
Dados do assinante (usuário, senha, CPF, telefone)	SVA → Usuário
Cliente e contrato vinculados	Cliente → Contrato (serviço do tipo SVA)

Perguntas frequentes

Qual a diferença entre SVA e NFe SVA?

SVA é o serviço que você revende e provisiona no parceiro (esta wiki). NFe SVA é a nota fiscal desse serviço, com modelo fiscal próprio — veja NFe SVA .

Cadastrar o assinante já cria o acesso no parceiro?

Sim. Ao salvar um usuário novo em SVA → Usuário, o Quaza chama a API e provisiona o acesso na plataforma do parceiro na hora.

Preciso digitar os planos um a um?

Não, quando o parceiro suporta. Use "Importar planos" na tela de Plano para puxar o catálogo automaticamente. Só digite manualmente se aquele gateway não tiver importação.

Por que cada integrador pede campos diferentes?

Cada parceiro tem uma API diferente. O Quaza mostra só os campos exigidos pelo gateway escolhido (usuário/senha, token, client id/secret, instância).

O SVA do cliente bloqueia sozinho quando ele fica devendo?

Sim, se o serviço estiver vinculado ao contrato como tipo SVA. Ao bloquear o contrato (manual ou pela tarefa de cobrança), o Quaza pede ao parceiro para suspender o acesso; ao desbloquear, reativa.

Como descubro por que o acesso de um cliente falhou?

Vá em SVA → Log Request, ache a chamada do cliente e veja o código da requisição (200 = ok; 4xx/5xx = erro) e a resposta do parceiro.

O que significam Homologação e Produção no integrador?

Homologação é o ambiente de teste do parceiro (não cria acesso real); Produção é o ambiente real. Opere com clientes só em Produção.

Posso reaproveitar um usuário/CPF/telefone já cadastrado?

Não enquanto houver um assinante ativo com aquele dado — o sistema bloqueia duplicidade. Verifique a listagem de Usuário antes.

Apagar o assinante remove o acesso no parceiro?

Sim. A exclusão tenta remover o assinante na plataforma do parceiro e desvincula o serviço do contrato.

Preciso de permissão especial para usar o módulo?

As telas de SVA ficam no grupo "SVA" do menu. Se você não as enxerga, peça ao administrador do provedor para liberar o acesso ao seu perfil.

Quem agenda as tarefas automáticas (renovação de token, criação em lote)?

O administrador do servidor, via crontab. Pela tela você não liga nem desliga essas tarefas; em caso de falha, acione o suporte.

Documentos relacionados

NFe SVA — a nota fiscal do serviço de valor agregado.
Contrato — onde o SVA é vinculado para entrar na cobrança e no bloqueio.
Cobrança — lançamento e gestão da inadimplência que dispara o bloqueio em cascata.
Fatura — como o serviço aparece na cobrança do cliente.