Empezar

De cero a tu primer request autenticado en 30 segundos. Esta guía usa curl porque no requiere instalar nada, pero el mismo flujo aplica desde cualquier lenguaje (ver la referencia para code samples).

Requisitos previos

Necesitas tres cosas:

  • Una organización activa de Hablame.
  • Una API key desde el dashboard de tu organización (un string que arranca con hk_).
  • curl, o cualquier cliente HTTP de tu preferencia.

1. Emite una API key

Las API keys se crean desde el dashboard de Hablame. Al crear una, el dashboard te muestra el token completo una sola vez. Cópialo de inmediato a un gestor de contraseñas o secret store. Hablame guarda solo un hash; si pierdes el plaintext, no podemos recuperarlo. Toca emitir uno nuevo.

!

Trata el token como una contraseña. Nunca lo subas al repositorio, nunca lo pegues en chats, nunca lo metas en URLs.

2. Haz tu primer request

El endpoint utilities/ping es el más simple. Corre el pipeline completo de autenticación y te devuelve lo que la API sabe de tu key, perfecto para confirmar que todo está bien conectado antes de pasar a un endpoint de módulo real.

curl 
$ curl -H 'Authorization: Bearer hk_YOUR_API_KEY' \
       https://developers.hablame.co/api/v6/utilities/ping

Una llamada exitosa devuelve HTTP 200 y un body JSON como este:

respuesta.json 
{
  "success": true,
  "data": {
    "pong":       true,
    "apiVersion": "v6",
    "account": { "id": 10000003, "status": "active" }
  },
  "meta": {
    "requestId":      "b9b1704baffab21150213c02fd853975",
    "responseTimeMs": 4.24
  }
}

3. Lee la envoltura

Cada respuesta (exitosa o no) viene en la misma envoltura: { success, data | error, meta }. Ramifica tu cliente sobre success, nunca sobre el HTTP status. La guía de envoltura cubre el contrato exacto.

4. Pasa a un endpoint real

Una vez que /api/v6/utilities/ping responde 200, el resto de v6 sigue el mismo patrón: auth Bearer, misma envoltura, mismos headers de rate limit. Explora la referencia interactiva para ver cada endpoint, parámetros y payloads de ejemplo, y probar requests directo desde la página.

Errores comunes

SíntomaCausa probable
401 AUTH_REQUIRED Olvidaste el header Authorization o usaste Basic en vez de Bearer.
401 AUTH_INVALID_KEY Typo en el token, copiaste la key incorrecta, o la key fue rotada/vencida.
404 NOT_FOUND El header Host no está en el allowlist: confirma que llamas a developers.hablame.co, no a una IP directa.
429 RATE_TPS_EXCEEDED Pegaste el cupo per-endpoint (ping es 20 req/min). Respeta Retry-After.
i

Cada respuesta trae un meta.requestId. Cítalo al abrir un ticket de soporte: le permite a ops saltar directo a tu request en los logs.

Siguientes pasos