Documentación — HIREN
Todo lo necesario para operar la app, conectar agentes IA y terminar el registro de la app en Freelancer.
1 · URLs para el formulario de app de Freelancer
Campos pendientes en accounts.freelancer.com/settings/develop:
Application Homepage: https://hiren.enerby.dev/ Redirect Endpoint (URI de redirección): https://hiren.enerby.dev/auth/callback
Scopes avanzados recomendados: 1 crear proyectos, 2 gestionar proyectos/bids, 3+4 concursos, 5 mensajería, 6 info de usuario. El scope basic es automático.
2 · Autenticación (dos vías)
Agentes IA / curl — header en TODA llamada a /api/**:
x-agent-key: <NUXT_AGENT_API_KEY>
Navegador — botón «Conectar con OAuth» (crea cookie HttpOnly) o guardar un PAT:
curl -X POST https://hiren.enerby.dev/api/auth/pat \
-H 'content-type: application/json' \
-H 'x-agent-key: TU_CLAVE' \
-d '{"token":"TU_PERSONAL_ACCESS_TOKEN"}'Freelancer no aprueba apps de un solo usuario: el PAT es la vía soportada para tu cuenta propia hoy; la app OAuth queda lista para la consultoría multi-usuario.
3 · Endpoints de HIREN
| Método + ruta | Upstream | Notas |
|---|---|---|
| GET /api/health | — | público |
| GET /api/spec | — | público, autodescubrimiento |
| GET /api/auth/status | — | modo conectado y expiración |
| POST /api/auth/pat | — | {token} |
| GET /api/me | users/0.1/self/ | perfil y balance |
| GET /api/projects/search | projects/0.1/projects/active/ | query, min_price, max_price, sort_field, limit… |
| GET /api/projects/:id | projects/0.1/projects/{id}/ | proyecciones via query |
| POST /api/projects | projects/0.1/projects/ | crear proyecto (consultoría) |
| GET /api/projects/jobs | projects/0.1/jobs/search/ | IDs de skills |
| GET /api/currencies | projects/0.1/currencies/ | para crear proyectos |
| GET /api/bids | projects/0.1/bids/ | mis bids por defecto |
| POST /api/bids | projects/0.1/bids/ | {project_id, amount, period, description?, milestone_percentage?} |
| PUT /api/bids/:id | projects/0.1/bids/{id}/ | actualizar o {action:"retract"} |
| GET /api/messages/threads | messages/0.1/threads/ | ?unread_thread_count=true |
| POST /api/messages/threads | messages/0.1/threads/ | {participant_ids[], project_id?, message_body} |
| POST /api/messages/threads/:id/messages | messages/0.1/threads/{id}/messages/ | responder hilo |
| POST /api/contests | contests/0.1/contests/ | crear concurso |
| POST /api/proxy | cualquier endpoint | {method, path, params?, body?} |
4 · Ejemplos para agentes IA
// Buscar proyectos
curl 'https://hiren.enerby.dev/api/projects/search?query=nuxt&limit=5' \
-H 'x-agent-key: TU_CLAVE'
// Postular (¡acción real!)
curl -X POST 'https://hiren.enerby.dev/api/bids' \
-H 'content-type: application/json' \
-H 'x-agent-key: TU_CLAVE' \
-d '{"project_id":40720284,"amount":180,"period":21,
"milestone_percentage":33,"description":"..."}'
// Cualquier endpoint vía pasarela
curl -X POST 'https://hiren.enerby.dev/api/proxy' \
-H 'content-type: application/json' \
-H 'x-agent-key: TU_CLAVE' \
-d '{"method":"GET","path":"users/0.1/self/"}'5 · Despliegue Cloudflare Workers
Checklist del dashboard (guía completa en el README del repo):
1. Workers & Pages → Create → Workers → Connect to Git → repo hiren
2. Build npm run build · Deploy npx wrangler deploy · Preview npx wrangler versions upload (usa el wrangler.jsonc del repo)
3. KV: ya declarado en wrangler.jsonc (namespace HIREN_KV, binding KV) — sin paso manual
4. Secrets (persisten): NUXT_AGENT_API_KEY; tras aprobarse la app OAuth: NUXT_FREELANCER_CLIENT_ID / NUXT_FREELANCER_CLIENT_SECRET
5. Custom domain: hiren.enerby.dev (Settings → Domains & Routes)
6. Probar /api/health y luego OAuth
El header de la API upstream es freelancer-oauth-v1; rate limits: 429 con RateLimit-Limit/`RateLimit-Remaining`.