Subir archivo multimedia

POST /api/v1/media-upload

Este endpoint permite subir un archivo multimedia a los servidores para obtener su ruta interna (media_path). Esta ruta física generada es necesaria posteriormente para enviarla de forma dinámica como un adjunto al utilizar el endpoint de envío de plantillas de WhatsApp.

El proceso es fundamental cuando se requiere enviar documentos, imágenes o videos personalizados que no forman parte de la configuración predeterminada de una plantilla. Esto permite una mayor flexibilidad en la comunicación, habilitando casos de uso como el envío de facturas, boletas, reportes, catálogos o contenido visual específico para cada destinatario.

El endpoint requiere una solicitud POST con un cuerpo en formato multipart/form-data que contenga el archivo que se desea subir al servidor. A continuación, se detalla su uso, incluyendo los parámetros requeridos, extensiones soportadas y la estructura de la respuesta.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).
Content-Type	String	✅ Sí	Debe ser multipart/form-data.

Cuerpo de la solicitud

Atributo	Tipo	Obligatorio	Descripción
file	Archivo	✅ Sí	El archivo multimedia a subir. (Límite: 20MB)

📝 Identificación de Equipo

El identificador de equipo se extrae automáticamente del token provisto en la cabecera Authorization. No envíe ningún parámetro de identificación adicional, cualquier intento de modificarlo será ignorado por seguridad.

Formatos soportados

Dependiendo del tipo de plantilla que vayas a utilizar, asegúrate de subir el archivo en el formato correcto que Meta soporta:

• Documentos: .pdf
• Imágenes: .jpg, .jpeg, .png
• Videos: .mp4

Ejemplo de solicitud completa

POST /api/v1/media-upload

La solicitud debe enviarse como multipart/form-data, adjuntando el archivo en el campo o atributo file. En una petición cURL se vería de la siguiente manera:

curl --location 'https://api.tu-dominio.com/api/v1/media-upload' \
--header 'Authorization: Bearer TU_TOKEN_AQUI' \
--form 'file=@"/ruta/local/al/archivo/documento.pdf"'

Respuesta

La API devuelve un json con la siguiente estructura.

Respuesta base 200

{
  "message": "Archivo subido correctamente",
  "data": {
    "full_name": "mi_archivo_1711894400.pdf",
    "media_path": "uploads/team1/mi_archivo_1711894400.pdf",
    "type": "application/pdf",
    "size": 102450
  }
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de respuesta del servidor.
data.full_name	String	Nombre autogenerado y único para el archivo en el servidor.
data.media_path	String	Ruta interna del archivo, la cual debes usar en el endpoint de envío.
data.type	String	Tipo MIME detectado del archivo subido.
data.size	Integer	Tamaño del archivo en bytes.

Errores generales

Código HTTP	Tipo	Causa común
401	Unauthorized	El token de acceso no fue proporcionado en el encabezado Authorization, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
422	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, from_date no es una fecha válida); 2. Recurso inexistente (wa_number no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
500	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.