# Ciclo de vida de las secuencias

> Cree, previsualice, actualice, archive y consulte las analíticas de sus secuencias

Source: https://docs.graph8.com/es/developers/sequences-lifecycle/

La página de [Secuencias](https://docs.graph8.com/developers/sequences/) cubre las operaciones básicas (listar, obtener, ejecutar, pausar/reanudar y gestionar los contactos inscritos). Esta página describe los endpoints de **ciclo de vida** que se usan para crear e inspeccionar una secuencia de extremo a extremo, normalmente lo que necesita una CLI o una herramienta de compilación.

Todos los endpoints comparten el prefijo `/sequences` y requieren una clave de API de tipo Bearer.

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/sequences` | POST | Crear una secuencia (con pasos y canales opcionales) |
| `/sequences/{id}/preview` | GET | Leer secuencia, pasos y canales (sin inscripción) |
| `/sequences/{id}` | PATCH | Actualizar metadatos de la secuencia |
| `/sequences/{id}/steps/{step_id}` | PATCH | Actualizar un único paso |
| `/sequences/{id}/pause` | POST | Pausar una secuencia activa |
| `/sequences/{id}/resume` | POST | Reanudar una secuencia pausada |
| `/sequences/{id}/analytics` | GET | Informe completo de analíticas |
| `/sequences/{id}` | DELETE | Eliminación temporal (archivar) de una secuencia |

Una secuencia en estado **transitional** (`scheduling`, `pausing`, `resuming`, `terminating`) no admite PATCH: se obtendrá `409 Conflict`. Espere a que la operación se estabilice.

Para esquemas legibles por máquina, consulte la [documentación interactiva de la API](https://be.graph8.com/api/v1/docs).

---

> **Note: Ids en estos ejemplos**
> Los ejemplos de solicitud usan variables de shell (`$SEQUENCE_ID` and `$STEP_ID`) para los ids. Asígnelas a partir de los campos `id` que devuelven las llamadas de creación o listado. Los ids de las respuestas de ejemplo son solo ilustrativos y no existen.

## Crear secuencia

`POST /sequences`

Crea una secuencia en estado `drafted`. De forma opcional puede incluir `steps[]` y `channels[]` en la misma llamada.

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `name` | string | **Sí** | Nombre de la secuencia |
| `user_email` | string | **Sí** | Dirección de correo del propietario |
| `description` | string | No | Descripción libre |
| `finish_on_reply` | boolean | No (predeterminado `true`) | Detener el contacto al recibir respuesta |
| `send_in_same_thread` | boolean | No | Enviar los seguimientos en el mismo hilo de correo |
| `wait_for_new_contacts` | boolean | No | Mantener la secuencia a la espera de nuevas inscripciones |
| `associated_list_id` | integer | No | Lista de contactos que se asociará |
| `steps` | object[] | No | Configuración de los pasos. Consulte [Configuración de paso](#step-config) |
| `channels` | object[] | No | Configuración de los canales. Consulte [Configuración de canal](#channel-config) |
| `campaign_id` | string | No | Campaña de AI Studio que se vinculará |

#### Configuración de paso

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `step_order` | integer | Orden dentro de la secuencia |
| `step_type` | string | `EMAIL`, `PHONE`, `SMS`, `LINKEDIN`, etc. |
| `input_type` | string | `ON_DEMAND` o `TEMPLATE` (predeterminado `ON_DEMAND`) |
| `time_interval` | integer | Retraso en segundos después del paso anterior |
| `step_data` | object | Datos de plantilla o contenido del paso (asunto, cuerpo, etc.) |

#### Configuración de canal

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `channel_id` | integer | ID del recurso (ID de buzón, ID de teléfono, etc.) |
| `channel_value` | string | La dirección o número en sí |
| `channel_type` | string | `EMAIL`, `PHONE`, `SMS`, `LINKEDIN`, `WHATSAPP` |
| `channel_data` | object | Metadatos opcionales |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/sequences" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Outbound",
    "user_email": "rep@graph8.com",
    "associated_list_id": 5,
    "steps": [
      {
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "Hi {{first_name}}..."}
      }
    ],
    "channels": [
      {
        "channel_id": 12,
        "channel_value": "rep@graph8.com",
        "channel_type": "EMAIL"
      }
    ]
  }'
```

### Respuesta `201 Created`

```json
{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "created_at": "2026-04-15T10:00:00Z"
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `400` | Configuración de paso o canal no válida |

---

## Vista previa de secuencia

`GET /sequences/{sequence_id}/preview`

Vista de solo lectura de una secuencia con todos sus pasos y canales. No inscribe a ningún contacto.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/sequences/$SEQUENCE_ID/preview" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "description": null,
    "steps": [
      {
        "id": "stp_1",
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "..."}
      }
    ],
    "channels": [
      {"id": "ch_1", "channel_id": 12, "channel_value": "rep@graph8.com", "channel_type": "EMAIL"}
    ]
  }
}
```

---

## Actualizar secuencia

`PATCH /sequences/{sequence_id}`

Actualiza los metadatos de la secuencia. Envíe únicamente los campos que desee modificar.

### Cuerpo de la solicitud

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `name` | string | Nombre de la secuencia |
| `description` | string | Descripción |
| `is_shared` | boolean | Compartir con la organización |
| `finish_on_reply` | boolean | Finalizar al recibir respuesta |
| `send_in_same_thread` | boolean | Seguimientos en el mismo hilo |
| `wait_for_new_contacts` | boolean | Esperar nuevos contactos |
| `schedule_id` | string | ID de programación |
| `appointment_id` | integer | ID de cita |

### Ejemplo

**cURL**

```bash
curl -X PATCH "https://be.graph8.com/api/v1/sequences/$SEQUENCE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Outbound v2", "send_in_same_thread": true}'
```

### Errores

| Estado | Significado |
|--------|-------------|
| `404` | Secuencia no encontrada |
| `409` | La secuencia se encuentra en un estado transitional (`scheduling`, `pausing`, `resuming`, `terminating`) |

---

## Actualizar paso

`PATCH /sequences/{sequence_id}/steps/{step_id}`

Actualiza un único paso. Se aplica la misma regla `409` si la secuencia principal está en transición.

### Cuerpo de la solicitud

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `step_data` | object | Datos de plantilla o contenido |
| `time_interval` | integer | Retraso en segundos después del paso anterior |
| `step_type` | string | Tipo de paso |
| `input_type` | string | `ON_DEMAND` o `TEMPLATE` |

### Ejemplo

**cURL**

```bash
curl -X PATCH "https://be.graph8.com/api/v1/sequences/$SEQUENCE_ID/steps/$STEP_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_data": {"subject": "Quick intro v2", "body": "Updated..."}}'
```

---

## Pausar y reanudar

`POST /sequences/{sequence_id}/pause`
`POST /sequences/{sequence_id}/resume`

Pausa una secuencia activa (o reanuda una pausada). Devuelve la cantidad de contactos afectados.

### Respuesta

```json
{
  "data": {
    "sequence_id": "seq_abc",
    "status": "paused",
    "contacts_affected": 150
  }
}
```

---

## Analíticas

`GET /sequences/{sequence_id}/analytics`

Devuelve un informe completo de analíticas: KPIs generales, rendimiento en el tiempo, desglose de engagement, distribución de contactos, métricas por paso y distribución por remitente. La estructura refleja el modelo interno `SequenceReports`.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/sequences/$SEQUENCE_ID/analytics" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": {
    "overview": {"sent": 320, "opened": 180, "replied": 22},
    "performance": {"open_rate": 0.56, "reply_rate": 0.07},
    "engagement": {"by_day": [...]},
    "timeline": [...],
    "contact_distribution": {"active": 150, "completed": 100, "stopped": 70},
    "step_breakdown": [
      {"step_id": "stp_1", "sent": 320, "opened": 180}
    ],
    "step_creation_methods": [...],
    "sender_distribution": [...]
  }
}
```

Encontrará el esquema completo en [/api/v1/docs](https://be.graph8.com/api/v1/docs), bajo `SequenceAnalyticsResponse`.

---

## Eliminar (archivar)

`DELETE /sequences/{sequence_id}`

Realiza una eliminación temporal de una secuencia estableciendo `is_archived = true`. Las secuencias ya archivadas devuelven `400`. Las secuencias en ciertos estados no terminales no pueden archivarse y devuelven `409`.

### Ejemplo

**cURL**

```bash
curl -X DELETE "https://be.graph8.com/api/v1/sequences/$SEQUENCE_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Errores

| Estado | Significado |
|--------|-------------|
| `400` | La secuencia ya está archivada |
| `404` | Secuencia no encontrada |
| `409` | La secuencia no puede archivarse en su estado actual |