API da Hapee

Conecte seu ERP, sua loja ou seu sistema interno a uma subconta da Hapee. API REST, JSON, webhooks assinados.

O que você pode fazer

A API cobre os mesmos objetos com os quais a equipe comercial trabalha dentro da Hapee:

O essencial, em cinco linhas

• Autenticação: Authorization: Bearer hp_live_… (ou hp_test_… no sandbox).
• A subconta vem da credencial. Nunca é enviada como parâmetro.
• Formatos: JSON UTF-8, datas ISO 8601 em UTC, telefones E.164, valores como texto decimal com sua currency, RUT como 12345678-K.
• Listas: paginação por cursor (limit até 100, cursor, next_cursor).
• Escritas: envie Idempotency-Key e uma nova tentativa não duplica nada.

Seu primeiro request

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

Ele responde quem você é, em qual subconta você opera, em qual modo e com quais limites. Se isso funciona, o resto funciona.

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

Saber o que acontece

Há dois caminhos e ambos entregam os mesmos eventos, com o mesmo corpo:

• Webhooks — você nos dá uma URL https e nós avisamos. Assinados com HMAC-SHA256.
• GET /events — se seu sistema não pode expor uma URL pública (o habitual em um ERP instalado na empresa), você consulta com um cursor. Retenção de 30 dias.

Você pode usar os dois, ou apenas um. Não é preciso configurar nada diferente: você escolhe conforme o que sua infraestrutura permite, não conforme o que quer receber.

Erros

Todos têm o mesmo formato, e o code é estável:

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

Versionamento

A v1 é estável. Adicionar um campo a uma resposta não é uma mudança que quebra a compatibilidade, então sua integração precisa ignorar os campos que não conhece. Uma mudança que quebra sai como v2, e a v1 continua ativa por pelo menos 12 meses desde o anúncio.

Como obter uma credencial

Elas são emitidas pela agência que administra sua conta da Hapee. Peça primeiro uma credencial hp_test_: ela aponta para uma subconta de teste com dados fictícios, assim você pode desenvolver sem tocar em nada real.

Ir para produção é trocar a credencial e a URL do webhook. Nada mais: o sandbox e a produção usam a mesma API.