developers · Oct 1, 2019

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

✦
Traduzido por IA
· Ver em inglês

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 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.

Índice

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 precisar de... Use Porquê
Ler ou modificar dados do Quire em nome de um utilizador na sua própria aplicação API OAuth do Quire (este artigo) Autorização do utilizador, acesso CRUD completo, sem necessidade de polling
Reagir a eventos no Quire (tarefa criada, estado alterado, comentário adicionado) Quire Webhooks Baseado em push, sem sobrecarga de polling, configuração simples
Ligar o Quire a um agente Claude ou outro agente de IA Servidor MCP do Quire Protocolo padrão para ferramentas LLM, inclui servidor pré-construído
Integrar o Quire num fluxo de automação ou BI API OAuth mais n8n ou Power BI Pipelines consolidadas, menos código personalizado

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. Quire developer app console

  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. Quire app organização

  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. Quire app list

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

Quire app credentials

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.

Parâmetro Valor
grant_type authorization_code
code {your-authorization-code}
client_id {your-client-ID}
client_secret {your-client-secret}
redirect_uri Obrigatório se especificou redirect_uri no Passo 2. O valor deve ser idêntico ao utilizado nesse passo.

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

Jimmy Shiau
Software Engineer