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

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

TL;DR: A API OAuth 2.0 do Quire permite que a sua aplicação atue na conta Quire de um utilizador sem armazenar 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, tratar resposta, trocar código por token) e um ciclo de atualização de tokens, pois os tokens de acesso expiram após uma hora.

Criar uma aplicação que lê ou modifica dados 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 como os programadores erram na primeira versão.

A versão 1.0.0 da OpenAPI do Quire foi lançada em outubro de 2019 e manteve-se estável. Com OAuth, os utilizadores autorizam a sua aplicação a aceder ao conteúdo Quire deles (tarefas, projetos, comentários, atribuições, tags, datas limite) sem que toque nas credenciais. O utilizador pode revogar esse acesso em qualquer momento sem alterar a palavra-passe — razão pela qual as integrações que armazenavam 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 tem quatro superfícies de integração suportadas em 2026, e cada uma resolve problemas diferentes.

Se está a construir 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 resto deste artigo pressupõe 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 ter sessão iniciada na sua conta Quire para criar uma aplicação.

1. Aceda à consola de aplicações do 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 podem ver/editar todas as aplicações que pertencem à organização selecionada.

3. Dê um nome à sua aplicação e uma URL de Redirecionamento; discutiremos o papel da URL de Redirecionamento mais adiante. Por agora pode indicar a seguinte URL:

   http://localhost:3000/callback

4. Clique no botão Criar nova aplicação; a aplicação OAuth recém-criada será apresentada na página da consola do programador, permitindo-lhe configurá-la melhor.

Em resumo, deverá 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 seu ambiente de desenvolvimento para a API Quire?

Passo 1. Configurar a Sua Aplicação

Guarde as informações de configuração da aplicação na própria aplicação.

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 vai redirecionar os seus utilizadores para o endpoint URI OAuth do Quire. Isto mostrará uma página web onde os utilizadores Quire com sessão iniciada podem autorizar a sua aplicação a aceder ao conteúdo deles.

URL de exemplo:

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

Um exemplo de vista de ligação de autorização pode ter este 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 de Cross-Site Request Forgery (CSRF). Deve gerar aleatoriamente uma cadeia de caracteres. Será passado de volta à sua aplicação, sem alterações, no Passo 3. A sua aplicação deve validar este valor. Embora seja opcional, recomendamos vivamente incluir este parâmetro.

URL de exemplo:

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

Passo 3. Tratar a resposta do servidor OAuth 2.0

O servidor OAuth 2.0 responde ao pedido de acesso da sua aplicação usando 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 query string, conforme mostrado abaixo:

Uma resposta de erro:

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

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

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

Um exemplo de callback pode ter este 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 é redirecionado de volta para o redirect_uri da sua aplicação, um parâmetro code e state também estarão presentes nos parâmetros da querystring. O state é o seu token anti-falsificação CSRF para validar o pedido.

Extraia o code e o state dos parâmetros da query string. O state pode ser validado neste ponto.

Um exemplo de validação pode ter este 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 pelo token de acesso

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

Um exemplo de pedido de token de acesso pode ter este 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 recebido em 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 com cuidado e de forma 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 este 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 da API Quire expirado?

Um token de acesso é intencionalmente concebido para uso de curto prazo. Este é um mecanismo de segurança importante do OAuth 2.0. Ao usar o Fluxo de Concessão de Código de Autorização, os tokens de acesso têm um tempo de vida de uma hora por defeito.

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

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

A sua aplicação precisará 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 que os programadores cometem com a API Quire?

Após observar equipas a desenvolver contra a API Quire, os mesmos cinco problemas repetem-se. Nenhum é subtil; todos são evitáveis.

1. Armazenar o segredo do cliente em código do lado do cliente. O segredo do cliente é exatamente isso, um segredo. Se acabar num binário de aplicação móvel ou num bundle de browser, qualquer pessoa pode extraí-lo e fazer-se passar pela sua aplicação. O segredo deve existir apenas num servidor que controla. Se a sua aplicação é 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 ignorar a sua validação no callback, deixou 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 armazenam o token e nunca o atualizam funcionam bem no Dia 1 e falham silenciosamente no Dia 2. Construa o ciclo de atualização de tokens antes de lançar qualquer coisa, não como um patch de "corrigir quando os utilizadores reclamarem".

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 em vez disso. O Webhooks entrega o evento instantaneamente; a chamada à API que teria de fazer para detetar esse evento nunca precisa de acontecer.

5. Ignorar a lista de permissões de URL de Redirecionamento. Cada registo de aplicação OAuth aceita uma lista de URLs de Redirecionamento. Se usar wildcard ou não configurar com precisão, um atacante pode registar o seu callback como o alvo de redirecionamento e intercetar códigos de autorização. Adicione apenas os URLs exatos que a sua aplicação realmente usa.

Se está a desenvolver contra 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, a atualização e os estados de erro.

Quando é que a API Quire não é a escolha 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 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 trabalho da sua aplicação é "avise-me quando algo acontecer", use webhooks, não a API.
• Está a construir uma integração com Claude ou agente LLM. O servidor MCP do Quire é a superfície certa aqui. Trata da autenticação, fornece um esquema padrão e significa que não escreve código OAuth. O MCP é criado especificamente para isso; fazer o mesmo com a API OAuth é mais trabalho para o mesmo resultado.
• Está a fazer uma exportação pontual de dados. Se apenas precisa de extrair os dados de um projeto uma vez para análise ou backup, a Integração n8n ou uma exportação CSV manual poupar-lhe-á uma semana de desenvolvimento.

Se nenhum desses 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 a 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 cliente oficial; a superfície da API é suficientemente pequena para que um wrapper simples à volta do cliente HTTP da sua linguagem seja o padrão comum.

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 ao utilizador. Incorpore o ciclo de atualização de tokens 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 em excesso 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 é 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.

Por onde continuar?

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 posterior em vez de o incorporar desde o Dia 1.

Comece na consola de aplicações do 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 por eventos, os webhooks são normalmente uma melhor opção do que o padrão de polling com que a maioria das integrações de API de primeira vez acabam.