Base URLs
| API | URL | Descrição |
|---|
| Core | https://api.global.komprai.dev | Identidade, stores, billing, SSO |
| Catalog (sa-east-1) | https://api.sa-east-1.komprai.dev | Ofertas — São Paulo |
| Catalog (us-east-1) | https://api.us-east-1.komprai.dev | Ofertas — North Virginia |
Autenticação
A API usa autenticação por cookie de sessão via better-auth.
Login
POST /auth/sign-in/email
Content-Type: application/json
{
"email": "usuario@exemplo.com",
"password": "senha"
}
better-auth.session_token (ou __Secure-better-auth.session_token em produção com HTTPS).
Usando o token
curl -b cookies.txt https://api.global.komprai.dev/api/stores
Não há autenticação por Bearer token. O cookie deve ser enviado com credentials: "include" em requisições cross-origin.
Regiões
O Core API (api.global.komprai.dev) é global — não varia por região.
O Catalog API é regional. Cada região retorna preços e ofertas específicos daquele mercado:
| Região | Host |
|---|
global | api.global.komprai.dev |
sa-east-1 | api.sa-east-1.komprai.dev |
us-east-1 | api.us-east-1.komprai.dev |
Erros
A API usa status HTTP padrão. Erros retornam JSON com a mensagem:
{
"statusCode": 404,
"error": "Not Found",
"message": "store.not_found"
}
| Status | Significado |
|---|
400 | Parâmetros inválidos |
401 | Não autenticado |
403 | Sem permissão |
404 | Recurso não encontrado |
409 | Conflito (ex: slug já existe) |
429 | Rate limit atingido |
500 | Erro interno |
Rate Limiting
Rotas sensíveis têm rate limiting automático. O endpoint /api/users/me aceita:
- 200 req/min para usuários autenticados
- 100 req/min para anônimos
