Hapee API

Connect your ERP, your store or your internal system to a Hapee subaccount. REST API, JSON, signed webhooks.

What you can do

The API covers the same objects your sales team works with inside Hapee:

The essentials, in five lines

• Authentication: Authorization: Bearer hp_live_… (or hp_test_… in the sandbox).
• The subaccount comes from the credential. It is never sent as a parameter.
• Formats: UTF-8 JSON, ISO 8601 dates in UTC, E.164 phone numbers, amounts as decimal strings with their currency, RUT as 12345678-K.
• Lists: cursor pagination (limit up to 100, cursor, next_cursor).
• Writes: send Idempotency-Key and a retry won't duplicate anything.

Your first request

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

It tells you who you are, which subaccount you operate on, in which mode and with which limits. If this works, everything else works.

{
  "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"
}

Finding out what happens

There are two paths and they serve the same events, with the same body:

• Webhooks — you give us an https URL and we notify you. Signed with HMAC-SHA256.
• GET /events — if your system can't expose a public URL (typical for an ERP installed on-premises), you poll with a cursor. 30-day retention.

You can use both, or just one. There is nothing different to configure: you choose based on what your infrastructure allows, not on what you want to receive.

Errors

They all have the same shape, and the code is stable:

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

Versioning

v1 is stable. Adding a field to a response is not a breaking change, so your integration must ignore fields it doesn't recognize. A breaking change ships as v2, and v1 stays alive for at least 12 months after the announcement.

How to get a credential

They are issued by the agency that manages your Hapee account. Ask for an hp_test_ credential first: it points to a test subaccount with fictitious data, so you can develop without touching anything real.

Going to production means changing the credential and the webhook URL. Nothing else: the sandbox and production speak the same API.