# Notificar en lote

`POST` `https://api.pushwoosh.com/messaging/v2/notify/batch`

Envía varios mensajes en una sola llamada. Cada elemento es una [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/) independiente: se valida exactamente igual que una solicitud `Notify` autónoma y obtiene su propio resultado.

<Aside type="caution" title="Lee los resultados, no el código de estado">
La llamada en sí devuelve HTTP 200 siempre que el sobre del lote sea válido, incluso si cada uno de los elementos ha fallado. Un elemento que falla nunca hace que falle toda la solicitud. Comprueba siempre `results[]` y los contadores `succeeded` / `failed`; no trates una respuesta 200 como una confirmación de que los mensajes se han enviado.
</Aside>

<Aside type="tip" title="Esta no es una forma más rápida de enviar">
`NotifyBatch` no envía mensajes más rápido que llamar a `Notify` directamente. Si tu integración ya puede emitir solicitudes de forma concurrente, ejecutar `Notify` en hilos/workers paralelos proporciona el mismo rendimiento; HTTP/2 lo gestiona por diseño. Usa `NotifyBatch` por comodidad cuando tu integración no esté diseñada para la concurrencia, no por velocidad.
</Aside>

## Estructura de la solicitud

```json title="Shape"
{
  "items": [
    {
      "item_id": "caller-defined-id",
      "request": { ... }
    }
  ]
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `items` | array de `NotifyBatchItem` | Requerido, de 1 a 500 entradas (límite configurado por el servidor). Los elementos se procesan de forma concurrente; los resultados se devuelven en el orden de la solicitud independientemente de ello. |

### NotifyBatchItem

| Campo | Tipo | Descripción |
|---|---|---|
| `item_id` | string | ID de correlación opcional proporcionado por el llamante, devuelto en el resultado correspondiente. Pushwoosh no lo utiliza para ningún otro fin. |
| `request` | [`NotifyRequest`](/es/developer/api-reference/messaging-api-v2/notify/#request-structure) | Mismo cuerpo que una llamada `Notify` única — `segment` o `transactional`, `transaction_id` incluido. Requerido. |

<Aside type="note" title="schedule sigue siendo requerido por elemento">
El `request` de cada elemento necesita su propio `schedule`, exactamente como una llamada `Notify` independiente. Omitirlo no recurre a "enviar ahora"; el elemento falla con un error `EmptySchedule`.
</Aside>

<Aside type="tip" title="Reintentar un lote es seguro">
Establece `transaction_id` en el `request` de cada elemento. Una llamada repetida con el mismo `transaction_id` devuelve el mismo `message_code` para ese elemento dentro de la ventana de deduplicación de 5 minutos descrita en la página [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/#request-structure) — por lo que reintentar todo el lote después de un error de red no duplica los mensajes que ya se enviaron.
</Aside>

### Ejemplo

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify/batch \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "order-1001",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-123"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1001-shipped"
          }
        }
      },
      {
        "item_id": "order-1002",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-456"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1002-shipped"
          }
        }
      }
    ]
  }'
```

## Respuesta

```json
{
  "results": [
    {
      "item_id": "order-1001",
      "index": 0,
      "result": {
        "message_code": "XXXXX-XXXXX-XXXXX",
        "unknown_identifiers": []
      }
    },
    {
      "item_id": "order-1002",
      "index": 1,
      "error": {
        "code": 3,
        "message": "invalid argument",
        "reason": "EmptySchedule",
        "domain": "api.pushwoosh.com"
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `results` | array de `NotifyBatchResult` | Una entrada por cada elemento solicitado, en el orden de la solicitud. |
| `succeeded` | entero | Número de elementos que devolvieron un resultado. |
| `failed` | entero | Número de elementos que devolvieron un error. |

### NotifyBatchResult

| Campo | Tipo | Descripción |
|---|---|---|
| `item_id` | string | Eco del `item_id` del elemento de la solicitud. |
| `index` | entero | Posición del elemento en la solicitud, basada en cero. Úsalo para correlacionar resultados cuando `item_id` se dejó vacío. |
| `result` | objeto | Se establece cuando el elemento tuvo éxito — misma forma que una respuesta [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/#response) única: `message_code` y `unknown_identifiers`. |
| `error` | `NotifyBatchError` | Se establece cuando el elemento falló. |

### NotifyBatchError

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | entero | Código de estado gRPC (`google.rpc.Code`), p. ej. `3` para `INVALID_ARGUMENT`. |
| `message` | string | Mensaje de error para el desarrollador, en inglés. |
| `reason` | string | Nombre corto del estado — el mismo valor que devolvería una llamada `Notify` única, p. ej. `EmptySchedule`. |
| `domain` | string | Dominio del error, `api.pushwoosh.com`. |

## Errores

Los errores utilizan el sobre de error estándar de gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`. Estos son errores a nivel de sobre que hacen que falle toda la solicitud; un elemento individual que falla produce un `error` por elemento en `results[]` en su lugar (ver [NotifyBatchError](#notifybatcherror) arriba), no uno de estos.

| Estado HTTP | Condición |
|---|---|
| `400` | `items` está vacío. |
| `400` | `items` tiene más del límite configurado por el servidor (500 por defecto). |
| `400` | A uno de los elementos le falta `request`. |

**Ejemplo**

Enviar 501 elementos cuando el límite es 500 devuelve HTTP `400`:

```json
{
  "code": 3,
  "message": "items must not exceed 500 entries, got 501",
  "details": []
}
```

## Relacionado

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Referencia de Payload" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="Visión general de la API de mensajería v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migración desde v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>