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.
URLs Base
https://api.corevo.dev/
https://api.corevo.com.br/
Serviços
| Serviço | Prefixo | Descriçã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/recurrencecomo 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)
Status de Portabilidade
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).
GET /api/rest/service_telecom/customers?pagination.page=2&pagination.limit=10
A resposta inclui um objeto metadata com os dados de paginação:
{
"metadata": {
"page": 1,
"limit": 10,
"total": "49",
"aggregations": {}
},
"data": [ /* array de registros */ ]
}
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.
Passo 1 — Obter o Access Token
Faça uma requisição com suas credenciais para obter o access_token OAuth2.
Parâmetros do Body
| Campo | Valor | Descrição |
|---|---|---|
grant_type * | client_credentials | Tipo de concessão OAuth2 |
client_id * | UUID fornecido pela Corevo | Identificador do cliente OAuth2 |
client_secret * | Secret fornecido pela Corevo | Chave 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'];
{
"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:
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);
client_id, client_secret ou tokens no frontend ou em repositórios públicos. Armazene-os como variáveis de ambiente no servidor.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
| Ambiente | URL Base | Uso |
|---|---|---|
Homologação | https://api.corevo.dev/ | Testes e desenvolvimento |
Produção | https://api.corevo.com.br/ | Operação real |
🚀 Fluxo de Integração
Passos para ativar uma nova linha MVNO:
portability no corpo do POST /mvno_carts e depois crie a solicitação com POST /mvno_portabilities.⚠️ Tratamento de Erros
Códigos HTTP
| Código | Significado | Ação Recomendada |
|---|---|---|
200 | Sucesso | Processar normalmente |
400 | Bad Request | Verificar campos obrigatórios e formatos |
401 | Não Autorizado | Renovar CompanyToken ou Bearer token |
403 | Proibido | Verificar permissões da conta |
404 | Não encontrado | Verificar UUID/referência informada |
500 | Erro Interno | Tentar novamente ou contatar suporte |
Estrutura de Erro
{
"code": 400,
"message": "Descrição detalhada do erro",
"details": []
}• 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