> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operaciones Masivas

> Ejecuta operaciones en múltiples contactos a la vez

Realiza operaciones masivas sobre contactos: crear, actualizar, eliminar, gestionar tags y mover en el funnel.

<Warning>
  **Límites:**

  * Máximo **100 contactos** por request
  * Rate limit: **10 requests/minuto** para operaciones bulk
</Warning>

***

## Operaciones Disponibles

| Operación          | Descripción                                |
| ------------------ | ------------------------------------------ |
| `create`           | Crear múltiples contactos                  |
| `update`           | Actualizar múltiples contactos             |
| `delete`           | Eliminar múltiples contactos (soft delete) |
| `add_tags`         | Agregar tags a múltiples contactos         |
| `remove_tags`      | Remover tags de múltiples contactos        |
| `set_funnel_stage` | Mover contactos a una etapa del funnel     |

***

## Body Parameters

<ParamField body="operation" type="string" required>
  Tipo de operación: `create`, `update`, `delete`, `add_tags`, `remove_tags`, `set_funnel_stage`
</ParamField>

<ParamField body="contacts" type="array">
  **Para `create` y `update`**: Array de objetos de contacto
</ParamField>

<ParamField body="contact_ids" type="string[]">
  **Para `delete`, `add_tags`, `remove_tags`, `set_funnel_stage`**: Array de UUIDs
</ParamField>

<ParamField body="tags" type="string[]">
  **Para `add_tags` y `remove_tags`**: Tags a agregar/remover
</ParamField>

<ParamField body="funnel_stage_id" type="string">
  **Para `set_funnel_stage`**: UUID de la etapa destino
</ParamField>

***

## Ejemplos por Operación

### Crear Múltiples Contactos

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/contacts/v1/bulk \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "operation": "create",
      "contacts": [
        { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
        { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
        { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/contacts/v1/bulk', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'create',
      contacts: [
        { phone_number: '+5215512345678', name: 'Juan', tags: ['lead'] },
        { phone_number: '+5215587654321', name: 'María', tags: ['lead'] },
        { phone_number: '+5215511223344', name: 'Pedro', tags: ['lead'] }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.whaapy.com/contacts/v1/bulk',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'operation': 'create',
          'contacts': [
              {'phone_number': '+5215512345678', 'name': 'Juan', 'tags': ['lead']},
              {'phone_number': '+5215587654321', 'name': 'María', 'tags': ['lead']},
              {'phone_number': '+5215511223344', 'name': 'Pedro', 'tags': ['lead']}
          ]
      }
  )
  ```
</RequestExample>

### Agregar Tags Masivamente

<RequestExample>
  ```json Request theme={null}
  {
    "operation": "add_tags",
    "contact_ids": [
      "uuid-1",
      "uuid-2",
      "uuid-3"
    ],
    "tags": ["campaña-enero", "newsletter"]
  }
  ```
</RequestExample>

### Remover Tags

<RequestExample>
  ```json Request theme={null}
  {
    "operation": "remove_tags",
    "contact_ids": ["uuid-1", "uuid-2"],
    "tags": ["lead", "sin-atender"]
  }
  ```
</RequestExample>

### Mover a Etapa del Funnel

<RequestExample>
  ```json Request theme={null}
  {
    "operation": "set_funnel_stage",
    "contact_ids": ["uuid-1", "uuid-2"],
    "funnel_stage_id": "stage-qualified-uuid"
  }
  ```
</RequestExample>

### Actualizar Múltiples Contactos

<RequestExample>
  ```json Request theme={null}
  {
    "operation": "update",
    "contacts": [
      { 
        "id": "uuid-1", 
        "add_tags": ["verificado"],
        "custom_fields": { "verified_at": "2026-01-28" }
      },
      { 
        "id": "uuid-2", 
        "add_tags": ["verificado"],
        "custom_fields": { "verified_at": "2026-01-28" }
      }
    ]
  }
  ```
</RequestExample>

### Eliminar Múltiples Contactos

<RequestExample>
  ```json Request theme={null}
  {
    "operation": "delete",
    "contact_ids": ["uuid-1", "uuid-2", "uuid-3"]
  }
  ```
</RequestExample>

***

## Respuestas

### Operación Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "operation": "add_tags",
    "success_count": 3,
    "error_count": 0,
    "results": [
      { "contact_id": "uuid-1", "success": true },
      { "contact_id": "uuid-2", "success": true },
      { "contact_id": "uuid-3", "success": true }
    ]
  }
  ```
</ResponseExample>

### Con Errores Parciales

<ResponseExample>
  ```json 207 Multi-Status theme={null}
  {
    "operation": "create",
    "success_count": 2,
    "error_count": 1,
    "results": [
      { 
        "phone_number": "+5215512345678", 
        "success": true, 
        "contact_id": "new-uuid-1" 
      },
      { 
        "phone_number": "+5215587654321", 
        "success": true, 
        "contact_id": "new-uuid-2" 
      },
      { 
        "phone_number": "+5215511223344", 
        "success": false, 
        "error": "duplicate_contact",
        "existing_contact_id": "existing-uuid"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  El código `207 Multi-Status` indica que algunas operaciones tuvieron éxito y otras fallaron. Revisa el array `results` para ver el detalle de cada una.
</Note>

### Errores Posibles en Results

| Error                  | Descripción                            |
| ---------------------- | -------------------------------------- |
| `not_found`            | Contacto no encontrado                 |
| `duplicate_contact`    | Ya existe un contacto con ese teléfono |
| `invalid_phone_number` | Número de teléfono inválido            |
| `create_failed`        | Error al crear contacto                |
| `update_failed`        | Error al actualizar contacto           |
| `delete_failed`        | Error al eliminar contacto             |
| `add_tags_failed`      | Error al agregar tags                  |
| `remove_tags_failed`   | Error al remover tags                  |
| `set_funnel_failed`    | Error al asignar etapa del funnel      |

***

## Casos de Uso

<AccordionGroup>
  <Accordion title="Importar contactos de CSV">
    Después de parsear un archivo CSV, crea los contactos en lote:

    ```javascript theme={null}
    const contacts = csvRows.map(row => ({
      phone_number: row.telefono,
      name: row.nombre,
      email: row.email,
      tags: ['importado-csv']
    }));

    // Dividir en chunks de 100
    for (let i = 0; i < contacts.length; i += 100) {
      await api.post('/contacts/v1/bulk', {
        operation: 'create',
        contacts: contacts.slice(i, i + 100)
      });
    }
    ```
  </Accordion>

  <Accordion title="Etiquetar resultados de campaña">
    Después de enviar una campaña, etiqueta los contactos:

    ```json theme={null}
    {
      "operation": "add_tags",
      "contact_ids": ["...ids de la campaña..."],
      "tags": ["campaña-enero-2026", "email-enviado"]
    }
    ```
  </Accordion>

  <Accordion title="Limpiar contactos inactivos">
    Elimina contactos que no han interactuado en 1 año:

    ```json theme={null}
    {
      "operation": "delete",
      "contact_ids": ["...ids de búsqueda avanzada..."]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Búsqueda Avanzada" icon="magnifying-glass" href="/api-reference/contacts/search">
    Encontrar contactos para operaciones masivas
  </Card>

  <Card title="Listar Contactos" icon="list" href="/api-reference/contacts/list">
    Ver contactos actualizados
  </Card>

  <Card title="Fusionar Contactos" icon="code-merge" href="/api-reference/contacts/merge">
    Combinar duplicados
  </Card>

  <Card title="Listar Tags" icon="tags" href="/api-reference/contacts/tags">
    Ver tags disponibles
  </Card>
</CardGroup>