Documentação da API de recarga

Documentação da API de recarga

Nova versão v1.1 API recarga online e pin. A v1.0 será descontinuada em 01/10/2018

A documentação da API de recarga e cartões de presentes (gift cards) do metallisson foi construída pra ser simples.

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 e cartão de presente (gift card api)

Olá desenvolvedor,

Meu nome é Allisson e sou quem implementou essa API de recarga online.

Embora essa plataforma seja voltada à vendas, essa API foi construída inicialmente para conectar a minha plataforma woocommerce às operadoras de Telefonia.

Um belo dia resolvi libera-la para o público em sua v1.0.

Devido solicitações, e para deixar ainda mais robusto, o webservece foi atualizado para a v1.1.

Essa API é real-time, ou seja, qualquer recarga solicitada imediatamente é enviada à operadora e retornado a resposta da mesma em frações de segundos. (não coloco a recarga na mão, como já me perguntaram ;))

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.

Quanto eu ganho de comissão e como?

Bom, nas recargas de operadoras de telefonia (recarga online) você tem 2%. E nos cartões de presente (recargas pin) 1%.

Sua comissão é paga no valor descontado em carteira. Ex.: Em uma recarga online de R$100,00 será descontado de sua carteira R$98,00.

É confiável e seguro?

Sim, tem minha foto por todo canto nesse site, o CNPJ da minha empresa e se precisar de mais alguma coisa pode falar comigo. A turma do setor de telecomunicações me conhece, não tenho o que esconder. 🙂

Sim é seguro. SSL, servidores SSDs e tudo mais. Eu só recomendo que você tenha uma rotina de renovar sua CHAVE DE API e sua senha. Eu sempre atualizo a minha de tempos em tempos.

Tudo o que é preciso para implementar está aqui?

Sim. Não espere nada de outro mundo, não complique o que é simples. Mãos à obra!

Segue as funções disponíveis.

Como saber meu 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 saber quais operadoras estão 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 saber quais 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 )

Retorno JSON com sucesso

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

 

Retorno JSON com erro

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

 

Ei fique atento aqui! Um valor de recarga pode estar habilitado para vender em um determinado DDD e no outro pode ser que ele não exista.

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

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

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’ )

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"
]

 

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 efetuada com sucesso!

Rotina de implantação

Atualize seu banco

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

É 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
  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 efetuada com sucesso me retorne os dados

if ($resultado[0] == 1)
	{
		$retorno = $resultado[1];
		echo $retorno['mensagem'];
		echo $retorno['nsu'];
		echo $retorno['pin'];
		echo $retorno['lote'];
		echo $retorno['serie'];
		echo $retorno['id_recarga'];
	}

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, sugestão ou problema entre em contato.

Avalie esse artigo para entendermos se você gostou do nosso conteúdo. Clique em uma estrela de acordo com seu nível de satisfação.

Conteúdo ruimPrecisa melhorar o conteúdoConteúdo razoávelConteúdo bomÓtimo conteúdo (Seja o primeiro a avaliar...)
 Loading...