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

api de recarga e gift card metallisson
Fluxo de pedidos

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:

ComponenteDescrição
Os verbos HTTP
  • GET – Requisita leitura de informações
  • POST – Envia dados para instruções de submissão
  • PATCH – Atualiza parcialmente um dado de um recurso
  • DELETE – Apaga algum dado no recurso
Os URIsAutenticação: https://auth.metallisson.com https://auth.sandbox.metallisson.com

Consumo: https://api.metallisson.com https://api.sandbox.metallisson.com
Os recursos
  • /oauth/token
  • /credits/balance
  • /credits
  • /orders
  • /providers/check
Os parâmetros de buscaUsando o verbo GET é possível incluir filtros para melhorar a busca. Ex.: /orders? page=2
O cabeçalho das requisiçõesEm todas as requisições a API determina o envio da versão da API e o tipo de conteúdo application/json

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 ''
CabeçalhoDescrição
Content-TypeDeverá ser enviado como: Content-Type: application/json
AcceptDeverá ser enviado como: Accept: com.metallisson.api-v2+json
AuthorizationNa manipulação dos tokens de acesso e atualização:
Authorization: Basic YOUR_BASE_64_API_KEY_AND_SIGNATURE

Na interação com os recursos:


Authorization: Bearer YOUR_HASH_ACCESS_TOKEN

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 ''
ParâmetroTipoDescrição
pageintegerDiz qual a página solicitada
sizeintegerDiz qual o a quantidade de itens de uma página
sortstringOrdena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo
start_datedateDiz a data delimitadora mais antiga no padrão YYYY-mm-dd
end_datedateDiz a data delimitadora mais recente no padrão YYYY-mm-dd

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
}
StatusDescrição
200OK – A solicitação foi requisitada com sucesso.
201Criado – Essa resposta é retornada quando a solicitação for de criação ao recurso. Por exemplo: Usando o POST no recurso /credits o servidor retornará este status ao ser inserido um comprovante de depósito.
202Aceito – Essa resposta diz que a solicitação foi bem estruturada, mas por alguma regra não entregou o resultado esperado.  

Por exemplo: Usando o PATCH no recurso /orders/{id}, para confirmar um pedido de recarga, o servidor retornará este status ao verificar que o status da compra não está como “aguardando confirmação”.

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
}
PropriedadeDescrição
errorRepresenta o código de erro
infoDescreve o erro
returnRepresenta a descrição de erro, seu motivo ou resposta de sucesso.

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.

gerenciador da api de recarga de celular gift card e tv metallisson
Gerenciador da API metallisson

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"
}'
PropriedadeTipoValorObrigatório
grant_typestringclient_credentialsSim
audiencestringhttps://api.sandbox.metallisson.comSim
persistbooleantrue ou falseNão

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
}
ParâmetroTipoTamanhoDescrição
access_tokenstring60Token que deverá ser enviado em todas as solicitações
scopestringDiz quais as permissões do token
expires_inintegerDiz o tempo em segundos para o token expirar
refresh_tokenstring60Esse é o token de atualização do access_token
refresh_token_expires_inintegerDiz o tempo em segundos para o token de atualização expirar
returnintegerÉ o código de retorno da operação

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"
}'
PropriedadeTipoValorObrigatório
grant_typestringrefresh_tokenSim
refresh_tokenstringO token de atualização da última autenticaçãoSim

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
}
ParâmetroTipoTamanhoDescrição
access_tokenstring60Token que deverá ser enviado em todas as solicitações
scopestringDiz quais as permissões do token
expires_inintegerDiz o tempo em segundos para o token expirar
refresh_tokenstring60Esse é o token de atualização do access_token
refresh_token_expires_inintegerDiz o tempo em segundos para o token de atualização expirar
returnintegerÉ o código de retorno da operação

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
}
PropriedadeTipoTamanhoDescrição
returnintegerÉ o código de retorno da operação

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
}
PropriedadeTipoTamanhoDescrição
amountdoubleSaldo de crédito virtual
currencystringMoeda do saldo
returnintegerÉ o código de retorno da operação

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"
}'
PropriedadeTipoValorObrigatórioDescrição
amountdoubleSimValor depositado
payment_methodstringDEPOSITSimÉ o identificador do método de pagamento
receiptstringSimÉ o número do comprovante de depósito NR. DOCUMENTO  ou NR. ENVELOPE
bankstring001SimÉ o código do banco conforme Febraban
currencystringBRLNãoÉ o código da moeda

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
}
PropriedadeTipoTamanhoDescrição
iddoubleId do pagamento
amountstringValor do pagamento
statusstring2Status do pagamento
bankstring5Código do banco
pricedoublePreço de compra do crédito
receiptstring30Este é o número do comprovante de depósito NR. DOCUMENTO ou NR. ENVELOPE.
payment_methodstring20É o identificador do método de pagamento
date_timedatetimeData e hora do envio do comprovante no padrão YYYY-mm-dd H:i:s
currencystring2Moeda
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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"
     	}
}'
PropriedadeTipoValorObrigatórioDescrição
amountdoubleSimValor depositado
payment_methodstringTRANSFERSimÉ o identificador do método de pagamento
bankstring001SimÉ o código do banco conforme Febraban
sender_accountobjectSimContém os dados do banco do remetente do comprovante
sender_account.bankstringSimÉ o código do banco do remetente conforme Febraban
sender_account.account_holderstringSimÉ o nome do titular da conta bancária remetente
sender_account.account_typestringSimÉ o tipo da conta bancária remetente. CC para conta corrente e CP para conta poupança
sender_account.branch_numberstringSimÉ a agencia  da conta bancária remetente
sender_account.account_numberstringSimÉ o número da conta bancária remetente
sender_account.identystringSimÉ o CPF ou CNPJ, com apenas números, do titular  da conta bancária remetente
currencystringBRLNãoÉ o código da moeda

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
}
PropriedadeTipoTamanhoDescrição
idintegerId do pagamento
amountdoubleValor do pagamento
statusstring2Status do pagamento
bankstringCódigo do banco
pricedoublePreço de compra do crédito
sender_accountobjectContém os dados do banco do remetente do comprovante
sender_account.bankstring5É o código do banco do remetente conforme Febraban
sender_account.account_holderstring100É o nome do titular da conta bancária remetente
sender_account.account_typestring2É o tipo da conta bancária remetente. CC para conta corrente e CP para conta poupança
sender_account.branch_numberstring20É a agencia  da conta bancária remetente
sender_account.account_numberstring20É o número da conta bancária remetente
sender_account.identystring14É o CPF ou CNPJ, com apenas números, do titular  da conta bancária remetente
payment_methodstring20É o identificador do método de pagamento
date_timedatetimeData e hora do envio do comprovante no padrão YYYY-mm-dd H:i:s
currencystring2Moeda
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

Boleto bancário

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

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"	
}'
PropriedadeTidoValorObrigatórioDescrição
amountdoubleSimValor depositado
payment_methodstringBILLSimÉ o identificador do método de pagamento
currencystringBRLNãoÉ o código da moeda

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
}
PropriedadeTipoTamanhoDescrição
idintegerId do pagamento
amountdoubleValor do pagamento
statusstring2Status do pagamento
pricedoubleÉ o preço de compra do crédito
billobjectContém os dados do banco do remetente do comprovante
bill.numberstring30É o nosso número. Obs.: Não armazene como único. Serão usados diferentes bancos.
bill.digitable_linestring48É a linha digitável do boleto
bill.urlstring100É o link para acesso ao boleto. Obs.: O boleto pode vir em html ou pdf.
bill.expiration_datedateÉ a data de vencimento do boleto no formato YYYY-mm-dd
payment_methodstring20É o identificador do método de pagamento
date_timedatetimeData e hora da solicitação do boleto no padrão YYYY-mm-dd H:i:s
payment_datedateData da baixa do título no padrão YYYY-mm-dd
currencystring2Moeda
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

Criptomoeda

Para adicionar saldo usando a criptomoeda  BTC – BitCoin será necessário um POST para o recurso /credits com a propriedade payment_methodamounte 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"
}'
PropriedadeTipoValorObrigatórioDescrição
amountdoubleSimValor depositado
payment_methodstringCRYPTOSimÉ o identificador do método de pagamento
cryptocurrencystringBTCSimÉ a moeda digital. BTC para BitCoin
currencystringBRLNãoÉ o código da moeda

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
}
PropriedadeTipoTamanhoDescrição
idintegerId do pagamento
amountdoubleValor do pagamento
statusstring2Status do pagamento
pricedoubleÉ o preço de compra de crédito
cryptoobjectContém os dados para a transferência de criptomoedas
crypto.cryptocurrencystring3É a sigla da moeda: BTC
crypto.amount_cryptodoubleÉ o valor em criptomoeda para ser transferido
crypto.wallet_addressstring100É o endereço da carteira da criptomoeda
crypto.qrcode_urlstringÉ o link da imagem do QRCODE para pagamento
payment_methodstring20É o identificador do método de pagamento
date_timedatetimeData e hora da solicitação do pagamento no padrão YYYY-mm-dd
payment_datedateData da liquidação do pagamento no padrão YYYY-mm-dd
currencystring2Moeda
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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"	
}'
PropriedadeTipoValorObrigatórioDescrição
statusstringCASimInstrução de mudança de status para cancelado.

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
}
PropriedadeTipoTamanhoDescrição
idintegerId do pagamento
amountdoubleValor do pagamento
statusstring2Status do pagamento
pricedoublePreço de compra do crédito
billobjectContém os dados do banco do remetente do comprovante
bill.numberstring30É o nosso número. Obs.: Não armazene como único. Serão usados diferentes bancos.
bill.digitable_linestring48É a linha digitável do boleto
bill.urlstring100É o link para acesso ao boleto
bill.expiration_datedateÉ a data de vencimento do boleto
payment_methodstring20É o identificador do método de pagamento
date_timedatetimeData e hora da solicitação do boleto no padrão YYYY-mm-dd
payment_datedateData da baixa do título no padrão YYYY-mm-dd
currencystring2Moeda
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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 ''
ParâmetroTipoDescrição
pageintegerDiz qual a página solicitada
sizeintegerDiz qual o a quantidade de itens de uma página
sortstringOrdena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo
start_datedateDiz a data delimitadora mais antiga no padrão YYYY-mm-dd
end_datedateDiz a data delimitadora mais recente no padrão YYYY-mm-dd
payment_methodstringÉ a modalidade de pagamento. Sendo elas: TRANSFER, DEPOSIT, BILL e CRYPTO
statusstringÉ o status do pedido de compra. Consulte a tabela Status de pagamentos nos Anexos.

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
}
PropriedadeTipoTamanhoDescrição
contentarrayContém um conjunto de fornecedores
content.providerstring30É o código que representa um fornecedor
content.provider_namestring100É o nome da empresa fornecedora
content.logostringImagem da logo do fornecedor
content.infostring300Informações adicionais sobre o fornecedor
content.categorystring30Categoria de produtos do fornecedor
content.country_codestring2Código do país com dois caracteres (ISO Alpha-2)
content.productsarrayContém um conjunto de produtos do fornecedor
content.products.titlestring100Título do produto
content.products.skustring40Código do produto formado pela concatenação de provider_amount. Ex.: provider = SKY e amount = 13.9 resulta em um sku = SKY_13.9
content.products.amountdoubleValor da quantidade unitária de recarga, ou seja, a face.
content.products.pricedoublePreço do produto no momento da consulta
content.products.min_amountdoubleValor mínimo aceito em recargas sem faces fixas. Ex.: Se um produto tem min_amount = 10 não aceitará uma compra de recarga de face 5
content.products.max_amountdouble Valor máximo aceito em recargas sem faces fixas. Ex.: Se um produto tem max_amount = 10 não aceitará uma compra de recarga de face 11
content.products.stepdouble É o valor mínimo aceitável para incremento de uma face. Um produto com step = 3 não aceitará uma recarga de face 5.
content.products.expirationintegerQuando informado pelo fornecedor, representa o número de dias da validade de consumo do produto
content.products.infostringInformações adicionais sobre o produto
content.products.subcategorystring30Subcategoria do produto
content.products.sectionstring30Seção do produto
content.products.typestring20Identifica o tipo do produto
content.products.area_codearray[integer] Diz quais são os DDDs que o produto pode ser consumido
returnintegerÉ o código de retorno da operação

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"
}'
PropriedadeTipoValorObrigatórioDescrição
skustringSimÉ o código que representa o produto solicitado no pedido
identifierstringSimÉ o número telefônico
statusstringOKNãoCaso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor
external_idstringNãoId único do pedido no sistema do desenvolvedor
receiptobjectNãoÉ o comprovante que poderá ser enviado para o cliente final
receipt.smsobjectNãoÉ o comprovante enviado via SMS
receipt.sms.numberstringNãoCaso o receipt seja enviado, o number se torna obrigatório e contém o número móvel COM ddd que receberá o SMS
receipt.sms.messagestringNãoCaso o receipt seja enviado, message se torna obrigatório e contém a mensagem que será enviada no SMS

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
}
PropriedadeTipoTamanhoDescrição
idintegerId da compra
titlestring100Título do produto
skustring40É o código do produto
identifierstring30É o número telefônico, CPF ou identificador único
providerstring30É o fornecedor
amountdoubleÉ o valor da recarga
pricedoubleÉ o preço pago pela compra
nsuintegerCódigo comprovante do fornecedor
pinstring50Código PIN do produto
serialstring50Número de série do produto
infostring300Informações adicionais sobre a compra.
categorystring30Categoria do produto
typestring20Identifica o tipo do produto
external_idstring36Id único do pedido no sistema do desenvolvedor
receiptobjectRetorna um comprovante caso exista um
statusstring2Status do pedido
date_timedatetimeData e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss
country_codestring2Código do país do produto
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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"
}'
PropriedadeTipoValorObrigatórioDescrição
skustringSimÉ o código que representa o produto solicitado no pedido
identifierstringSimÉ o número telefônico
statusstringOKNãoCaso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor
external_idstringNãoId único do pedido no sistema do desenvolvedor
receiptobjectNãoÉ o comprovante que poderá ser enviado para o cliente final
receipt.smsobjectNãoÉ o comprovante enviado via SMS
receipt.sms.numberstringNãoCaso o receipt seja enviado, o number se torna obrigatório e contém o número móvel COM ddd que receberá o SMS
receipt.sms.messagestringNãoCaso o receipt seja enviado, message se torna obrigatório e contém a mensagem que será enviada no SMS

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
}
PropriedadeTipoTamanhoDescrição
idintegerId da compra
titlestring100Título do produto
skustring40É o código do produto
identifierstring30É o número telefônico, CPF ou identificador único
providerstring30É o fornecedor
amountdoubleÉ o valor da recarga
pricedoubleÉ o preço pago pela compra
nsuintegerCódigo comprovante do fornecedor
pinstring50Código PIN do produto
serialstring50Número de série do produto
infostring300Informações adicionais sobre a compra.
categorystring30Categoria do produto
typestring20Identifica o tipo do produto
external_idstring36Id único do pedido no sistema do desenvolvedor
receiptobjectRetorna um comprovante caso exista um
statusstring2Status do pedido
date_timedatetimeData e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss
country_codestring2Código do país do produto
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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" 
}'
PropriedadeTipoValorObrigatórioDescrição
skustringSimÉ o código que representa o produto solicitado no pedido
identifierstringSimÉ o número telefônico
statusstringOKNãoCaso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor
external_idstringNãoId único do pedido no sistema do desenvolvedor
receiptobjectNãoÉ o comprovante que poderá ser enviado para o cliente final
receipt.smsobjectNãoÉ o comprovante enviado via SMS
receipt.sms.numberstringNãoCaso o receipt seja enviado, o number se torna obrigatório e contém o número móvel COM ddd que receberá o SMS
receipt.sms.messagestringNãoCaso o receipt seja enviado, message se torna obrigatório e contém a mensagem que será enviada no SMS

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
}
PropriedadeTipoTamanhoDescrição
idintegerId da compra
titlestring100Título do produto
skustring40É o código do produto
identifierstring30É o número telefônico, CPF ou identificador único
providerstring30É o fornecedor
amountdoubleÉ o valor da recarga
pricedoubleÉ o preço pago pela compra
nsuintegerCódigo comprovante do fornecedor
pinstring50Código PIN do produto
serialstring50Número de série do produto
infostring300Informações adicionais sobre a compra.
categorystring30Categoria do produto
typestring20Identifica o tipo do produto
external_idstring36Id único do pedido no sistema do desenvolvedor
receiptobjectRetorna um comprovante caso exista um
statusstring2Status do pedido
date_timedatetimeData e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss
country_codestring2Código do país do produto
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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"
}'
PropriedadeTipoValorObrigatórioDescrição
skustringSimÉ o código que representa o produto solicitado no pedido
identifierstringSimÉ o número telefônico
statusstringOKNãoCaso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor
external_idstringNãoId único do pedido no sistema do desenvolvedor
receiptobjectNãoÉ o comprovante que poderá ser enviado para o cliente final
receipt.smsobjectNãoÉ o comprovante enviado via SMS
receipt.sms.numberstringNãoCaso o receipt seja enviado, o number se torna obrigatório e contém o número móvel COM ddd que receberá o SMS
receipt.sms.messagestringNãoCaso o receipt seja enviado, message se torna obrigatório e contém a mensagem que será enviada no SMS

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
}
PropriedadeTipoTamanhoDescrição
idintegerId da compra
titlestring100Título do produto
skustring40É o código do produto
identifierstring30É o número telefônico, CPF ou identificador único
providerstring30É o fornecedor
amountdoubleÉ o valor da recarga
pricedoubleÉ o preço pago pela compra
nsuintegerCódigo comprovante do fornecedor
pinstring50Código PIN do produto
serialstring50Número de série do produto
infostring300Informações adicionais sobre a compra.
categorystring30Categoria do produto
typestring20Identifica o tipo do produto
external_idstring36Id único do pedido no sistema do desenvolvedor
receiptobjectRetorna um comprovante caso exista um
statusstring2Status do pedido
date_timedatetimeData e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss
country_codestring2Código do país do produto
linksarrayLinks de interação
returnintegerÉ o código de retorno da operação

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
}

PropriedadeTipoTamanhoDescrição
...
receiptobjectContém os dados do comprovante
receipt.smsobjectContém os dados do SMS
receipt.sms.idintegerÉ o id do SMS
receipt.sms.numberstring20É o número do telefone celular
receipt.sms.messagestringÉ o corpo da mensagem
receipt.sms.amountintegerÉ a quantidade de SMSs que foram necessários para conter a mensagem (160 carácter = 1 SMS). (Esse campo fica 0 quando em recargas não confirmadas).
receipt.sms.pricedoublePreço do envio do comprovante enviado (Esse campo fica 0 quando em recargas não confirmadas).
receipt.sms.statusstring2Status do SMS quando enviado (Esse status fica vazio quando em recargas não confirmadas).
...

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"	
}'
PropriedadeTipoValorObrigatórioDescrição
statusstringOKSimInstrução de mudança de status para confirmado.

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"	
}'
PropriedadeTipoValorObrigatórioDescrição
statusstringCASimInstrução de mudança de status para cancelado.

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 ''
ParâmetroTipoDescrição
pageintegerDiz qual a página solicitada
sizeintegerDiz qual o a quantidade de itens de uma página
sortstringOrdena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo
start_datedateDiz a data delimitadora mais antiga no padrão YYYY-mm-dd
end_datedateDiz a data delimitadora mais recente no padrão YYYY-mm-dd
categorystringCategoria do produto
statusstringÉ o status do pedido de compra
identifierstringÉ o identificador
external_idstringÉ o id do pedido no sistema do desenvolvedor

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
}
PropriedadeTipoTamanhoDescrição
contentarrayContém um conjunto de pedidos
content.idintegerId da compra
content.titlestring100Título do produto
content.skustring40É o código do produto
content.identifierstring30É o número telefônico
content.providerstring30É o fornecedor
content.amountdatetimeÉ o valor da recarga
content.pricedoubleÉ o preço pago pela compra
content.nsuintegerCódigo comprovante do fornecedor
content.pinstring50Código PIN para produtos da categoria GIFT_CARD
content.serialstring50Número de série para produtos em PIN
content.infostring300Informações adicionais sobre a compra.
content.categorystring30Categoria do produto
content.typestring20Identifica o tipo do produto
content.external_idstring36Id único do pedido no sistema do desenvolvedor
content.receiptobjectRetorna um comprovante caso exista um
content.statusstring2Status do pedido
content.date_timedatetimeData e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss
content.country_codestring2Código do país do produto
content.linksarrayLinks de interação
paginationobjectContém informações de paginação
pagination.pageintegerDiz qual a página atual da requisição
pagination.sizeintegerDiz a quantidade de fornecedores por página
pagination.total_pagesintegerDiz a quantidade total de páginas
returnintegerÉ o código de retorno da operação

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
}
PropriedadeTipoTamanhoDescrição
identifierstring30Número do celular com DDD
providerstring30Nome da operadora
portedbooleanÉ verdadeiro se o número já foi portado de uma operadora para outra
returnintegerÉ o código de retorno da operação

Anexos

Categorias de produtos

CategoriaDescrição
TELEPHONYProdutos de telefonia fixa ou móvel
TELEVISIONProdutos de TV
GIFT_CARDProdutos via código PIN

Subcategorias de produtos

SubcategoriaDescrição
CASHGift Cards que adicionam saldo nas plataformas fornecedoras (Ex.: LEAGUE OF LEGENDS)
SUBSCRIPTIONGift Cards de assinaturas (Ex.: XBOX GAME PASS)
TOP-UPRecargas que completam um saldo pré-pago (Ex.: CLARO)

Seções de produtos

SeçãoDescrição
CELL_PHONESRelacionados a telefonia celular
LANDLINE_PHONESRelacionados a telefonia fixa
CABLE_TVRelacionados a tv por assinatura
GAMESRelacionados a jogos
PAYAMENTSRelacionados a meios de pagamento
STREAMINGRelacionados a servios de streaming (áudio e vídeo)
TRANSPORTRelacionados ao transporte de passageiros
DELIVERYRelacionados ao trasporte e entrega de pedidos

Tipos de produtos

TipoDescrição
REAL_TIMESão produtos com entrega em tempo real (online).
PIN_CODESão produtos com entrega via código PIN, que necessitam de resgate na plataforma do fornecedor

Status de pagamentos

StatusDescriçãoInformações
APAguarde pagamentoEsse status é setado ao solicitar um boleto de compra de crédito
AQAguarde quitaçãoEsse status é setado logo após o envio de um comprovante de depósito ou transferência
ARAguarde registroEsse status pode ocorrer na solicitação de um boleto
NRComprovante não reconhecidoQuando um número de comprovante de depósito ou dados de contas bancárias inválidas forem enviadas, o sistema setará como não reconhecido o pagamento.
CAPedido canceladoQuando um pagamento for cancelado
PRProcessandoO pagamento foi sinalizado para quitação
OKPagoQuando um pagamento é quitado e recebido
PAPago parcialQuando um pagamento é feito com o valor parcial do título
ABAbertoQuando um pagamento à vista não é quitado
CACanceladoQuando um pagamento é cancelado
ESEstornoQuando o pagamento é devolvido

Status de pedidos de compras

StatusDescrição
OKPedido confirmado e produto entregue
ACPedido aguardando confirmação (pedido autorizado pelo fornecedor ou pin pronto para ser entregue) ou cancelamento
SOPedido solicitado, mas que ainda não pode ser confirmado (o fornecedor ainda não respondeu ao pedido)
CAPedido cancelado

Status de SMS

StatusDescrição
OKSMS recebido
ACSMS enviado
SOSMS solicitado e encontra-se na fila de envio
CASMS cancelado e não enviado
BLSMS na black list

Códigos de retorno

ReturnMensagemInformação
0Erro genérico 
1Requisição processada com sucesso 
2Recurso não encontrado 
3Credenciais não enviadas 
4Não autenticado 
5O identificador está inválido 
6O código de área não existe 
7O envio da variável {identifier} é obrigatório 
8O fornecedor não está ativo no momento 
9Não foi possível reconhecer o fornecedor do identificador 
10A variável {value} precisa ser do tipo double 
11No momento o fornecedor não disponibiliza o valor solicitado 
12O envio do valor é obrigatório 
13Se enviada, a variável {externalId} não pode ser vazia 
14O id externo não pode ser inserido mais de uma vez 
15A variável {status} foi enviada com um conteúdo inválido 
16A variável {id} precisa ser do tipo inteiro 
17O envio da variável {status} é obrigatório 
18O fornecedor não conseguiu executar a solicitação de confirmação ou cancelamento 
19Saldo de conta insuficiente 
20O Content-type do header tem que ser enviado como application/json 
21A informação enviada não está no formato JSON válido 
22Ocorreu um erro interno com a base de dados 
23A variável {page} precisa ser do tipo inteiro 
24A variável {size} precisa ser do tipo inteiro 
25A variável {startDate} deve estar no formato YYYY-mm-dd 
26A variável {endDate} deve estar no formato YYYY-mm-dd 
27Produto com estoque insuficiente no momentoUm produto sem estoque não é listado no webservice, mas é possível, sobre alta demanda, um produto listado em algum segundo está sem estoque e ser desativado imediatamente
28O fornecedor não retornou o comprovante NSU ou código PIN 
29Fornecedor informa que o identificador não foi autorizado 
30Fornecedor informa que o sistema está sobrecarregado 
31Fornecedor informa que a compra está expirada 
32Fornecedor informa que o identificador está bloqueado para compra 
33Fornecedor informa erro genérico 
34Fornecedor informa que não reconhece o identificador 
35Sistema indisponível para compra de recarga e gift cards 
36Se enviada, a variável {name} não pode ser vazia*Ainda não implementado 
37O Token de acesso ou token de atualização está em conflito 
38A solicitação não incluiu um token de autenticação ou o token de autenticação expirou ou a chave e a assinatura da API são inválidas 
39Basic ou bearer está inválido no cabeçário 
40{grant_type}, {audience} ou o {refresh_token} está inválido no corpo 
41{currency} está inválido no corpo 
42Este tipo de método não é suportado para este recurso 
43{access_token} inválido 
44A variável {payment_method} foi enviada com um conteúdo inválidoValores aceitos “BILL”, “DEPOSIT”, “TRANSFER” ou “CRYPTO”
45Há mais de uma fatura em aberto 
46A quantia enviada foi abaixo do valor mínimo de pedido 
47O envio da variável {receipt} é obrigatórioQuando usada com o meio de pagamento DEPOSIT 
48A variável {receipt} não pode ser vazia 
49Banco não suportadoAtualmente é apenas aceito 001 (Banco do Brasil)
50O envio da variável {bank} é obrigatório 
51Se enviada, a variável {currency} não pode ser vazia 
52Não foi possível cancelar o pagamento Pode acontecer quando um pagamento já foi quitado ou cancelado.
53O envio da variável {sender_account} é obrigatório 
54O envio da variável {bank_code} é obrigatório 
55O envio da variável {type} é obrigatório 
56A variável {type} foi enviada com um conteúdo inválidoValores aceitos “CC” ou “CP”. CC=conta corrente e CP=conta poupança
57O envio da variável {branch_number} é obrigatório 
58A variável {branch_number} não pode ser vazia 
59O envio da variável {account_number} é obrigatório 
60A variável {account_number} não pode ser vazia 
61O envio da variável {identification_number} é obrigatório 
62{identification_number} está inválido no corpo 
63O envio da variável {account_holder} é obrigatório 
64A variável {account_holder} não pode ser vazia 
65O cadastro do seu perfil não foi completamente preenchido ou não foi aprovado 
66Compra não autorizada pelo gateway de pagamento.Esse erro pode ocorrer deviso a erro nos dados cadastrais do titular do perfil
67A variável {category} foi enviada com um conteúdo inválidoOs valores aceitos são: TELEPHONY, GIFT_CARD e TELEVISION
68O envio da variável {sku} é obrigatório 
69A variável {sort} foi enviada com um conteúdo inválidoValores aceitos “ASC” ou “DESC”.
70Accept não foi reconhecidoEssa documentação descreve a versão 2.0 da API e Accept precisa ser enviado como com.metallisson.api-v2+json
71A variável {provider} foi enviada com um conteúdo inválido 
72A variável {category} foi enviada com um conteúdo inválido 
73Se enviada, a variável {persist} precisa ser true ou false 
74O valor solicitado não está na faixa mínima e máximaEsse erro ocorre quando uma recarga é solicitada com valor variável menor ou maior do que o permitido 
75O envio da variável {cryptocurrency} é obrigatório
76A variável {cryptocurrency} foi enviada com um conteúdo inválidoOs valores aceitos são: BTC
BTC = BitCoin
77Estrutura de recibo inválidaVerifique se os campos do comprovante de gift card ou recarga foram enviados ou preenchidos
78Chave de API bloqueadaO bloqueio acontece for infração, uso suspeito, sem moderação ou falta de documentação comprovatória (O comprovante de residência com RG/CNH pessoa física ou cartão CNPJ jurídica deve ser enviado para contato@metallisson.com)
79Limite de solicitações atingido*Ainda não implementado
80A compra excede o limite diário do meio de pagamentoVerifique seu limite de compra no painel

Códigos de erros

StatusErrorInformação
400INVALID_REQUESTA requisição foi enviada em um formato não esperado
401UNAUTHORIZEDA solicitação não incluiu um token de autenticação válido ou a chave e a assinatura da API estão inválidas
403FORBIDDENO cliente não tem permissão de acessar o conteúdo do recurso
404NOT_FOUNDO recurso solicitado não foi encontrado
405METHOD_NOT_SUPPORTEDO método não é suportado para o recurso
422UNPROCESSABLE_ENTILYA requisição foi entendida, mas ão está no formato correto.
500INTERNAL_SERVER_ERRORA solicitação não foi concluída devido a um erro interno no lado do servidor.
502BAD_GATEWAYFoi recebida uma resposta inválida do servidor principal
503SERVICE_UNAVAILABLEO servidor não está pronto para lidar com a requisição