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 e pin.

A documentação da API de recarga de celular e cartões de presentes (api gift cards) da metallisson.com foi construída pra 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á:

  1. Criar uma conta em nosso painel
  2. Preencher todos os seus dados no perfil
  3. Adicionar R$10 no mínimo à sua carteira
  4. 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 completo e saldo na carteira virtual 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.

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)

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)

Retorno JSON com sucesso

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

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) (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 e pins, como cartões de presente).

“Operação” pode ser “p” para PIN e “o” para online.

“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 ( a operação é um char de 1 carácter sendo “o” para recarga online ou “p” para recarga pin )
  • numero ( número é uma string de 11 dígitos, sendo o telefone com DDD)
  • 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)

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”.

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 de 1 carácter sendo “o” para recarga online ou “p” para recarga pin – 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 int no formato ddd999999999 – 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)

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, apenas 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.

Recomendo 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:

  1. Telefone do cliente
  2. NSU (caso seja recarga de telefonia)
  3. PIN (caso seja recarga pin)
  4. LOTE (caso seja recarga pin)
  5. SERIE ( caso seja recarga pin)
  6. Mensagem
  7. 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

$url = 'https://www.metallisson.com/api/v1.1/recarga'; //vamos fazer um POST para essa url
$chave = 'sua-chave-de-api-aqui'; //pegue sua chave api no menu Configuração de sua Conta de revendedor
/*

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
$content = http_build_query(array(
	'chave-api'   => $chave,
	'operacao'    => $operacao,
	'numero'      => $numero,
	'operadora'   => $operadora,
	'recarga'     => $recarga
));
$context = stream_context_create(array(
	'http' => array(
		'method'  => 'POST',
		'content' => $content,
		'header'  => "Content-Type: application/json",
	)
));

// faz a solicitação da recarga via POST

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

// transforma o resultado JSON para um array

$resultado = json_decode($resultado);

// se a recarga foi solicitada com sucesso me retorne os dados

if ($resultado[0] == 1)
	{
		$retorno = $resultado[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'];
	}

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 de revendedor 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).

Como o foco da API é na venda final, estão sendo implementados novas funções para a v1.1 onde as principais ações de vendas estarão disponíveis em nosso webservice, não havendo necessidade, caso assim precise, da alimentação de um DB em seu lado.

Obs. 1: Nunca uma função será excluída ou modificada sem um email de aviso prévio, mas não obrigatoriamente será informado novas funcionalidades. Fique atento sempre a esta página.

Obs. 2: 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. 3: Recargas solicitadas mas não efetuadas serão automaticamente canceladas.

Última atualização 30/11/2018 às 02:00h.

Sobre


metallisson® integra em uma única plataforma diferentes produtos digitais.

- Compra Ae Atividades de Internet Ltda
- 26.696.425/0001-70
- contato@metallisson.com
- Rua Gabriel Chabo, 35, Jardim Paulistano,
- Campina Grande - PB

Informações


Ajuda API Contato Termos Privacidade Mapa do Site
Segurança contra vírus Google

Segurança contra vírus
Deus seja louvado!
Aguarde... processando. OK! Tudo certo.