Primeira chamada à API

Do zero à primeira chamada autenticada à API da Axuz com um token pessoal axp_, usando curl, Node ou Python.

Este guia leva você de uma conta Axuz até a primeira resposta 200 da API usando um token pessoal (axp_...). Leva uns cinco minutos e não exige instalar nada além de curl, Node 20+ ou Python 3.

Os exemplos usam o ambiente de staging, https://api.axuz.net. Em produção o host é https://api.axuz.club; o resto do contrato é o mesmo.

1. Crie o token

Entre no workspace e abra Configurações pessoais → Tokens de API (caminho /me/settings/api-tokens).
Dê um nome que diga onde o token vai morar (por exemplo script-de-backup), escolha os escopos e a validade.
Copie o valor axp_... na hora: o servidor guarda só o hash e nunca mais mostra o segredo.

Os escopos reconhecidos são me:read (leituras em /me/*), me:write (criar, alterar e apagar em notas, tarefas, arquivos e eventos pessoais) e me:profile. Para este guia basta me:read. O teto de requisições por minuto vai de 1 a 1000 (padrão 60) e a validade, de 1 dia a 5 anos (ou sem expiração).

Guarde o token numa variável de ambiente, nunca no código nem em repositório:

export AXUZ_TOKEN='cole-aqui-o-token-axp_'
export AXUZ_API='https://api.axuz.net'

2. Faça a primeira chamada: quem sou eu e quais equipes tenho

O serviço principal não tem um GET /me para tokens. O equivalente é GET/me/summary, que devolve as equipes ativas da sua conta junto com contadores de tarefas e do financeiro de cada uma. É a forma de descobrir os team.id que você vai usar depois.

curl

curl -sS "$AXUZ_API/me/summary" \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Accept: application/json" \
  -i

Node

// node 20+, ESM (arquivo .mjs)
const res = await fetch(`${process.env.AXUZ_API}/me/summary`, {
  headers: { Authorization: `Bearer ${process.env.AXUZ_TOKEN}` },
});
if (!res.ok) {
  throw new Error(`HTTP ${res.status}: ${JSON.stringify(await res.json().catch(() => null))}`);
}
const summary = await res.json();
for (const entry of summary.teams ?? []) {
  console.log(entry.team.id, entry.team.name, `tarefas abertas: ${entry.tasks.open}`);
}

Python

import json
import os
import urllib.error
import urllib.request

req = urllib.request.Request(
    os.environ["AXUZ_API"] + "/me/summary",
    headers={"Authorization": "Bearer " + os.environ["AXUZ_TOKEN"]},
)
try:
    with urllib.request.urlopen(req, timeout=15) as res:
        summary = json.load(res)
except urllib.error.HTTPError as e:
    raise SystemExit(f"HTTP {e.code}: {e.read().decode()}")

for entry in summary.get("teams") or []:
    print(entry["team"]["id"], entry["team"]["name"], "tarefas abertas:", entry["tasks"]["open"])

O que esperar

Uma resposta 200 com Content-Type: application/json. O formato (valores ilustrativos):

{
  "generated_at": "2026-10-22T12:00:00Z",
  "teams": [
    {
      "team": { "id": "2f1c9a52-6a1e-4a3b-9d55-0c7e1d2b7a10", "name": "Acme", "slug": "acme" },
      "tasks": { "open": 3, "overdue": 1, "due_week": 2, "assigned": 3 },
      "financer": { "month_spent_cents": 0, "to_pay_cents": 0, "overdue_cents": 0, "overdue_count": 0 }
    }
  ],
  "unavailable": [
    { "bucket": "calendar", "owner_service": "axuz_calendar_api", "reason": "eventos vivem no DB local do axuz_calendar_api; ..." }
  ]
}

Três coisas para notar. Valores de dinheiro são inteiros em centavos, nunca decimais. O campo unavailable declara o que o endpoint não consegue agregar (hoje, o calendário) em vez de devolver zero. E, com Redis ativo no servidor, a resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; veja Limites de taxa. A resposta também traz X-Trace-Id, útil ao abrir um chamado.

3. Uma segunda chamada: suas notas

GET/me/notes lista as notas pessoais (também com me:read):

curl -sS "$AXUZ_API/me/notes?limit=5" -H "Authorization: Bearer $AXUZ_TOKEN"

A resposta é {"items": [...]}. Para ler além da primeira página veja Paginação.

Erros comuns neste ponto

Sintoma	Causa provável
`401` com `{"error":"unauthorized"}`	Token ausente, com erro de digitação, expirado ou revogado. O cabeçalho precisa ser exatamente `Authorization: Bearer axp_...`; o token não vai na URL.
`403` com `scope required: me:read`	O token foi criado sem o escopo da operação (`me:read` para GET, `me:write` para o resto). Crie outro: escopo não se altera depois.
`401` em `/teams` ou `/teams/{id}/...`	Essas rotas não aceitam `axp_`, só sessão. Use `/me/summary` para listar equipes.
`429` com `rate_limited`	Passou do teto por minuto do token. Espere o `Retry-After`.

A lista completa de status e o formato do corpo estão em Erros.

Próximos passos

Erros: o formato {"error": "..."}, o que cada status significa e quais erros repetir com segurança.
Paginação: como percorrer listas grandes sem perder nem repetir itens.
Limites de taxa: headers, Retry-After e backoff com jitter.
Referência da API: todas as operações, geradas do contrato.
Histórico de mudanças: o que mudou e quando.

Segurança: trate o token como senha. Se ele vazar, revogue em Tokens de API (ou com DELETE/me/api-tokens/{tokenID} usando uma sessão): a revogação vale já na requisição seguinte (o servidor invalida o cache de 30 segundos do token).

Atualizado em 2026-10-22