API de Hapee

Conecta tu ERP, tu tienda o tu sistema interno con una subcuenta de Hapee. API REST, JSON, webhooks firmados.

Qué puedes hacer

La API cubre los mismos objetos con los que trabaja el equipo comercial dentro de Hapee:

Lo esencial, en cinco líneas

• Autenticación: Authorization: Bearer hp_live_… (o hp_test_… en sandbox).
• La subcuenta sale de la credencial. Nunca se manda por parámetro.
• Formatos: JSON UTF-8, fechas ISO 8601 en UTC, teléfonos E.164, montos como texto decimal con su currency, RUT como 12345678-K.
• Listas: paginación por cursor (limit hasta 100, cursor, next_cursor).
• Escrituras: manda Idempotency-Key y un reintento no duplica nada.

Tu primer request

curl https://beta.hapee.ai/api/v1/me \
  -H "Authorization: Bearer hp_test_TU_CREDENCIAL"

Te responde quién eres, sobre qué subcuenta operas, en qué modo y con qué límites. Si esto anda, el resto anda.

{
  "key": { "id": 44, "name": "Mi ERP", "mode": "test", "read_only": false },
  "subaccount": { "id": 91, "name": "Cliente — Sandbox",
                  "timezone": "America/Santiago", "default_currency": "CLP",
                  "sandbox": true, "language": "es" },
  "limits": { "requests_per_minute": 100, "batch_max_items": 100,
              "events_retention_days": 30, "idempotency_window_hours": 24 },
  "api_version": "v1"
}

Enterarte de lo que pasa

Hay dos caminos y sirven los mismos eventos, con el mismo cuerpo:

• Webhooks — nos das una URL https y te avisamos. Firmados con HMAC-SHA256.
• GET /events — si tu sistema no puede exponer una URL pública (lo habitual en un ERP instalado en la empresa), consultas tú con un cursor. Retención de 30 días.

Puedes usar los dos, o solo uno. No hay que configurar nada distinto: eliges según lo que tu infraestructura permite, no según lo que quieres recibir.

Errores

Todos tienen la misma forma, y el code es estable:

{
  "error": {
    "code": "validation_error",
    "message": "El RUT no es válido.",
    "details": [{ "field": "rut", "issue": "invalid_check_digit" }],
    "request_id": "7e3a6a14dfe84d359fc3108b5974f880"
  }
}

Versionado

v1 es estable. Agregar un campo a una respuesta no es un cambio que rompa, así que tu integración tiene que ignorar los campos que no conoce. Un cambio que sí rompa sale como v2, y v1 sigue vivo al menos 12 meses desde el anuncio.

Cómo conseguir una credencial

Las emite la agencia que administra tu cuenta de Hapee. Pide una credencial hp_test_ primero: apunta a una subcuenta de prueba con datos ficticios, así puedes desarrollar sin tocar nada real.

Pasar a producción es cambiar la credencial y la URL del webhook. Nada más: el sandbox y producción hablan la misma API.