Suporte / Ajuda

Pesquise sua dúvida diretamente abaixo ou busque nos tópicos frequentes.

Leitores

API de controle de assinatura externa

Introdução

A API de gerenciamento de assinaturas da Magtab foi criada por nossos desenvolvedores, para facilitar a integração da base assinantes com o aplicativo de revista da editora. Todo o desenvolvimento segue os padrões de design RESTful, Crud e JSON API.

O acesso a API somente estará disponível usando o protocolo HTTPS, sendo a URL base https://api.magtab.com/api/assinav1. Todos os dados deverão ser enviados e retornados em formato válido JSON. Os campos de data sempre deverão ser informados no formato AAAA-MM-DD. O campo email não pode ser alterado por ser a chave primária da API.

Atenção: TODOS OS ASSINANTES CRIADOS RECEBERÃO E-MAIL INFORMANDO SOBRE A NOVA CONTA E/OU RESET DE SENHA. SUGERIMOS QUE EVITE UTILIZAR SUA BASE DE ASSINANTES REAIS PARA TESTES

Status HTTP response

Os seguintes status code do protocolo HTTP podem ser retornados no header de cada response.

200 OK – Tudo funcionou como esperado.

201 CREATED – Objeto criado.

400 Bad Request – Geralmente, um problema com os parâmetros.

401 Unauthorized – Tentativa de acesso com chave inválida ou sem permissão para acessar o recurso/método.

404 Not Found – O recurso acessado não existe.

409 Conflict – O recurso informado já existe com a mesma chave primária (campo email) e não pode ser criado.

50X Server errors – Falha nossa, algum erro no servidor, o administrador da API será notificado sobre o erro.

Autenticação

Como o próprio nome já diz, a chave de autenticação é usado para autenticar o usuário na API. Essa chave será usada em todas as chamadas da API. Em nossos exemplo usaremos a chave 03425d44943ffc5ac843c2b6c0b771d4ef57952f

Criação chave

Para a primeira autenticação, você deve gerar uma chave acessando o menu de preferências do editor, no site da Magtab.

Api assinatura 1.png

Após gerar a chave, você ja poderá usar API, sempre informando a chave criada.

Revogando a chave

Caso a chave tenha sido comprometido, você pode gerar uma nova clicando no botão Revogar chave no menu de preferencias do editor, no site da Magtab.

ID do título

Todo título possui um id único, e é através dele que a referência do título com o assinante será feita. O id dos título pode ser acessado na tela de menu de preferências do editor. Em nossos exemplos usuaremos o id 35.

O id do título somente será informado na URL de busca, para os demais recursos o título será informado no body da requisição no formato abaixo.

"titulo": "/api/assinav1/titulo/35/"

Schema

Através da schema você poderá ver os campos, filtro e métodos disponíveis na API.

Resource URL

GET https://www.magtab.com/api/assinav1/assinatura/schema/ – Schema assinatura

GET https://www.magtab.com/api/assinav1/titulo/schema/ – Schema do título

Parâmetros

api_key: obrigatório

Exemplo de uso

curl "https://www.magtab.com/api/assinav1/assinatura/schema/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f"

Exemplo de retorno

{
    "allowed_detail_http_methods": [
        "get",
        "post",
        "patch",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "post",
        "patch",
        "delete"
    ],
    "default_format": "application/json",
    "default_limit": 30,
    "fields": {
        "ativa": {
            "blank": true,
            "default": true,
            "help_text": "Determina se a assinatura est\u00e1 ativa ou n\u00e3o.",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "data_fim": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Data de expira\u00e7\u00e3o da assinatura no formato: AAAA-MM-DD",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "data_inicio": {
            "blank": false,
            "default": "1900-01-01T00:00:00",
            "help_text": "Data de in\u00edcio da assinatura no formato: AAAA-MM-DD",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "email": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "E-mail do usu\u00e1rio de assinatura",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "nome": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Nome do usu\u00e1rio de assinatura",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resetar_senha": {
            "blank": false,
            "default": false,
            "help_text": "Campo para resetar a senha do usu\u00e1rio",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "titulo": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "T\u00edtulo associado a assinatura",
            "nullable": false,
            "readonly": false,
            "related_type": "to_one",
            "type": "related",
            "unique": false
        }
    },
    "filtering": {
        "ativa": 1,
        "email": [
            "exact"
        ],
        "data_fim": 1,
        "data_inicio": 1,
        "titulo": 2
    }
}

Cadastrando usuários

Ao cadastrar um assinante e caso ele ainda não esteja ativo, será enviado um email com um link de confirmação em que o mesmo deverá clicar para ativar sua assinatura. O email deverá ser ÚNICO na API, e caso já exista, o erro HTTP 409 CONFLICT será retornado.

Resource URL

POST https://www.magtab.com/api/assinav1/assinatura/

Parametros

api_key: obrigatório

Body
{
    "ativa": true, 
    "email": "boneco@magtab.com", 
    "data_fim": "2014-12-31", 
    "data_inicio": "2013-05-01",
    "nome": "Boneco Magtab",     
    "titulo": "/api/assinav1/titulo/35/"
}

Exemplo uso

curl -X POST "https://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f" \
-d '{"ativa": true, "email": "boneco@magtab.com", "data_fim": "2014-12-31", "data_inicio": "2013-05-01", "nome": "Boneco Magtab", "titulo": "/api/assinav1/titulo/35/"}'   \
-H "Content-Type: application/json"

Exemplo retorno

HTTP Response: 201 CREATED

{
    "ativa": true,
    "data_fim": "2014-12-31",
    "data_inicio": "2013-05-01",
    "email": "boneco@magtab.com",
    "nome": "Boneco Magtab",
    "resetar_senha": false,
    "resource_uri": "/api/assinav1/assinatura/53003/",
    "titulo": "/api/assinav1/titulo/35/"
}

Buscando usuários

A API disponibiliza o recurso de consulta de assinantes através de filtros. Todos os resultados são paginados por padrão, com o total de resultados retornado na meta total_count.. Através dos parâmetro limit e offset ou da url resource next/previous será possível percorrer as páginas.

Resource URL

GET https://www.magtab.com/api/assinav1/assinatura/

Parâmetros

api_key: obrigatório.

email: opcional, email do assinante cadastrado.

ativa: opcional, somente assinantes ativos (true) ou inativos (false).

data_fim: opcional, data exata de expiração da assinatura.

data_fim_lt: opcional, data menor que expiração da assinatura.

data_fim_gt: opcional, data maior que expiração da assinatura.

data_inicio: opcional, data de ínicio da assinatura.

data_inicio_lt: opcional, data menor que inicio da assinatura.

data_inicio_gt: opcional, data maior que inicio da assinatura.

titulo: opcional, API_de_gerenciamento_de_assinaturas#ID do título.

limit: opcional, limite de resultados na busca, se informado 0 retornará todos os assinantes.

offset: opcional, inicio dos resultados na busca, usado para paginar os resultados.

Caso nenhum dos parâmetros opcionais sejam informados, todos os assinantes vinculados à editora serão listados.

Exemplo de uso

Assinante com email boneco@magtab.com
curl "https://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&email=boneco@magtab.com"
Todos os assinantes cadastrados, sem paginação e pertencendo ao título id 35
curl "https://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&limit=0&titulo=35"
Todos os assinantes ativos e paginando a partir do 30º resultado com limite de até 40 resultados
curl "https://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&email=boneco@magtab.com&limit=40&offset=30&ativa=true
Todos os assinantes com data de inicio da assinatura maior que 1º de janeiro de 2013
curl "https://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&data_inicio__gt=2013-01-01
Todos os assinantes com data de início de assinatura menor que 10 de março de 2013
curl "httsp://www.magtab.com/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&data_fim__lt=2013-03-10

Exemplo retorno

HTTP Response: 20O OK

{
     "meta": {
        "limit": 30,
        "next": "/api/assinav1/assinatura/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f&limit=30&offset=30",
        "offset": 0,
        "previous": null,
        "total_count": 33
    },
 
    .....
    .....
    .....
 
    "assinantes": [
        {
            "ativa": true,
            "email": "boneco@magtab.com",
            "data_fim": "2013-05-01",
            "data_inicio": "1900-01-01",
            "nome": "Boneco Magtab",
            "resetar_senha": false,
            "resource_uri": "/api/assinav1/assinatura/53003/",
            "titulo": "/api/assinav1/titulo/35/"
        }
    ]
}

Excluindo usuários

Ao cadastrar erroneamente um usuário é possível excluí-lo da API. Desta forma mesmo que a assinatura tenha expirado, o assinante não poderá mais ler nenhuma edição em seu dispositivo.

Resource URL

DELETE https://www.magtab.com/api/assinav1/assinatura/ – Deleta todos os usuários da editora ATENÇÃO: ESTÁ AÇÃO NÃO PODERÁ SER DESFEITA

DELETE httsp://www.magtab.com/api/assinav1/assinatura/53003/ – Deleta somente o usuário informado no endpoint.

Parametros

api_key: obrigatório

Body

Em branco

Exemplo uso

curl -X DELETE "https://www.magtab.com/api/assinav1/assinatura/53003/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f"

Exemplo retorno

HTTP Response: 204 NO CONTENT

Inativando o assinante

A opção de inativar o assinante pode ser usado quando o mesmo está inadimplente e não deve ter acesso a nenhuma edição.

Resource URL

PATCH https://www.magtab.com/api/assinav1/assinatura/53003

Parametros

api_key: obrigatório

Body
{"ativa": false, "titulo": "/api/assinav1/titulo/35/"}

Exemplo uso

curl -X PATCH "https://www.magtab.com/api/assinav1/assinatura/53003/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f" \
-d '{"ativa": false,  "titulo":  "/api/assinav1/titulo/35/"}'   -H "Content-Type: application/json"

Exemplo retorno

HTTP Response: 202 ACCEPTED

{
    "ativa": false,
    "data_fim": "2014-12-31",
    "data_inicio": "2013-05-01",
    "email": "boneco@magtab.com",
    "nome": "Boneco Magtab",
    "resetar_senha": false,
    "resource_uri": "/api/assinav1/assinatura/53003/",
    "titulo": "/api/assinav1/titulo/35/"
}

Listando dados do assinante

Após buscar um assinante poderemos acessar os dados deles através do endpoint informado na resource_uri.

Resource URL

GET https://www.magtab.com/api/assinav1/assinatura/53003/

Parâmetros

api_key: obrigatório

Exemplo uso

curl "https://www.magtab.com/api/assinav1/assinatura/53003/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f"

Exemplo retorno

HTTP Response: 200 OK

{
    "ativa": false,
    "data_fim": "2014-12-31",
    "data_inicio": "2013-05-01",
    "email": "boneco@magtab.com",
    "nome": "Boneco Magtab",
    "resetar_senha": false,
    "resource_uri": "/api/assinav1/assinatura/53003/",
    "titulo": "/api/assinav1/titulo/35/"
}

Editando um usuário

Exceto o campo e email, todos os outros campos do usuários são editáveis,. Para editar será necessário acessar seu endpoint informado na resource_uri.

Resource URL

PATCH https://www.magtab.com/api/assinav1/assinatura/53003/

Parâmetros

api_key: obrigatório

Body
{"ativa": false, "data_fim": "2016-01-01", "nome": "Boneco Editado Magtab"}

Exemplo uso

curl -X PATCH "https://www.magtab.com/api/assinav1/assinatura/53003/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f" \
-d '{"ativa": false, "data_fim": "2016-01-01", "nome": "Boneco Editado Magtab"}' -H "Content-Type: application/json"

Exemplo retorno

HTTP Response: 202 ACCEPTED

{
    "ativa": false,
    "email": "boneco@magtab.com",
    "data_fim": "2016-01-01",
    "inicio": "1900-01-01",
    "nome": "Boneco Editado Magtab",
    "resetar_senha": false,
    "resource_uri": "/api/assinav1/assinatura/53003/",
    "titulo": "/api/assinav1/titulo/35/"
}

Resetando a senha

O opção de resetar senha altera o valor do campo resetar_senha para True e envia um email ao assinante com um link para alterar sua senha. Esta senha será enviada por email apenas 1 vez e assim que for alterada, a api API da Magtab retornará o valor para False.

Resource URL

PATCH https://www.magtab.com/api/assinav1/assinatura/53003/

Parametros

api_key: obrigatório

Body
{"resetar_senha": true}

Exemplo uso

curl -X PATCH "https://www.magtab.com/api/assinav1/assinatura/53003/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f" \
-d '{"resetar_senha": true}' -H "Content-Type: application/json"

Exemplo retorno

HTTP Response: 202 ACCEPTED

{
    "ativa": true,
    "email": "boneco@magtab.com",
    "data_fim": "2013-05-01",
    "inicio": "1900-01-01",
    "nome": "Boneco Magtab",
    "resetar_senha": true,
    "resource_uri": "/api/assinav1/assinatura/53003/",
    "titulo": "/api/assinav1/titulo/35/"
}

Liberando acesso de edições avulsas pagas a um usuário

Essa chamada da API libera uma edição paga para leitura a um usuário.

Resource URL

PATCH https://www.magtab.com/api/assinav1/edicaoavulsa/

Parametros

api_key: obrigatório

Body
  • Apenas os parâmetros “email” e “edicao” são obrigatórios.
  • O parâmetro “resetar_senha” só será efetivo se o usuário já existir.
{
    "email": "email@usuario.com",
    "edicao": "/api/assinav1/edicao/ID_EDICAO/",
    "ativa": true,
    "nome": "Nome Usuário",
    "resetar_senha": true
}

Exemplo uso

curl -X POST "https://www.magtab.com/api/assinav1/edicaoavulsa/?api_key=03425d44943ffc5ac843c2b6c0b771d4ef57952f" \
-d '{"email":"dev@magtab.com","edicao":"/api/assinav1/edicao/1/"}' -H "Content-Type: application/json"

Ferramentas de auxílio ao desenvolvedor

Curl

Plugin restClient para Firefox

Ajuda e suporte

Caso tenha dúvidas ou eventuais problemas, você deverá encaminhar um email para suporte@magtab.com.

Não encontrou o
que procurava?

Converse conosco para receber uma resposta
personalizada ou para obter assistência.

Quero saber mais sobre...

Leitores