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.

Sócios

GET /associates?search=silva&page=1&pageSize=25

{
  "data": [
    {
      "id": "clx7a2b...",
      "associateNumber": 142,
      "name": "Maria Silva",
      "status": "ACTIVE",
      "hasPicture": true
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 1,
  "totalPages": 1
}

GET /associates/clx7a2b.../avatar?size=64
→ 200 image/webp

GET /associates/clx7a2b.../payable-quotas

{
  "associate": {
    "id": "clx7a2b...",
    "name": "Maria Silva",
    "associateNumber": 142,
    "status": "ACTIVE"
  },
  "quotas": [
    {
      "id": "clx9f4d...",
      "kind": "RECURRING",
      "label": null,
      "referenceDate": "2026-01-01T00:00:00.000Z",
      "dueDate": "2026-01-31T00:00:00.000Z",
      "amount": 10,
      "status": "OVERDUE"
    },
    {
      "id": "clxa1e7...",
      "kind": "ONE_OFF",
      "label": "Jantar de aniversário",
      "referenceDate": "2026-03-01T00:00:00.000Z",
      "dueDate": "2026-03-15T00:00:00.000Z",
      "amount": 25,
      "status": "PENDING"
    }
  ]
}

Quotas e pagamentos

POST /quotas/mark-paid
{
  "quotaIds": ["clx9f4d...", "clxa1e7..."],
  "paymentMethod": "POS — Multibanco",
  "externalReference": "order-item-8891"
}

{
  "idempotent": false,
  "status": "completed",
  "paid": 2,
  "quotaIds": ["clx9f4d...", "clxa1e7..."],
  "externalReference": "order-item-8891"
}

POST /quotas/unmark-paid
{ "externalReference": "order-item-8891" }

{
  "reversed": true,
  "alreadyReversed": false,
  "quotaIds": ["clx9f4d...", "clxa1e7..."]
}

GET /payment-requests

{
  "data": [
    {
      "id": "clxb3c9...",
      "name": "Jantar de aniversário",
      "amount": 25,
      "total": 80,
      "paid": 31,
      "pending": 49,
      "createdAt": "2026-02-10T09:12:00.000Z"
    }
  ]
}

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 no fluxo de ligação, que devolve também o segredo de assinatura (começa por whsec_).

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.

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.