Docs: Documentar API REST con endpoints de API Key
All checks were successful
build-and-deploy / build-and-deploy (push) Successful in 1m10s
All checks were successful
build-and-deploy / build-and-deploy (push) Successful in 1m10s
- Agregar tabla resumen de endpoints disponibles - Documentar endpoint principal POST /api/messages/send - Documentar GET /api/messages/:instanceId/chats para listar contactos - Documentar GET /api/messages/:instanceId/:chatId con paginación - Documentar POST /api/messages/:instanceId/react para reacciones - Eliminar documentación de endpoints OAuth (solo interfaz web)
This commit is contained in:
257
README.md
257
README.md
@@ -37,12 +37,21 @@ node .output/server/index.mjs
|
|||||||
|
|
||||||
### Autenticación
|
### Autenticación
|
||||||
|
|
||||||
Todos los endpoints requieren autenticación mediante API Key:
|
**API Externa (servicios, bots, agentes):**
|
||||||
|
|
||||||
```
|
```
|
||||||
Authorization: Bearer <NUXT_MASTER_API_KEY>
|
Authorization: Bearer <NUXT_MASTER_API_KEY>
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Resumen de Endpoints
|
||||||
|
|
||||||
|
| Endpoint | Descripción |
|
||||||
|
|----------|-------------|
|
||||||
|
| `POST /api/messages/send` | **Enviar mensaje de texto** |
|
||||||
|
| `GET /api/instances` | Listar instancias |
|
||||||
|
| `GET /api/messages/:instanceId/chats` | Listar chats/contactos |
|
||||||
|
| `GET /api/messages/:instanceId/:chatId` | Obtener mensajes de un chat |
|
||||||
|
| `POST /api/messages/:instanceId/react` | Reaccionar a un mensaje |
|
||||||
|
|
||||||
### Instancias
|
### Instancias
|
||||||
|
|
||||||
| Método | Endpoint | Descripción |
|
| Método | Endpoint | Descripción |
|
||||||
@@ -218,225 +227,40 @@ curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatI
|
|||||||
### Enviar Mensajes
|
### Enviar Mensajes
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/messages/:instanceId/:chatId/send
|
POST /api/messages/send
|
||||||
```
|
```
|
||||||
|
|
||||||
Endpoint unificado para enviar todos los tipos de mensaje. El tipo se detecta automáticamente según el Content-Type y body.
|
**Este es el endpoint principal para enviar mensajes desde servicios externos.** Solo requiere el número de teléfono, no necesitas buscar el chatId previamente.
|
||||||
|
|
||||||
#### Mensaje de Texto
|
**Parámetros:**
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"content": "Hola! Este es un mensaje de texto"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Con mensaje citado:**
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"content": "Esta es mi respuesta",
|
|
||||||
"quotedMessageId": "3EB0A1B2C3D4E5F6"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Imagen
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@foto.jpg" \
|
|
||||||
-F "caption=Descripción de la imagen"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Video
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@video.mp4" \
|
|
||||||
-F "caption=Mi video"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Audio / Nota de Voz
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Audio normal
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@audio.mp3"
|
|
||||||
|
|
||||||
# Nota de voz (PTT - Push To Talk)
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@nota.ogg" \
|
|
||||||
-F "isPtt=true"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Documento
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@reporte.pdf" \
|
|
||||||
-F "caption=Reporte mensual de ventas"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Sticker
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@imagen.png" \
|
|
||||||
-F 'asSticker=["true"]'
|
|
||||||
```
|
|
||||||
|
|
||||||
> Se convierte automáticamente a WebP. Formatos soportados: JPG, PNG, WebP.
|
|
||||||
|
|
||||||
#### Contacto
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"type": "contact",
|
|
||||||
"contacts": [
|
|
||||||
{
|
|
||||||
"displayName": "Juan Pérez",
|
|
||||||
"phoneNumber": "+5491155551234",
|
|
||||||
"organization": "Empresa SA"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Múltiples contactos:**
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"type": "contact",
|
|
||||||
"contacts": [
|
|
||||||
{"displayName": "Juan", "phoneNumber": "+5491155551234"},
|
|
||||||
{"displayName": "María", "phoneNumber": "+5491166662345"}
|
|
||||||
]
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Encuesta (Poll)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"type": "poll",
|
|
||||||
"name": "¿Qué día prefieres para la reunión?",
|
|
||||||
"options": ["Lunes", "Martes", "Miércoles", "Jueves", "Viernes"],
|
|
||||||
"selectableCount": 1
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Parámetros de Poll:**
|
|
||||||
| Campo | Requerido | Descripción |
|
| Campo | Requerido | Descripción |
|
||||||
|-------|-----------|-------------|
|
|-------|-----------|-------------|
|
||||||
| `name` | Sí | Pregunta de la encuesta |
|
| `instanceId` | Sí | ID de la instancia de WhatsApp |
|
||||||
| `options` | Sí | Array de opciones (mín: 2, máx: 12) |
|
| `to` | Sí | Número de teléfono (con o sin código país) |
|
||||||
| `selectableCount` | No | Cuántas opciones se pueden elegir (default: 1) |
|
| `message` | Sí | Texto del mensaje |
|
||||||
|
|
||||||
#### Evento
|
|
||||||
|
|
||||||
|
**Ejemplo:**
|
||||||
```bash
|
```bash
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/send" \
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
-H "Authorization: Bearer <API_KEY>" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{
|
-d '{
|
||||||
"type": "event",
|
"instanceId": "4b57e897-f29b-4562-bd41-9a6fa32d584b",
|
||||||
"name": "Reunión de equipo",
|
"to": "5491155551234",
|
||||||
"startDate": "2025-01-20T14:00:00Z",
|
"message": "Hola! Este es un mensaje de texto"
|
||||||
"endDate": "2025-01-20T15:00:00Z",
|
|
||||||
"description": "Revisión semanal del proyecto",
|
|
||||||
"location": {
|
|
||||||
"name": "Oficina Central",
|
|
||||||
"address": "Av. Corrientes 1234, CABA",
|
|
||||||
"latitude": -34.6037,
|
|
||||||
"longitude": -58.3816
|
|
||||||
}
|
|
||||||
}'
|
}'
|
||||||
```
|
```
|
||||||
|
|
||||||
**Parámetros de Event:**
|
**Respuesta:**
|
||||||
| Campo | Requerido | Descripción |
|
|
||||||
|-------|-----------|-------------|
|
|
||||||
| `name` | Sí | Nombre del evento |
|
|
||||||
| `startDate` | Sí | Fecha/hora inicio (ISO 8601) |
|
|
||||||
| `endDate` | No | Fecha/hora fin |
|
|
||||||
| `description` | No | Descripción del evento |
|
|
||||||
| `location.name` | No | Nombre del lugar |
|
|
||||||
| `location.address` | No | Dirección |
|
|
||||||
| `location.latitude` | No | Latitud |
|
|
||||||
| `location.longitude` | No | Longitud |
|
|
||||||
|
|
||||||
**Respuesta de envío (todos los tipos):**
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"success": true,
|
||||||
"messages": [
|
"messageId": "3EB06791F557866FDA1823",
|
||||||
{
|
"to": "5491155551234@s.whatsapp.net"
|
||||||
"messageId": "3EB0A1B2C3D4E5F6",
|
|
||||||
"type": "text"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
> **Nota:** El número se formatea automáticamente a JID. Puedes enviar `5491155551234` o `+54 9 11 5555-1234`, ambos funcionan.
|
||||||
|
|
||||||
### Responder/Citar Mensajes (quotedMessageId)
|
|
||||||
|
|
||||||
Todos los tipos de mensaje soportan citar otro mensaje usando `quotedMessageId`. El mensaje citado aparece como "respuesta a" en WhatsApp.
|
|
||||||
|
|
||||||
**Texto citando otro mensaje:**
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"content": "Totalmente de acuerdo!",
|
|
||||||
"quotedMessageId": "3EB0A1B2C3D4E5F6"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Imagen citando otro mensaje:**
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-F "file=@imagen.jpg" \
|
|
||||||
-F "caption=Mira esto!" \
|
|
||||||
-F "quotedMessageId=3EB0A1B2C3D4E5F6"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Encuesta citando otro mensaje:**
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
|
|
||||||
-H "Authorization: Bearer <API_KEY>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"type": "poll",
|
|
||||||
"name": "¿Qué opinan sobre esto?",
|
|
||||||
"options": ["De acuerdo", "En desacuerdo", "Neutral"],
|
|
||||||
"quotedMessageId": "3EB0A1B2C3D4E5F6"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Nota:** El `quotedMessageId` se obtiene del campo `messageId` al listar mensajes con `GET /api/messages/:instanceId/:chatId`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -493,35 +317,6 @@ curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/react
|
|||||||
|
|
||||||
> **Nota:** El `messageId` se obtiene de la respuesta al obtener mensajes (`GET /api/messages/:instanceId/:chatId`)
|
> **Nota:** El `messageId` se obtiene de la respuesta al obtener mensajes (`GET /api/messages/:instanceId/:chatId`)
|
||||||
|
|
||||||
### Formato de Destinatarios (JID)
|
|
||||||
|
|
||||||
- **Contacto individual:** `5491155551234@s.whatsapp.net` (código país sin +)
|
|
||||||
- **Grupo:** `123456789012345678@g.us`
|
|
||||||
|
|
||||||
### Tipos de Mensaje Soportados
|
|
||||||
|
|
||||||
| Tipo | Descripción |
|
|
||||||
|------|-------------|
|
|
||||||
| `text` | Mensaje de texto |
|
|
||||||
| `image` | Imagen con caption opcional |
|
|
||||||
| `video` | Video con caption opcional |
|
|
||||||
| `audio` | Audio o nota de voz |
|
|
||||||
| `document` | Documento/archivo |
|
|
||||||
| `sticker` | Sticker |
|
|
||||||
| `contact` | Tarjeta de contacto |
|
|
||||||
| `poll` | Encuesta (2-12 opciones) |
|
|
||||||
| `event` | Evento con fecha/ubicación |
|
|
||||||
|
|
||||||
### Límites de Archivos
|
|
||||||
|
|
||||||
| Tipo | Tamaño Máximo |
|
|
||||||
|------|---------------|
|
|
||||||
| Imagen | 16 MB |
|
|
||||||
| Video | 64 MB |
|
|
||||||
| Audio | 16 MB |
|
|
||||||
| Documento | 100 MB |
|
|
||||||
| Sticker | 500 KB |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Stack
|
## Stack
|
||||||
|
|||||||
Reference in New Issue
Block a user