HALPII para agentes de IA

Qué es 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. Cada cliente puede tener un pedido activo a la vez.

HALPII S.A.C. (RUC 20615614841), Lima, Perú. Contacto: [email protected]

Cómo consultar (sin crear nada)

• Directorio de profesionales: busca por oficio, ciudad y país. Acepta ?habilidad=gasfitero&ciudad=Lima.
• Servicios por oficio y ciudad: páginas como /servicios/gasfitero/lima con profesionales reales.
• Tablero en vivo: cuántos profesionales de cada oficio hay ahora mismo.
• Pedir un profesional: el formulario web, para mandar al usuario si prefiere hacerlo él (acepta ?q= y ?ciudad=).
• halpii.com · App en Google Play · Política de privacidad

Cómo crear un pedido

Es la misma API pública que usa el formulario de /solicitar. Base: https://api.halpii.com/api. Son dos llamadas.

Paso 1 — crear la identidad de invitado

Devuelve un token JWT. El nombre es opcional; usa el que el usuario quiera dar.

curl -X POST https://api.halpii.com/api/auth/guest \
  -H "Content-Type: application/json" \
  -d '{ "name": "María" }'

{
  "id": "6f1c…",
  "nombre": "María",
  "is_guest": true,
  "token": "eyJhbGciOi…",
  "isNewUser": true
}

Paso 2 — crear el pedido con ese token

curl -X POST https://api.halpii.com/api/publications \
  -H "Authorization: Bearer <token del paso 1>" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'

{
  "id": "9b2e…",
  "title": "Necesito gasfitero por fuga de agua en el baño",
  "status": "active",
  "posting_type": "gig",
  "city": "Lima",
  "country": "Perú",
  "created_at": "2026-09-08T15:04:05.000Z",
  "reach": { "shown": 418, "scope": "oficio_ciudad", "matching": 418, "notified": 120 }
}

reach dice 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ó.

Campos

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

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 con mensaje de validación — Falta o no vale un campo (teléfono, país, ciudad, título corto, campo desconocido). Corrígelo con el usuario y reintenta una vez.
• 401 — Falta o venció el token del paso 1.
• 429 — Demasiadas peticiones. Espera y reintenta más tarde; no insistas en bucle.

Reglas

• Crea un pedido solo cuando el usuario lo haya pedido explícitamente y haya confirmado el contenido: oficio, ciudad, qué necesita y 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 usa el directorio o las páginas de servicios; no hace falta crear nada.

Contacto

Dudas, integraciones o reportes de abuso: [email protected]