API: Recarga de celular, fixos e cartão de presente Gift Card API

A API de recarga é uma solução websevice que tem como principal objetivo integrar sistemas multiplataformas às operadoras de telefonia e de cartões de presente pré-pagos (gift cards).

Nova versão v1.1 API recarga online, pin e tv.

A documentação da API de recarga de celular, TV pré-paga e cartões de presentes (api gift cards) da metallisson.com foi construída para ser simples.

Todo o foco do websercice foi construído no mapeamento de ações de vendas para o cliente final.

Antes de mais nada você deverá:

Criar uma conta em nosso painel
Preencher todos os seus dados no perfil
Criar uma chave de api no menu configuração

API Recarga de celular e cartão de presente (gift card api)

A API para recarga de celular real-time da metallisson.com foi desenvolvida simulando o processo de venda.

Não é preciso nada além de um cadastro para tudo funcionar. Caso seja de seu interesse fique à vontade para implementar em seu aplicativo.

Para adicionar saldo à sua carteira leia aqui.

Segue as funções disponíveis.

Autenticação de chamadas

Para realizar chamadas POST ou GET é necessário o envio obrigatório da chave de api. Essa chave só pode ser enviada associada a um IP ou uma assinatura.

Quando um IP é associado a uma chave somente esse IP poderá interagir com o webservice usando a chave.

Para sistemas com IPs dinâmicos é recomendado o uso de uma assinatura. Uma assinatura sobrepõe um IP associado e dá acesso de interação com o webservice.

Somente quando uma assinatura é gerada seu envio se torna obrigatório. Nas chamadas POST deve ser enviada no header e nas chamadas GET como variável.

Caso as associações não sejam obedecidas e/ou a chave não seja enviada, uma mensagem de chave inexistente será mostrada.

Como obter o saldo em carteira?

Faça um GET para a URL: https://www.metallisson.com/api/v1.1/recarga

Parâmetros da solicitação

chave-api ( string de 30 caracteres )
saldo ( apenas envie true)
assinatura ( string de 30 caracteres – opcional ) (novo)

Retorno JSON com sucesso

[
  1,
  {
    "saldo": "760.50"
  }
]

Retorno JSON com erro

[
  0,
  "Mensagem de erro",
  "Código do erro"
]

Como obter as operadoras habilitadas?

Faça um GET para a URL: https://www.metallisson.com/api/v1.1/recarga

Parâmetros da solicitação

chave-api ( string de 30 caracteres )
listar-operadoras ( apenas envie true)
assinatura ( string de 30 caracteres – opcional ) (novo)

Retorno JSON com sucesso

[
  1,
  {
    "online": [
      "OI",
      "VIVO",
      "CLARO",
      "TIM",
      ...
    ],
    "pin": [
      "STEAM",
      "XBOX",
      "LEVEL UP",
      "NETFLIX",
      "UBER",
      "GOOGLE PLAY",
      ...
    ],
    "tv": [
      "SKY",      
      ...
    ]
  }
]

Retorno JSON com erro

[
  0,
  "Mensagem de erro",
  "Código do erro"
]

Como obter os valores de recarga de uma operadora?

Faça um GET para a URL: https://www.metallisson.com/api/v1.1/recarga

Parâmetros da solicitação

chave-api ( string de 30 caracteres )
listar-faces-operadora ( enviar uma string com o nome da operadora )
ddd ( int representando o ddd do telefone – opcional – default = null )
assinatura ( string de 30 caracteres – opcional ) (novo)

Retorno JSON com sucesso

[
  1,
  [
    {
      "nome": "GOOGLE 10",
      "face": "10",
      "validade": "0",
      "operacao": "p",
      "ddds": [
        "11",
        "12",
        "13",
        "14",
        "15",
        ...
      ]
    },
    {
      "nome": "GOOGLE 50",
      "face": "50",
      "operacao": "p",
      "validade": "0",
      "ddds": [
        "66",
        "67",
        "68",
        "83",
        "94",
        ...
      ]
    },
    ...
  ]
]

Retorno JSON com erro

[
  0,
  "Mensagem de erro",
  "Código do erro"
]

Nos campos retornados “nome” é o nome do produto repassado pela operadora.

“Face” é o valor da recarga que o cliente irá colocar (recargas online, pins e tv).

“Operação” pode ser “p” para PIN, “o” para ONLINE e “t” para TV.

“Validade” é a quantidade em dias que aquele determinado produto pode ser usado. Algumas operadoras disponibilizam essa informação.

O campo “ddds” diz quais DDDs estão habilitados para consumirem aquele produto (face).

Obs.: Um valor de recarga pode estar habilitado para ser vendido em um determinado DDD e no outro pode ser que ele não exista.

Trate isso aí em seu aplicativo. Primeiro pergunte o DDD do cliente e depois ofereça o catálogo correto pra ele, caso contrário sua recarga será perdida!

Como fazer uma recarga online via api?

Faça um POST para a URL: https://www.metallisson.com/api/v1.1/recarga

Parâmetros da solicitação

chave-api ( string de 30 caracteres )
operacao ( é um char sendo “o” para recarga online, “p” para recarga pin ou “t” para recarga tv )
numero ( número é uma string podendo ser o telefone com DDD ou o código do assinante de TV)
operadora ( é o nome da operadora conforme comando GET ‘listar-operadoras’ )
recarga ( é o valor da recarga conforme comando GET ‘listar-faces-operadora’ )
id-externo ( é um id int de seu sistema – opcional )
teste ( é uma string – opcional )
assinatura ( string de 30 caracteres – opcional ) (novo)

Retorno JSON com sucesso (Comprovante de recarga)

[
  1,
  {
    "mensagem": "Mensagem de sucesso",
    "nsu": "123",
    "pin": "123",
    "lote": "123",
    "serie": "123",
    "id_recarga": "123"
  }
]

Retorno JSON com erro

[
  0,
  "Mensagem de erro",
  "Código do erro"
]

Observe que o “id-externo” é um campo opcional. Um caso interessante para seu uso é quando você quiser identificar as recargas de seus clientes.

Envie o id do seu cliente nesse campo para representa-lo em nossa base de dados.

Para recargas pin, que não necessitem de número de telefone, envie vazio na variável “numero”.

Para que você não consuma seu saldo realizando a integração de seu sistema à API, envie com a solicitação POST o parâmetro “teste“. As recargas com essa opção serão simuladas e não constarão no relatório. Para simular um erro envie “teste=CODIGOERRO“, ex.: “teste=METE1“. Para realizar uma recarga com sucesso (retornando NSU ou PIN) envie “teste=OK“.

Uma recarga só é efetivamente concluída com sucesso quando um número NSU ou um código PIN é retornado. Fique atento!

Como listar o histórico de recargas?

Faça um GET para a URL: https://www.metallisson.com/api/v1.1/recarga

Parâmetros da solicitação

chave-api ( string de 30 caracteres )
listar-historico-recargas ( é um char sendo “o” para online, “p” para pin ou “t” para tv – default = o )
pagina ( é um int representando a página solicitada – opcional – default = 1 )
datai ( é a data de início (dd/mm/aaaa) – opcional – default = hoje )
dataf ( é a data de fim (dd/mm/aaaa) – opcional – default = hoje )
telefone ( é um string que representa o telefone ou o código de assinatura de tv – opcional – default = null)
qtd-linhas ( é um int com a quantidade de linhas por página – opcional – default = 20 )
id-externo ( é um id int de seu sistema – opcional – default = null )
assinatura ( string de 30 caracteres – opcional ) (novo)

Retorno JSON com sucesso

[  
   1,
   {  
      "recargas":[  
         {  
            "id_recarga":"123",
            "telefone":"",
            "operadora":"NETFLIX",
            "face":"30.00",
            "data_hora":"07/01/2018 21:49:36",
            "nsu":"123",
            "pin":"123",
            "serie":"123",
            "lote":"123",
            "mensagem":"Mensagem da operadora",
            "status":"ok"
         },
         {  
            "id_recarga":"124",
            "telefone":"",
            "operadora":"NETFLIX",
            "face":"30.00",
            "data_hora":"07/01/2018 23:09:00",
            "nsu":"124",
            "pin":"124",
            "serie":"124",
            "lote":"124",
            "mensagem":"Mensagem da operadora",
            "status":"ok"
         },
	 ...
      ],
      "paginacao":{  
         "pagina-anterior":"",
         "proxima-pagina":2
      }
   }
]

Observe o campo do retorno JSON “paginacao”. A api já retorna a próxima ou a página anterior, caso exista, entretanto se não existir, retornará vazio no campo (mais uma facilidade para você, meu caro desenvolvedor :)).

Os campos: nsu, pin, serie ou lote podem vir com null. No caso do campo telefone do retorno JSON, ele só terá valor quando você requisitar recargas no modo online (operadoras de telefonia, por exemplo).

O campo status pode conter “ac”, “ca”, “so” e “ok”:

ac = Aguardando confirmação
ca = Cancelada
so = Solicitada
ok = Confirmada

Retorno JSON com erro

[
  0,
  "Mensagem de erro",
  "Código do erro"
]

Quais os códigos de mensagem de erro, aviso e sucesso?

Código 0 de erro:

METE1 = O campo operadora está vazio!
METE2 = O campo número está vazio!
METE3 = O campo face está vazio!
METE4 = No momento não trabalhamos com essa operadora!
METE5 = O número está inválido!
METE6 = No momento não trabalhamos com essa Operadora PIN!
METE7 = No momento não trabalhamos com esse valor de face para a operadora $NOME_OPERADORA
METE8 = Você não tem crédito suficiente para realizar essa recarga. Por favor adicione mais dinheiro à sua carteira. (Saldo:$SALDO Face:$VALOR_DE_FACE )
METE12 = Alguma coisa ocorreu de errado! Tente em outro momento.
METE13 = Ocorreu um problema ao tentar solicitar a recarga.
METE14 = A recarga no momento não pode ser solicitada!
METE15 = Produto e/ou operadora não estão presentes na classe de recarga adequada!
METE16 = Tivemos um problema no acesso à base de dados. Por favor tentar mais tarde.

Código -2 de aviso:

META1 = Essa recarga já foi programada. Caso ela esteja inativa você terá que reativa-la para que a recarga seja colocada no dia programado.
META2 = Recarga solicitada mas não confirmada.
META3 = Recarga solicitada mas não foi enviado código de confirmação.

Código 1 de sucesso

OK – Recarga solicitada com sucesso!

Rotina de implantação

Atualize seu banco de dados

Todos os dias, 1 vez ao dia, você deve fazer uma chamada para listar as recargas disponíveis e operadoras para alimentar seu banco ode dados.

É comum que uma operadora deixe de vender um determinado valor ou mesmo acrescente uma nova face de recarga.

Recomendamos depois das 2:30h. Escolha qualquer horário para atualizar seu banco de dados.

DDD do cliente

Ofereça apenas recargas que estão habilitadas ao DDD correspondente

Entregue o comprovante de recarga do cliente

O comprovante de recarga deve conter obrigatoriamente os seguintes itens:

Telefone do cliente
NSU (caso seja recarga de telefonia)
PIN (caso seja recarga pin)
LOTE (caso seja recarga pin)
SERIE ( caso seja recarga pin)
Mensagem
Horário

Essas informações são importantes caso a recarga seja efetuada com sucesso, pois o cliente poderá entrar em contato com as operadoras caso tenha algum problema.

Oriente seu cliente a informar sempre o NSU à operadora.

API de recarga: Exemplo de uma recarga Vivo em PHP

/*

Se você for fazer uma recarga de uma operadora de telefonia como a VIVO ou a TIM use um o na operação.

Recarga Online são recargas que são transferidas direto das operadoras (tempo real).

Para recargas (Gift Cards), ou seja, que precisam de códigos de cartões (PINs) use a operação p.

Observe que o retorno JSON só trará algum valor nos campos pin, lote e serie quando a operação for p.

*/
$operacao = 'o';//operação o = recarga online p == recarga pin
$numero = 83999999999; //número de telefone com ddd  (11 dígitos)
$operadora = 'VIVO'; //nome exato da operadora habilitada
$recarga = 10; //valor de face da recarga (conforme comando listar) ex:10 é uma recarga de R$10,00 e 9.9 é uma de R$9,90

//sua chave de API
function getChave() {
    return 'SUA_CHAVE_AQUI';
}

//sua assinatura, caso não queira usar um IP fixo
function getAssinatura() {
    return 'SUA_ASSINATURA_AQUI';
}

//endpoint
function getUrl() {
    return 'https://www.metallisson.com/api/v1.1/recarga';
}


function geraGET_METALLISSON($campos = array()) {

    $campos = array_merge($campos, array(
        'chave-api'  => getChave(),
        'assinatura' => getAssinatura()
    ));
    
    $content = http_build_query($campos);
    
    $resultado = file_get_contents(getUrl() . '?' . $content);
    
    $json = json_decode($resultado, true);
    
    return $json;
}

function prepareHeaders($headers) {
    $flattened = array();

    foreach ($headers as $key => $header) {
        if (is_int($key)) {
            $flattened[] = $header;
        } else {
            $flattened[] = $key . ': ' . $header;
        }
    }

    return implode('\r\n', $flattened);
}

function geraPOST_METALLISSON($campos = array()) {
    
    $campos = array_merge($campos, array(
        'chave-api'  => getChave(),
        'assinatura' => getAssinatura()
    ));

    $content = http_build_query($campos);

    $headers = array(
        'Content-Type' => 'application/x-www-form-urlencoded; charset=utf-8'        
    );

    $context = stream_context_create(array(
        'http' => array(
            'method'  => 'POST',
            'content' => $content,
            'header'  => prepareHeaders($headers)
        )
    ));

    $resultado = file_get_contents(getUrl(), null, $context);

    $resultado = json_decode($resultado);

    return $resultado;
}


//faz uma recarga teste online
$recarga_online = geraPOST_METALLISSON(array(    
    'operacao'  => $operacao, 
    'operadora' => $operadora, 
    'numero'    => $numero,
    'recarga'   => $recarga, 
    'teste'     => 'OK'// Esse parâmetro deve ser removido quando em produção
));

//faz uma recarga teste PIN
$recarga_pin = geraPOST_METALLISSON(array(    
    'operacao'  => 'p', 
    'operadora' => 'XBOX', 
    'numero'    => '',
    'recarga'   => '50', 
    'teste'     => 'OK'// Esse parâmetro deve ser removido quando em produção
));

//consulta o saldo
$saldo = geraGET_METALLISSON(array(
    'saldo' => true    
 ));

//imprime os resultados
echo ' Recarga Online: ';

echo json_encode($recarga_online);

//imprime os resultados
echo ' Recarga PIN: ';

echo json_encode($recarga_pin);

echo ' Saldo: ';

echo json_encode($saldo);

// verificando se a recarga online foi solicitada com sucesso me retorne os dados
// a PIN também deve ser vefificada
if ($recarga_online[0] == 1)
{
	$retorno = $recarga_online[1];
	echo $retorno['mensagem'];
	echo $retorno['nsu'];//teste se existe o NSU confirmando a recarga
	echo $retorno['pin'];//teste se existe o código alfanumérico confirmando o produto
	echo $retorno['lote'];
	echo $retorno['serie'];
	echo $retorno['id_recarga'];
}

O post data deve ser enviado como segue o exemplo:

chave-api=SUA_CHAVE_AQUI&numero=&operacao=p&operadora=XBOX&recarga=50&teste=OK&assinatura=SUA_ASSINATURA

Header

‘Content-Type’ – ‘application/x-www-form-urlencoded; charset=utf-8’

Veja mais um exemplo de script de recarga em PHP aqui.

Observe que uma recarga nunca poderá ser cancelada. Fique atento!

Para você usar a API de recarga será necessário fazer um novo cadastro no Painel e adicionar dinheiro em sua carteira.

Se você está entrando agora na área de telecomunicações e venda direta, recomendo a leitura do post sobre revenda de recargas e sobre recarga online em nosso blog.

Qualquer dúvida acesse nossa ajuda, entretanto caso ainda tenha pergunta, sugestão ou problema entre em contato (contato@metallisson.com).

O painel disponibiliza um log das últimas interações com o webservice. Acesse o menu Configuração > Log API.

Obs. 1: Uma operadora pode disponibilizar produtos promocionais por um determinado período que não sejam propriamente uma recarga ou um cartão pré-pago. A operadora pode liberar produtos como jogos ou pacotes de internet e voz (combos). Faça a conferência de qual mix de produtos você quer repassar em seu aplicativo.

Obs. 2: Recargas solicitadas mas não efetuadas serão automaticamente canceladas.

Obs. 3: Caso o sistema encontre alguma dificuldade crítica ao solicitar alguma recarga em qualquer produto, poderá desabilita-lo automaticamente não listando esse produto por um período. É possível que o seu aplicativo receba METE7 após essa rotina.