Api de Recarga, Gift Card e TV

Introdução

A API metallisson é um conjunto de ferramentas que formam a interface do MWS (metallisson webservice).

A versão da API apresentada nessa documentação é a 2.0. Para acessar a 1.1 clique aqui.

O padrão utilizado é o RESTful baseado em HTTP implantando a autenticação com o padrão oauth 2.0 sobre o protocolo SSL/TLS. Além disso, todas as interações de requisição e resposta estão formatadas no padrão JSON.

Conceitos

A API de recarga de celular é uma solução websevice que tem como principal objetivo integrar sistemas multiplataformas às operadoras de telefonia fixa e móvel em tempo real, gerando crédito por recargas para uso em ligações, conexão de internet, entre outros serviços oferecidos pelos fornecedores.

A API de Gift Card (cartões de presente) é uma interface de solicitações e ativações de códigos alfanuméricos PIN, reconhecidos oficialmente pelos fornecedores, com o objetivo de gerar crédito virtual através do resgate do saldo atrelado ao PIN na plataforma fornecedora.

Autorização

Uma recarga deve ser previamente autorizada pela operadora para que posteriormente seja confirmada.

Em uma autorização, a recarga não é efetivamente executada. Nesta ação, um número de NSU com o status de autorização (aguardando confirmação) deve ser retornado pela operadora fornecedora, demonstrando assim que o identificador (número telefônico ou código de assinante) está apto a receber a recarga em seu saldo pré-pago e que existe estoque, no momento, para o produto.

O mesmo ocorre para os gift cards.

Caso um NSU não seja retornado, o status da compra permanecerá em solicitado, mas não estará apto a ser confirmada, que neste caso, seria a recarga que se encontra com status de “aguardando confirmação”.

Logo mais será apresentado ao desenvolvedor todos os status de recarga implementados na API.

Confirmação/Cancelamento

Uma confirmação é a segunda etapa de uma recarga.

A partir do momento que a operadora de telefonia, tv ou qualquer outro fornecedor retorna o número NSU e a recarga está com o status “aguardando confirmação” é hora de confirmar ou possivelmente cancelar a recarga.

Quando uma autorização não é confirmada, ela não inserirá saldo pré-pago na conta do identificador. Neste caso, quando a confirmação não ocorre, a recarga não será efetivamente realizada.

Já no caso de um gift card gerado e não confirmado, não será retornado um código PIN.

Obs: Uma recarga só poderá ser cancelada quando seu status não for de “confirmado”.

Fluxo

Estrutura

A API de recarga e gift card é uma interface com solicitações real-time para as operadoras fornecedoras de telefonia, tv e código PIN, pré-pagas, que são executadas com a seguinte estrutura de ações:

• Autorização
• Confirmação ou cancelamento

Para todas as operações serem realizadas, a API necessita de alguns componentes básicos. são eles:

Cabeçalhos

A API de gift card e recarga, em todas as suas solicitações, necessita de três propriedades nas requisições usando qualquer verbo: Content-Type, Accept e Authorization.

curl --location --request GET 'https://api.sandbox.metallisson.com/credits?page=3&size=20' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Parâmetros de busca

Os parâmetros de busca permitem opcionalmente filtrar resultados de alguns recursos com o verbo GET.
Por exemplo: Os recursos /orders e /credits compartilham alguns filtros básicos (será apresentado cada filtro de recurso na documentação):

curl --location --request GET 'https://api.sandbox.metallisson.com/orders?page=2&sort=DESC' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Códigos de status HTTP e padrão de respostas

Para todas as interações com os recursos da API um código de status http é retornado. Esses códigos representam duas categorias de respostas: as com sucesso e as com erros.

Além do código de status http a API reponde no corpo do JSON a propriedade return. Ela retorna um número inteiro que é o código de retorno. Este código descreve uma mensagem de sucesso, erro ou justifica uma ação tomada pelo sistema.

Sucesso

As respostas de sucesso tem uma formatação dependente do recurso interagido, todavia return é mantido como padrão no fim do corpo de cada resposta.

Exemplo:

{
   "return": 1
}

Erros

As respostas de erros tem uma formatação padrão e possuem três propriedades: error, info e return .Exemplo:

{
    "error": "AUTHENTICATION_FAILURE",
    "info": "Token or signature incorrect.",
    "return": 4
}

Sandbox: O ambiente de testes e implementação

Para implementar a API em qualquer aplicativo o desenvolvedor poderá usar o ambiente sandbox metallisson.

Acessando o sandbox, cadastrando-se e preenchendo os dados de perfil o desenvolvedor estará apto a gerar os dois itens principais para que seja realizada a conexão webservice:

• Chave de API
• A assinatura da chave

A chave de api e a assinatura só podem ser gerados manualmente via Painel.

Essas credenciais, se forem geradas no ambiente sandbox só darão acesso aos recursos do webservice de teste. Já uma chave e assinatura gerada no ambiente de produção metallisson.com darão acesso aos recursos conectados aos fornecedores.

Autenticação e permissão

Ao criar uma conta na metallisson o desenvolvedor deverá gerar uma chave de api e uma assinatura para serem usados no processo de autenticação de todas as solicitações à API.

Essas credenciais serão usadas para gerarem um token de acesso. Este por sua vez, poderá ou não ter uma vida útil finita definida pelo desenvolvedor.

O token de acesso poderá ser gerado de duas formas: via webservice ou via Painel.

Via Painel será possível criar um novo token no menu gerenciador da API.

Nesse menu o desenvolvedor dará permissões de acesso aos recursos criando um token, assim como poderá definir se o token gerado de autorização de acesso irá expirar ou não.

No exemplo acima um token de acesso persistente, ou seja, que nunca expirará foi criado manualmente.

É recomendado que seja usado a configuração de expiração do token. Essa configuração além de manter as melhores práticas implementadas no Oauth 2.0, dará muito mais segurança a interação do aplicativo do desenvolvedor com a API de TV, recarga e gift card.

Fazendo login no painel e acessando o gerenciador da API será possível escolher qual dos dois modelos de expiração será usado.

Caso as credenciais sejam válidas e não estejam expiradas o servidor metallisson dará acesso ao recurso solicitado.

É possível fazer todo o gerenciamento do token via webservice. Os próximos tópicos descreverão os processos.

Oauth 2.0

Usando Oauth 2.0 a autenticação na API se dará em um processo mais seguro. Isso ocorre, entre muitos outros motivos, devido a volatidade do token e permissões de acesso que esse padrão documenta.

Através do protocolo Oauth 2.0 o desenvolvedor também poderá usufruir de todos os recursos permitidos ao usuário.

Uma autenticação feita com sucesso resulta em um access_token com autorização de manipulação de todas as funcionalidades permitidas.

Um access_token é um hash que tem vida útil finita. Por padrão todo access_token é desativado em 24h após sua criação, devendo assim o desenvolvedor criar uma rotina de atualização do access_token uma vez ao dia.

Para gerar um access_token, o desenvolvedor deverá primeiro autenticar seu aplicativo no padrão básico.

A partir da resposta de sucesso 200 e de posse do novo access_token, toda e qualquer manipulação de dados nos recursos deverão ter em seu header o Authorization: Bearer access_token.

Gerando um token de acesso

A requisição de geração do access_token deverá ser autenticada usando o modelo básico. O desenvolvedor deverá enviar no header da solicitação uma string contendo a codificação em base 64  da chave de api e sua assinatura na seguinte formatação:

Authorization: Basic {credenciais em base64 no formato chave_de_api:assinatura}

Observe o uso dos pontos entre a chave e a assinatura. Sem esse sinal de pontuação a API retornará erro.

Ex.: Para uma chave_de_api=ABCDE12345 e uma assinatura=QWER67890 o desenvolvedor deverá codificar a concatenação ABCDE12345:QWER67890 na base64, onde neste exemplo o resultado seria QUJDREUxMjM0NTpRV0VSNjc4OTA=

O header completo enviado em na solicitação de geração do token de acesso seria Authorization: Basic QUJDREUxMjM0NTpRV0VSNjc4OTA=

Um dos pontos principais de segurança do Oauth 2.0 é a volatidade dos token, entretanto há possibilidade de consumo do webservice com um “token fixo”. Na API 2.0 existe uma propriedade que inibe essa expiração. O persist.

Por padrão essa propriedade é setada como falso, todavia quando enviada como verdeiro, o sistema não expirará os tokens.

Obs.: Usando persist, as propriedades de retorno expires_in, refresh_token e refresh_token_expires_in vem com conteúdo vazio.

Requisição

POST https://auth.sandbox.metallisson.com/oauth/token

curl --location --request POST 'https://auth.sandbox.metallisson.com/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Basic YOUR_BASE_64_API_KEY_AND_SIGNATURE' \
--data-raw '{
	"grant_type": "client_credentials",
	"audience": "https://api.sandbox.metallisson.com"
}'

Resposta – 200

{
    "access_token": "A00190531012020LV98SDALOCQGFYPUKX07GJF12QY0WCYOCYJE1ESANDBOX",
    "scope": "order-topups read-topups-history order-gift-cards read-gift-cards-history read-providers-catalog order-credits read-credits-history read-credits-balance read-providers-check",
    "expires_in": 86400,
    "token_type": "Bearer",
    "refresh_token": "R00190531012020N07I0UQUXHXLOQK8TRN806R3I4KSF9WCIPM5XKSANDBOX",
    "refresh_token_expires_in": 172800,
    "return": 1
}

Atualizando um token de acesso

Assim como frisado anteriormente, sem o envio do persist como verdadeiro, o access_token em 24h expirará. Antes ou depois que isso ocorra o desenvolvedor deverá executar a rotina de atualização do token.

Monitorando o token

O desenvolvedor deverá implementar em seu aplicativo uma rotina de monitoração para verificar a vida útil do token de acesso.

Veja algumas sugestões de implantação logo a seguir.

Checando o return

Quando uma requisição a qualquer um dos recursos não for autorizada devido a expiração da validade do token, a API retornará o seguinte erro:

{
    "error": "AUTHENTICATION_FAILURE",
    "info": "Token or signature incorrect.",
    "return": 4
}

A rotina deverá checar a existência do código de erro 4 da propriedade return. Nesse caso, desde que se garanta que a chave de api e a assinatura estejam corretas, o erro indicará que o token deverá ser atualizado.

Por exemplo:

Na ação de solicitar a leitura do saldo o aplicativo recebe o código de erro 4.

Neste caso, uma ação de atualização de token deverá ser executada e logo depois com um novo token de acesso, deverá ser repetido a solicitação de leitura do saldo feita anteriormente.

Executando tarefas agendadas

O desenvolvedor também poderá adiantar-se a expiração do token agendando, no servidor do aplicativo, uma rotina de atualização. Desta forma não será preciso esperar o token de acesso expirar para poder troca-lo.

Após implementada a rotina de atualização deverá ser adicionado no crontab do servidor do aplicativo uma atividade de execução para rotina desenvolvida.

ATENÇÃO: Excessivas tentativas de atualização do token resultarão no bloqueio do refresh_token e a critério de análises de segurança interna, no bloqueio da chave de api. Durante o período de 24h um token poderá ser atualizado no máximo 4 vezes.

Observando expires_in

A propriedade expires_in  diz, em segundos, quanto tempo o novo token de acesso terá de vida útil.

Ao solicitar o token, o desenvolvedor poderá armazenar a hora do recebimento do JSON de sucesso com os dois tokens.

Implementando uma rotina de verificação, comparando essa hora com expires_in , o desenvolvedor poderá executar uma chamada de atualização no mínimo uma vez ao dia, sem perder a validade de um token.

Requisição

POST https://auth.sandbox.metallisson.com/oauth/token

curl --location --request POST 'https://auth.sandbox.metallisson.com/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Basic YOUR_BASE_64_API_KEY_AND_SIGNATURE' \
--data-raw '{
	"grant_type": "refresh_token",
	"refresh_token": "R02240707022020JZXRMGUQBZ6WXO0RJ3HJ55605QK7MGB7L15T6JSANDBOX"
}'

Resposta – 200

{
    "access_token": "A00190531012020LV98SDALOCQGFYPUKX07GJF12QY0WCYOCYNOVOSANDBOX",
    "scope": "request-order read-order-history read-catalog read-accounts-balance read-provider-check request-credits read-credits-history",
    "expires_in": 86400,
    "token_type": "Bearer",
    "refresh_token": "R00190531012020N07I0UQUXHXLOQK8TRN806R3I4KSF9WCIPNOVOSANDBOX",
    "refresh_token_expires_in": 172800,
    "return": 1
}

Revogando um token de acesso

Um access_token poderá por n motivos ser revogado, ou seja, perder sua validade. Para isso será necessário a exclusão do token da tabela temporária de permissão.

Caso uma nova tentativa de interação, em qualquer recurso, seja feita usando um token revogado, um erro UNAUTHORIZED com código de retorno 4 será retornado.

Requisição

DELETE https://auth.sandbox.metallisson.com/oauth/token/{access_token}

curl --location --request DELETE 'https://auth.sandbox.metallisson.com/oauth/token/A00190531012020LV98SDALOCQGFYPUKX07GJF12QY0WCYOCYJE1ESANDBOX' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Basic YOUR_BASE_64_API_KEY_AND_SIGNATURE' \
--data-raw ''

Resposta – 410

{
    "return": 1
}

Consultando o saldo

Esse recurso irá retornar qual o saldo atual da carteira virtual.

Os produtos e serviços consumidos pela API são consumidos do saldo da carteira virtual da metallisson.

Produtos e serviços que requerem pedidos de compra são descontados do saldo em carteira.

Obs.: A metallisson oferece desconto em produtos e serviços conforme a política de compra. Verifique as informações de desconto no painel.

Requisição

GET https://api.sandbox.metallisson.com/credits/balance

curl --location --request GET 'https://api.sandbox.metallisson.com/credits/balance' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Resposta – 200

{
    "amount": 132.8,
    "currency": "BRL",
    "return": 1
}

Comprando créditos

A plataforma metallisson é pré-paga e necessita de saldo para poder realizar compras dos produtos e serviços digitais.

Para inserir saldo usando a API existem 4 métodos de pagamento disponíveis:

1. Depósito bancário
2. Transferência bancária
3. Boleto bancário
4. Criptomoedas

Depósito bancário

Para adicionar saldo usando o depósito bancário o titular da conta deverá realizar um depósito no Banco do Brasil na conta bancária informada no menu carteira no painel.

Veja que no comprovante de depósito do Banco do Brasil existe o NR. DOCUMENTO ou NR. ENVELOPE. Este é o número do comprovante que o aplicativo deverá enviar via receipt para identificar o depósito bancário .

Além disso deverá ser enviado o valor depositado, amount, conforme comprovante.

Obs.: Depósitos terão até  2 dias para serem identificados. Após esse período não serão mais aceitos comprovantes de depósitos e os comprovantes não compensados serão cancelados.

Requisição

POST https://api.sandbox.metallisson.com/credits

curl --location --request POST 'https://api.sandbox.metallisson.com/credits' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"amount":560.50,
	"payment_method":"DEPOSIT",
	"receipt":"012345678901234",
	"bank":"001"
}'

Resposta – 201

{
    "id": 2140,
    "amount": 560.5,
    "status": "AQ",
    "bank": "001",
    "price": 560.5,
    "receipt": "012345678901234",
    "payment_method": "DEPOSIT",
    "date_time": "2020-02-08 20:26:46",
    "currency": "BRL",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/credits/2140"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/credits/2140"
        }
    ],
    "return": 1
}

Transferência bancária

Para adicionar saldo usando a transferência bancária, o titular do perfil na metallisson deverá realizar uma transferência de seu banco para a conta bancária listada no menu carteira no painel.

Nessa modalidade os dados do banco do remetente deverão ser anexados na solicitação de inserção de saldo.

Além disso deverá ser enviado o valor transferido, amount, conforme comprovante.

Obs.: Transferências terão até  2 dias para serem identificadas. Após esse período não serão mais aceitos comprovantes de transferências.

POST https://api.sandbox.metallisson.com/credits

curl --location --request POST 'https://api.sandbox.metallisson.com/credits' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"amount":560.6,
	"payment_method":"TRANSFER",
	"bank":"001",
	"sender_account":{
    		"bank":"001",
    		"account_holder": "COMPRA AE ATIVIDADES DE INTERNET LTDA",
    		"account_type":"CC",
    		"branch_number":"12345",
    		"account_number":"123456789",
    		"identity":"26696425000170"
     	}
}'

Resposta – 201

{
    "id": 2144,
    "amount": 506.6,
    "status": "AQ",
    "bank": "001",
    "price": 506.6,
    "sender_account": {
        "bank": "001",
        "account_holder": "COMPRA AE ATIVIDADES DE INTERNET LTDA",
        "account_type": "CC",
        "branch_number": "12345",
        "account_number": "123456789",
        "identity": "26696425000170"
    },
    "payment_method": "TRANSFER",
    "date_time": "2020-02-10 23:50:27",
    "currency": "BRL",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/credits/2144"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/credits/2144"
        }
    ],
    "return": 1
}

Boleto bancário

Para adicionar saldo usando o boleto bancário será necessário um POST para o recurso /credits com a propriedade payment_method e amount.

Obs.:  Só são permitidos, no máximo, 2 boletos em aberto. Caso esse número seja atingido a API bloqueará novas solicitações.

Requisição

POST https://api.sandbox.metallisson.com/credits

curl --location --request POST 'https://api.sandbox.metallisson.com/credits' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"amount":200,
	"payment_method":"BILL"	
}'

Resposta – 201

{
    "id": 2077,
    "amount": 200,
    "status": "AQ",
    "price": 201.96,
    "bill": {
        "number": "29788999999999999",
        "digitable_line": "00190000090297889000800000101170581499999999999",
        "url": "https://pay.sandbox.metallisson.com/bill/506MWIOP8TYB6BZ8RZZP8BMXO9YNBKCTESTE",
        "expiration_date": "2020-01-29"
    },
    "payment_method": "BILL",
    "date_time": "2020-01-19 16:13:53",
    "payment_date": "",
    "currency": "BRL",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/credits/2077"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/credits/2077"
        }
    ],
    "return": 1
}

Criptomoeda

Para adicionar saldo usando a criptomoeda  BTC – BitCoin será necessário um POST para o recurso /credits com a propriedade payment_method, amounte cryptocurrency.

Obs.:  Só são permitidos no máximo 2 pedidos em aberto. Caso esse número seja atingido a API bloqueará novas solicitações.

Requisição

POST https://api.sandbox.metallisson.com/credits

curl --location --request POST 'https://api.sandbox.metallisson.com/credits' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"amount":1600,
	"payment_method":"CRYPTO",
	"cryptocurrency":"BTC"
}'

Resposta – 201

{
    "id": 2077,
    "amount": 200,
    "status": "AQ",
    "price": 202,
    "crypto": {
        "cryptocurrency": "BTC",
        "amount_crypto": 0.035,
        "wallet_address": "ajshdgc5wD2jsSsvfif8eHrvd6UfTteste",
        "qrcode_url": "https://cdn.example.com/81ed76bb-bd72-49d5-b5a0-ee0f332a050c.png"
    },
    "payment_method": "CRYPTO",
    "date_time": "2020-01-19 16:13:53",
    "payment_date": "",
    "currency": "BRL",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/credits/2077"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/credits/2077"
        }
    ],
    "return": 1
}

Cancelando uma compra de crédito

Para cancelar uma compra de crédito o desenvolvedor deverá implementar uma chamada PATCH para o recurso /credits/{id} com a propriedade status.

Caso o pagamento já esteja cancelado ou quitado a API reponderá com um return=52.

No exemplo será cancelado uma compra por meio do boleto. Neste caso, a API retornará um JSON compatível com o método de pagamento do id.

É importante a verificação do meio de compra, pois o retorno terá o mesmo formato.

Requisição

PATCH https://api.sandbox.metallisson.com/credits/{id}

curl --location --request PATCH 'https://api.sandbox.metallisson.com/credits/{id}' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"status":"CA"	
}'

Resposta – 200

{
    "id": 2077,
    "amount": 200,
    "status": "CA",
    "price": 201.96,
    "bill": {
        "number": "29788999999999999",
        "digitable_line": "00190000090297889000800000101170581499999999999",
        "url": "https://pay.sandbox.metallisson.com/bill/506MWIOP8TYB6BZ8RZZP8BMXO9YNBKCTESTE",
        "expiration_date": "2020-01-29"
    },
    "payment_method": "BILL",
    "date_time": "2020-01-19 16:13:53",
    "payment_date": "",
    "currency": "BRL",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/credits/2077"
        }
    ],
    "return": 1
}

Consultando compras de crédito

Após gerar um pedido de crédito o desenvolvedor poderá consulta-lo através do verbo GET.

Para acessar os dados de um único pedido de compra, por exemplo, com id = 10, basta apenas consultar /credits/10. Executando um GET no recurso /credits, sem a presença de um id, todos os pedidos serão listados. Neste caso os parâmetros de filtro serão opcionais.

Obs.: O padrão JSON muda de acordo com a modalidade de pagamento.

Requisição

GET https://api.sandbox.metallisson.com/credits/{id}

curl --location --request GET 'https://api.sandbox.metallisson.com/credits' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Resposta – 200

{
   "content":[
      {
         "id":2144,
         "amount":333.6,
         "status":"AQ",
         "bank":"001",
         "price":333.6,
         "sender_account":{
            "bank":"001",
            "account_holder":"COMPRA AE ATIVIDADES DE INTERNET LTDA",
            "account_type":"CC",
            "branch_number":"12345",
            "account_number":"123456789",
            "identity":"26696425000170"
         },
         "payment_method":"TRANSFER",
         "date_time":"2020-02-10 23:50:27",
         "payment_date":"",
         "currency":"BRL",
         "links":[
            {
               "method":"GET",
               "rel":"self",
               "href":"https://api.sandbox.metallisson.com/credits/2144"
            },
            {
               "method":"PATCH",
               "rel":"confirm/cancel",
               "href":"https://api.sandbox.metallisson.com/credits/2144"
            }
         ]
      },
      {
         "id":2142,
         "amount":100,
         "status":"OK",
         "bank":"001",
         "price":100,
         "receipt":"0987654321",
         "payment_method":"DEPOSIT",
         "date_time":"2020-02-10 19:48:25",
         "payment_date":"2020-02-11",
         "currency":"BRL",
         "links":[
            {
               "method":"GET",
               "rel":"self",
               "href":"https://api.sandbox.metallisson.com/credits/2142"
            }
         ]
      },
      {
         "id":2077,
         "amount":4.4,
         "status":"AQ",
         "price":6.36,
         "bill":{
            "number":"297889999999999999",
            "digitable_line":"00190000090297889000800000101170599999999999999",
            "url":"https://pay.metallisson.com/bill/506MWIOP8TYB6BZ8RZZP8BMXO9YNBKCTESTE",
            "expiration_date":"2020-01-29"
         },
         "payment_method":"BILL",
         "date_time":"2020-01-19 16:13:53",
         "payment_date":"",
         "currency":"BRL",
         "links":[
            {
               "method":"GET",
               "rel":"self",
               "href":"https://api.sandbox.metallisson.com/credits/2077"
            },
            {
               "method":"PATCH",
               "rel":"confirm/cancel",
               "href":"https://api.sandbox.metallisson.com/credits/2077"
            }
         ]
      },
      {
         "id":2077,
         "amount":200,
         "status":"AQ",
         "price":1640,
         "crypto":{
            "cryptocurrency":"BTC",
            "amount_crypto":0.035,
            "wallet_address":"ajshdgc5wD2jsSsvfif8eHrvd6UfTteste",
            "qrcode_url":"https://cdn.example.com/81ed76bb-bd72-49d5-b5a0-ee0f332a050c.png"
         },
         "payment_method":"CRYPTO",
         "date_time":"2020-01-19 16:13:53",
         "payment_date":"",
         "currency":"BRL",
         "links":[
            {
               "method":"GET",
               "rel":"self",
               "href":"https://api.sandbox.metallisson.com/credits/2077"
            },
            {
               "method":"PATCH",
               "rel":"confirm/cancel",
               "href":"https://api.sandbox.metallisson.com/credits/2077"
            }
         ]
      }
   ],
   "pagination":{
      "page":1,
      "size":30,
      "total_pages":5
   },
   "return":1
}

Catálogo de produtos

O recurso “catalogs” lista todo o catálogo de produtos e serviços disponíveis no momento da consulta.

Um produto só será listado se o fornecedor informar estoque. Entretanto, por motivos diversos, um produto ou serviço poderá permanecer no catálogo sem estoque, nesse caso, assim que identificado, a própria interface irá desabilitar o produto, excluindo-o da lista, até que o estoque seja restabelecido.

Para poder fazer qualquer solicitação de recarga ou pedido de gift card é necessário uma consulta prévia a este recurso.

Obs1.: O catálogo deve ser lido no mínimo uma vez ao dia para que sejam atualizadas as tabelas de produtos do aplicativo desenvolvido. Recomendamos após às 2h.

Obs2.: O sistema poderá desativar qualquer produto caso identifique algum problema.

Obs3.: Novos produtos preferencialmente podem ser adicionados no período da noite.

Requisição

GET https://api.sandbox.metallisson.com/catalogs

curl --location --request GET 'https://api.sandbox.metallisson.com/catalogs' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Resposta – 200

{
    "content": [        
        {
            "provider": "OI",
            "provider_name": "OI S/A",
            "logo": "https://cdn.example.com/OI.jpg",
            "info": "",
            "category": "TELEPHONY",
            "country_code": "BR",
            "products": [
                {
                    "title": "OI R$100",
                    "sku": "OI_100",
                    "amount": 100,
                    "price": 98,
                    "min_amount": 100,
                    "max_amount": 100,
                    "step": 0.01,
                    "expiration": 90,
                    "info": "",
                    "subcategory": "TOP-UP",
                    "section": "CELL_PHONES",
                    "type": "REAL_TIME",
                    "area_code": [
                        11,12,13,94,95,96,97,98,99
                    ]
                },
                {
                    "title": "OI R$95",
                    "sku": "OI_95",
                    "amount": 95,
                    "price": 93.1,
                    "min_amount": 95,
                    "max_amount": 95,
                    "step": 0.01,
                    "expiration": 90,
                    "info": "",
                    "subcategory": "TOP-UP",
                    "section": "CELL_PHONES",
                    "type": "REAL_TIME",
                    "area_code": [                        
                        11,12,13,84,85,94,95,96,97,98,99
                    ]
                }
            ]
        },                        
        {
            "provider": "NETFLIX",
            "provider_name": "NETFLIX INC",
            "logo": "https://cdn.example.com/NETFLIX.jpg",
            "info": "",
            "category": "GIFT_CARD",
            "country_code": "BR",
            "products": [
                {
                    "title": "NETFLIX R$ 70,00",
                    "sku": "NETFLIX_70",
                    "amount": 70,
                    "price": 69.3,
                    "min_amount": 70,
                    "max_amount": 70,
                    "step": 0,
                    "expiration": 0,
                    "info": "",
                    "subcategory": "CASH",
                    "section": "STREAMING",
                    "type": "PIN_CODE",
                    "area_code": []
                },
                {
                    "title": "NETFLIX R$ 50,00",
                    "sku": "NETFLIX_50",
                    "amount": 50,
                    "price": 49.5,
                    "min_amount": 50,
                    "max_amount": 50,
                    "step": 0,
                    "expiration": 0,
                    "info": "",
                    "subcategory": "CASH",
                    "section": "STREAMING",
                    "type": "PIN_CODE",
                    "area_code": []
                }
            ]
        }
    ],
    "return": 1
}

Pedidos

Através do recurso /orders o desenvolvedor poderá fazer um pedido de recarga.

Um pedido nada mais é que uma solicitação de autorização de compra junto ao fornecedor, que posteriormente deverá ser confirmada.

Uma autorização de recarga valida um identificador permitindo a transferência de saldo para a conta pré-paga do cliente junto à operadora.

Quando uma solicitação de compra é aprovada pelo fornecedor um nsu é retornado. Além disso, os dados da recarga junto com a propriedade status setada com o valor AC irão compor a resposta de sucesso.

O sku

A API gift card, recarga de celular e tv 2.0 vem com um conceito de pedidos de compras por intermédio de um sku. Um sku é um identificador de produto ou serviço na plataforma metallisson.com. Através desse identificador um pedido poderá ser solicitado.

O sku é formado pela concatenação do provider(nome do fornecedor) com o amount(face ou valor de recarga).

Exemplificando

Um sku da recarga de R$20 da OI tem a seguinte aparência: OI_20

Um sku da recarga de R$100 da CORREIOS CELULAR tem a seguinte aparência: CORREIOS_CELULAR_100

Um sku contém as duas informações básicas para qualquer recarga: O fornecedor e o valor da recarga.

Para solicitar um pedido de recarga basta apenas um POST para /orders com o sku e um identifier (número telefônico) no corpo do JSON.

Exemplo do POST de uma recarga de R$20 da OI:

{
	"sku":"OI_20",
	"identifier":"83988888888"
}

Caso o desenvolvedor não tenha informação da operadora do número telefônico, o sistema metallisson irá automaticamente checar qual a operadora do número, onde logo em seguida, solicitará a recarga para o fornecedor correto. Para isso, o sku deverá ser enviado sem o nome do fornecedor, apenas a face de recarga (o valor).

Exemplo do POST sem informar a operadora:

{
	"sku":"_20",
	"identifier":"83988888888"
}

Obs.: O serviço de identificação de operadora não é gratuito e tem um custo de R$0,009 por identificação.

Veja que o identifier não necessita do código do país 55, mas precisa do DDD do número.

Para prevenir erros nos pedidos de recargas o desenvolvedor deverá apenas liberar para o usuário final, a face disponível para o DDD do número. Assim, no processo de solicitação de recarga, o aplicativo deverá perguntar, primeiramente, o DDD do número ao usuário final.

Digamos que no DDD 11 a recarga de R$10 da VIVO esteja disponível, mas no DDD 88 a recarga de R$10 não esteja disponível. Um aplicativo deseja solicitar um pedido para o sku=”VIVO_10″ para o número VIVO identifier=”88999999999″.

Neste exemplo, caso o aplicativo solicite o pedido de recarga, a API retornará um erro com return=11.

Obs.: O sistema aguardará 30 minutos por uma confirmação de recarga. Caso um pedido não seja confirmado nesse período, será automaticamente cancelado. Recargas também podem expirar por falta de confirmação a critério do fornecedor. O recomendado é a confirmação imediata de uma recarga via PATCH, ou o envio do status=OK na solicitação via POST.

Simulando pedidos na API de gift card e recarga

No ambiente sandbox o desenvolvedor deverá usar as seguintes regras para simular recargas de celular com e sem sucesso:

Números com DDD e o prefixo listado abaixo serão de suas respectivas operadoras.

988 – OI
999 – TIM
993 – CLARO
996 – VIVO

Então por exemplo, o número 81993445762 será sempre da CLARO e o número 11988102396 será sempre OI.

O desenvolvedor poderá simular um erro enviando uma operadora diferente desta regra.

Um outro exemplo seria fazer uma recarga da TIM no número 14996612345. O prefixo 996 depois do DDD 14, pela regra de simulação do sandbox, é da VIVO.

Outra regra para simulação de erro é que qualquer número terminado em 0 retornará erro, mesmo que seja aceito com a regra de simulação de prefixo correta, ou seja, a recarga CLARO para o número 81993445760 retornará erro pois termina em zero.

Para erros de saldo basta apenas o desenvolvedor acessar o painel do sandbox e modificar o saldo em carteira.

Será possível também fazer aprovação e cancelamento de recargas, além de também realizar as mesmas ações com faturas.

A API de Gift Card, no sandbox, simulará pedidos de vale-presente com sucesso para: XBOX, PAYSAFECARD, GOOGLE PLAY, STEAM, UBER, NETFLIX, LEVEL UP, CLARO FIXO, LEAGUE OF LEGENDS e BLIZZARD.

Erros comuns à API de gift card, recarga de celular e TV

Existe um erro comum entre os três produtos. Veja alguns prováveis erros em tempo de execução usando o cada um dos produtos no webservice metallisson

API de recarga de celular

• Recarga solicitada para número de celular bloqueado por falta de crédito ou outro motivo
• Recarga solicitada para um número com a operadora divergente da do CHIP
• Recarga solicitada para números pós-pagos ou em planos controle
• Recarga solicitada para número inválido e/ou sem ddd
• Recarga solicitada para um valor de face que não existe no DDD
• Recarga solicitada para uma face ou faixa que não existe no fornecedor

API de TV pré-paga

• Recarga solicitada para um identificador bloqueado por falta de crédito ou outro motivo
• Recarga solicitada para número identificador de assinatura ou cpf inválido
• Recarga solicitada para uma face que não existe no fornecedor

API de gift card

• Recarga solicitada para uma face que não existe no fornecedor

Fazendo um pedido à API de recarga celular e fixo

Para fazer uma recarga de celular através da API o desenvolvedor deverá fazer um POST para o recurso /orders com o identificador e o sku.

Requisição

POST https://api.sandbox.metallisson.com/orders

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"sku":"TIM_10",
	"identifier":"83999999999"
}'

Resposta – 201

{
    "id": 14080,
    "title": "TIM R$10",
    "sku": "TIM_10",
    "identifier": "83999999999",
    "provider": "TIM",
    "amount": 10,
    "price": 9.8,
    "nsu": 804208,
    "pin": "",
    "serial": "",
    "info": "O Pré-Pago da TIM está muito mais simples, fácil e melhor para você. Agora sua recarga é transformada em benefícios. Ligações ilimitadas, SMSs, redes sociais e muito mais.",
    "category": "TELEPHONY",
    "type": "REAL_TIME",
    "external_id": "",
    "receipt": {},
    "status": "AC",
    "date_time": "2020-02-12 22:22:00",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14080"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/orders/14080"
        }
    ],
    "return": 1
}

Fazendo um pedido à API de Gift Card

Requisição

POST https://api.sandbox.metallisson.com/orders

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"sku":"NETFLIX_50"
}'

Resposta – 201

{
  "id": 11863,
  "title": "NETFLIX R$50",
  "sku": "NETFLIX_50",
  "identifier": "",
  "provider": "NETFLIX",
  "amount": 50,
  "price": 49.5,
  "nsu": 4056085041,
  "pin": "TESTE689851",
  "serial": "457810000000931200",
  "info": "Acesse netflix.com/redeem e resgate seu Gift Card.",
  "category": "GIFT_CARD",
  "type": "PIN_CODE",
  "external_id": "",
  "receipt": {},
  "status": "AC",
  "date_time": "2020-02-02 17:08:53",
  "country_code": "BR",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://api.sandbox.metallisson.com/orders/11863"
    },
    {
      "method": "PATCH",
      "rel": "confirm/cancel",
      "href": "https://api.sandbox.metallisson.com/orders/11863"
    }
  ],
  "return": 1
}

Fazendo um pedido à API de recarga de TV pré-paga

Requisição

POST https://api.sandbox.metallisson.com/orders

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"sku":"SKY_13.9",
	"identifier":"99999999999" 
}'

Resposta – 201

{
    "id": 14571,
    "title": "SKY SMART 3 DIAS R$13.90",
    "sku": "SKY_13.9",
    "identifier": "10783325410",
    "provider": "SKY",
    "amount": 13.9,
    "price": 13.76,
    "nsu": 5711,
    "pin": "",
    "serial": "",
    "info": "",
    "category": "TELEVISION",
    "type": "REAL_TIME",
    "external_id": "",
    "status": "AC",
    "receipt": {},
    "date_time": "2020-02-26 18:05:37",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14571"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/orders/14571"
        }
    ],
    "return": 1
}

Fazendo um pedido à API de recarga variável

Uma recarga variável é um produto não feceado, ou seja, não tem valor fixo para ser apresentado ao cliente final. Esse tipo de produto tem um valor mínimo e um valor máximo, onde no processo de compra o cliente final pode escolher qualquer valor na faixa apresentada.

Além da faixa, a propriedade step rege o valor de incremento ou decremento aceito pelo fornecedor.

A API de gift card e recarga 2.0 da metallisson, assim como já apresentado, aceita pedidos apenas pelo sku. A formação desta propriedade está na concatenação do provider mais um sublinhado e o amount.

Mantendo então este conceito, o aplicativo deverá preparar, com o valor digitado pelo cliente final, um sku obedecendo os saltos informados no step.

Com step=1 o aplicativo não poderá aceitar uma recarga de 12.5, assim como não poderá aceitar um valor menor que o valor mínimo ou maior que o valor máximo.

Requisição

POST https://api.sandbox.metallisson.com/orders

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"sku":"OI_FIXO_57",
	"identifier":"1133333333"
}'

Resposta – 201

{
    "id": 14578,
    "title": "OI FIXO",
    "sku": "OI_FIXO_57",
    "identifier": "10783325410",
    "provider": "OI_FIXO",
    "amount": 57,
    "price": 56.43,
    "nsu": 53111,
    "pin": "",
    "serial": "",
    "info": "",
    "category": "TELEPHONY",
    "type": "REAL_TIME",
    "external_id": "",
    "receipt": {},
    "status": "AC",
    "date_time": "2020-02-26 19:00:07",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14578"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/orders/14578"
        }
    ],
    "return": 1
}

Enviando um SMS com a API de Gift Card

Embora o título enfatize a API de Gift Card, um SMS pode ser enviado automaticamente para um número de celular com qualquer um dos produtos disponibilizados no webservise da metallisson.

Esse SMS poderá ser utilizado como comprovante de compra, entrega do Gift Card ou até mesmo uma mensagem de agradecimento ou parabenização. São inúmeros as possibilidades de uso desse campo.

Não use esse recurso como único meio de entrega de um PIN de Gift Card, por exemplo. Um SMS pode não chegar ao seu destinatário por vários fatores, tais como: fora de área, bloqueio pela operadora, bloqueio pelo próprio dono do CHIP, etc,

Atributos disponíveis para envio de SMS

Um SMS contendo qualquer informação poderá ser enviado na ação de confirmação de um pedido. A API reconhece variáveis, adicionando o valor representado pelo campo, quando identificar na mensagem um dos shortcodes abaixo.

• [ID] – Contém o id do pedido de compra
• [PROVIDER] – Contém o nome curto do fornecedor
• [AMOUNT] – Valor da recarga
• [PIN] – Contém o código do Gift Card
• [SERIAL] – Contém o número ou serial do Gift Card
• [NSU] – Contém o número NSU da recarga
• [EXTERNAL_ID] – Contém o id da compra do sistema do desenvolvedor

Por exemplo, em uma confirmação de recarga de R$35 da NETFLIX que contenha a mensagem:

Obrigado. Segue seu Gift Card [PROVIDER] R$[AMOUNT]: [PIN]

Chegará um SMS para o cliente da seguinte forma:

Obrigado. Segue seu Gift Card NETFLIX R$35: TEST123435

Não use qualquer tipo de carácter especial, ç ou letras com acentros. Utilize apenas:

• Letras sem acentro A-Z ou a-z
• Números 0-9
• Pontuação e símbolos . , – _ $

Usando esses caracteres você poderá enviar uma mensagem contendo 160 caracteres e aumentará as chances de entrega.

O serviço de SMS tem um preço de R$0,08 por SMS solicitado.

Enviando um comprovante SMS

No exemplo abaixo uma recarga de R$50 da Netflix foi solicitada junto com um comprovante SMS para o número 83999999999.

Só é possível verificar um status de SMS na consulta de um pedido de recarga.

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
   "sku":"NETFLIX_50",
   "receipt":{
      "sms":{
         "number":"83999999999",
         "message":"Obrigado pelo pagamento do pedido [EXTERNAL_ID]. Segue os dados do Gift Card [PROVIDER] R$[AMOUNT]: PIN [PIN] e Serial [SERIAL]."
      }
   }
}'

Resposta – 200

{
    "id": 1000,
    "title": "NETFLIX R$35",
    "sku": "NETFLIX_35",
    "identifier": "",
    "provider": "NETFLIX",
    "amount": 35,
    "price": 34.65,
    "nsu": 2378335330,
    "pin": "",
    "serial": "",
    "info": "",
    "category": "GIFT_CARD",
    "type": "PIN_CODE",
    "external_id": "",
    "receipt": {
        "sms": {
            "id": 30,
            "number": "83999999999",
            "message": "Obrigado pelo pagamento do pedido [EXTERNAL_ID]. Segue os dados do Gift Card [PROVIDER] R$[AMOUNT]: PIN [PIN] e Serial [SERIAL].",
            "amount": 0,
            "price": 0,
            "status": ""
        }
    },
    "status": "AC",
    "date_time": "2020-07-05 23:23:27",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/1000"
        },
        {
            "method": "PATCH",
            "rel": "confirm/cancel",
            "href": "https://api.sandbox.metallisson.com/orders/1000"
        }
    ],
    "return": 1
}

Confirmando ou cancelando um pedido gift card ou recarga

Existem duas formas para fazer uma confirmação de recarga: Solicitando a confirmação ou configurando a API para confirmar automaticamente.

Obs.: Todo pedido de recarga só poderá ser confirmado ou cancelado somente se seu status for AC.

Solicitando uma confirmação

Para confirmar um pedido de recarga o desenvolvedor deverá implementar uma chamada PATCH para o recurso /orders/{id} com a propriedade status.

O processo de confirmação se dará através da propriedade status enviada no corpo da solicitação com o valor OK.

Após ser enviado o pedido de confirmação, o recurso retornará o status também com OK e return setado como 1, confirmando assim a ação com sucesso.

Obs.: Caso o status da resposta não seja o mesmo da solicitação, houve falha na operação.

Requisição

PATCH https://api.sandbox.metallisson.com/orders/{id}

curl --location --request PATCH 'https://api.sandbox.metallisson.com/orders/{id}' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"status":"OK"	
}'

Resposta – 200

{
    "id": 14080,
    "title": "TIM R$10",
    "sku": "TIM_10",
    "identifier": "83999999999",
    "provider": "TIM",
    "amount": 10,
    "price": 9.8,
    "nsu": 804208,
    "pin": "",
    "serial": "",
    "info": "O Pré-Pago da TIM está muito mais simples, fácil e melhor para você. Agora sua recarga é transformada em benefícios. Ligações ilimitadas, SMSs, redes sociais e muito mais.",
    "category": "TELEPHONY",
    "type": "REAL_TIME",
    "external_id": "",
    "receipt": {},
    "status": "OK",
    "date_time": "2020-02-12 22:22:00",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14080"
        }
    ],
    "return": 1
}

Solicitando um cancelamento

Para cancelar um pedido de recarga o desenvolvedor deverá implementar uma chamada PATCH para o recurso /orders/{id} com a propriedade status.

O processo de confirmação se dará através da propriedade status enviada no corpo da solicitação com o valor CA.

Após ser enviado o pedido de cancelamento, o recurso retornará o status também com CA e return setado como 1, confirmando assim a ação com sucesso.

Obs.: Caso o status da resposta não seja o mesmo da solicitação, houve falha na operação.

Requisição

PATCH https://api.sandbox.metallisson.com/orders/{id}

curl --location --request PATCH 'https://api.sandbox.metallisson.com/orders/{id}' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"status":"CA"	
}'

Resposta – 200

{
    "id": 14080,
    "title": "TIM R$10",
    "sku": "TIM_10",
    "identifier": "83999999999",
    "provider": "TIM",
    "amount": 10,
    "price": 9.8,
    "nsu": 804208,
    "pin": "",
    "serial": "",
    "info": "O Pré-Pago da TIM está muito mais simples, fácil e melhor para você. Agora sua recarga é transformada em benefícios. Ligações ilimitadas, SMSs, redes sociais e muito mais.",
    "category": "TELEPHONY",
    "type": "REAL_TIME",
    "external_id": "",
    "receipt": {},
    "status": "CA",
    "date_time": "2020-02-12 22:22:00",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14080"
        }
    ],
    "return": 1
}

Confirmação automática

A API 2.0 disponibiliza uma propriedade de confirmação automática da recarga, o status enviado com OK.

Em um processo de compra ideal, a ação de confirmação de um pedido de compra deve ser realizada pelo cliente, mas caso o desenvolvedor queira deixar essa fase transparente para seu aplicativo, a metallisson poderá solicitar a confirmação.

A confirmação automática nada mais do que uma solicitação de recarga já definindo seu status.

O desenvolvedor deve observar que solicitando alguma compra com esse parâmetro e caso haja alguma problema com o identificador, o erro ocorrerá na fase de entrega do produto (confirmação) e não na de autorização. 

e mais

O desenvolvedor, caso queria prevenir recargas repetidas, deverá criar rotinas que evitem solicitação de recargas duplicadas, visto que, por algum possível problema no script do aplicativo ou mesmo ação do cliente final, recargas repetidas podem ser solicitadas e não poderão ser mais canceladas.

Exemplo do POST de uma recarga de R$10 da TIM com confirmação automática:

Requisição

POST https://api.sandbox.metallisson.com/orders

curl --location --request POST 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw '{
	"sku":"TIM_10",
	"identifier":"83999999999",
	"status":"OK"
}'

Resposta – 200

{
    "id": 14080,
    "title": "TIM R$10",
    "sku": "TIM_10",
    "identifier": "83999999999",
    "provider": "TIM",
    "amount": 10,
    "price": 9.8,
    "nsu": 804208,
    "pin": "",
    "serial": "",
    "info": "O Pré-Pago da TIM está muito mais simples, fácil e melhor para você. Agora sua recarga é transformada em benefícios. Ligações ilimitadas, SMSs, redes sociais e muito mais.",
    "category": "TELEPHONY",
    "type": "REAL_TIME",
    "external_id": "",
    "receipt": {},
    "status": "OK",
    "date_time": "2020-02-12 22:22:00",
    "country_code": "BR",
    "links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://api.sandbox.metallisson.com/orders/14080"
        }
    ],
    "return": 1
}

Consultando pedidos

Após realizar umas das três operações básicas (solicitação, confirmação ou cancelamento), o desenvolvedor poderá consultar dados do pedido usando o verbo GET no recurso /orders .

Lendo o recurso sem o id do pedido, o desenvolvedor terá acesso ao relatório completo de compras, todavia caso utilize-o, estará lendo apenas um único pedido.

O padrão JSON não muda de acordo com ao tipo do produto.

Requisição

GET https://api.sandbox.metallisson.com/orders/{id}

curl --location --request GET 'https://api.sandbox.metallisson.com/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Resposta – 200

{
  "content": [
    {
      "id": 11863,
      "title": "NETFLIX R$50",
      "sku": "NETFLIX_50",
      "identifier": "",
      "provider": "NETFLIX",
      "amount": 50,
      "price": 49.5,
      "nsu": 4056085041,
      "pin": "TESTE689851",
      "serial": "457810000000931200",
      "info": "Acesse netflix.com/redeem e resgate seu Gift Card.",
      "category": "GIFT_CARD",
      "type": "PIN_CODE",
      "external_id": "",
      "receipt": {},
      "status": "OK",
      "date_time": "2020-02-02 17:08:53",
      "country_code": "BR",
      "links": [
        {
          "method": "GET",
          "rel": "self",
          "href": "https://api.sandbox.metallisson.com/orders/11863"
        }
      ]
    },
    {
      "id": 14080,
      "title": "TIM R$10",
      "sku": "TIM_10",
      "identifier": "83999999999",
      "provider": "TIM",
      "amount": 10,
      "price": 9.8,
      "nsu": 804208,
      "pin": "",
      "serial": "",
      "info": "O Pré-Pago da TIM está muito mais simples, fácil e melhor para você. Agora sua recarga é transformada em benefícios. Ligações ilimitadas, SMSs, redes sociais e muito mais.",
      "category": "TELEPHONY",
      "type": "REAL_TIME",
      "external_id": "",
      "receipt": {},
      "status": "OK",
      "date_time": "2020-02-12 22:22:00",
      "country_code": "BR",
      "links": [
        {
          "method": "GET",
          "rel": "self",
          "href": "https://api.sandbox.metallisson.com/orders/14080"
        }
      ]
    },
    {
      "id": 14571,
      "title": "SKY SMART 3 DIAS R$13.90",
      "sku": "SKY_13.9",
      "identifier": "10783325410",
      "provider": "SKY",
      "amount": 13.9,
      "price": 13.76,
      "nsu": 5711,
      "pin": "",
      "serial": "",
      "info": "",
      "category": "TELEVISION",
      "type": "REAL_TIME",
      "external_id": "",
      "receipt": {},
      "status": "AC",
      "date_time": "2020-02-26 18:05:37",
      "country_code": "BR",
      "links": [
        {
          "method": "GET",
          "rel": "self",
          "href": "https://api.sandbox.metallisson.com/orders/14571"
        },
        {
          "method": "PATCH",
          "rel": "confirm/cancel",
          "href": "https://api.sandbox.metallisson.com/orders/14571"
        }
      ]
    }
  ],
  "pagination": {
    "page": 2,
    "size": 1,
    "total_pages": 2
  },
  "return": 1
}

API para consulta de operadoras de chip celular

Usando a API de consulta de operadora de celular um sistema poderá automaticamente identificar qual a operadora de um número móvel.

Para consultar a operadora de celular através da API, identificando assim o nome do fornecedor do chip, basta enviar uma solicitação de leitura com o verbo GET ao recurso /providers/check/{identifier}.

O parâmetro identifier será o número do celular com ddd.

O serviço de identificação de operadora tem um preço de R$0,009 a consulta.

Requisição

GET https://api.sandbox.metallisson.com/providers/check/{identifier}

curl --location --request GET 'https://api.sandbox.metallisson.com/providers/check/83999999999' \
--header 'Content-Type: application/json' \
--header 'Accept: com.metallisson.api-v2+json' \
--header 'Authorization: Bearer YOUR_HASH_ACCESS_TOKEN' \
--data-raw ''

Resposta – 200

{
    "identifier": "83999999999",
    "provider": "TIM",
    "ported": false,
    "return": 1
}

Anexos

Categorias de produtos

Subcategorias de produtos

Seções de produtos

Tipos de produtos

Status de pagamentos

Status de pedidos de compras

Status de SMS

Códigos de retorno

Códigos de erros