MVNO Corevo API

MVNO Corevo API

API REST para gestão completa de operações MVNO — clientes, linhas, planos, portabilidades, carrinhos e faturamento. Integre do zero de forma rápida e eficiente.

🔐
Autenticação
CompanyToken + OAuth2 Bearer
🚀
Fluxo de Integração
Passos para ativar sua primeira linha
🛒
Criar Carrinho
Ativação, recarga e recorrência

URLs Base

🧪 Homologação
https://api.corevo.dev/
🚀 Produção
https://api.corevo.com.br/

Serviços

ServiçoPrefixoDescrição
Corevo Service/api/rest/service_telecom/Operações principais MVNO
Shared Service/api/rest/service_shared/Localização (cidades, estados, países)

📚 Glossário

Termos técnicos que aparecem ao longo da documentação:

MVNO
Mobile Virtual Network Operator — operadora de telefonia que não possui infraestrutura própria, operando sobre a rede de outra operadora.
MSISDN
Mobile Station International Subscriber Directory Number — o número de telefone completo com código de país e DDD (ex: 5511999990001).
ICCID
Integrated Circuit Card Identifier — número serial único do SIM card, com 19 ou 20 dígitos (ex: 89550192240000000001).
IMSI
International Mobile Subscriber Identity — identificador único do assinante na rede celular, gravado no SIM card.
eSIM
Embedded SIM — chip de SIM embutido no dispositivo, sem cartão físico. Ativado via QR Code ou perfil digital.
DDD
Discagem Direta a Distância — código de área brasileiro com 2 dígitos que identifica a região geográfica do número.
Portabilidade
Processo regulamentado pela Anatel que permite ao usuário manter seu número ao trocar de operadora.
NFCom
Nota Fiscal Fatura de Serviços de Comunicação Eletrônica, modelo 62 — documento fiscal eletrônico emitido por empresas de telecomunicações.
Carrinho (Cart)
Objeto que representa uma intenção de compra: ativação de nova linha, recarga de crédito ou configuração de recorrência.
CompanyToken
Token de identificação da empresa parceira, enviado em todas as requisições no header CompanyToken.
personId
Identificador do cliente no sistema. Retornado no POST /customers como um UINT64 em formato string. Usado em carrinhos e consultas de linhas.
Recorrência
Renovação automática mensal do plano contratado pelo cliente. Configurável via POST /mvno_lines/:id/recurrence como pré-pago ou pós-pago.

🔄 Ciclo de Vida da Linha MVNO

Uma linha MVNO passa pelos seguintes estados ao longo de sua existência:

Status da Linha (mvno_lines)

Nenhum
mlsNone
Ativa
mlsActive
Linha em operação normal.
Inativa
mlsInactive
Aguardando Portabilidade
mlsWaitingPortability
Portabilidade solicitada, aguardando efetivação.
Cancelada
mlsCanceled
Linha cancelada definitivamente.
Portada (entrada)
mlsPorted
Número portado com sucesso para esta operadora.
Portabilidade Saída
mlsPortout
Número portado para outra operadora.
Bloqueada
mlsBlocked
Suspensa
mlsSuspended
Linha temporariamente suspensa.
Quarentena
mlsQuarantine
Número em quarentena após cancelamento.

Status de Portabilidade

Pendente
mpsPending
Solicitação criada, aguardando envio.
Enviada
mpsSent
Solicitação enviada para a operadora doadora.
Cancelada
mpsCanceled
Concluída
mpsSuccess
Portabilidade efetivada com sucesso.
Erro
mpsError
Cancelamento Pendente
mpsCancelPending
💡
Transições automáticasApós criar e processar um carrinho (PATCH /mvno_carts/:id), a linha entra em ativa automaticamente. A suspensão pode ser configurada via POST /mvno_lines/:id/recurrence com "suspend": true.

📄 Paginação

Endpoints de listagem suportam paginação via parâmetros de query. O padrão é consistente em toda a API:

pagination.page
Número da página, iniciando em 1. Default: 1.
pagination.limit
Quantidade de registros por página. Default varia por endpoint (geralmente 20 ou 50).
Exemplo — página 2 com 10 itens
GET /api/rest/service_telecom/customers?pagination.page=2&pagination.limit=10

A resposta inclui um objeto metadata com os dados de paginação:

JSON — resposta paginada
{
  "metadata": {
    "page": 1,
    "limit": 10,
    "total": "49",
    "aggregations": {}
  },
  "data": [ /* array de registros */ ]
}
ℹ️
Para buscar todos os registros, incremente pagination.page até que page >= totalPages. Evite valores muito altos de limit para não degradar a performance.

🔐 Autenticação

A autenticação é feita em três etapas. As credenciais client_id e client_secret são fornecidas pela Corevo no momento do cadastro.

01
Obter Access Token
POST /oauth2/token
02
Obter CompanyToken
GET /companies
03
Usar nas requisições
Bearer + CompanyToken + x-tenant

Passo 1 — Obter o Access Token

Faça uma requisição com suas credenciais para obter o access_token OAuth2.

URL (HML)https://api.corevo.dev/oauth2/token
URL (Produção)https://api.corevo.com.br/oauth2/token
MétodoPOST
Content-Typeapplication/x-www-form-urlencoded
x-tenantseu_tenant — header obrigatório (identificador da MVNO)

Parâmetros do Body

CampoValorDescrição
grant_type *client_credentialsTipo de concessão OAuth2
client_id *UUID fornecido pela CorevoIdentificador do cliente OAuth2
client_secret *Secret fornecido pela CorevoChave secreta do cliente OAuth2
curl -X POST https://api.corevo.dev/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-tenant: seu_tenant" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=seu_client_id" \
  --data-urlencode "client_secret=seu_client_secret"
const params = new URLSearchParams({
  grant_type: 'client_credentials',
  client_id: 'seu_client_id',
  client_secret: 'seu_client_secret'
});

const res = await fetch('https://api.corevo.dev/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'x-tenant': 'seu_tenant' },
  body: params
});
const { access_token } = await res.json();
import requests

response = requests.post(
    'https://api.corevo.dev/oauth2/token',
    headers={'x-tenant': 'seu_tenant'},
    data={
        'grant_type': 'client_credentials',
        'client_id': 'seu_client_id',
        'client_secret': 'seu_client_secret'
    }
)
access_token = response.json()['access_token']
$ch = curl_init('https://api.corevo.dev/oauth2/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded', 'x-tenant: seu_tenant'],
    CURLOPT_POSTFIELDS     => http_build_query([
        'grant_type'    => 'client_credentials',
        'client_id'     => 'seu_client_id',
        'client_secret' => 'seu_client_secret'
    ])
]);
$result = json_decode(curl_exec($ch), true);
$accessToken = $result['access_token'];
Resposta (200 OK)
JSON
{
  "access_token": "I475-FU2m_1DnVjqOo38xB0vlMenJrkOpnKuWG0-Dzs...",
  "expires_in": 29,
  "scope": "",
  "token_type": "bearer"
}

Passo 2 — Obter o CompanyToken

Com o access_token em mãos, consulte GET /companies para obter o CompanyToken da empresa/revenda.

# Homologação
curl -X GET https://api.corevo.dev/api/rest/service_telecom/companies \
  -H "Authorization: Bearer seu_access_token" \
  -H "x-tenant: seu_tenant"

# Produção
curl -X GET https://api.corevo.com.br/api/rest/service_telecom/companies \
  -H "Authorization: Bearer seu_access_token" \
  -H "x-tenant: seu_tenant"
const res = await fetch('https://api.corevo.dev/api/rest/service_telecom/companies', {
  headers: { 'Authorization': `Bearer ${access_token}`, 'x-tenant': 'seu_tenant' }
});
const companies = await res.json();
const { companies } = await res.json();
const companyToken = companies[0].token; // usar no header CompanyToken
response = requests.get(
    'https://api.corevo.dev/api/rest/service_telecom/companies',
    headers={'Authorization': f'Bearer {access_token}', 'x-tenant': 'seu_tenant'}
)
data = response.json()
company_token = data['companies'][0]['token']  # usar no header CompanyToken
$ch = curl_init('https://api.corevo.dev/api/rest/service_telecom/companies');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer $accessToken", "x-tenant: seu_tenant"]
]);
$companies = json_decode(curl_exec($ch), true);
$companyToken = $companies['companies'][0]['token']; // usar no header CompanyToken

Passo 3 — Usar nas requisições

Todas as requisições à API MVNO devem incluir os três headers obrigatórios simultaneamente:

AuthorizationBearer {access_token} — obtido no Passo 1
CompanyToken{company_token} — obtido no Passo 2
x-tenantseu_tenant — valor da sua matriz (ver tabela abaixo)
Content-Typeapplication/json
🏷️
Header x-tenantCada MVNO que utiliza a integração por API precisa enviar o header x-tenant com o valor correspondente ao seu ambiente em todos os requests — sempre o nome da matriz. O valor é um identificador curto da sua matriz (ex.: seu_tenant) e é informado pela Corevo no momento do cadastro.
curl -X GET https://api.corevo.dev/api/rest/service_telecom/customers \
  -H "Authorization: Bearer seu_access_token" \
  -H "CompanyToken: seu_company_token" \
  -H "x-tenant: seu_tenant" \
  -H "Content-Type: application/json"
const HEADERS = {
  'Authorization': `Bearer ${access_token}`,
  'CompanyToken': company_token,
  'x-tenant': 'seu_tenant',
  'Content-Type': 'application/json'
};

const res = await fetch(`${BASE_URL}/api/rest/service_telecom/customers`, { headers: HEADERS });
const data = await res.json();
HEADERS = {
    'Authorization': f'Bearer {access_token}',
    'CompanyToken': company_token,
    'x-tenant': 'seu_tenant',
    'Content-Type': 'application/json'
}

response = requests.get(f'{BASE_URL}/api/rest/service_telecom/customers', headers=HEADERS)
data = response.json()
$headers = [
    "Authorization: Bearer $accessToken",
    "CompanyToken: $companyToken",
    "x-tenant: seu_tenant",
    'Content-Type: application/json'
];

$ch = curl_init("$BASE_URL/api/rest/service_telecom/customers");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $headers]);
$data = json_decode(curl_exec($ch), true);
⚠️
SegurançaNunca exponha client_id, client_secret ou tokens no frontend ou em repositórios públicos. Armazene-os como variáveis de ambiente no servidor.
ℹ️
Expiração do tokenO access_token expira conforme indicado no campo expires_in (em segundos). Implemente renovação automática antes da expiração para evitar interrupções.

🌐 Ambientes

AmbienteURL BaseUso
Homologaçãohttps://api.corevo.dev/Testes e desenvolvimento
Produçãohttps://api.corevo.com.br/Operação real
🚨
AtençãoOperações em produção afetam linhas reais de clientes. Teste exaustivamente em homologação antes de migrar.

🚀 Fluxo de Integração

Passos para ativar uma nova linha MVNO:

01
Obter Token
POST /oauth2/token
02
Obter CompanyToken
GET /companies
03
Criar Cliente
POST /customers
04
Escolher Plano
GET /mvno_plans
05
Criar Carrinho
POST /mvno_carts
06
Processar Carrinho
PATCH /mvno_carts/:id
07
Consultar Linha
GET /mvno_lines/:id
💡
PortabilidadePara portar um número, inclua o objeto portability no corpo do POST /mvno_carts e depois crie a solicitação com POST /mvno_portabilities.

⚠️ Tratamento de Erros

Códigos HTTP

CódigoSignificadoAção Recomendada
200SucessoProcessar normalmente
400Bad RequestVerificar campos obrigatórios e formatos
401Não AutorizadoRenovar CompanyToken ou Bearer token
403ProibidoVerificar permissões da conta
404Não encontradoVerificar UUID/referência informada
500Erro InternoTentar novamente ou contatar suporte

Estrutura de Erro

JSON
{
  "code": 400,
  "message": "Descrição detalhada do erro",
  "details": []
}
⚠️
Erros mais comuns • Token expirado ou ausente → renovar o Bearer token
• CompanyToken inválido → verificar o header em todas as requisições
• UUID mal formatado → garantir formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Campos obrigatórios ausentes → revisar o body conforme a documentação