Introdução
Caro desenvolvedor, estaremos encerrando nossos serviços de intermediação dentro dos próximos dias. Por favor, não realizar novas integrações nas versões 1.1 e 2.0 de nossa API. Não estamos aceitando novos cadastros. Para nossos clientes, por favor, acessar o Painel e verificar as datas dos encerramentos das operações.
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:
| Componente | Descrição |
|---|---|
| Os verbos HTTP |
|
| Os URIs | Autenticação: https://auth.metallisson.com https://auth.sandbox.metallisson.comConsumo: https://api.metallisson.com https://api.sandbox.metallisson.com |
| Os recursos |
|
| Os parâmetros de busca | Usando o verbo
GET é possível incluir filtros para melhorar a busca. Ex.: /orders?
page=2
|
| O cabeçalho das requisições | Em 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çalho | Descrição |
|---|---|
Content-Type | Deverá ser enviado como: Content-Type: application/json |
Accept | Deverá ser enviado como: Accept: com.metallisson.api-v2+json |
Authorization | Na 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âmetro | Tipo | Descrição |
|---|---|---|
page | integer | Diz qual a página solicitada |
size | integer | Diz qual o a quantidade de itens de uma página |
sort | string | Ordena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo |
start_date | date | Diz a data delimitadora mais antiga no padrão YYYY-mm-dd |
end_date | date | Diz 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
}
| Status | Descrição |
|---|---|
200 | OK – A solicitação foi requisitada com sucesso. |
201 | Criado – 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. |
202 | Aceito – Essa resposta diz que a solicitação foi bem estruturada, mas por alguma regra não entregou o resultado esperado. Por exemplo: Usando 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
}
| Propriedade | Descrição |
|---|---|
error | Representa o código de erro |
info | Descreve o erro |
return | Representa 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.
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 retornoexpires_in,refresh_tokenerefresh_token_expires_invem 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"
}'
| Propriedade | Tipo | Valor | Obrigatório |
|---|---|---|---|
grant_type | string | client_credentials | Sim |
audience | string | https://api.sandbox.metallisson.com | Sim |
persist | boolean | true ou false | Nã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âmetro | Tipo | Tamanho | Descrição |
|---|---|---|---|
access_token | string | 60 | Token que deverá ser enviado em todas as solicitações |
scope | string | – | Diz quais as permissões do token |
expires_in | integer | – | Diz o tempo em segundos para o token expirar |
refresh_token | string | 60 | Esse é o token de atualização do access_token |
refresh_token_expires_in | integer | – | Diz o tempo em segundos para o token de atualização expirar |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório |
|---|---|---|---|
grant_type | string | refresh_token | Sim |
refresh_token | string | O token de atualização da última autenticação | Sim |
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âmetro | Tipo | Tamanho | Descrição |
|---|---|---|---|
access_token | string | 60 | Token que deverá ser enviado em todas as solicitações |
scope | string | – | Diz quais as permissões do token |
expires_in | integer | – | Diz o tempo em segundos para o token expirar |
refresh_token | string | 60 | Esse é o token de atualização do access_token |
refresh_token_expires_in | integer | – | Diz o tempo em segundos para o token de atualização expirar |
return | integer | – | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
return | integer | – | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
amount | double | – | Saldo de crédito virtual |
currency | string | – | Moeda do saldo |
return | integer | – | É 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:
- Depósito bancário
- Transferência bancária
- Boleto bancário
- 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
amount | double | – | Sim | Valor depositado |
payment_method | string | DEPOSIT | Sim | É o identificador do método de pagamento |
receipt | string | – | Sim | É o número do comprovante de depósito NR. DOCUMENTO ou NR. ENVELOPE |
bank | string | 001 | Sim | É o código do banco conforme Febraban |
currency | string | BRL | Nã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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | double | – | Id do pagamento |
amount | string | – | Valor do pagamento |
status | string | 2 | Status do pagamento |
bank | string | 5 | Código do banco |
price | double | – | Preço de compra do crédito |
receipt | string | 30 | Este é o número do comprovante de depósito NR. DOCUMENTO ou NR. ENVELOPE. |
payment_method | string | 20 | É o identificador do método de pagamento |
date_time | datetime | – | Data e hora do envio do comprovante no padrão YYYY-mm-dd H:i:s |
currency | string | 2 | Moeda |
links | array | – | Links de interação |
return | integer | – | É 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"
}
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
amount | double | – | Sim | Valor depositado |
payment_method | string | TRANSFER | Sim | É o identificador do método de pagamento |
bank | string | 001 | Sim | É o código do banco conforme Febraban |
sender_account | object | – | Sim | Contém os dados do banco do remetente do comprovante |
sender_account.bank | string | – | Sim | É o código do banco do remetente conforme Febraban |
sender_account.account_holder | string | – | Sim | É o nome do titular da conta bancária remetente |
sender_account.account_type | string | – | Sim | É o tipo da conta bancária remetente. CC para conta corrente e CP para conta poupança |
sender_account.branch_number | string | – | Sim | É a agencia da conta bancária remetente |
sender_account.account_number | string | – | Sim | É o número da conta bancária remetente |
sender_account.identy | string | – | Sim | É o CPF ou CNPJ, com apenas números, do titular da conta bancária remetente |
currency | string | BRL | Nã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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id do pagamento |
amount | double | – | Valor do pagamento |
status | string | 2 | Status do pagamento |
bank | string | – | Código do banco |
price | double | – | Preço de compra do crédito |
sender_account | object | – | Contém os dados do banco do remetente do comprovante |
sender_account.bank | string | 5 | É o código do banco do remetente conforme Febraban |
sender_account.account_holder | string | 100 | É o nome do titular da conta bancária remetente |
sender_account.account_type | string | 2 | É o tipo da conta bancária remetente. CC para conta corrente e CP para conta poupança |
sender_account.branch_number | string | 20 | É a agencia da conta bancária remetente |
sender_account.account_number | string | 20 | É o número da conta bancária remetente |
sender_account.identy | string | 14 | É o CPF ou CNPJ, com apenas números, do titular da conta bancária remetente |
payment_method | string | 20 | É o identificador do método de pagamento |
date_time | datetime | – | Data e hora do envio do comprovante no padrão YYYY-mm-dd H:i:s |
currency | string | 2 | Moeda |
links | array | – | Links de interação |
return | integer | – | É 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_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"
}'
| Propriedade | Tido | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
amount | double | – | Sim | Valor depositado |
payment_method | string | BILL | Sim | É o identificador do método de pagamento |
currency | string | BRL | Nã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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id do pagamento |
amount | double | – | Valor do pagamento |
status | string | 2 | Status do pagamento |
price | double | – | É o preço de compra do crédito |
bill | object | – | Contém os dados do banco do remetente do comprovante |
bill.number | string | 30 | É o nosso número. Obs.: Não armazene como único. Serão usados diferentes bancos. |
bill.digitable_line | string | 48 | É a linha digitável do boleto |
bill.url | string | 100 | É o link para acesso ao boleto. Obs.: O boleto pode vir em html ou pdf. |
bill.expiration_date | date | – | É a data de vencimento do boleto no formato YYYY-mm-dd |
payment_method | string | 20 | É o identificador do método de pagamento |
date_time | datetime | – | Data e hora da solicitação do boleto no padrão YYYY-mm-dd H:i:s |
payment_date | date | – | Data da baixa do título no padrão YYYY-mm-dd |
currency | string | 2 | Moeda |
links | array | – | Links de interação |
return | integer | – | É 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_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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
amount | double | – | Sim | Valor depositado |
payment_method | string | CRYPTO | Sim | É o identificador do método de pagamento |
cryptocurrency | string | BTC | Sim | É a moeda digital. BTC para BitCoin |
currency | string | BRL | Nã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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id do pagamento |
amount | double | – | Valor do pagamento |
status | string | 2 | Status do pagamento |
price | double | É o preço de compra de crédito | |
crypto | object | – | Contém os dados para a transferência de criptomoedas |
crypto.cryptocurrency | string | 3 | É a sigla da moeda: BTC |
crypto.amount_crypto | double | – | É o valor em criptomoeda para ser transferido |
crypto.wallet_address | string | 100 | É o endereço da carteira da criptomoeda |
crypto.qrcode_url | string | – | É o link da imagem do QRCODE para pagamento |
payment_method | string | 20 | É o identificador do método de pagamento |
date_time | datetime | – | Data e hora da solicitação do pagamento no padrão YYYY-mm-dd |
payment_date | date | – | Data da liquidação do pagamento no padrão YYYY-mm-dd |
currency | string | 2 | Moeda |
links | array | – | Links de interação |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
status | string | CA | Sim | Instruçã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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id do pagamento |
amount | double | – | Valor do pagamento |
status | string | 2 | Status do pagamento |
price | double | – | Preço de compra do crédito |
bill | object | – | Contém os dados do banco do remetente do comprovante |
bill.number | string | 30 | É o nosso número. Obs.: Não armazene como único. Serão usados diferentes bancos. |
bill.digitable_line | string | 48 | É a linha digitável do boleto |
bill.url | string | 100 | É o link para acesso ao boleto |
bill.expiration_date | date | – | É a data de vencimento do boleto |
payment_method | string | 20 | É o identificador do método de pagamento |
date_time | datetime | – | Data e hora da solicitação do boleto no padrão YYYY-mm-dd |
payment_date | date | – | Data da baixa do título no padrão YYYY-mm-dd |
currency | string | 2 | Moeda |
links | array | – | Links de interação |
return | integer | – | É 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âmetro | Tipo | Descrição |
|---|---|---|
page | integer | Diz qual a página solicitada |
size | integer | Diz qual o a quantidade de itens de uma página |
sort | string | Ordena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo |
start_date | date | Diz a data delimitadora mais antiga no padrão YYYY-mm-dd |
end_date | date | Diz a data delimitadora mais recente no padrão YYYY-mm-dd |
payment_method | string | É a modalidade de pagamento. Sendo elas: TRANSFER, DEPOSIT, BILL e CRYPTO |
status | string | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
content | array | – | Contém um conjunto de fornecedores |
content.provider | string | 30 | É o código que representa um fornecedor |
content.provider_name | string | 100 | É o nome da empresa fornecedora |
content.logo | string | – | Imagem da logo do fornecedor |
content.info | string | 300 | Informações adicionais sobre o fornecedor |
content.category | string | 30 | Categoria de produtos do fornecedor |
content.country_code | string | 2 | Código do país com dois caracteres (ISO Alpha-2) |
content.products | array | – | Contém um conjunto de produtos do fornecedor |
content.products.title | string | 100 | Título do produto |
content.products.sku | string | 40 | Có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.amount | double | – | Valor da quantidade unitária de recarga, ou seja, a face. |
content.products.price | double | – | Preço do produto no momento da consulta |
content.products.min_amount | double | – | Valor 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_amount | double | 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.step | double | É 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.expiration | integer | – | Quando informado pelo fornecedor, representa o número de dias da validade de consumo do produto |
content.products.info | string | – | Informações adicionais sobre o produto |
content.products.subcategory | string | 30 | Subcategoria do produto |
content.products.section | string | 30 | Seção do produto |
content.products.type | string | 20 | Identifica o tipo do produto |
content.products.area_code | array[integer] | Diz quais são os DDDs que o produto pode ser consumido | |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
sku | string | – | Sim | É o código que representa o produto solicitado no pedido |
identifier | string | – | Sim | É o número telefônico |
status | string | OK | Não | Caso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor |
external_id | string | – | Não | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Não | É o comprovante que poderá ser enviado para o cliente final |
receipt.sms | object | – | Não | É o comprovante enviado via SMS |
receipt.sms.number | string | – | Não | Caso 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.message | string | – | Não | Caso 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id da compra |
title | string | 100 | Título do produto |
sku | string | 40 | É o código do produto |
identifier | string | 30 | É o número telefônico, CPF ou identificador único |
provider | string | 30 | É o fornecedor |
amount | double | – | É o valor da recarga |
price | double | – | É o preço pago pela compra |
nsu | integer | – | Código comprovante do fornecedor |
pin | string | 50 | Código PIN do produto |
serial | string | 50 | Número de série do produto |
info | string | 300 | Informações adicionais sobre a compra. |
category | string | 30 | Categoria do produto |
type | string | 20 | Identifica o tipo do produto |
external_id | string | 36 | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Retorna um comprovante caso exista um |
status | string | 2 | Status do pedido |
date_time | datetime | – | Data e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss |
country_code | string | 2 | Código do país do produto |
links | array | – | Links de interação |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
sku | string | – | Sim | É o código que representa o produto solicitado no pedido |
identifier | string | – | Sim | É o número telefônico |
status | string | OK | Não | Caso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor |
external_id | string | – | Não | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Não | É o comprovante que poderá ser enviado para o cliente final |
receipt.sms | object | – | Não | É o comprovante enviado via SMS |
receipt.sms.number | string | – | Não | Caso 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.message | string | – | Não | Caso 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id da compra |
title | string | 100 | Título do produto |
sku | string | 40 | É o código do produto |
identifier | string | 30 | É o número telefônico, CPF ou identificador único |
provider | string | 30 | É o fornecedor |
amount | double | – | É o valor da recarga |
price | double | – | É o preço pago pela compra |
nsu | integer | – | Código comprovante do fornecedor |
pin | string | 50 | Código PIN do produto |
serial | string | 50 | Número de série do produto |
info | string | 300 | Informações adicionais sobre a compra. |
category | string | 30 | Categoria do produto |
type | string | 20 | Identifica o tipo do produto |
external_id | string | 36 | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Retorna um comprovante caso exista um |
status | string | 2 | Status do pedido |
date_time | datetime | – | Data e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss |
country_code | string | 2 | Código do país do produto |
links | array | – | Links de interação |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
sku | string | – | Sim | É o código que representa o produto solicitado no pedido |
identifier | string | – | Sim | É o número telefônico |
status | string | OK | Não | Caso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor |
external_id | string | – | Não | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Não | É o comprovante que poderá ser enviado para o cliente final |
receipt.sms | object | – | Não | É o comprovante enviado via SMS |
receipt.sms.number | string | – | Não | Caso 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.message | string | – | Não | Caso 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id da compra |
title | string | 100 | Título do produto |
sku | string | 40 | É o código do produto |
identifier | string | 30 | É o número telefônico, CPF ou identificador único |
provider | string | 30 | É o fornecedor |
amount | double | – | É o valor da recarga |
price | double | – | É o preço pago pela compra |
nsu | integer | – | Código comprovante do fornecedor |
pin | string | 50 | Código PIN do produto |
serial | string | 50 | Número de série do produto |
info | string | 300 | Informações adicionais sobre a compra. |
category | string | 30 | Categoria do produto |
type | string | 20 | Identifica o tipo do produto |
external_id | string | 36 | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Retorna um comprovante caso exista um |
status | string | 2 | Status do pedido |
date_time | datetime | – | Data e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss |
country_code | string | 2 | Código do país do produto |
links | array | – | Links de interação |
return | integer | – | É 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
sku | string | – | Sim | É o código que representa o produto solicitado no pedido |
identifier | string | – | Sim | É o número telefônico |
status | string | OK | Não | Caso seja enviado, a API automaticamente confirmará o pedido de compra junto ao fornecedor |
external_id | string | – | Não | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Não | É o comprovante que poderá ser enviado para o cliente final |
receipt.sms | object | – | Não | É o comprovante enviado via SMS |
receipt.sms.number | string | – | Não | Caso 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.message | string | – | Não | Caso 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
id | integer | – | Id da compra |
title | string | 100 | Título do produto |
sku | string | 40 | É o código do produto |
identifier | string | 30 | É o número telefônico, CPF ou identificador único |
provider | string | 30 | É o fornecedor |
amount | double | – | É o valor da recarga |
price | double | – | É o preço pago pela compra |
nsu | integer | – | Código comprovante do fornecedor |
pin | string | 50 | Código PIN do produto |
serial | string | 50 | Número de série do produto |
info | string | 300 | Informações adicionais sobre a compra. |
category | string | 30 | Categoria do produto |
type | string | 20 | Identifica o tipo do produto |
external_id | string | 36 | Id único do pedido no sistema do desenvolvedor |
receipt | object | – | Retorna um comprovante caso exista um |
status | string | 2 | Status do pedido |
date_time | datetime | – | Data e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss |
country_code | string | 2 | Código do país do produto |
links | array | – | Links de interação |
return | integer | – | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
... | – | ||
receipt | object | – | Contém os dados do comprovante |
receipt.sms | object | – | Contém os dados do SMS |
receipt.sms.id | integer | – | É o id do SMS |
receipt.sms.number | string | 20 | É o número do telefone celular |
receipt.sms.message | string | – | É o corpo da mensagem |
receipt.sms.amount | integer | – | É 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.price | double | – | Preço do envio do comprovante enviado (Esse campo fica 0 quando em recargas não confirmadas). |
receipt.sms.status | string | 2 | Status 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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
status | string | OK | Sim | Instruçã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"
}'
| Propriedade | Tipo | Valor | Obrigatório | Descrição |
|---|---|---|---|---|
status | string | CA | Sim | Instruçã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âmetro | Tipo | Descrição |
|---|---|---|
page | integer | Diz qual a página solicitada |
size | integer | Diz qual o a quantidade de itens de uma página |
sort | string | Ordena do mais antigo para o mais recente registro com ASC e DESC do mais recente para o mais antigo |
start_date | date | Diz a data delimitadora mais antiga no padrão YYYY-mm-dd |
end_date | date | Diz a data delimitadora mais recente no padrão YYYY-mm-dd |
category | string | Categoria do produto |
status | string | É o status do pedido de compra |
identifier | string | É o identificador |
external_id | string | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
content | array | – | Contém um conjunto de pedidos |
content.id | integer | – | Id da compra |
content.title | string | 100 | Título do produto |
content.sku | string | 40 | É o código do produto |
content.identifier | string | 30 | É o número telefônico |
content.provider | string | 30 | É o fornecedor |
content.amount | datetime | – | É o valor da recarga |
content.price | double | – | É o preço pago pela compra |
content.nsu | integer | – | Código comprovante do fornecedor |
content.pin | string | 50 | Código PIN para produtos da categoria GIFT_CARD |
content.serial | string | 50 | Número de série para produtos em PIN |
content.info | string | 300 | Informações adicionais sobre a compra. |
content.category | string | 30 | Categoria do produto |
content.type | string | 20 | Identifica o tipo do produto |
content.external_id | string | 36 | Id único do pedido no sistema do desenvolvedor |
content.receipt | object | – | Retorna um comprovante caso exista um |
content.status | string | 2 | Status do pedido |
content.date_time | datetime | – | Data e hora da solicitação do pedido no padrão YYYY-mm-dd HH:ii:ss |
content.country_code | string | 2 | Código do país do produto |
content.links | array | – | Links de interação |
pagination | object | – | Contém informações de paginação |
pagination.page | integer | – | Diz qual a página atual da requisição |
pagination.size | integer | – | Diz a quantidade de fornecedores por página |
pagination.total_pages | integer | – | Diz a quantidade total de páginas |
return | integer | – | É 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
}
| Propriedade | Tipo | Tamanho | Descrição |
|---|---|---|---|
identifier | string | 30 | Número do celular com DDD |
provider | string | 30 | Nome da operadora |
ported | boolean | – | É verdadeiro se o número já foi portado de uma operadora para outra |
return | integer | – | É o código de retorno da operação |
Anexos
Categorias de produtos
| Categoria | Descrição |
|---|---|
TELEPHONY | Produtos de telefonia fixa ou móvel |
TELEVISION | Produtos de TV |
GIFT_CARD | Produtos via código PIN |
Subcategorias de produtos
| Subcategoria | Descrição |
|---|---|
CASH | Gift Cards que adicionam saldo nas plataformas fornecedoras (Ex.: LEAGUE OF LEGENDS) |
SUBSCRIPTION | Gift Cards de assinaturas (Ex.: XBOX GAME PASS) |
TOP-UP | Recargas que completam um saldo pré-pago (Ex.: CLARO) |
Seções de produtos
| Seção | Descrição |
|---|---|
CELL_PHONES | Relacionados a telefonia celular |
LANDLINE_PHONES | Relacionados a telefonia fixa |
CABLE_TV | Relacionados a tv por assinatura |
GAMES | Relacionados a jogos |
PAYAMENTS | Relacionados a meios de pagamento |
STREAMING | Relacionados a servios de streaming (áudio e vídeo) |
TRANSPORT | Relacionados ao transporte de passageiros |
DELIVERY | Relacionados ao trasporte e entrega de pedidos |
Tipos de produtos
| Tipo | Descrição |
|---|---|
REAL_TIME | São produtos com entrega em tempo real (online). |
PIN_CODE | São produtos com entrega via código PIN, que necessitam de resgate na plataforma do fornecedor |
Status de pagamentos
| Status | Descrição | Informações |
|---|---|---|
AP | Aguarde pagamento | Esse status é setado ao solicitar um boleto de compra de crédito |
AQ | Aguarde quitação | Esse status é setado logo após o envio de um comprovante de depósito ou transferência |
AR | Aguarde registro | Esse status pode ocorrer na solicitação de um boleto |
NR | Comprovante não reconhecido | Quando 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. |
CA | Pedido cancelado | Quando um pagamento for cancelado |
PR | Processando | O pagamento foi sinalizado para quitação |
OK | Pago | Quando um pagamento é quitado e recebido |
PA | Pago parcial | Quando um pagamento é feito com o valor parcial do título |
AB | Aberto | Quando um pagamento à vista não é quitado |
CA | Cancelado | Quando um pagamento é cancelado |
ES | Estorno | Quando o pagamento é devolvido |
Status de pedidos de compras
| Status | Descrição |
|---|---|
OK | Pedido confirmado e produto entregue |
AC | Pedido aguardando confirmação (pedido autorizado pelo fornecedor ou pin pronto para ser entregue) ou cancelamento |
SO | Pedido solicitado, mas que ainda não pode ser confirmado (o fornecedor ainda não respondeu ao pedido) |
CA | Pedido cancelado |
Status de SMS
| Status | Descrição |
|---|---|
OK | SMS recebido |
AC | SMS enviado |
SO | SMS solicitado e encontra-se na fila de envio |
CA | SMS cancelado e não enviado |
BL | SMS na black list |
Códigos de retorno
| Return | Mensagem | Informação |
|---|---|---|
0 | Erro genérico | |
1 | Requisição processada com sucesso | |
2 | Recurso não encontrado | |
3 | Credenciais não enviadas | |
4 | Não autenticado | |
5 | O identificador está inválido | |
6 | O código de área não existe | |
7 | O envio da variável {identifier} é obrigatório | |
8 | O fornecedor não está ativo no momento | |
9 | Não foi possível reconhecer o fornecedor do identificador | |
10 | A variável {value} precisa ser do tipo double | |
11 | No momento o fornecedor não disponibiliza o valor solicitado | |
12 | O envio do valor é obrigatório | |
13 | Se enviada, a variável {externalId} não pode ser vazia | |
14 | O id externo não pode ser inserido mais de uma vez | |
15 | A variável {status} foi enviada com um conteúdo inválido | |
16 | A variável {id} precisa ser do tipo inteiro | |
17 | O envio da variável {status} é obrigatório | |
18 | O fornecedor não conseguiu executar a solicitação de confirmação ou cancelamento | |
19 | Saldo de conta insuficiente | |
20 | O Content-type do header tem que ser enviado como application/json | |
21 | A informação enviada não está no formato JSON válido | |
22 | Ocorreu um erro interno com a base de dados | |
23 | A variável {page} precisa ser do tipo inteiro | |
24 | A variável {size} precisa ser do tipo inteiro | |
25 | A variável {startDate} deve estar no formato YYYY-mm-dd | |
26 | A variável {endDate} deve estar no formato YYYY-mm-dd | |
27 | Produto com estoque insuficiente no momento | Um 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 |
28 | O fornecedor não retornou o comprovante NSU ou código PIN | |
29 | Fornecedor informa que o identificador não foi autorizado | |
30 | Fornecedor informa que o sistema está sobrecarregado | |
31 | Fornecedor informa que a compra está expirada | |
32 | Fornecedor informa que o identificador está bloqueado para compra | |
33 | Fornecedor informa erro genérico | |
34 | Fornecedor informa que não reconhece o identificador | |
35 | Sistema indisponível para compra de recarga e gift cards | |
36 | Se enviada, a variável {name} não pode ser vazia | *Ainda não implementado |
37 | O Token de acesso ou token de atualização está em conflito | |
38 | A 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 | |
39 | Basic 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 | |
42 | Este tipo de método não é suportado para este recurso | |
43 | {access_token} inválido | |
44 | A variável {payment_method} foi enviada com um conteúdo inválido | Valores aceitos “BILL”, “DEPOSIT”, “TRANSFER” ou “CRYPTO” |
45 | Há mais de uma fatura em aberto | |
46 | A quantia enviada foi abaixo do valor mínimo de pedido | |
47 | O envio da variável {receipt} é obrigatório | Quando usada com o meio de pagamento DEPOSIT |
48 | A variável {receipt} não pode ser vazia | |
49 | Banco não suportado | Atualmente é apenas aceito 001 (Banco do Brasil) |
50 | O envio da variável {bank} é obrigatório | |
51 | Se enviada, a variável {currency} não pode ser vazia | |
52 | Não foi possível cancelar o pagamento | Pode acontecer quando um pagamento já foi quitado ou cancelado. |
53 | O envio da variável {sender_account} é obrigatório | |
54 | O envio da variável {bank_code} é obrigatório | |
55 | O envio da variável {type} é obrigatório | |
56 | A variável {type} foi enviada com um conteúdo inválido | Valores aceitos “CC” ou “CP”. CC=conta corrente e CP=conta poupança |
57 | O envio da variável {branch_number} é obrigatório | |
58 | A variável {branch_number} não pode ser vazia | |
59 | O envio da variável {account_number} é obrigatório | |
60 | A variável {account_number} não pode ser vazia | |
61 | O envio da variável {identification_number} é obrigatório | |
62 | {identification_number} está inválido no corpo | |
63 | O envio da variável {account_holder} é obrigatório | |
64 | A variável {account_holder} não pode ser vazia | |
65 | O cadastro do seu perfil não foi completamente preenchido ou não foi aprovado | |
66 | Compra não autorizada pelo gateway de pagamento. | Esse erro pode ocorrer deviso a erro nos dados cadastrais do titular do perfil |
67 | A variável {category} foi enviada com um conteúdo inválido | Os valores aceitos são: TELEPHONY, GIFT_CARD e TELEVISION |
68 | O envio da variável {sku} é obrigatório | |
69 | A variável {sort} foi enviada com um conteúdo inválido | Valores aceitos “ASC” ou “DESC”. |
70 | Accept não foi reconhecido | Essa documentação descreve a versão 2.0 da API e Accept precisa ser enviado como com.metallisson.api-v2+json |
71 | A variável {provider} foi enviada com um conteúdo inválido | |
72 | A variável {category} foi enviada com um conteúdo inválido | |
73 | Se enviada, a variável {persist} precisa ser true ou false | |
74 | O valor solicitado não está na faixa mínima e máxima | Esse erro ocorre quando uma recarga é solicitada com valor variável menor ou maior do que o permitido |
75 | O envio da variável {cryptocurrency} é obrigatório | |
76 | A variável {cryptocurrency} foi enviada com um conteúdo inválido | Os valores aceitos são: BTC BTC = BitCoin |
77 | Estrutura de recibo inválida | Verifique se os campos do comprovante de gift card ou recarga foram enviados ou preenchidos |
78 | Chave de API bloqueada | O 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) |
79 | Limite de solicitações atingido | *Ainda não implementado |
80 | A compra excede o limite diário do meio de pagamento | Verifique seu limite de compra no painel |
Códigos de erros
| Status | Error | Informação |
|---|---|---|
400 | INVALID_REQUEST | A requisição foi enviada em um formato não esperado |
401 | UNAUTHORIZED | A solicitação não incluiu um token de autenticação válido ou a chave e a assinatura da API estão inválidas |
403 | FORBIDDEN | O cliente não tem permissão de acessar o conteúdo do recurso |
404 | NOT_FOUND | O recurso solicitado não foi encontrado |
405 | METHOD_NOT_SUPPORTED | O método não é suportado para o recurso |
422 | UNPROCESSABLE_ENTILY | A requisição foi entendida, mas ão está no formato correto. |
500 | INTERNAL_SERVER_ERROR | A solicitação não foi concluída devido a um erro interno no lado do servidor. |
502 | BAD_GATEWAY | Foi recebida uma resposta inválida do servidor principal |
503 | SERVICE_UNAVAILABLE | O servidor não está pronto para lidar com a requisição |