Referencia de la API REST

WQRJB expone una API REST que permite enviar mensajes de texto y documentos PDF directamente desde tus sistemas.

Referencia interactiva (Swagger)

Puedes explorar y probar todos los endpoints directamente en la documentación interactiva: https://panel.wqr.jbsoft.pe/api/docs

El Swagger UI permite ejecutar solicitudes en tiempo real con tu token. Esta página es el complemento narrativo para integración y ejemplos de código.

Autenticación

Todas las solicitudes requieren un Bearer Token en el encabezado HTTP:

Authorization: Bearer {tu_token_api}

Obtienes este token de tu Reseller. Inclúyelo en cada solicitud.

URL bases

1. URL base: https://api.wqr.jbsoft.pe/api
2. URL base específica: https://api.wqr.jbsoft.pe/{session_name}/api

Tu Reseller te proporcionará la URL exacta del servidor.

Endpoints

GET /api/me

Verifica que tu token sea válido y obtiene información de tu cuenta, disponible solo para URL base Ref. URL bases.

Solicitud:

GET /api/me
Authorization: Bearer {token}

Respuesta exitosa (200 OK):

{
  "id": 5,
  "company_name": "Mi Empresa S.A.",
  "status": "active",
  "max_sessions": 3
}

GET /api/sessions

Lista todas tus sesiones de WhatsApp, disponible solo para URL base Ref. URL bases.

Solicitud:

GET /api/sessions
Authorization: Bearer {token}

Respuesta exitosa (200 OK):

[
  {
    "session_name": "ventas-01",
    "label": "Ventas",
    "phone_number": "50212345678",
    "status": "connected",
    "connected_at": "2025-03-20T10:30:00Z"
  },
  {
    "session_name": "soporte-01",
    "label": "Soporte",
    "phone_number": null,
    "status": "disconnected",
    "connected_at": null
  }
]

Estados posibles de sesión:

Estado	Significado
`connected`	Activa y lista para enviar mensajes
`connecting`	Esperando que el usuario escanee el QR
`disconnected`	Desconectada, no puede enviar mensajes
`failed`	Error de conexión

GET /api/sessions/`{session_name}`

Obtiene el estado de una sesión específica, disponible solo para URL base Ref. URL bases.

Solicitud:

GET /api/sessions/ventas-01
Authorization: Bearer {token}

Respuesta exitosa (200 OK):

{
  "session_name": "ventas-01",
  "label": "Ventas",
  "phone_number": "50212345678",
  "whatsapp_name": "Empresa Ventas",
  "status": "connected",
  "connected_at": "2025-03-20T10:30:00Z"
}

POST /api/sessions/`{session_name}`/connect-link

Genera un enlace público temporal para que el cliente final escanee el código QR de la sesión, disponible solo para URL base Ref. URL bases.

Solicitud:

POST /api/sessions/ventas-01/connect-link
Authorization: Bearer {token}

Respuesta exitosa (200 OK):

{
  "url": "https://tu-dominio.com/connect/abc123xyz",
  "expires_at": "2025-03-25T15:45:00Z"
}

El enlace expira automáticamente. Una vez escaneado el QR, el enlace deja de funcionar.

POST /api/message/send-text

Envía un mensaje de texto a un número de WhatsApp, disponible para URL base y URL base específica Ref. URL bases.

Solicitud:

POST /api/message/send-text
Authorization: Bearer {token}
Content-Type: application/json

{
  "session": "ventas-01",
  "phone": "50212345678",
  "message": "Hola, tu pedido está listo para recoger."
}

Parámetros del cuerpo:

Campo	Tipo	Requerido	Descripción
`session`	string	Sí	Nombre de la sesión a usar
`phone`	string	Sí	Número de WhatsApp (con código de país, sin `+`)
`message`	string	Sí	Texto del mensaje

Respuesta exitosa (200 OK):

{
  "success": true,
  "message_id": "3EB0123456789ABCDEF",
  "recipient": "50212345678"
}

Respuesta de error — sesión desconectada (422):

{
  "error": "Session is not connected",
  "session": "ventas-01",
  "status": "disconnected"
}

POST /api/message/send/pdf

Envía un archivo PDF a un número de WhatsApp. Puedes enviar el PDF por URL o en base64, disponible para URL base y URL base específica Ref. URL bases.

Opción A: PDF por URL

POST /api/message/send/pdf
Authorization: Bearer {token}
Content-Type: application/json

{
  "session": "ventas-01",
  "phone": "50212345678",
  "pdf_url": "https://mi-servidor.com/facturas/FAC-001.pdf",
  "caption": "Adjunto tu factura del mes de marzo."
}

Opción B: PDF en base64

POST /api/message/send/pdf
Authorization: Bearer {token}
Content-Type: application/json

{
  "session": "ventas-01",
  "phone": "50212345678",
  "pdf_base64": "JVBERi0xLjQKJeLjz9MKNiAwIG9iago...",
  "filename": "Factura-001.pdf",
  "caption": "Adjunto tu factura del mes de marzo."
}

Parámetros del cuerpo:

Campo	Tipo	Requerido	Descripción
`session`	string	Sí	Nombre de la sesión a usar
`phone`	string	Sí	Número de WhatsApp (con código de país, sin `+`)
`pdf_url`	string	Condicional	URL pública del PDF (usar si no se envía base64)
`pdf_base64`	string	Condicional	Contenido del PDF en base64 (usar si no se envía URL)
`filename`	string	No	Nombre del archivo (por defecto: `document.pdf`)
`caption`	string	No	Texto que acompaña al archivo

nota

El tamaño máximo del archivo es 50 MB.

Respuesta exitosa (200 OK):

{
  "success": true,
  "message_id": "3EB0987654321FEDCBA",
  "recipient": "50212345678"
}

Formato de números de teléfono

Todos los números deben enviarse con el código de país y sin caracteres especiales:

Correcto	Incorrecto
`50212345678`	`+502 1234-5678`
`50299887766`	`(502) 9988-7766`
`17025551234`	`+1 702 555-1234`

La longitud válida es entre 8 y 15 dígitos.

Códigos de respuesta

Código	Significado
`200`	Solicitud procesada correctamente
`401`	Token inválido o no proporcionado
`403`	Cuenta suspendida o sin acceso
`404`	Sesión no encontrada
`422`	Error de validación (datos incorrectos o sesión desconectada)
`429`	Límite de mensajes diarios alcanzado
`500`	Error interno del servidor

Ejemplo de integración en PHP

<?php

$token   = 'tu_token_api';
$baseUrl = 'https://api.wqr.jbsoft.pe/api';

function enviarMensaje(string $session, string $phone, string $mensaje): array
{
    global $token, $baseUrl;

    $ch = curl_init("$baseUrl/message/send-text");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer $token",
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'session' => $session,
            'phone'   => $phone,
            'message' => $mensaje,
        ]),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

$resultado = enviarMensaje('ventas-01', '50212345678', 'Tu pedido está listo.');
print_r($resultado);

Ejemplo de integración en JavaScript (Node.js)

const axios = require("axios");

const token = "tu_token_api";
const baseUrl = "https://api.wqr.jbsoft.pe/api";

async function enviarMensaje(session, phone, message) {
  const response = await axios.post(
    `${baseUrl}/message/send-text`,
    { session, phone, message },
    { headers: { Authorization: `Bearer ${token}` } },
  );
  return response.data;
}

enviarMensaje("ventas-01", "50212345678", "Tu pedido está listo.")
  .then(console.log)
  .catch(console.error);

Autenticación​

URL bases​

Endpoints​

GET /api/me​

GET /api/sessions​

GET /api/sessions/{session_name}​

POST /api/sessions/{session_name}/connect-link​

POST /api/message/send-text​

POST /api/message/send/pdf​

Opción A: PDF por URL​

Opción B: PDF en base64​

Formato de números de teléfono​

Códigos de respuesta​

Ejemplo de integración en PHP​

Ejemplo de integración en JavaScript (Node.js)​

Autenticación

URL bases

Endpoints

GET /api/me

GET /api/sessions

GET /api/sessions/`{session_name}`

POST /api/sessions/`{session_name}`/connect-link

POST /api/message/send-text

POST /api/message/send/pdf

Opción A: PDF por URL

Opción B: PDF en base64

Formato de números de teléfono

Códigos de respuesta

Ejemplo de integración en PHP

Ejemplo de integración en JavaScript (Node.js)