# Iniciar por API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

Ingresa un conjunto de usuarios en el **punto de entrada de la API** de un journey. Úselo para impulsar journeys desde su propio backend. Por ejemplo, inicie un flujo de onboarding cuando un usuario complete el registro en su servidor.

<Aside type="tip">
No confunda esta llamada con [Inicio del ciclo de vida](/es/developer/api-reference/customer-journey-api/lifecycle/#endpoints), que activa un journey y lo pasa a estado **En ejecución**. Iniciar por API inyecta usuarios en un journey que ya está en ejecución. Consulte la [tabla comparativa](/es/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Requisitos previos

- El journey está en el estado **En ejecución**.
- El journey contiene exactamente un punto de entrada de API (el elemento "Iniciar por API"), y ese elemento no está desactivado.
- Los nombres de los atributos que envía coinciden con los atributos configurados en ese punto de entrada de la API.

<Aside type="caution" title="Límite de tasa">
Cada punto de entrada de la API acepta **una solicitud por minuto**. Una segunda solicitud dentro de ese período de tiempo devuelve un error (`Enhance your calm! only one request per minute is allowed`). Agrupe a sus destinatarios en una sola solicitud en lugar de enviar muchas pequeñas.
</Aside>

## Parámetros de ruta

| Nombre | Tipo | Descripción |
|---|---|---|
| `id` | string | [ID del Journey](/es/developer/api-reference/api-identifiers/#journey-id) del journey en ejecución. |

## Encabezados de la solicitud

| Nombre | Requerido | Valor |
|---|---|---|
| `Content-Type` | Sí | `application/json` |
| `Authorization` | Sí | `Api <server_api_token>`. Consulte [Token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token). |

## Cuerpo de la solicitud

El cuerpo tiene un único objeto `payload`. Debe proporcionar **exactamente uno** de `users`, `hwids` o `filter` para seleccionar quién ingresa al journey.

| Campo | Tipo | Descripción |
|---|---|---|
| `payload.users` | string[] | [ID de usuario](/es/developer/api-reference/api-identifiers/#user-id) para ingresar. Mutuamente excluyente con `hwids` y `filter`. |
| `payload.hwids` | string[] | [HWIDs](/es/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) para ingresar. Mutuamente excluyente con `users` y `filter`. |
| `payload.filter` | string | Una expresión de [seglang](/es/developer/api-reference/segmentation-filters-api/segmentation-language/) que selecciona la audiencia. Mutuamente excluyente con `users` y `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | Opcional. Valores para los atributos personalizados definidos en el punto de entrada de la API. Cada clave debe coincidir con un nombre de atributo configurado. |

### Ejemplos de solicitud

##### Ingresar usuarios específicos

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### Ingresar usuarios específicos con atributos

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### Ingresar una audiencia por filtro

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## Respuesta

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `request_uuid` | string | Identificador de la solicitud de entrada aceptada. La solicitud se procesa de forma asíncrona. |

</TabItem>
<TabItem label="400">

Los errores de validación devuelven HTTP `400` con un mensaje descriptivo. Casos comunes:

| Mensaje | Causa |
|---|---|
| `one of users, hwids or filter must be provided` | No se estableció ninguno de los tres selectores. |
| `only one of users, hwids or filter must be provided` | Se estableció más de un selector. |
| `Journey is not running` | El journey no está en el estado En ejecución. |
| `zero api start points` | El journey no tiene un punto de entrada de API. |
| `there is more then one api start point` | El journey tiene más de un punto de entrada de API. |
| `point is deactivated` | El punto de entrada de la API está desactivado. |
| `unknown attribute: <name>` | Una clave de `attribute_values` no está configurada en el punto de entrada de la API. |
| `Enhance your calm! only one request per minute is allowed` | Límite de tasa alcanzado (una solicitud por minuto por punto de entrada). |

</TabItem>
</Tabs>

## Relacionado

<CardGrid>
  <LinkCard title="Ciclo de vida" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Obtener estadísticas del Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Lenguaje de segmentación" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>