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

# Crea un viaje

> La respuesta contiene webhookSecret solo aquí: firma las llamadas legacy woku_signature. Las credenciales v2 url_token y sender_hmac se configuran por separado en cada momento. Guarda el secreto de forma segura.



## OpenAPI

````yaml /openapi-v1.es.json post /v1/journeys
openapi: 3.0.0
info:
  title: Woku Client API v1
  description: >-
    API REST pública para la administración programática de programas
    Voice-of-Customer de woku: trackers, instrumentos VoC (NPS, woku, CES,
    CSAT), planes de acción, tickets de soporte, envío multicanal y captura de
    respuestas. Las solicitudes están delimitadas por empresa mediante la clave
    API. Nunca envíe un id de empresa.
  version: 1.0.0
  contact:
    name: Woku
    url: https://woku.app
    email: team@woku.app
servers:
  - url: https://clientapi.woku.app
    description: Producción
security: []
tags: []
paths:
  /v1/journeys:
    post:
      tags:
        - v1 - journeys
      summary: Crea un viaje
      description: >-
        La respuesta contiene webhookSecret solo aquí: firma las llamadas legacy
        woku_signature. Las credenciales v2 url_token y sender_hmac se
        configuran por separado en cada momento. Guarda el secreto de forma
        segura.
      operationId: V1JourneysController_create
      parameters:
        - name: X-Woku-Idempotency-Key
          in: header
          description: >-
            Clave generada por el cliente para reintentar con seguridad. Un
            reintento con la misma clave y operación devuelve el resultado
            original. No reutilices la clave con datos nuevos: se reproduce el
            cuerpo original. Una operación diferente devuelve 422.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1CreateJourneyBodyDto'
      responses:
        '201':
          description: Viaje creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CreatedJourneyResponseDto'
        '400':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
        '403':
          description: Clave de API, acceso a la empresa o permiso inválidos
        '404':
          description: Viaje, momento o evaluación no encontrados
        '409':
          description: Conflicto de clave del viaje
        '422':
          description: Clave de idempotencia reutilizada para una operación diferente
      security:
        - bearer: []
components:
  schemas:
    V1CreateJourneyBodyDto:
      type: object
      properties:
        authHeader:
          type: string
          deprecated: true
          writeOnly: true
          description: >-
            Clave de API legacy en el cuerpo. Prefiere Authorization: Bearer. La
            consume la autenticación y nunca se envía a los comandos del viaje.
        authoringVersion:
          type: number
          enum:
            - 1
            - 2
          description: >-
            Usa 2 para el contrato del formulario de negocio. Las definiciones
            v1 existentes conservan sus reglas de ejecución.
        startMode:
          type: string
          enum:
            - operator
            - response
            - webhook
          description: >-
            Quién inicia el primer momento. El modo response exige una primera
            respuesta guardada; abrir el enlace no inicia el viaje.
        recipients:
          $ref: '#/components/schemas/JourneyRecipientsDto'
        name:
          type: string
          example: Viaje de ventas
        enabled:
          type: boolean
          description: Un viaje nace apagado. Enciéndelo cuando esté listo.
          default: false
        moments:
          description: >-
            Los momentos del viaje. Cada uno crea un woku, CSAT, CES o NPS a
            partir de toolSpec. Los momentos nuevos de v2 usan shared por
            defecto dentro de ese momento; per_enrollment crea una herramienta
            por participación. Se rechazan las asignaciones de herramientas
            existentes mediante toolRef. Una espera afterStage de cero días
            equivale a una hora. En v2 solo el primer momento puede ser manual.
            Los posteriores usan webhook o afterStage; la configuración
            independiente de webhook también permite adelantar un momento
            temporal. fallbackAfterMs es la espera secundaria opcional de un
            momento cuyo disparador principal es webhook, con origen en
            fallbackFromStage. Las definiciones anteriores conservan sus
            disparadores.
          type: array
          items:
            $ref: '#/components/schemas/V1JourneyMomentDto'
      required:
        - name
    V1CreatedJourneyResponseDto:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        version:
          type: number
        authoringVersion:
          type: number
          enum:
            - 1
            - 2
        startMode:
          type: string
          enum:
            - operator
            - response
            - webhook
        recipients:
          $ref: '#/components/schemas/JourneyRecipientsDto'
        routing:
          $ref: '#/components/schemas/V1JourneyRoutingDto'
        moments:
          type: array
          items:
            $ref: '#/components/schemas/V1JourneyMomentReadDto'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        webhookSecret:
          type: string
          description: >-
            Secreto de firma global legacy, devuelto una vez. No es el token URL
            ni el secreto del emisor de cada momento.
      required:
        - id
        - enabled
        - version
        - moments
        - webhookSecret
    ValidationErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: Código de estado HTTP
          example: 400
        message:
          description: Arreglo de mensajes de error de validación
          example:
            - email must be a valid email
            - password must be at least 8 characters
          type: array
          items:
            type: string
        error:
          type: string
          description: Tipo de error
          example: Bad Request
      required:
        - statusCode
        - message
        - error
    JourneyRecipientsDto:
      type: object
      properties:
        ticketsEnabled:
          type: boolean
          description: Omite para mantener la creación de tickets activada.
        plansEnabled:
          type: boolean
          description: Omite para mantener la creación de planes activada.
        ticketEmails:
          description: Emails que reciben tickets; incluye al creador por defecto.
          type: array
          items:
            type: string
        planMembers:
          description: Usuarios de la plataforma que integran el grupo de planes del viaje.
          type: array
          items:
            $ref: '#/components/schemas/JourneyPlanMemberDto'
      required:
        - ticketEmails
        - planMembers
    V1JourneyMomentDto:
      type: object
      properties:
        key:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        name:
          type: string
          maxLength: 80
        description:
          type: string
          maxLength: 280
        order:
          type: number
          description: Orden visible. La ejecución sigue el grafo de disparadores.
        tool:
          type: string
          enum:
            - woku
            - csat
            - ces
            - nps
        toolScope:
          type: string
          enum:
            - shared
            - per_enrollment
          description: >-
            V2 usa shared por defecto dentro del momento. El contenido dinámico
            del webhook requiere per_enrollment.
        toolSpec:
          $ref: '#/components/schemas/V1JourneyToolSpecDto'
        enabled:
          type: boolean
        trigger:
          $ref: '#/components/schemas/V1JourneyTriggerDto'
        webhook:
          $ref: '#/components/schemas/V1JourneyWebhookDto'
        channel:
          type: string
          enum:
            - email
            - whatsapp_first
        sequence:
          $ref: '#/components/schemas/V1JourneySequenceDto'
        presentation:
          $ref: '#/components/schemas/V1JourneyPresentationDto'
        fallbackAfterMs:
          type: number
          minimum: 1
          description: >-
            Espera secundaria para un momento cuyo disparador principal es
            webhook.
        fallbackFromStage:
          type: string
          description: Clave del momento habilitado que inicia la espera secundaria.
      required:
        - key
        - tool
        - enabled
        - trigger
        - channel
        - sequence
    V1JourneyRoutingDto:
      type: object
      properties:
        ticketsReady:
          type: boolean
        plansReady:
          type: boolean
        ticketDestinationId:
          type: string
        actionPlanGroupId:
          type: string
      required:
        - ticketsReady
        - plansReady
    V1JourneyMomentReadDto:
      type: object
      properties:
        key:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        name:
          type: string
          maxLength: 80
        description:
          type: string
          maxLength: 280
        order:
          type: number
          description: Orden visible. La ejecución sigue el grafo de disparadores.
        tool:
          type: string
          enum:
            - woku
            - csat
            - ces
            - nps
        toolScope:
          type: string
          enum:
            - shared
            - per_enrollment
          description: >-
            V2 usa shared por defecto dentro del momento. El contenido dinámico
            del webhook requiere per_enrollment.
        toolSpec:
          $ref: '#/components/schemas/V1JourneyToolSpecDto'
        enabled:
          type: boolean
        trigger:
          $ref: '#/components/schemas/V1JourneyTriggerDto'
        webhook:
          $ref: '#/components/schemas/V1JourneyWebhookDto'
        channel:
          type: string
          enum:
            - email
            - whatsapp_first
        sequence:
          $ref: '#/components/schemas/V1JourneySequenceDto'
        presentation:
          $ref: '#/components/schemas/V1JourneyPresentationDto'
        fallbackAfterMs:
          type: number
          minimum: 1
          description: >-
            Espera secundaria para un momento cuyo disparador principal es
            webhook.
        fallbackFromStage:
          type: string
          description: Clave del momento habilitado que inicia la espera secundaria.
        toolRef:
          readOnly: true
          description: >-
            Solo snapshots legacy. Se rechazan nuevas asignaciones de
            herramientas existentes.
          allOf:
            - $ref: '#/components/schemas/V1JourneyLegacyToolRefDto'
      required:
        - key
        - tool
        - enabled
        - trigger
        - channel
        - sequence
    JourneyPlanMemberDto:
      type: object
      properties:
        userId:
          type: string
          description: Id del usuario que pertenece a la empresa.
        role:
          type: string
          enum:
            - admin
            - assignee
      required:
        - userId
        - role
    V1JourneyToolSpecDto:
      type: object
      properties:
        fileId:
          type: string
          description: ID de media pública subida para Woku, perteneciente a esta empresa.
        imageUrl:
          type: string
          description: >-
            URL de media derivada. Guardar con fileId resuelve su URL
            autoritativa.
        descriptionEn:
          type: string
          minLength: 3
          maxLength: 140
        subject:
          description: >-
            Variable de la pregunta fija de CSAT, CES o NPS, no la pregunta
            completa.
          allOf:
            - $ref: '#/components/schemas/V1JourneyLocaleDto'
        audience:
          description: Audiencia de recomendación de NPS.
          allOf:
            - $ref: '#/components/schemas/V1JourneyLocaleDto'
    V1JourneyTriggerDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - manual
            - event
            - webhook
            - afterStage
        event:
          type: string
          description: >-
            Nombre del disparador de evento legacy. Los eventos reservados del
            viaje no se pueden emitir.
        stage:
          type: string
          description: 'afterStage: clave del momento anterior.'
        anchor:
          type: string
          enum:
            - sent
            - response
            - event
        delayMs:
          type: number
          minimum: 0
          description: >-
            Espera afterStage en milisegundos. Un retraso cero en v2 significa
            una hora.
        window:
          $ref: '#/components/schemas/V1JourneySendWindowDto'
        verification:
          description: Verificación de webhook legacy; usa webhook.verification en v2.
          allOf:
            - $ref: '#/components/schemas/V1JourneyVerificationDto'
        payload:
          description: Mapeo de webhook legacy; usa webhook.payload en v2.
          allOf:
            - $ref: '#/components/schemas/V1JourneyPayloadMapDto'
      required:
        - type
    V1JourneyWebhookDto:
      type: object
      properties:
        verification:
          $ref: '#/components/schemas/V1JourneyVerificationDto'
        payload:
          $ref: '#/components/schemas/V1JourneyPayloadMapDto'
        contentMode:
          type: string
          enum:
            - manual
            - webhook
          description: >-
            Origen del contenido, independiente del disparador. El contenido de
            webhook requiere alcance per_enrollment.
        schema:
          type: object
          additionalProperties: true
          description: >-
            JSON Schema acotado: raíz objeto, hasta 20000 caracteres,
            profundidad 8, 200 nodos y 50 propiedades por nodo. Admite type,
            properties, required, additionalProperties, items, enum, minLength,
            maxLength, minimum, maximum, minItems, maxItems, title y
            description. Sin referencias ni regex.
        content:
          $ref: '#/components/schemas/V1JourneyWebhookContentDto'
    V1JourneySequenceDto:
      type: object
      properties:
        attemptOffsetsMs:
          description: >-
            Offsets de invitación inicial y recordatorios desde la activación.
            [0, 86400000] envía un recordatorio al día siguiente.
          type: array
          items:
            type: number
        deadlineMs:
          type: number
          minimum: 1
        cooldownAfterResponseMs:
          type: number
          minimum: 0
        sendWindow:
          $ref: '#/components/schemas/V1JourneySendWindowDto'
      required:
        - attemptOffsetsMs
        - deadlineMs
        - cooldownAfterResponseMs
    V1JourneyPresentationDto:
      type: object
      properties:
        imageUrl:
          type: string
        copy:
          $ref: '#/components/schemas/V1JourneyLocaleDto'
    V1JourneyLegacyToolRefDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - csat
            - ces
            - woku
            - nps
            - flow
            - form
        id:
          type: string
      required:
        - type
        - id
    V1JourneyLocaleDto:
      type: object
      properties:
        es:
          type: string
        en:
          type: string
    V1JourneySendWindowDto:
      type: object
      properties:
        startHour:
          type: number
          minimum: 0
          maximum: 23
        endHour:
          type: number
          minimum: 1
          maximum: 24
        timeZone:
          type: string
          example: America/Santiago
      required:
        - startHour
        - endHour
        - timeZone
    V1JourneyVerificationDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - woku_signature
            - url_token
            - sender_hmac
          description: >-
            Solo configuración de verificación. Define los secretos mediante los
            endpoints de credenciales.
        header:
          type: string
        encoding:
          type: string
          enum:
            - hex
            - base64
        prefix:
          type: string
        signedPayload:
          type: string
          enum:
            - body
            - timestamp_dot_body
        timestampHeader:
          type: string
      required:
        - mode
    V1JourneyPayloadMapDto:
      type: object
      properties:
        subjectKey:
          type: string
          description: Ruta con puntos a la referencia estable del caso.
        email:
          type: string
          example: customer.email
        phone:
          type: string
          example: customer.phone
        match:
          type: array
          items:
            $ref: '#/components/schemas/V1JourneyPayloadRuleDto'
        clientFields:
          maxItems: 20
          type: array
          items:
            $ref: '#/components/schemas/V1JourneyClientFieldDto'
    V1JourneyWebhookContentDto:
      type: object
      properties:
        description:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        descriptionEn:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        folderSecondaryKey:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        folderName:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        parentFolderSecondaryKey:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        parentFolderName:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        subject:
          $ref: '#/components/schemas/V1JourneyDynamicLocaleDto'
        audience:
          $ref: '#/components/schemas/V1JourneyDynamicLocaleDto'
        imageUrlPath:
          type: string
          description: 'Solo Woku: ruta con puntos a una URL HTTPS pública de imagen.'
        trackers:
          maxItems: 20
          type: array
          items:
            $ref: '#/components/schemas/V1JourneyTrackerMappingDto'
    V1JourneyPayloadRuleDto:
      type: object
      properties:
        path:
          type: string
          example: order.status
        equals:
          type: string
          example: delivered
      required:
        - path
        - equals
    V1JourneyClientFieldDto:
      type: object
      properties:
        key:
          type: string
          description: Clave única de Client.customFields; hasta 20 mapeos.
        path:
          type: string
          example: customer.tier
      required:
        - key
        - path
    V1JourneyTextValueDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - literal
            - javascript
        value:
          type: string
          description: >-
            Literal de hasta 200 caracteres o cuerpo JavaScript acotado de hasta
            2000. JavaScript recibe payload y debe devolver un string, sin IO ni
            imports.
      required:
        - mode
        - value
    V1JourneyDynamicLocaleDto:
      type: object
      properties:
        es:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
        en:
          $ref: '#/components/schemas/V1JourneyTextValueDto'
    V1JourneyTrackerMappingDto:
      type: object
      properties:
        name:
          type: string
          description: >-
            Nombre del tracker, hasta 60 caracteres. Los trackers del sistema
            del viaje están reservados.
        path:
          type: string
          example: order.id
      required:
        - name
        - path
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: Clave API secreta de la empresa.

````