API para programadores
API REST pública para integrar a Vocagora: autenticação, perfil, recomendações, anúncios e vagas. Respostas em JSON, com envelope previsível.
Autenticação
A API usa JWT (HS256) via cabeçalho Authorization: Bearer <accessToken>. Obténs os tokens em /auth/login ou /auth/register. O access token é válido 1 hora; renova-o com /auth/refresh usando o refresh token (válido 30 dias).
# 1) Obter tokens
curl -X POST https://vocagora.com/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"tu@email.pt","password":"a-tua-password"}'
# 2) Usar o access token devolvido
curl https://vocagora.com/api/v1/me/profile \
-H "Authorization: Bearer <accessToken>"Para integrações server-to-server, cria uma chave de API e envia-a no cabeçalho X-API-Key — autentica como tu, sem gerir tokens.
Formato das respostas
Sucesso devolve { "ok": true, "data": … } e erro devolve { "ok": false, "error": "…", "code": "…" }. Os códigos são estáveis:
| Código | HTTP | Significado |
|---|---|---|
| VALIDATION | 400 | Corpo ou parâmetros inválidos. |
| UNAUTHENTICATED | 401 | Bearer ausente ou inválido. |
| PLAN_LIMIT | 402 | Limite do plano atingido. |
| FORBIDDEN | 403 | Sem permissão para o recurso. |
| NOT_FOUND | 404 | Recurso inexistente. |
| CONFLICT | 409 | Conflito (ex.: email já registado). |
| RATE_LIMITED | 429 | Demasiados pedidos. |
| INTERNAL | 500 | Erro interno. |
Limites de uso
Por IP. Ao exceder, a API devolve 429 com código RATE_LIMITED.
/api/v1/auth/register— 5/min/api/v1/auth/login— 10/min/api/v1/auth/refresh— 20/min
Endpoints
Autenticação
Criar conta, iniciar sessão e renovar tokens.
- POST
/api/v1/auth/registerCriar conta e obter tokens Bearer.Público - POST
/api/v1/auth/loginIniciar sessão com email e password; devolve tokens.Público - POST
/api/v1/auth/refreshTrocar um refresh token por um novo par de tokens.Público
Conta
Dados do utilizador autenticado (requer Bearer).
- GET
/api/v1/me/profilePerfil do utilizador autenticado.Bearer - GET
/api/v1/me/recommendationsRecomendações personalizadas (vagas, anúncios e ligações).Bearer
Marketplace
Anúncios públicos e criação de anúncios.
- GET
/api/v1/listingsListar anúncios ativos com filtros e paginação.Público - POST
/api/v1/listingsCriar um anúncio (respeita o limite do plano).Bearer - GET
/api/v1/listings/{slug}Detalhe público de um anúncio ativo.Público
Emprego
Vagas publicadas.
- GET
/api/v1/jobsListar vagas publicadas com filtros e paginação.Público - GET
/api/v1/jobs/{id}Detalhe público de uma vaga publicada.Público
Webhooks
Cria webhooks em /painel/webhooks para receber um POST assinado quando ocorre um evento. Cada pedido inclui os cabeçalhos:
X-Webhook-Event— nome do eventoX-Webhook-Timestamp— epoch (segundos)X-Webhook-Signature—sha256=HMAC(secret, "<timestamp>.<body>")
Verifica recalculando o HMAC-SHA256 com o teu segredo e comparando com o cabeçalho. Eventos disponíveis:
ping— Teste (ping)listing.created— Anúncio criadolisting.updated— Anúncio atualizado
SDK TypeScript
Cliente tipado sem dependências (Node e browser) que espelha esta API. Autenticação por Bearer ou chave de API (auto-detetada).
import { VocagoraClient } from "@/sdk";
const api = new VocagoraClient({ baseUrl: "https://vocagora.com" });
const res = await api.listListings({ q: "bicicleta" });
if (res.ok) console.log(res.data);Pronto para construir?
Importa o documento OpenAPI no teu cliente favorito e começa a integrar em minutos. Esta é a v1 — webhooks e chaves de API estão no roteiro.
Ver OpenAPI