API Pública

Como começar

Há duas formas de obter uma chave:

• Integrações próprias — um administrador cria a chave em Definições → API, escolhendo o nome, as permissões e (se quiser) uma validade.
• Aplicações parceiras — se está a ligar uma aplicação já integrada com o Associados.app, use o fluxo de ligação. A chave é emitida automaticamente após o administrador dar consentimento, e aparece na mesma lista.

Uma chave dá acesso aos dados de uma única associação — a que a emitiu. Não é preciso identificar a associação nos pedidos: ela é determinada pela chave.

Autenticação

Todos os pedidos exigem uma chave de API, no cabeçalho Authorization ou x-api-key. As chaves começam por assoc_live_.

curl https://associados.app/api/public/v1/associates?search=silva \
  -H "Authorization: Bearer assoc_live_a1b2c3..."

# em alternativa
curl https://associados.app/api/public/v1/associates?search=silva \
  -H "x-api-key: assoc_live_a1b2c3..."

A chave é apresentada uma única vez, no momento em que é criada — guardamos apenas um hash, pelo que não é recuperável depois. Se a perder, é preciso emitir uma nova. Trate-a como uma palavra-passe: mantenha-a no servidor, nunca no código de uma aplicação cliente ou no navegador.

Uma chave pode ser revogada a qualquer momento em Definições → API, com efeito imediato no pedido seguinte. É o que deve fazer se suspeitar que a chave foi exposta.

Um pedido sem chave, ou com uma chave desconhecida, revogada ou expirada, devolve 401 unauthorized.

Âmbitos

Cada chave tem um conjunto de âmbitos (scopes) que delimita o que pode fazer. Um pedido a um endpoint fora dos âmbitos da chave devolve 403 forbidden.

Erros

Os erros usam sempre o mesmo formato. Programe contra o campo code, que é estável — a message é destinada a humanos e pode mudar.

{
  "error": {
    "code": "validation_error",
    "message": "Dados inválidos",
    "issues": [ /* detalhe por campo, apenas em erros de validação */ ]
  }
}

Limites

Os pedidos são contados por chave, numa janela de um minuto. Os limites diferem consoante o custo do endpoint:

As respostas bem-sucedidas — e os erros 403 e 429 — trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (epoch em segundos), para que possa abrandar antes de ser cortado. Um 401 não os traz: sem chave válida não há contador a reportar. Ao exceder o limite recebe 429 rate_limited com Retry-After em segundos — respeite-o.

Um pedido recusado conta na mesma para o limite. Um 403 por falta de permissão não é gratuito: se insistir num endpoint que a chave não pode usar, acabará por receber 429.

A chave

Sócios

Quotas

Campanhas de pagamento

Movimentos

Eventos

Idempotência

Pagamentos não podem ser cobrados duas vezes por causa de uma rede instável. Por isso /quotas/mark-paid exige uma externalReference: um identificador estável e único do seu lado para aquele pagamento — tipicamente o id da linha de encomenda. Não use um valor aleatório gerado a cada tentativa, ou a proteção deixa de funcionar.

Com essa referência, pode repetir o pedido à vontade:

• Se a liquidação já tinha terminado, a resposta original é devolvida tal e qual, com idempotent: true. Nada é pago de novo.
• Se ainda estiver a decorrer (o seu pedido anterior ainda não respondeu), recebe 409 settlement_in_progress. Aguarde um momento e repita.
• Se a tentativa anterior falhou a meio, a repetição liquida normalmente.

Perante um timeout ou um 500, a atitude correta é repetir o pedido com a mesma referência — nunca com uma nova.

Webhooks

Em vez de sondar a API, pode receber um POST quando algo acontece na associação. O endpoint é registado de duas maneiras: pela própria associação, em Definições → Webhooks, ou pelo fluxo de ligação. Em ambos os casos é devolvido o segredo de assinatura (começa por whsec_) uma única vez — guardamo-lo cifrado e não há forma de o voltar a ler.

Nem todos os endereços são aceites — veja endereços aceites.

quota.paid inclui source (admin, api ou stripe) e externalReference, para que possa distinguir os pagamentos que o seu sistema registou dos restantes e ignorar o eco dos seus próprios lançamentos. Os restantes campos são quotaId, associateId, transactionId, amount, kind, paymentMethod, receiptNumber e paidAt.

O pedido

POST https://o-seu-servidor.pt/webhooks/associados
X-Webhook-Event: payment_request.created
X-Webhook-Delivery: clxd8e2...
X-Webhook-Signature: sha256=3f9a1c...

{
  "id": "clxd8e2...",
  "event": "payment_request.created",
  "createdAt": "2026-02-10T09:12:00.000Z",
  "data": { /* específico do evento */ }
}

Verificar a assinatura

X-Webhook-Signature é sha256= seguido do HMAC-SHA256 do corpo em bruto do pedido, com o seu segredo como chave. Calcule o HMAC antes de fazer parse do JSON — se reserializar o objeto, a assinatura deixa de bater certo. Rejeite qualquer pedido cuja assinatura não confira.

import crypto from "crypto";

const esperado =
  "sha256=" +
  crypto.createHmac("sha256", WEBHOOK_SECRET).update(corpoEmBruto).digest("hex");

const valido = crypto.timingSafeEqual(
  Buffer.from(esperado),
  Buffer.from(req.headers["x-webhook-signature"]),
);

Repetições

Responda 2xx para confirmar a receção. Qualquer outra resposta — ou não responder em 10 segundos — conta como falha e o envio é repetido, até 6 tentativas, com espera exponencial a começar em 1 minuto e limitada a 6 horas.

Como há repetições, o mesmo evento pode chegar mais do que uma vez. Use o id da entrega (também em X-Webhook-Delivery) para ignorar duplicados. Responda depressa e processe em segundo plano.

Endereços aceites

Quem entrega os eventos é um cliente HTTP que corre dentro da nossa rede, por isso um endereço de webhook é uma instrução para irmos buscar alguma coisa a algum lado. Não aceitamos qualquer um. Se vir URL não permitido numa entrega, ou uma recusa ao guardar, é uma destas regras:

• Só https, e só no porto 443. Um porto arbitrário é como se chega a um painel interno.
• Sem credenciais no URL — nada de https://utilizador:senha@….
• Tem de resolver para um endereço público. Ficam de fora localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, os intervalos de documentação e reservados, e os equivalentes em IPv6 — incluindo um IPv4 embrulhado em IPv6, como ::ffff:127.0.0.1.
• Nomes reservados para a rede local — .local, .internal, .lan, .home.arpa — não são aceites.

A verificação corre ao guardar e outra vez antes de cada envio, e a ligação é feita para um dos endereços que a verificação aprovou. Verificar só ao guardar não chegaria: um nome pode ser reapontado a seguir, e é exactamente isso que alguém tentaria.

Não seguimos redirecionamentos. Uma resposta 3xx conta como entrega falhada — o endereço para onde aponta não passou por verificação nenhuma. Aponte o webhook directamente para o destino final.

Alterar o endereço de um endpoint gera um segredo novo e invalida o anterior: um endpoint reapontado é uma relação de confiança nova, e o destino antigo deixa de conseguir verificar as nossas assinaturas.

Ligar uma aplicação

As aplicações parceiras obtêm a chave através de um fluxo de consentimento, em vez de a chave ser copiada à mão. É um authorization code simplificado:

1. A aplicação envia o administrador para /connect/authorize, com client_id, redirect_uri e, opcionalmente, state, scope e webhook_url.
2. O administrador autentica-se, escolhe a associação a ligar e vê os acessos pedidos. Ao autorizar, é reencaminhado para a redirect_uri com um code de utilização única, válido por 5 minutos.
3. A aplicação troca esse código, servidor-a-servidor, em POST /api/connect/token, autenticando-se com client_id e client_secret. A resposta traz a chave de API e, se tiver sido pedido um webhook_url, o segredo de assinatura do webhook.

POST /api/connect/token
{
  "code": "ac_...",
  "client_id": "a-sua-app",
  "client_secret": "...",
  "redirect_uri": "https://a-sua-app.pt/callback"
}

{
  "api_key": "assoc_live_...",
  "scopes": "associates:read,quotas:read,quotas:write",
  "tenant": { "id": "...", "name": "Associação Exemplo" },
  "webhook": { "id": "...", "secret": "whsec_...", "events": "..." },
  "base_url": "https://associados.app"
}

A chave nunca viaja num reencaminhamento do navegador — só o código de utilização única — para não ficar em históricos e registos de servidor.

Não há registo dinâmico de clientes: cada aplicação parceira é pré-registada por nós, com o seu segredo e a lista exata de redirect_uri permitidas. Para registar uma aplicação, fale connosco.

Especificação

Toda a referência acima é gerada a partir das próprias rotas, e a mesma origem serve um documento OpenAPI 3.1:

GET https://associados.app/api/public/v1/openapi.json

Não exige chave — uma especificação é o que se lê antes de ter uma credencial, e descreve formatos, não dados de nenhuma associação. Serve para gerar um cliente na sua linguagem, para importar num Postman ou num Insomnia, e para comparar contra o que o seu código espera.

Porque é gerado, não pode divergir do que a API faz: um endpoint que exista sem estar declarado faz a nossa suite de testes falhar. Cada operação traz também o âmbito que exige e o orçamento de pedidos por minuto que gasta.