Seja um Herói: Crie a Sua Própria Aplicação com a API Quire

Última atualização: 28 de maio de 2026

Resumo: A API OAuth 2.0 do Quire permite que a sua aplicação atue na conta Quire de um utilizador sem guardar a sua palavra-passe. Vai precisar de uma aplicação OAuth registada (ID de cliente, segredo, URL de Redirecionamento), um fluxo de autorização em quatro passos (configurar, redirecionar, processar resposta, trocar código por token) e um ciclo de token de atualização, pois os tokens de acesso expiram após uma hora.

Criar uma aplicação que lê ou modifica dados do Quire de um utilizador começa com uma decisão: como autenticar sem nunca ver a palavra-passe do utilizador? A API Quire responde a isso com OAuth 2.0. Este artigo percorre a configuração da aplicação OAuth, o fluxo de autorização em quatro passos, o ciclo de token de acesso e atualização, e as formas mais comuns de os programadores errarem na primeira implementação.

A versão 1.0.0 da OpenAPI do Quire foi lançada em outubro de 2019 e mantém-se estável. Com o OAuth, os utilizadores autorizam a sua aplicação a aceder ao conteúdo Quire deles (tarefas, projetos, comentários, atribuições, tags, data limite) sem que toque nas suas credenciais. O utilizador pode revogar esse acesso a qualquer altura sem alterar a sua palavra-passe — é por isso que as integrações que guardam palavras-passe eram um antipadrão de segurança antes de o OAuth as tornar desnecessárias.

Qual abordagem de integração do Quire se adequa ao seu caso de uso?

Antes de configurar a API OAuth, certifique-se de que a API é de facto a ferramenta certa. O Quire dispõe de quatro superfícies de integração suportadas em 2026, e cada uma resolve problemas diferentes.

Se estiver a criar uma integração de aplicação típica (aplicação móvel, painel web, serviço de sincronização), a API OAuth é o que precisa. O restante deste artigo assume que está nesse caminho.

Como configurar uma aplicação OAuth para a API Quire?

Para usar a API Quire, terá de criar uma aplicação OAuth.

Criar a sua aplicação OAuth do Quire

Precisa de estar com sessão iniciada na sua conta do Quire para criar uma aplicação.

1. Aceda à consola de programador do Quire e clique no botão Criar nova aplicação.

2. Escolha a Organização Quire à qual a sua aplicação pertence; os membros da organização poderão ver e editar todas as Aplicações pertencentes à organização selecionada.

3. Dê um nome à sua aplicação e defina a URL de Redirecionamento — falaremos sobre o papel da URL de Redirecionamento mais à frente. Por agora, pode usar o seguinte URL:

   http://localhost:3000/callback

4. Clique no botão Criar nova aplicação; a sua nova aplicação OAuth será apresentada na página da consola de programador, onde poderá configurá-la em detalhe.

Em resumo, deve ter estas três informações:

• ID do Cliente de Desenvolvimento: :wJoMEodI4fSSR54pfNwIuIzLnaJ
• Segredo do Cliente de Desenvolvimento: eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
• URL de Callback: http://localhost:3000/callback

Como configurar o ambiente de desenvolvimento para a API Quire?

Passo 1. Configurar a Sua Aplicação

Guarde as informações de configuração da aplicação no seu código.

const clientId = ':wJoMEodI4fSSR54pfNwIuIzLnaJ';
const clientSecret = 'eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex';
const redirectURI = 'http://localhost:3000/callback';
  
const authorizationUrl = 'https://quire.io/oauth';
const tokenUrl = 'https://quire.io/oauth/token';
const apiUrl = 'https://quire.io/api';

Passo 2. Redirecionar o Utilizador para Autorizar a Aplicação no Quire

Gere um URL de autorização para onde irá redirecionar os seus utilizadores, apontando para o endpoint OAuth do Quire. Será apresentada uma página web onde os utilizadores com sessão iniciada no Quire podem autorizar a sua aplicação a aceder ao seu conteúdo.

URL de exemplo:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri

Um exemplo de ligação de autorização pode ter o seguinte aspeto:

var http = require('http');
var url = require('url');
var server = http.createServer(function (req, res) { 
    var uri = url.parse(req.url, true);
    if (uri.pathname == '/') {        
        //..    
    } else if (uri.pathname == "/install") {
        var authUrl = authorizationUrl 
            + '?client_id=' + clientId 
            + '&redirect_uri=' + encodeURIComponent(redirectURI);
        res.writeHead(200, { 'Content-Type': 'text/html' });
        res.write(
             '<html><body>' 
            + '<a href="' + authUrl + '">Connect Quire</a>' 
         + '</body></html>');
        res.end();

    } else if (uri.pathname == "/callback") {
        //...
    }
});
server.listen(3000);

O parâmetro state é uma string aleatória usada para prevenir ataques CSRF (Cross-Site Request Forgery). Deve gerar uma string de caracteres aleatória. Será devolvida à sua aplicação, sem alterações, no Passo 3. A sua aplicação deve validar este valor. Embora seja opcional, recomendamos fortemente a sua inclusão.

URL de exemplo:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri&state=lpcl9v94z

Passo 3. Processar a Resposta do Servidor OAuth 2.0

O servidor OAuth 2.0 responde ao pedido de acesso da sua aplicação utilizando o URL especificado em redirect_uri.

Se o utilizador aprovar o pedido de acesso, a resposta contém um código de autorização. Se o utilizador não aprovar o pedido, a resposta contém uma mensagem de erro. O código de autorização ou a mensagem de erro devolvidos ao servidor web aparecem na string de consulta, conforme mostrado abaixo:

Uma resposta de erro:

http://localhost:3000/callback?error=access_denied

Uma resposta com código de autorização:

http://localhost:3000/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Um exemplo de callback pode ter o seguinte aspeto:

//...
} else if (uri.pathname == "/callback") {
   var result = uri.query;
   var message = 'Auth fail';
   if (result["error_description"] != null) {
       message = result["error_description"];
       if (result["error"] == 'access_denied') {
           //display reject message
       }
       messageView(res, message);
   } else if (result["code"] != null) {
       return exchangeAccessToken(result["code"])
       .then(function(data) {
            var token = data['access_token'];
            message = token != null ? 'Success': 'Fail';
            messageView(res, message);
        });
   }
}

Quando o utilizador for redirecionado de volta para o redirect_uri da sua aplicação, um parâmetro code e um parâmetro state também estarão presentes nos parâmetros da string de consulta. O state é o seu token anti-CSRF para validar o pedido.

Extraia o código e o state dos parâmetros da string de consulta. O state pode ser validado neste ponto.

Um exemplo de validação pode ter o seguinte aspeto:

} else if (result["code"] != null) {
    if (result["state"] != stateFromSession(res))
        return messageView(res, 'invalid state');
            
    return exchangeAccessToken(result["code"])
    .then(function(data) {
         var token = data['access_token'];
         message = token != null ? 'Success': 'Fail';
         messageView(res, message);
     });
}

Passo 4. Trocar o código de autorização por um token de acesso

A sua aplicação precisa de fazer uma chamada POST ao endpoint de token com o código de autorização extraído e os parâmetros de pedido indicados abaixo.

Um exemplo de pedido de token de acesso pode ter o seguinte aspeto:

var request = require('request');
function exchangeAccessToken(code) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl,
            form: {
              grant_type: 'authorization_code',
              code: code,
              client_id: clientId,
              client_secret: clientSecret,
              redirect_uri: redirectURI
            }
          },
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

O token de acesso que recebe na resposta estará em formato JSON.

Exemplo de resposta:

{ 
  "access_token":"ACCESS_TOKEN", 
  "token_type": "bearer", 
  "expires_in":2592000, 
  "refresh_token":"REFRESH_TOKEN"
}

O token deve ser guardado de forma cuidadosa e permanente, pois é necessário para aceder a toda a API Quire.

Como fazer chamadas à API com o token de acesso do Quire?

A sua aplicação tem agora um token de acesso que pode ser usado para fazer chamadas à API em nome do utilizador.

Chamar a API

Faça a chamada à API passando o token de acesso como bearer token no cabeçalho do pedido.

Um exemplo de chamada à API pode ter o seguinte aspeto:

function getCurrentUser(token) {
    return new Promise(function(resolve, reject){
        request.get({
            url: apiUrl + '/user/id/me', 
            headers: {
              "Authorization": "Bearer " + token
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

Exemplo de resposta:

{
  "email": "john@gmail.cc",
  "website": "https://coolwebsites.com",
  "id": "My_ID",
  "description": "This is *cool*!",
  "url": "https://quire.io/u/My_ID",
  "nameText": "My Name",
  "nameHtml": "My Name",
  "descriptionText": "This is cool!",
  "descriptionHtml": "This is <i>cool</i>!",
  "image": "https://quire.s3.amazonaws.com/oid/image.jpg",
  "iconColor": "37",
  "name": "My Name",
  "oid": "Dyh2YkFcu9uLgLFIeN1kB4Ld"
}

Como atualizar um token de acesso expirado da API Quire?

Um token de acesso é intencionalmente concebido apenas para uso de curta duração. Este é um mecanismo de segurança importante do OAuth 2.0. Ao usar o Authorization Code Grant Flow, os tokens de acesso têm uma duração padrão de uma hora.

Quando um token de acesso expira, será devolvido um erro HTTP 401:

{ 
  code: 401, 
  message: 'Invalid or expired token.' 
}

A sua aplicação terá de atualizar o token de acesso.
function refreshToken(refreshToken) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl, 
            form: {
              grant_type: 'refresh_token',
              refresh_token: refreshToken,
              client_id: clientId,
              client_secret: clientSecret
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

Em alternativa, a sua aplicação pode redirecionar o utilizador para o fluxo de autenticação.

Quais são os erros mais comuns dos programadores com a API Quire?

Após observar equipas a desenvolver sobre a API Quire, os mesmos cinco problemas surgem repetidamente. Nenhum é subtil; todos são evitáveis.

1. Guardar o segredo do cliente em código do lado do cliente. O segredo do cliente é exatamente isso, um segredo. Se ficar exposto num binário de aplicação móvel ou num bundle de browser, qualquer pessoa pode extraí-lo e personificar a sua aplicação. O segredo deve existir apenas num servidor que controla. Se a sua aplicação for puramente do lado do cliente (single-page app, móvel), use o fluxo PKCE do OAuth 2.0 em vez de incorporar o segredo.

2. Esquecer de validar o parâmetro state. O parâmetro state existe para prevenir ataques CSRF. Se não o validar no callback, criou uma vulnerabilidade que um site malicioso pode usar para associar silenciosamente uma conta Quire à sessão da aplicação de um atacante. Gere o state por pedido, guarde-o na sessão e rejeite qualquer callback onde o state devolvido não corresponda.

3. Tratar o token de acesso como permanente. Os tokens de acesso expiram após uma hora. As Aplicações que guardam o token e nunca o atualizam funcionam bem no Dia 1 e falham silenciosamente no Dia 2. Construa o ciclo de token de atualização antes de lançar qualquer coisa, não como uma correção do "arranjar quando os utilizadores se queixarem".

4. Fazer polling à API para detetar alterações. O polling consome limite de taxa, latência e bateria. Se precisar de reagir a alterações no Quire, use webhooks. O webhook entrega o evento instantaneamente; a chamada à API que teria de fazer para detetar esse evento nunca precisa de acontecer.

5. Ignorar a lista de URLs de redirecionamento autorizadas. Cada registo de aplicação OAuth aceita uma lista de URLs de Redirecionamento. Se usar carateres universais ou não configurar a lista com precisão, um atacante pode registar o seu callback como destino de redirecionamento e intercetar códigos de autorização. Adicione apenas os URLs exatos que a sua aplicação utiliza.

Se estiver a desenvolver sobre a API pela primeira vez, a forma mais rápida de aprender os padrões é fazer fork de uma integração existente como o conector n8n e estudar como trata a autenticação, atualização de tokens e estados de erro.

Quando é que a API Quire não é a opção certa?

Três padrões em que deve optar por uma superfície de integração diferente.

• Só precisa de reagir a eventos, não de consultar o estado. Os Webhooks são mais simples, baseados em push e não requerem autorização do utilizador para Assinaturas de eventos de leitura. Se o objetivo da sua aplicação é "notificar-me quando algo acontece", use Webhooks, não a API.
• Está a criar uma integração com o Claude ou outro agente LLM. O servidor MCP do Quire é a superfície certa aqui. Trata da autenticação, inclui um esquema padrão e significa que não escreve código OAuth. O MCP foi criado especificamente para isto; implementar a sua própria solução com a API OAuth é mais trabalho para o mesmo resultado.
• Está a fazer uma exportação de dados pontual. Se só precisa de extrair os dados de um projeto uma vez para análise ou backup, a Integração n8n ou uma exportação manual em CSV poupam-lhe uma semana de desenvolvimento.

Se nenhuma dessas situações se aplica, a API OAuth é a sua ferramenta.

Perguntas Frequentes

A API Quire requer um plano Quire pago?

Não. A API Quire está disponível em todos os planos, incluindo o nível gratuito. Os limites de taxa aplicam-se em todos os planos; consulte a documentação da API para os limites atuais por aplicação.

Que linguagens de programação suporta a API Quire?

A API é baseada em HTTP com corpos de pedido e resposta em JSON, pelo que qualquer linguagem com um cliente HTTP e um analisador JSON funciona. Os exemplos neste artigo são em JavaScript, mas o mesmo fluxo funciona de forma idêntica em Python, Go, Ruby, PHP e qualquer outra linguagem. Não existe uma biblioteca de cliente oficial; a superfície da API é suficientemente pequena para que um simples invólucro em torno do cliente HTTP da sua linguagem seja o padrão habitual.

Quanto tempo duram os tokens de acesso do Quire?

Os tokens de acesso expiram após uma hora por defeito. Os tokens de atualização duram mais tempo e podem ser usados para obter novos tokens de acesso sem voltar a solicitar autorização ao utilizador. Incorpore o ciclo de token de atualização na sua aplicação desde o Dia 1.

Posso usar a API Quire apenas para acesso de leitura?

Sim. Os âmbitos OAuth permitem-lhe solicitar apenas as permissões de que a sua aplicação necessita. Se a sua aplicação apenas lê tarefas, solicite âmbitos de leitura. Os utilizadores do Quire verão os âmbitos solicitados na página de autorização e podem recusar se o pedido parecer excessivo, por isso solicitar demasiadas permissões prejudica a conversão.

Qual é a diferença entre a API Quire e o servidor MCP do Quire?

A API é uma superfície REST de uso geral para qualquer aplicação que pretenda ler ou modificar dados do Quire em nome de um utilizador. O servidor MCP foi criado especificamente para o Claude e outros agentes LLM: trata da autenticação, expõe um esquema de ferramentas padrão e significa que não escreve código OAuth. Use a API para integrações de aplicações tradicionais; use o MCP para integrações de agentes LLM.

Para onde ir a partir daqui?

Este é o fluxo OAuth 2.0 completo para a API Quire: configuração da aplicação OAuth, autorização em quatro passos, utilização do token de acesso e o ciclo de atualização. A razão mais comum pela qual os programadores lançam uma integração funcional que falha dois dias depois é tratar o ciclo de atualização como uma correção futura em vez de o incorporar desde o Dia 1.

Comece na consola de programador do Quire ou leia a referência completa da API. Se preferir não escrever código OAuth, o servidor MCP do Quire trata da autenticação por si e é a escolha certa para integrações de agentes LLM. Para integrações orientadas a eventos, os webhooks são geralmente mais adequados do que o padrão de polling com que a maioria das primeiras integrações de API acaba.