Documentación de MiAPI WhatsApp VIP
Esta API propia permite conectar múltiples números de WhatsApp (instancias por device_id) para VetIA y cualquiera de tus sistemas.
Ofrece dos modos de consumo equivalentes sobre el mismo núcleo:
- Modo Compatible (
?acao=...):https://api.nubetech.online/api.php?acao=NOMBRE_ACCION— enchufable directo en VetIA cambiando solo la URL base y el token. - Modo REST v1:
https://api.nubetech.online/v1/...— rutas limpias para nuevos sistemas.
Autenticación y Reglas de Validación
Cada cliente o sistema recibe un token único desde el Panel Admin. Podés enviarlo de cualquiera de estas formas:
- Encabezado HTTP:
Authorization: Bearer TU_TOKENoX-Api-Token: TU_TOKEN - Cuerpo JSON:
{"token": "TU_TOKEN", ...} - Query string:
?acao=meus_dados&token=TU_TOKEN
En cada petición el Gateway valida: token válido, estado activo, fecha de vencimiento, cupo de instancias, whitelist de IP/CIDR y whitelist de dominio (Origin / Referer / X-Client-Domain) si están configuradas.
Gestión de Cuenta e Instancias
Acción Legacy (api.php) | Equivalente REST v1 | Parámetros principales |
|---|---|---|
GET ?acao=meus_dados | GET /v1/account | token |
GET ?acao=minhas_instancias | GET /v1/instances | token |
POST ?acao=criar_instancia | POST /v1/instances | apelido, webhook_url (opc), cron_url (opc) |
GET ?acao=login_instancia | GET /v1/instances/{device_id}/qr | device_id |
GET ?acao=login_com_codigo | POST /v1/instances/{device_id}/pair-code | device_id, telefone |
GET ?acao=status_instancia | GET /v1/instances/{device_id}/status | device_id |
POST ?acao=atualizar_instancia | PATCH /v1/instances/{device_id} | device_id, apelido, webhook_url |
POST ?acao=logout_instancia | POST /v1/instances/{device_id}/logout | device_id |
POST ?acao=remover_instancia | DELETE /v1/instances/{device_id} | device_id |
Ejemplo: Crear instancia y obtener QR (PHP)
$ch = curl_init('https://api.nubetech.online/api.php?acao=criar_instancia');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'token' => 'TU_TOKEN',
'apelido' => 'Recepción VetIA',
'webhook_url' => 'https://tusistema.com/webhook_whatsapp.php',
]),
]);
$resp = json_decode(curl_exec($ch), true);
Mensajería, Multimedia y Encuestas
Acción Legacy (api.php) | Equivalente REST v1 | Campos |
|---|---|---|
POST ?acao=enviar_mensagem | POST /v1/messages/text | device_id, telefone, mensagem |
POST ?acao=enviar_midia | POST /v1/messages/media | device_id, telefone, tipo (image|audio|video|file), conteudo_base64, nome_arquivo, legenda |
POST ?acao=enviar_enquete | POST /v1/messages/poll | device_id, telefone, pergunta, opcoes[], max_respostas |
POST ?acao=reagir | POST /v1/messages/react | device_id, telefone, message_id, emoji |
POST ?acao=editar_mensagem | POST /v1/messages/edit | device_id, telefone, message_id, mensagem |
POST ?acao=apagar_mensagem | POST /v1/messages/delete | device_id, telefone, message_id |
POST ?acao=encaminhar | POST /v1/messages/forward | device_id, telefone (destino), message_id |
Ejemplo cURL (Enviar texto)
curl -X POST "https://api.nubetech.online/api.php?acao=enviar_mensagem" \
-H "Content-Type: application/json" \
-d '{
"token": "TU_TOKEN",
"device_id": "t1_a1b2c3d4e5",
"telefone": "5491122334455",
"mensagem": "Hola! Te recordamos tu turno veterinario mañana a las 10:00 hs."
}'
Grupos y Verificación de Números
| Acción Legacy | REST v1 | Campos |
|---|---|---|
GET ?acao=listar_grupos | GET /v1/groups | device_id |
POST ?acao=enviar_msg_grupo | POST /v1/groups/send | device_id, grupo_id, mensagem |
POST ?acao=criar_grupo | POST /v1/groups | device_id, nome, participantes[] |
POST ?acao=verificar_numero_whatsapp | POST /v1/contacts/check | device_id, telefone |
Perfil de Empresa y Cuenta
| Acción Legacy | REST v1 | Campos |
|---|---|---|
GET ?acao=perfil_empresa | GET /v1/profile/business | device_id, telefone (opcional, por defecto la instancia) |
GET ?acao=info_usuario | GET /v1/profile/info | device_id, telefone (opcional) |
GET ?acao=obter_avatar | GET /v1/profile/avatar | device_id, telefone (opcional) |
POST ?acao=atualizar_avatar | POST /v1/profile/avatar | device_id, conteudo_base64, nome_arquivo (opc) |
POST ?acao=atualizar_nome | POST /v1/profile/name | device_id, nome (pushname visible) |
Cola Antibaneo, Spintax y Opt-Out
Todos los envíos (enviar_mensagem, enviar_midia, enviar_enquete, enviar_msg_grupo) entran automáticamente en la cola asíncrona antibaneo y devuelven al instante "queued": true y "queue_id".
- Prioridad: enviá
"prioridade": "alta"(o"priority": "high") para respuestas 1-a-1 en tiempo real (salta delante de campañas y no queda retenido por horario nocturno). - Spintax: podés usar variaciones como
"{Hola|Buen día|Qué tal} {cliente|amigo}"; la API elige una variante aleatoria en cada mensaje. - Programar envío: parámetro opcional
"agendar_para": "2026-11-12 09:30:00". - Opt-Out automático: si un contacto responde
SALIR,BAJA,STOPoNO MAS, se bloquean futuros envíos a ese número.
| Acción Legacy | REST v1 | Campos |
|---|---|---|
GET ?acao=status_mensagem | GET /v1/queue/{id} | queue_id |
GET ?acao=listar_fila | GET /v1/queue | device_id (opc), status (opc) |
POST ?acao=cancelar_mensagem | DELETE /v1/queue/{id} | queue_id |
GET ?acao=stats_antibaneo | GET /v1/instances/{id}/antiban-stats | device_id |
POST ?acao=bloquear_contato | POST /v1/optouts | telefone, motivo (opc) |
POST ?acao=desbloquear_contato | DELETE /v1/optouts | telefone |
GET ?acao=listar_bloqueados | GET /v1/optouts | token |
Webhooks Entrantes y Cron Periódico
Cada vez que llega un mensaje o cambia el estado de conexión de una instancia, el Gateway reenvía un POST JSON a la webhook_url configurada en esa instancia. Tu receptor debe responder HTTP 200 rápidamente.
Si la instancia tiene configurado un cron_url, el runner (scripts/run_crons.php) lo invoca periódicamente por POST JSON con evento: "cron", device_id, status y telefone para clientes activos y vigentes.
Cabeceras enviadas por el Gateway: X-ApiVip-Event, X-ApiVip-DeviceId y opcionalmente X-ApiVip-Signature (HMAC-SHA256).
Códigos de Estado HTTP
200: Operación exitosa ("ok": true).400: Parámetros faltantes o inválidos.401: Token ausente o inválido.402: Acceso vencido (expires_atsuperado).403: Cuenta suspendida, cupo de instancias alcanzado, o IP/dominio fuera de whitelist.404: Instancia no encontrada o perteneciente a otro cliente.502: Motor GoWA inaccesible o error al comunicarse con WhatsApp.
Admin API (para automatizar desde tu sistema de facturación)
Endpoint: https://api.nubetech.online/admin/api.php?acao=... con encabezado X-Admin-Key: TU_ADMIN_MASTER_KEY.
GET ?acao=listar_clientesPOST ?acao=crear_cliente(name,system_name,max_instances,expires_at,allowed_ips,allowed_domains)POST ?acao=actualizar_cliente(id+ campos a modificar, ej.status: "suspended"o nueva fechaexpires_at)POST ?acao=regenerar_token(id)