Atestador.com.br - API - Documentação

A API do Atestador.com.br é muito simples de ser utilizada por qualquer linguagem de programação.

Vamos explicar o conceito de utilização e o código de funcionamento utilizando linguagens como PHP e C#, mas você pode facilmente alterar para outras linguagens. Se desejar contribuir com essa documentação, envie-nos por e-mail o código de funcionamento em outras linguagens e publicaremos aqui com o seu nome nos créditos.

É desaconselhado o uso da linguagem javascript para acessar a API, pois a senha de autenticação fica exposta no código, podendo ser facilmente usada por outros desenvolvedores sem registro, o que consumiria os seus créditos no site.

Autor: Marcelo Gomes
Contato: api@atestador.com.br
Versão Atual: 1.0.3
Versão da Documentação 1.1.0
Criado em: 25/03/2013
Última Modificação: 10/04/2013

O acesso a API do Atestador.com.br pode ser feito enviando variáveis pré-definidas para uma url específica. Os métodos suportados são GET e POST.

O retorno da API é sempre em formato JSON.


Para acessar a API é necessário que você seja um usuário registrado no site e que tenha criado uma senha para acesso da API, pelo link de "Meu Perfil" que você encontrará após efetuar o login no site. No seu perfil, você também encontrará o HASH necessário para se identificar na API.

Formato

O formato de acesso basicamente consiste em 3 níveis

Item Descrição
URL A url básica de acesso da API
Comando O nome do comando que define a ação que a API deve executar.
Opções Uma sequência de variáveis que informam a API como ela deve agir para o comando especificado.

URL da API:

http://www.atestador.com.br/api/comando/?variavel1=conteudo1 &variavel2=conteudo2 &variavel3=conteudo3

Se desejar acessar em modo seguro, você pode utilizar HTTPS no lugar do HTTP

Comandos

A relação de comandos existentes na API

Comando Descrição
captura Gera uma captura imediata da url solicitada.
Consome 1 crédito.
agenda Verifica e faz o agendamento de uma captura da url solicitada para a data e hora especificada.
Consome 1 crédito.
exclui Exclui um ou mais agendamentos feitos previamente, desde que não tenham sido processados ainda.
Devolve 1 crédito para cada agendamento excluído.
lista Lista os agendamentos feitos previamente, estando ou não processados.
Não consome crédito.
consulta Consulta os dados de um certificado específico que tenha sido gerado pelo próprio usuário.
Não consome crédito.

Retornos comuns

Os retornos variam de acordo com cada comando, porém há os retornos padrões

Retorno Descrição
comando Nome do comando utilizado. Geralmente é igual ao comando chamado na url.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
creditos_utilizados Número de créditos utilizados pelo comando executado. Normalmente 0 ou 1.
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.

http://www.atestador.com.br/api/captura/?apihash=SUAHASH &apipass=SUASENHA &url=endereco_do_site_com_urlencode

Parâmetros

Parâmetros utilizados para esse comando

Parâmetro Descrição
apihash Sua HASH de usuário para se identificar na API. Pode ser encontrada no link "Meu Perfil" abaixo da sua foto após o login.
apipass Sua senha de acesso na API. Pode ser criada ou recriada no link "Meu Perfil" após o seu login.
url O endereço da página que pretende capturar. A página deve ser pública, de acesso direto a qualquer pessoa, sem necessitar de login ou cliques específicos para ser mostrada. Deve-se usar URLENCODE para ser enviada como parâmetro.

Retornos

Itens retornados para esse comando

Retorno Descrição
comando Nome do comando utilizado. Geralmente será 'captura'.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
creditos_utilizados Número de créditos utilizados pelo comando executado. Normalmente 0 ou 1.
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.
url_solicitada Endereço de página solicitado pelo parâmetro URL. É retornado apenas se "sucesso=1".
url_produzida Endereço de página que gerou a captura. Normalmente será igual ao parâmetro URL, a não ser que o site tenha redirecionamentos internos que mudem essa opção. É retornado apenas se "sucesso=1".
cod_validacao O código de validação gerado para o certificado. É retornado apenas se "sucesso=1".

Exemplo de código

Segue exemplo de código para a chamada deste comando. Usuário e senha neste exemplo são fictícios.

<?php
$atestador_hash = "1234";
$atestador_pass = "zyc989%a";
$atestar_url = "http://www.google.com.br";
$retorno = file_get_contents("http://www.atestador.com.br/api/captura/?" .
           "apihash=" . $atestador_hash .
           "&apipass=" . $atestador_pass .
           "&url=" . urlencode($atestar_url) );
$atestado = json_decode($retorno, true);
if($atestado["sucesso"]) {
    echo "A URL solicitada " . $atestado["url_solicitada"];
    echo " foi produzida pelo endereço " . $atestado["url_produzida"];
    echo " e gerou o certificado código " . $atestado["cod_validacao"];
    echo " utilizando " . $atestado["creditos_utilizados"] . " crédito.";
} else {
    echo $atestado["erro"] . " - " . $atestado["erro_mensagem"];
}
?>
string atestador_hash = "1234";
string atestador_pass = "zyc989%a";
string atestar_url = "http://www.google.com.br";
string url = "http://www.atestador.com.br/api/captura/?";
string urlCompleta = url + "apihash=" + atestador_hash + "&apipass=" + atestador_pass + "&url=" +  atestar_url;

var webClient = new WebClient();

webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
var result = webClient.DownloadString(urlCompleta);

// Sem usar JSON.NET
var jsonSerializer = new JavaScriptSerializer();
var obj = jsonSerializer.Deserialize(result);

if (Convert.ToBoolean(obj["sucesso"])) {
    Console.WriteLine("A URL solicitada " + obj["url_solicitada"]);
    Console.WriteLine("foi produzida pelo endereco " + obj["url_produzida"]);
    Console.WriteLine("e gerou o certificado código " + obj["cod_validacao"]);
    Console.WriteLine("utilizando " + obj["creditos_utilizados"] + " créditos.");
} else {
    Console.WriteLine(obj["erro"] + " - " + obj["erro_mensagem"]);
}

// Usando JSON.NET
dynamic dynObj = JsonConvert.DeserializeObject(result);

if (Convert.ToBoolean(dynObj.sucesso)) {
    Console.WriteLine("A URL solicitada " + dynObj.url_solicitada);
    Console.WriteLine("foi produzida pelo endereco " + dynObj.url_produzida);
    Console.WriteLine("e gerou o certificado código " + dynObj.cod_validacao);
    Console.WriteLine("utilizando " + dynObj.creditos_utilizados + " créditos.");
} else {
    Console.WriteLine(dynObj.erro + " - " + dynObj.erro_mensagem);
}

Console.ReadLine();

http://www.atestador.com.br/api/agenda/?apihash=SUAHASH &apipass=SUASENHA &data=dd-mm-aaaa &hora=hh:mm &url=endereco_do_site_com_urlencode

Parâmetros

Parâmetros utilizados para esse comando

Parâmetro Descrição
apihash Sua HASH de usuário para se identificar na API. Pode ser encontrada no link "Meu Perfil" abaixo da sua foto após o login.
apipass Sua senha de acesso na API. Pode ser criada ou recriada no link "Meu Perfil" após o seu login.
data Data de agendamento para captura. Deve ser no formato dd-mm-aaaa. Não deve ser anterior a data atual e nem posterior a 60 dias.
hora Hora de agendamento para captura. Deve ser no formato hh:mm (não deve conter segundos). Se a data for "hoje", não deve ser anterior aos próximos 10 minutos. Não deve ser posterior a 60 dias exatos.
url O endereço da página que pretende capturar. A página deve ser pública, de acesso direto a qualquer pessoa, sem necessitar de login ou cliques específicos para ser mostrada. Deve-se usar URLENCODE para ser enviada como parâmetro.

Retornos

Itens retornados para esse comando

Retorno Descrição
comando Nome do comando utilizado. Geralmente será 'agenda'.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
creditos_utilizados Número de créditos utilizados pelo comando executado. Normalmente 0 ou 1.
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.
url_solicitada Endereço de página solicitado pelo parâmetro URL. É retornado apenas se "sucesso=1".
url_produzida Endereço de página que gerou a captura. Normalmente será igual ao parâmetro URL, a não ser que o site tenha redirecionamentos internos que mudem essa opção. É retornado apenas se "sucesso=1".
cod_agendamento O código de agendamento gerado para a posterior captura. É retornado apenas se "sucesso=1" e não significa o código de validação. O código de agendamento é um número interno único e sequencial, que permite o acesso futuro a esse agendamento para consulta de dados ou exclusão.
data_hora Confirmação da data e hora do agendamento no formato "dd-mm-aaaa hh:mm:ss". É retornado apenas se "sucesso=1".
acao Confirmação da ação de agendamento e retorna 'agendado'. É retornado apenas se "sucesso=1".

Exemplo de código

Segue exemplo de código para a chamada deste comando. Usuário e senha neste exemplo são fictícios.

<?php
$atestador_hash = "1234";
$atestador_pass = "zyc989%a";
$data = date("d-m-Y", strtotime("+1 week")); // o mesmo dia na próxima semana
$hora = "11:00"; // 11h da manhã
$atestar_url = "http://www.google.com.br";
$retorno = file_get_contents("http://www.atestador.com.br/api/agenda/?" .
           "apihash=" . $atestador_hash .
           "&apipass=" . $atestador_pass .
           "&data=" . $data .
           "&hora=" . $hora .
           "&url=" . urlencode($atestar_url) );
$atestado = json_decode($retorno, true);
if($atestado["sucesso"]) {
    echo "A URL solicitada " . $atestado["url_solicitada"];
    echo " será produzida pelo endereço " . $atestado["url_produzida"];
    echo " na seguinte data e hora " . $atestado["data_hora"];
    echo ". O agendamento gerou o código " . $atestado["cod_agendamento"];
    echo " utilizando " . $atestado["creditos_utilizados"] . " crédito.";
    echo " A ação de confirmação retornou " . $atestado["acao"];
} else {
    echo $atestado["erro"] . " - " . $atestado["erro_mensagem"];
}
?>
string atestador_hash = "1234";
string atestador_pass = "zyc989%a";
string atestar_url = "http://www.google.com.br";
string url = "http://www.atestador.com.br/api/agenda/?";
string data = "19-05-2013";
string hora = "11:00";
string urlCompleta = url + "apihash=" + atestador_hash + "&apipass=" + atestador_pass + "&url=" +  atestar_url + "&data=" + data + "&hora=" + hora;

var webClient = new WebClient();

webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
var result = webClient.DownloadString(urlCompleta);

var jsonSerializer = new JavaScriptSerializer();
var obj = jsonSerializer.Deserialize(result);

if (Convert.ToBoolean(obj["sucesso"])) {
    Console.WriteLine("A URL solicitada " + obj["url_solicitada"]);
    Console.WriteLine("será produzida pelo endereco " + obj["url_produzida"]);
    Console.WriteLine("na seguinte data e hora " + obj["data_hora"]);
    Console.WriteLine("O agendamento gerou o código " + obj["cod_agendamento"]);
    Console.WriteLine("utilizando " + obj["creditos_utilizados"] + " créditos");
    Console.WriteLine("A ação de confirmação retornou " + obj["acao"]);
} else {
    Console.WriteLine(obj["erro"] + " - " + obj["erro_mensagem"]);
}
Console.ReadLine();

http://www.atestador.com.br/api/exclui/?apihash=SUAHASH &apipass=SUASENHA &codigos=codigos,dos,agendamentos,separados,por,virgulas

Parâmetros

Parâmetros utilizados para esse comando

Parâmetro Descrição
apihash Sua HASH de usuário para se identificar na API. Pode ser encontrada no link "Meu Perfil" abaixo da sua foto após o login.
apipass Sua senha de acesso na API. Pode ser criada ou recriada no link "Meu Perfil" após o seu login.
codigos Os códigos retornados pelos agendamentos a serem excluídos, separados por vírgulas. Caso queira excluir apenas 1 agendamento, basta informar o único código, sem necessidade de virgula.

Retornos

Itens retornados para esse comando

Retorno Descrição
comando Nome do comando utilizado. Geralmente será 'exclui'.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.
creditos_devolvidos Número de créditos devolvidos pelo comando executado. Normalmente o mesmo número de itens solicitados é retornado se "sucesso=1". Se der erro, retorna 0.
acao Confirmação da ação solicitada, retornando 'excluido'. É retornado apenas se "sucesso=1".

Exemplo de código

Segue exemplo de código para a chamada deste comando. Usuário e senha neste exemplo são fictícios.

<?php
$atestador_hash = "1234";
$atestador_pass = "zyc989%a";
$codigos = "54,87,219,347";
$retorno = file_get_contents("http://www.atestador.com.br/api/exclui/?" .
           "apihash=" . $atestador_hash .
           "&apipass=" . $atestador_pass .
           "&codigos=" . $codigos );
$atestado = json_decode($retorno, true);
if($atestado["sucesso"]) {
    echo "Os códigos solicitados foram excluidos devolvendo " . $atestado["creditos_devolvidos"] . " créditos para a sua conta.";
} else {
    echo $atestado["erro"] . " - " . $atestado["erro_mensagem"];
}
?>
string atestador_hash = "1234";
string atestador_pass = "zyc989%a";
string codigos = "54,87,219,347";
string url = "http://www.atestador.com.br/api/exclui/?";
string urlCompleta = url + "apihash=" + atestador_hash + "&apipass=" + atestador_pass + "&codigos=" + codigos;

var webClient = new WebClient();

webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
var result = webClient.DownloadString(urlCompleta);

var jsonSerializer = new JavaScriptSerializer();
var obj = jsonSerializer.Deserialize(result);

if (Convert.ToBoolean(obj["sucesso"])) {
    Console.WriteLine("Os códigos solicitados foram excluidos devolvendo " + obj["creditos_devolvidos"] + " créditos para a sua conta.");
}else{
    Console.WriteLine(obj["erro"] + " - " + obj["erro_mensagem"]);
}

Console.ReadLine();

http://www.atestador.com.br/api/lista/?apihash=SUAHASH &apipass=SUASENHA &produzido=0/1 &codigo=xx &limite=40 &ordem=ASC/DESC

Parâmetros

Parâmetros utilizados para esse comando

Parâmetro Descrição
apihash Sua HASH de usuário para se identificar na API. Pode ser encontrada no link "Meu Perfil" abaixo da sua foto após o login.
apipass Sua senha de acesso na API. Pode ser criada ou recriada no link "Meu Perfil" após o seu login.
produzido 0 - Não tenha sido produzido
1 - Já tenha sido produzido
Se omitido ou diferente de 0/1 - Retorna os produzidos e não produzidos
ordem ASC - Ordena de forma ascendente pelo código
DESC (padrão) - Ordena de forma descendente os códigos.
limite nn - Retorna o número de agendamentos definidos. Se omitido, o valor padrão é 30.
codigo nn - Código do agendamento. Se utilizado, traz informações específicas apenas desse agendamento. Se utilizado, os parâmetros produzido, ordem e limite não são necessários.

Retornos

Itens retornados para esse comando

Este retorno é encapsulado no objeto lista
Retorno Descrição
comando Nome do comando utilizado. Geralmente será 'lista'.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
creditos_utilizados Número de créditos utilizados pelo comando executado. Normalmente 0 ou 1.
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.
codigo Código do agendamento.
ativo 0 - Suspenso
1 - Ativo
processado 0 - Não processado
1 - Processado
data_cadastro Data de cadastro do agendamento. Formato yyyy-mm-dd hh:mm:ss
data_agendamento Data agendada para captura. Formato yyyy-mm-dd hh:mm:ss
url_solicitada URL solicitada para captura.
url_a_fazer URL final identificada para a captura.
codigo_validacao O código de validação gerado para o certificado, se o agendamento já foi processado. Retorna vazio ( "" ) se não foi processado.
mensagem Mensagem de erro caso captura já tenha sido processada e, na ocasião, o site estava fora do ar.
api_ou_painel Retorna por onde foi cadastrado o agendamento. Utilizando a "API" ou "Painel".
credito_usado Retorna o tipo de crédito utilizado para fazer o agendamento. Se foi "Fixo" (para créditos individuais) ou "Mensal" (para planos mensais).

Exemplo de código

Segue exemplo de código para a chamada deste comando. Usuário e senha neste exemplo são fictícios.

<?php
$atestador_hash = "1234";
$atestador_pass = "zyc989%a";
$limite = 20;
$ordenacao = "ASC";
$produzido = 0;
$retorno = file_get_contents("http://www.atestador.com.br/api/lista/?" .
           "apihash=" . $atestador_hash .
           "&apipass=" . $atestador_pass .
           "&limite=" . $limite .
           "&ordem=" . $ordenacao .
           "&produzido=" . $produzido );
$atestado = json_decode($retorno, true);
if($atestado["sucesso"]) {
    echo "<pre>";
    foreach($atestado["lista"] as $item) {
        print_r($item);
        // Uso direto: $item["codigo"] , $item["codigo_validacao"] , $item["url_a_fazer"] ... 
    }
    echo "</pre>";
} else {
    echo $atestado["erro"] . " - " . $atestado["erro_mensagem"];
}
?>
string atestador_hash = "1234";
string atestador_pass = "zyc989%a";
string limite = "20";
string ordenacao = "ASC";
string produzido = "0";
string url = "http://www.atestador.com.br/api/lista/?";
string urlCompleta = url + "apihash=" + atestador_hash + "&apipass=" + atestador_pass + "&limite=" + limite + "&ordem=" + ordenacao + "&produzido=" + produzido;

var webClient = new WebClient();

webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
var result = webClient.DownloadString(urlCompleta);

var jsonSerializer = new JavaScriptSerializer();
var obj = jsonSerializer.Deserialize(result);

if (Convert.ToBoolean(obj["sucesso"])){
    foreach(var item in obj["lista"]) {
        Console.WriteLine("Codigo ==> " + item["codigo"]);
        // Uso direto: item["codigo"] , item["codigo_validacao"] , item["url_a_fazer"] ...
    }
}else{
    Console.WriteLine(obj["erro"] + " - " + obj["erro_mensagem"]);
}
Console.ReadLine();

http://www.atestador.com.br/api/consulta/?apihash=SUAHASH &apipass=SUASENHA &validacao=codigo_de_validacao

Parâmetros

Parâmetros utilizados para esse comando

Parâmetro Descrição
apihash Sua HASH de usuário para se identificar na API. Pode ser encontrada no link "Meu Perfil" abaixo da sua foto após o login.
apipass Sua senha de acesso na API. Pode ser criada ou recriada no link "Meu Perfil" após o seu login.
validacao O código de validação do certificado a ser consultado.

Retornos

Itens retornados para esse comando

Retorno Descrição
comando Nome do comando utilizado. Geralmente será 'consulta'.
sucesso 1 - comando executado com sucesso
0 - erro
erro 0 - comando executado com sucesso
-1 - URL inválida
diferente de 0 - retorno Header da URL solicitada (404, por exemplo)
erro_mensagem Texto informativo sobre o tipo de erro causado, caso sucesso seja igual a 0.
codigo_validacao Código final do certificado emitido.
ativo 0 - Suspenso
1 - Ativo
data_agendamento Data de cadastro do agendamento. Formato yyyy-mm-dd hh:mm:ss
data_captura Data final real da captura. Formato yyyy-mm-dd hh:mm:ss
data_validade Data de validade do certificado da captura. Normalmente 1 ano após a data da captura. Formato yyyy-mm-dd hh:mm:ss
solicitante O nome do solicitante a ser impresso no certificado. Pode ser definido no link "Meu Perfil" abaixo da foto do usuário após o login no site.
url_solicitada URL solicitada para captura.
url_capturada URL final identificada para a captura.
api_ou_painel Retorna por onde foi cadastrado o agendamento. Utilizando a "API" ou "Painel".
credito_usado Retorna o tipo de crédito utilizado para fazer o agendamento. Se foi "Fixo" (para créditos individuais) ou "Mensal" (para planos mensais).
http_code O código do header da página capturada. Normalmente "200" se foi capturada com sucesso ou o código de erro da página no momento da captura.

Exemplo de código

Segue exemplo de código para a chamada deste comando. Usuário e senha neste exemplo são fictícios.

<?php
$atestador_hash = "1234";
$atestador_pass = "zyc989%a";
$certificado = "1234-A0987654-0321";
$retorno = file_get_contents("http://www.atestador.com.br/api/consulta/?" .
           "apihash=" . $atestador_hash .
           "&apipass=" . $atestador_pass .
           "&validacao=" . $certificado );
$atestado = json_decode($retorno, true);
if($atestado["sucesso"]) {
    if($atestado["http_code"] == "200") {
        echo "A URL solicitada  " . $atestado["url_solicitada"];
        echo " foi produzida pelo endereço " . $atestado["url_capturada"];
        echo " e gerou o certificado código " . $atestado["codigo_validacao"];
        echo " utilizando crédito " . $atestado["credito_usado"]. ".";
        echo " Foi solicitada via " . $atestado["api_ou_painel"];
        echo " pela empresa solicitante " . $atestado["solicitante"];
        echo ", produzida na data " . $atestado["data_captura"];
        echo " com validade até " . $atestado["data_validade"] . ".";
    } else {
        echo "A URL solicitada  " . $atestado["url_solicitada"];
        echo " e visualizada pelo endereço " . $atestado["url_capturada"];
        echo " produziu um código de erro de acesso " . $atestado["http_code"];
    }
} else {
    echo $atestado["erro"] . " - " . $atestado["erro_mensagem"];
}
?>
string atestador_hash = "1234";
string atestador_pass = "zyc989%a";
string certificado = "1234-A0987654-0321";
string url = "http://www.atestador.com.br/api/consulta/?";
string urlCompleta = url + "apihash=" + atestador_hash + "&apipass=" + atestador_pass + "&validacao=" + certificado;

var webClient = new WebClient();

webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
var result = webClient.DownloadString(urlCompleta);

var jsonSerializer = new JavaScriptSerializer();
var obj = jsonSerializer.Deserialize(result);

if (Convert.ToBoolean(obj["sucesso"])){
    if (obj["http_code"] == "200")    {
        Console.WriteLine("A URL solicitada " + obj["url_solicitada"]);
        Console.WriteLine("foi produzida pelo endereço " + obj["url_capturada"]);
        Console.WriteLine("e gerou o certificado código " + obj["codigo_validacao"]);
        Console.WriteLine("utilizando crédito " + obj["credito_usado"]);
        Console.WriteLine("Foi solicitada via " + obj["api_ou_painel"]);
        Console.WriteLine("pela empresa solicitante " + obj["solicitante"]);
        Console.WriteLine(", produzida na data " + obj["data_captura"]);
        Console.WriteLine("com validade até " + obj["data_validade"]);
    } else {
        Console.WriteLine("A URL solicitada " + obj["url_solicitada"]);
        Console.WriteLine("e visualizada pelo endereço " + obj["url_capturada"]);
        Console.WriteLine("produziu um código de erro de acesso " + obj["http_code"]);
    }
} else {
    Console.WriteLine(obj["erro"] + " - " + obj["erro_mensagem"]);
}
Console.ReadLine();