Empezar
De cero a tu primera petición autenticada en 30 segundos. Esta guía usa curl porque no requiere instalar nada, pero el mismo flujo aplica desde cualquier lenguaje.
3 min de lectura
Requisitos previos
Necesitas tres cosas:
- Una organización activa de Hablame.
- Una API key emitida desde el portal de clientes: una cadena que empieza con
hk_. curl, o el cliente HTTP que prefieras.
1. Emite una API key
Las API keys se crean desde el portal de clientes. Al crear una, el portal te muestra el token completo una sola vez. Cópialo de inmediato a un gestor de contraseñas o a tu gestor de secretos. Hablame guarda solo un hash: si pierdes el valor original, no se puede recuperar y toca emitir uno nuevo.
Trata el token como una contraseña. Nunca lo subas al repositorio, nunca lo pegues en un chat, nunca lo pongas en una URL.
2. Haz tu primera petición
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 servicio real.
curl -H 'Authorization: Bearer hk_TU_API_KEY' \
https://developers.hablame.co/api/v6/utilities/pingUna llamada exitosa devuelve HTTP 200 y un cuerpo JSON como este:
{
"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 código HTTP. La guía de la envoltura cubre el contrato exacto.
4. Pasa a un endpoint real
Cuando /api/v6/utilities/ping responde 200, el resto de v6 sigue el mismo patrón: autenticación Bearer, misma envoltura, mismos headers de límites. Explora la referencia para ver cada endpoint, sus parámetros y ejemplos, y probar peticiones desde la misma página.
Errores comunes
| Síntoma | Causa probable |
|---|---|
401 AUTH_REQUIRED | Olvidaste el header Authorization, o usaste Basic en vez de Bearer. |
401 AUTH_INVALID_KEY | Error de tipeo en el token, copiaste la key equivocada, o la key fue rotada o venció. |
404 NOT_FOUND | Confirma que estás llamando a developers.hablame.co y no a una dirección IP directa. |
429 RATE_TPS_EXCEEDED | Llegaste al cupo del endpoint (ping admite 20 solicitudes por minuto). Respeta Retry-After. |
Cada respuesta trae un meta.requestId. Cítalo al abrir un ticket de soporte: con ese id encontramos tu petición exacta.
Siguientes pasos
Ciclo de vida del token, rotación y qué hacer si una key se compromete.
El contrato completo y cómo ramificar tu cliente sin adivinar formas.
El modelo de dos capas, los headers y la estrategia de reintentos.
Cada endpoint con parámetros, errores y panel Try-It en vivo.