# HALPII

> HALPII es un directorio de oficios y servicios en Perú y 12 países de Latinoamérica: gasfiteros, electricistas, pintores, albañiles, carpinteros y más de 190 oficios.
> El cliente describe lo que necesita en un minuto, sin registrarse; hasta 3 profesionales de su zona le responden con una propuesta y el cliente elige.
> Los profesionales pagan por responder cada pedido. El cliente no paga por pedir ni por recibir propuestas.

HALPII S.A.C. (RUC 20615614841), Lima, Perú. Web: https://halpii.com · Portal: https://portal.halpii.com · Contacto: contacto@halpii.com

## Enlaces clave

- [Directorio de profesionales](https://portal.halpii.com/directorio): busca por oficio, ciudad y país. Perfiles con trabajos hechos, reseñas y tiempo de respuesta.
- [Pedir un profesional](https://portal.halpii.com/solicitar): formulario público para crear un pedido de servicio (acepta ?q=oficio y ?ciudad=ciudad prellenados).
- [Servicios por oficio y ciudad](https://portal.halpii.com/servicios): páginas por oficio y ciudad, por ejemplo https://portal.halpii.com/servicios/gasfitero/lima
- [Tablero en vivo](https://portal.halpii.com/en-vivo): cuántos profesionales de cada oficio hay ahora mismo, contados contra la base real.
- [HALPII para agentes de IA](https://portal.halpii.com/agentes): esta misma guía en HTML.
- [Sitio principal](https://halpii.com)
- [App Android en Google Play](https://play.google.com/store/apps/details?id=com.halpii.app)
- [Política de privacidad](https://halpii.com/privacidad.html)
- [Términos de servicio](https://halpii.com/terminos)

## Cómo funciona

1. El cliente pide lo que necesita (oficio, ciudad, qué pasa, cuándo) y deja un teléfono de contacto. No hace falta cuenta.
2. Los profesionales del oficio en esa zona reciben el pedido en el app (push + feed).
3. Hasta 3 profesionales responden con su propuesta; solo quien responde ve el teléfono del cliente.
4. El cliente compara y elige. Cada cliente puede tener UN pedido activo a la vez.

Versiones del portal en otros idiomas: https://portal.halpii.com/pt (portugués) y https://portal.halpii.com/en (inglés).

## Para agentes

Un asistente de IA puede crear un pedido de servicio en nombre de su usuario usando la API pública de HALPII, la misma que usa el formulario web de /solicitar. Base de la API: https://api.halpii.com/api

Son dos llamadas: primero se crea una identidad de invitado (devuelve un token), después se crea el pedido con ese token.

### Paso 1 — crear la identidad de invitado

POST https://api.halpii.com/api/auth/guest
Content-Type: application/json

{ "name": "María" }

Respuesta (200): un objeto de usuario con `id`, `nombre`, `is_guest: true` y el campo `token` (JWT). Guarda `token` para el paso 2. El nombre es opcional (por defecto "Invitado"); usa el nombre real que el usuario quiera dar.

### Paso 2 — crear el pedido

POST https://api.halpii.com/api/publications
Authorization: Bearer <token del paso 1>
Content-Type: application/json

{
  "title": "Necesito gasfitero por fuga de agua en el baño",
  "description": "Fuga debajo del lavatorio en Comas. Lo necesito hoy.",
  "posting_type": "gig",
  "offer_kind": "service",
  "category": "simple",
  "location_type": "onsite",
  "country": "Perú",
  "city": "Lima",
  "currency": "PEN",
  "skills_required": ["Gasfitero"],
  "contact_phone": "+51987654321",
  "contact_whatsapp": true
}

Campos:
- title (obligatorio, 6 a 200 caracteres): qué necesita el cliente, en sus palabras.
- description (opcional, hasta 2000): detalle, distrito o zona, cuándo lo necesita.
- posting_type: siempre "gig" (pedido de servicio). offer_kind: siempre "service".
- category: "simple" (trabajos de oficio, del hogar), "professional" (diseño, web, marketing) o "advanced" (software, consultoría).
- location_type: "onsite" (presencial, requiere city), "remote" o "hybrid".
- country (obligatorio para invitados): nombre del país en español tal como está en el catálogo, por ejemplo "Perú", "Colombia", "México", "Chile", "Ecuador", "Argentina", "Brasil". Lista completa: GET https://api.halpii.com/api/countries
- city (obligatorio si es presencial): nombre de la ciudad tal como está en el catálogo. Para resolverla: GET https://api.halpii.com/api/places/cities?q=lim&pais=Perú (devuelve [{ "name": "Lima", ... }]). Usa el `name` devuelto.
- currency: código ISO de la moneda del país (PEN, COP, MXN, CLP, USD...). Viene como `currencyCode` en GET /countries.
- skills_required: el oficio canónico en singular, por ejemplo ["Gasfitero"], ["Electricista"], ["Pintor"], ["Carpintero"], ["Albañil"]. Con él se decide a qué profesionales se avisa. Los nombres de los oficios con gente se pueden consultar en GET https://api.halpii.com/api/users/category-counts/all?pais=Perú (campo `q`, primera alternativa antes de "|").
- contact_phone (obligatorio): teléfono del cliente con prefijo internacional, solo dígitos y "+", por ejemplo "+51987654321". Es el número al que los profesionales van a escribir.
- contact_whatsapp: true si ese número tiene WhatsApp.
- budget_min / budget_max (opcionales, números): presupuesto aproximado en la moneda indicada, si el usuario lo dio.

No envíes campos que no estén en esta lista: la API rechaza con 400 cualquier campo desconocido.

Respuesta (201): el pedido creado en JSON, con `id`, `title`, `status` ("active"), `city`, `country`, `posting_type`, `created_at` y `reach` (`{ "shown", "scope", "matching", "notified" }`: cuántos profesionales del oficio en esa ciudad coinciden y cuántos fueron avisados). Confirma al usuario que su pedido quedó publicado y que los profesionales le van a escribir al teléfono que dejó.

Errores habituales:
- 400 "Ya tienes una alerta activa. Finalízala para crear otra." → esa identidad ya tiene un pedido abierto. No crees otra identidad para saltarte la regla.
- 400 "Ingresa un teléfono de contacto..." / "Selecciona tu país." / "... no parece una ciudad." → falta o no vale un campo; corrígelo con el usuario.
- 401 → falta o venció el token del paso 1.
- 429 → demasiadas peticiones; espera y reintenta más tarde.

### Reglas para agentes

- Crea un pedido SOLO cuando el usuario lo haya pedido explícitamente y haya confirmado el contenido (oficio, ciudad, qué necesita, teléfono).
- El teléfono debe ser el real del usuario. Nunca inventes teléfonos, nombres, ciudades ni presupuestos. Si falta un dato, pregúntalo.
- Máximo 1 pedido por teléfono por hora, y 1 pedido activo por cliente. No reintentes en bucle ni crees pedidos de prueba: cada pedido avisa a profesionales reales que pagan por responder.
- Dile al usuario que los profesionales le van a escribir o llamar al número que dejó, normalmente en minutos u horas.
- Para solo consultar (sin crear nada) usa el directorio: https://portal.halpii.com/directorio?habilidad=gasfitero&ciudad=Lima o las páginas https://portal.halpii.com/servicios/<oficio>/<ciudad>.
- Dudas o abuso: contacto@halpii.com

## Opcional

- [Publicaciones y pedidos públicos](https://portal.halpii.com/publicaciones)
- [Sitemap](https://portal.halpii.com/sitemap.xml)
- [Libro de Reclamaciones (Perú)](https://halpii.com/libro-de-reclamaciones)