Almacenamiento

Objetivo

Tus servicios de Hablame guardan archivos por ti, por ejemplo grabaciones de llamadas, audios o documentos. Con esta API puedes ver cuánto ocupan, qué se eliminará pronto, cuánto tiempo se conserva cada tipo de archivo, qué tarifa te aplica y, si tu clave lo permite, listar los archivos y descargarlos.

Requisitos

• Una organización activa y una clave de API vigente. Cómo obtenerla.
• El servicio Almacenamiento (storage) en la clave. Con él, la clave ve todo: resumen, consumo, conservación, tarifa, archivos y descargas. Sin él, las siete rutas responden 403 AUTH_SERVICE_NOT_ALLOWED. Solo el propietario de tu organización crea las claves.
• Para ver la tarifa, tu organización necesita tener su moneda definida; si no, los campos de precio llegan en null.

Credenciales

Toda petición lleva Authorization: Bearer hk_TU_API_KEY. El servicio Almacenamiento se da completo, y los archivos pueden contener datos sensibles (una grabación, un documento): una clave con el servicio los ve y los descarga.

Pasos

1. 01
   Mira el resumen

   GET /storage/summary devuelve lo que ocupan ahora tus archivos (en total, por servicio y por tipo), la tarifa de hoy, el consumo del mes y cuántos archivos se eliminan en las próximas 24 horas y 7 días.

2. 02
   Revisa el consumo

   GET /storage/usage trae la serie de GB al mes por día, por mes o por hora, y la compara con el rango anterior de la misma duración.

3. 03
   Consulta la conservación

   GET /storage/retention dice cuánto tiempo se guarda cada tipo de archivo antes de eliminarse, con el mínimo, el máximo y el de por omisión.

4. 04
   Consulta la tarifa

   GET /storage/pricing devuelve el precio por GB al mes que rige hoy y el siguiente si ya está fijado. Esta documentación no publica cifras.

5. 05
   Lista tus archivos

   GET /storage/objects los devuelve del más reciente al más antiguo, paginados por cursor. Filtra por service, scope y fechas.

6. 06
   Descarga uno

   GET /storage/objects/{id}/download-url devuelve un enlace firmado y temporal. Descarga el archivo con ese enlace.

Ejemplos

Consultar el resumen

curl https://developers.hablame.co/api/v6/storage/summary \
  -H 'Authorization: Bearer hk_TU_API_KEY'

const res = await fetch('https://developers.hablame.co/api/v6/storage/summary', {
  headers: { Authorization: `Bearer ${process.env.HABLAME_API_KEY}` },
})
const { success, data, error } = await res.json()
if (success) console.log(data.now.bytes, 'bytes en', data.now.objects, 'archivos')
else console.error(error.code)

import os
import requests

r = requests.get(
    "https://developers.hablame.co/api/v6/storage/summary",
    headers={"Authorization": f"Bearer {os.environ['HABLAME_API_KEY']}"},
    timeout=30,
)
body = r.json()
if body["success"]:
    print(body["data"]["now"]["bytes"], "bytes")

Recorrer todos tus archivos

Si next no es null, pásalo como cursor en la siguiente petición con los mismos filtros. Un cursor alterado, de otra organización, con otros filtros o de hace más de 24 horas responde 400 INVALID_CURSOR: vuelve a la primera página.

const base = 'https://developers.hablame.co/api/v6/storage/objects'
const headers = { Authorization: `Bearer ${process.env.HABLAME_API_KEY}` }

let cursor = null
do {
  const url = new URL(base)
  url.searchParams.set('limit', '100')
  if (cursor) url.searchParams.set('cursor', cursor)

  const body = await (await fetch(url, { headers })).json()
  if (!body.success) throw new Error(`${body.error.code} (${body.meta.requestId})`)

  for (const archivo of body.data.objects) console.log(archivo.id, archivo.name, archivo.size)
  cursor = body.data.next
} while (cursor)

import os
import requests

base = "https://developers.hablame.co/api/v6/storage/objects"
headers = {"Authorization": f"Bearer {os.environ['HABLAME_API_KEY']}"}

cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    body = requests.get(base, headers=headers, params=params, timeout=30).json()
    if not body["success"]:
        raise RuntimeError(f"{body['error']['code']} ({body['meta']['requestId']})")
    for archivo in body["data"]["objects"]:
        print(archivo["id"], archivo["name"], archivo["size"])
    cursor = body["data"]["next"]
    if not cursor:
        break

Descargar un archivo

# 1. Pide el enlace temporal (válido 15 minutos si no indicas otro plazo)
curl 'https://developers.hablame.co/api/v6/storage/objects/obj_01JABCDEFGHJKMNPQRSTVWXYZ0/download-url?minutes=15' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

# 2. Descarga con la URL de data.url (no lleva tu clave)
curl -o archivo.wav 'URL_DE_DATA.URL'

Respuestas esperadas

El listado devuelve archivos con esta forma. Los valores son de ejemplo:

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "obj_01JABCDEFGHJKMNPQRSTVWXYZ0",
        "name": "llamada-3001234567.wav",
        "service": "callblasting",
        "scope": "recordings",
        "size": 482113,
        "contentType": "audio/wav",
        "storedAt": "2026-10-18T10:00:00.000-05:00",
        "expiresAt": "2026-11-17T10:00:00.000-05:00",
        "status": "available",
        "deletable": false
      }
    ],
    "next": "c1.t3b9X0k..."
  },
  "meta": {
    "requestId": "5d0f3a9c7b2e41a8",
    "clientIp": "203.0.113.10",
    "timestamp": "2026-10-19T15:30:00+00:00",
    "responseTimeMs": 12.4
  }
}

status

available: se puede descargar. deleting: se está eliminando o ya venció; no se puede descargar y se cobra hasta que termine.

expiresAt

Cuándo se elimina según el tiempo de conservación vigente, o null si no vence.

size

Tamaño en bytes. Los GB de la facturación son decimales (10⁹ bytes).

Importes

Todos los importes van en micros de la moneda de tu organización: unidades multiplicadas por 10⁶. El resumen y la tarifa los llevan en currency y ...Micro.

El enlace de descarga responde { url, expiresAt }. Es válido hasta expiresAt: 15 minutos por omisión, 60 como máximo (parámetro minutes), y nunca más allá de cuando el archivo se elimina.

Errores habituales

Seguridad

• Da el servicio Almacenamiento solo a quien lo necesita. Con él, la clave ve y descarga los archivos, que pueden ser grabaciones de llamadas o documentos de tu organización.
• El enlace de descarga es un secreto de corta vida. No lo guardes ni lo compartas; pide uno nuevo cada vez que lo necesites.
• Cada enlace queda registrado con la clave de API que lo pidió y la IP desde la que llamaste, en el registro de auditoría de tu organización.
• La API nunca muestra la ubicación interna de un archivo ni identificadores consecutivos: un archivo ajeno responde igual que uno que no existe.
• Restringe las redes permitidas de la clave a las IP de tu servidor.

Endpoints relacionados

Las seis consultas comparten un cupo por organización (el enlace de descarga tiene el suyo). Las siete piden el servicio Almacenamiento (storage) en la clave.

Próximos pasos

Para dudas técnicas escribe a developers@hablame.co. Si tienes una incidencia en producción, escribe por WhatsApp al +57 319 660 0002, las 24 horas.