Esta guía es para desarrolladores que integran sistemas externos con Chateea. Para obtener tus credenciales de la API y la URL base, escribe a soporte de Chateea en [email protected].
Ventajas
El flujo en tres pasos
1
Iniciar
Envía los metadatos del archivo (nombre, tamaño y tipo de contenido) para solicitar una URL firmada y la ruta del objeto.
2
Subir
Tu cliente sube el archivo directamente a la URL firmada con una petición
PUT, antes de que venza.3
Completar
Confirma la subida. Chateea verifica el archivo guardado y te devuelve la URL pública que usarás en el mensaje.
Límites de tamaño por canal
Los archivos que superan el límite se rechazan antes de empezar la subida, para no gastar tiempo ni datos.
Validación del tipo de contenido
El tipo de contenido (MIME) se valida dos veces para bloquear archivos disfrazados o con extensión incorrecta:- Al iniciar: se comprueba que el tipo declarado coincida con la extensión del archivo.
- Al completar: se comprueba que el tipo guardado coincida con el nombre del archivo.
Seguridad y control de acceso
- Se confirma que la conversación existe y pertenece a tu cuenta.
- Se verifica que el usuario tenga acceso a esa cuenta.
- Se valida que la ruta del archivo tenga el formato esperado para la cuenta y la conversación.
- Las URL firmadas duran 15 minutos para reducir el riesgo de mal uso.
Errores comunes y cómo resolverlos
Recomendaciones de implementación
- Llama a Iniciar justo antes de subir, para aprovechar los 15 minutos completos.
- Envía siempre un encabezado
Content-Typeexplícito en elPUT, que coincida con el archivo. - Guarda en tus registros la ruta del objeto que devuelve Iniciar. Te ayudará a diagnosticar problemas.
- Con archivos grandes, como videos para WhatsApp, evita reintentos innecesarios. Si la subida se estanca cerca del vencimiento, vuelve a iniciar.
- Valida tamaño y tipo en tu propio sistema antes de iniciar, para mostrar errores más rápido a tus usuarios.
Preguntas frecuentes
¿Es obligatorio el paso Completar?
¿Es obligatorio el paso Completar?
Sí. Es el que verifica el archivo guardado y te devuelve la URL final para usar en el mensaje.
¿Qué pasa si la URL vence a mitad de la subida?
¿Qué pasa si la URL vence a mitad de la subida?
Reinicia el flujo: vuelve a llamar a Iniciar, sube el archivo y completa.
¿El archivo queda público al completar?
¿El archivo queda público al completar?
El paso Completar devuelve una URL pública para usar en mensajes. Sigue las políticas de manejo de datos de tu negocio al compartirla.
¿Puedo subir cualquier tipo de archivo si cumple el tamaño?
¿Puedo subir cualquier tipo de archivo si cumple el tamaño?
No. Si la extensión y el tipo de contenido no coinciden, la validación lo bloquea.
¿Otros canales además de WhatsApp aceptan 100 MB?
¿Otros canales además de WhatsApp aceptan 100 MB?
No. Los demás canales tienen un límite de 5 MB.
¿Puedo reutilizar una URL firmada para varios archivos?
¿Puedo reutilizar una URL firmada para varios archivos?
No. Cada llamada a Iniciar genera una URL para un archivo, una ruta y un período específicos.