YCloud Developer Kit: Construye y prueba integraciones de WhatsApp API con Codex

• ¿Cómo autenticará la aplicación la solicitud de la API?
• ¿Está disponible la plantilla de mensaje correcta?
• ¿Cómo se registrarán las actualizaciones de entrega o fallo?
• ¿Qué sucede si llega dos veces el mismo evento de Webhook?
• ¿Qué debe hacer la aplicación cuando una solicitud se agota el tiempo de espera y el resultado es incierto?

YCloud Developer Kit proporciona habilidades específicas de YCloud en Codex para planificar integraciones, implementar cambios de código local y probar flujos de trabajo con datos simulados. Los desarrolladores comienzan describiendo sus requisitos en lenguaje natural.

• Instalar y verificar YCloud Developer Kit
• Crear un plan de integración en Codex
• Aplicar el plan a un proyecto local
• Probar escenarios normales y de fallo con datos simulados
• Identificar lo que aún requiere verificación con YCloud
• Preparar la integración para revisión técnica e implementación

TL;DR

• Instala el Kit de Desarrollo YCloud en Codex y ejecuta la prueba de humo para confirmar que sus habilidades están disponibles. Esto no conecta Codex a una cuenta de YCloud.
• Describe un flujo de trabajo empresarial, como una confirmación de pedido, y usa "$ycloud-integration-architect" para identificar los mensajes necesarios, plantillas, Webhooks y autenticación.
• Define el proyecto, el alcance de implementación y las acciones permitidas antes de permitir cambios de código locales.
• Aplica el plan a solicitudes API, registros empresariales y manejo asíncrono de eventos.
• Prueba escenarios de éxito y fallo con datos simulados. Trata los tiempos de espera como resultados inciertos y no confundas los resultados locales con la entrega real de mensajes.
• Antes del lanzamiento, configura la cuenta de YCloud, el número de teléfono, las plantillas, las credenciales del lado del servidor y el Webhook público. Luego completa la revisión humana, pruebas en entorno real, despliegue y monitoreo.

¿Qué es el Kit de Desarrollo YCloud?

Este artículo cubre versión 0.7.9.

• Flujos de trabajo de integración y requisitos técnicos
• Planes de implementación
• Cambios de código locales
• Escenarios de prueba y resultados registrados cuando se ejecutan las pruebas
• Listas de verificación de integración y despliegue

Alcance y Acceso a Cuenta

• Planificación de integración
• Implementación local autorizada
• Prueba de escenarios definidos con datos simulados

Qué necesita manejar una integración de WhatsApp

El envío y la entrega son etapas separadas

• Registrar la solicitud original
• Procesar eventos posteriores de estado del mensaje
• Almacenar el envío de la solicitud por separado de las actualizaciones de estado posteriores

Los Webhooks introducen procesamiento asincrónico

• Validar las solicitudes entrantes antes de procesarlas
• Manejar eventos duplicados, retrasados y fuera de orden
• Evitar actualizaciones comerciales repetidas
• Conectar cada evento al mensaje original y a la transacción comercial

Las plantillas y la configuración de la cuenta tienen dependencias externas

La integración también necesita operaciones confiables

• Gestión segura de credenciales en el servidor
• Manejo de tiempos de espera sin envíos duplicados automáticos
• Idempotencia para evitar acciones comerciales repetidas
• Registro, monitoreo y alertas
• Reglas de recuperación para solicitudes fallidas o inciertas
• Entornos separados de pruebas y producción
• Investigación de fallos y preparación de rollback

¿Qué capacidades de YCloud cubre el Kit?

Cómo funciona el flujo de trabajo del Kit de desarrollo de YCloud

Describa el flujo de trabajo → Revise el plan → Implemente en su proyecto → Pruebe localmente → Verifique con YCloud e implemente

1. Definir el Objetivo del Negocio

• La experiencia del cliente que se creará
• El sistema o aplicación existente
• El evento que inicia el flujo de trabajo
• El resultado previsto que enfrentará el cliente
• La información que el sistema interno debe registrar
• Lo que está incluido y excluido de la implementación actual

2. Confirmar el Diseño de la Integración

• Capacidades requeridas de YCloud
• Requisitos previos de cuenta y número de teléfono
• Requisitos de plantilla y envío
• Mapeo de registros comerciales
• Requisitos de webhook y procesamiento de estado
• Manejo de fallos y eventos duplicados
• Elementos que aún requieren confirmación

3. Implementar en su Proyecto

• El proyecto local
• Los módulos incluidos en la tarea
• Si se deben agregar pruebas
• Si se requiere un ejemplo aislado o una implementación aplicada
• Si las llamadas API externas están prohibidas

4. Ejecutar Pruebas Simuladas

• Envío de solicitud exitoso
• Rechazo de API o fallo de envío
• Tiempo de espera agotado
• Evento de estado de mensaje duplicado
• Webhook no válido
• Configuración faltante o incorrecta

Importante: Trata una solicitud de envío con tiempo de espera agotado como un resultado incierto. La solicitud pudo haber sido aceptada, así que no la vuelvas a enviar solo porque el cliente agotó el tiempo de espera. Usa los identificadores disponibles, los eventos de estado y el comportamiento de recuperación documentado para decidir la próxima acción.

5. Verifica con YCloud e Implementa

• La cuenta de YCloud y el número de teléfono de WhatsApp
• Las plantillas de mensajes aprobadas
• Las claves API del lado del servidor
• El endpoint público de Webhook
• Las variables del entorno de producción
• Las solicitudes API reales y las devoluciones de llamada de estado
• Supervisión y alertas
• Procedimientos de implementación y reversión

Antes de Comenzar

Requisitos del Entorno

• Un entorno Codex soportado por la versión documentada
• El Kit de Desarrollo de YCloud instalado
• Acceso al proyecto de aplicación local cuando sea necesaria la implementación
• Un entorno adecuado para desarrollo y pruebas

Información que ayuda con la planificación

• Sistema existente y pila tecnológica
• Evento desencadenante
• Mensaje o experiencia del cliente esperada
• Registros internos que deben crearse o actualizarse
• Estado actual de la implementación
• Alcance del trabajo
• Criterios de aceptación

Información no requerida durante la planificación

• Claves API reales
• Números de teléfono reales de clientes
• Conversaciones privadas de clientes
• Credenciales de producción

Nota de seguridad: Usa marcadores de posición o datos sintéticos en planes, ejemplos de código y pruebas simuladas. Almacena las credenciales reales en el entorno del lado del servidor utilizando las prácticas de gestión de secretos de tu equipo.

Cómo instalar y verificar el Kit de Desarrollo de YCloud

Instala el Kit de Desarrollo

1. Abre la página del complemento de YCloud Developer Kit.
2. Selecciona Instalar o Probar ahora.
3. Confirma que el plugin está habilitado en el entorno de Codex donde lo utilizarás.
4. Inicia una nueva tarea en Codex antes de ejecutar el prompt de verificación.

</> Bash
npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*' -a codex --copy -y

Ejecuta la Prueba de Humo

</> Plain Text
Use $ycloud-developer-kit-smoke-test to check whether the plugin is ready.

</> Plain Text
YCloud Developer Kit is ready. No external API was called.

Qué Confirma Esto

• Codex puede encontrar e invocar la habilidad smoke-test.
• El Kit está disponible en el entorno actual de Codex.
• El chequeo se completó sin llamar a una API externa.

Qué No Confirma Esto

• Conexión a una cuenta de YCloud
• Credenciales de API válidas
• Disponibilidad de funciones a nivel de cuenta
• Entrega exitosa de mensajes de WhatsApp
• Preparación para producción

Ejemplo paso a paso: Crear una integración de confirmación de pedidos por WhatsApp

Requisito comercial

• Activar una confirmación de pedido por WhatsApp cuando se crea el pedido
• Asociar la solicitud de mensaje con el pedido
• Registrar eventos de entrega o falla posteriores
• Mantener el pedido válido incluso si la notificación falla

Paso 1: Solicitar un plan de integración

Use $ycloud-integration-architect to plan a WhatsApp
order-confirmation integration.

Our backend uses Node.js, Express and SQLite.

After a customer places an order, send a WhatsApp confirmation.
The backend must associate the message with the order and record
subsequent delivery or failure events.

Include order-confirmation messages and message-status Webhooks only.
Do not include marketing broadcasts or inbound-message handling.

Provide the business flow, prerequisites, development steps, risks
and acceptance criteria.

Do not modify files or call real APIs.

• Activador de creación de pedidos
• Requisitos de cuenta y número de teléfono
• Requisito de plantilla aprobada
• Flujo de envío de mensajes
• Conexión entre el pedido, el valor de correlación de la aplicación, el ID de mensaje de YCloud y el evento de Webhook
• Flujo de Webhook de estado de mensajes
• Manejo de fallos y eventos duplicados
• Requerimientos no resueltos

Paso 2: Confirmar el Alcance

Limit this implementation to order-confirmation messages
and message-status processing.

List:

1. Required information
2. Modules that must be changed
3. Acceptance criteria
4. Items that still require confirmation

• Prevenir cambios de código no relacionados
• Establecer criterios de aceptación
• Separar el trabajo actual de la funcionalidad futura
• Registrar dependencias no resueltas

Paso 3: Autorizar la Implementación Local

Implement the approved order-confirmation and message-status
flow in the current local project.

Identify the relevant order-notification and message-status
modules, implement the workflow there and add tests.

Use fictional orders and simulated data.
Do not read real credentials or call real APIs.

After implementation, list the changed files, configuration
requirements, test results and items that still require
real-environment verification.

• Código de integración
• Marcadores de posición de configuración
• Lógica de correlación entre mensajes y órdenes
• Procesamiento de Webhook
• Pruebas de rutas normales y de fallos
• Instrucciones de ejecución local
• Limitaciones conocidas

Paso 4: Probar Escenarios Normales y de Fallos

Importante: Este ejemplo utiliza respuestas simuladas de YCloud y eventos de Webhook sintéticos. No se conecta a una cuenta activa de YCloud ni envía un mensaje real de WhatsApp.

Run local simulated tests for:

- Successful message submission
- API rejection and a later failed-message status as separate cases
- Request timeout
- Duplicate message-status event
- Invalid Webhook

Do not treat a timeout as confirmation that the message failed.

Separate executed tests, actual results and unverified items.

• Formación correcta de solicitudes
• Almacenamiento separado para el envío y el estado posterior del mensaje
• Procesamiento idempotente de eventos
• Sin actualizaciones comerciales duplicadas
• Informes de errores claros
• Sin reenvío automático después de un tiempo de espera incierto

Paso 5: Preparar la Entrega Técnica

List the remaining account configuration, integration tests
and deployment tasks for the technical team.

Separate completed local work from work that still requires
the authorized YCloud environment.

Include account, phone number, templates, API credentials,
Webhook configuration, testing, monitoring, exception handling
and rollback.

Do not perform real operations.

• Implementación y pruebas locales completadas
• Requisitos de cuenta de YCloud y número de teléfono
• Requisitos de plantillas aprobadas
• Configuración de credenciales del lado del servidor
• Configuración de Webhook público
• Pruebas de integración real
• Monitoreo y manejo de excepciones
• Tareas de implementación y reversión
• Riesgos pendientes y preguntas sin resolver

Entendiendo los diferentes niveles de validación

Advertencia: La validación aplica solo a los escenarios y entornos probados. Verifique el flujo de trabajo deseado con YCloud y siga el proceso de lanzamiento de su equipo antes de habilitar mensajes para clientes.

Habilidades del YCloud Developer Kit y cuándo usarlas

• Usar "$ycloud-integration-architect" cuando el requisito involucra múltiples capacidades de YCloud o el punto de partida no está claro.
• Usar una habilidad específica para la tarea cuando la capacidad requerida y el alcance de implementación ya estén definidos.

Cómo escribir prompts efectivos para integración con la API de YCloud

Objetivo empresarial + Sistema actual + Alcance + Acciones autorizadas + Resultado requerido

1. Objetivo Empresarial

2. Sistema Actual

• Proyecto existente o nuevo
• Stack tecnológico
• Servicios y bases de datos relevantes
• Implementación de mensajes o Webhooks existentes

3. Alcance

4. Acciones Autorizadas

• Solo planificación
• Solo revisión de código
• Generar un ejemplo aislado
• Modificar el proyecto local definido
• Agregar o ejecutar pruebas
• No llamar a API externas

5. Salida Requerida

• Arquitectura
• Prerrequisitos
• Archivos modificados
• Evidencia de pruebas
• Riesgos y preguntas sin resolver
• Criterios de aceptación
• Lista de verificación de preparación para producción

Prompt Reutilizable

Use YCloud Developer Kit to help implement [business workflow]
in our [technology stack] project.

The workflow starts when [trigger] and should produce [outcome].

Include [scope] and exclude [out-of-scope items].

You may [permitted actions].

Use simulated data and do not call real APIs.

Provide the implementation plan, changed files, executed tests,
actual results and remaining integration requirements.

Ask about missing details that affect the design.

Prácticas de Seguridad y Desarrollo Empresarial

Proteger Credenciales y Datos del Cliente

• No pegues claves API o secretos de Webhook en los prompts.
• No codifiques credenciales en el repositorio.
• Usa números de teléfono sintéticos y cargas útiles en ejemplos y pruebas locales.
• Mantén las credenciales de producción en el entorno del lado del servidor.
• Usa las prácticas de gestión de secretos y control de acceso aprobadas por el equipo.

Verifica con la Documentación Oficial de la API

• Endpoints de la API y métodos de solicitud
• Campos requeridos y opcionales
• Requisitos de autenticación
• Formatos de respuesta y errores
• Comportamiento soportado

synthetic_unverified

Diseña Webhooks para Confiabilidad

• Validar la fuente antes del procesamiento empresarial
• Rechazar firmas o cargas útiles inválidas
• Procesar eventos duplicados sin repetir acciones empresariales
• Preservar eventos desconocidos para investigación
• Seguir los requisitos de respuesta documentados por YCloud
• Conectar cada evento al mensaje correcto y registro empresarial
• Registrar identificadores útiles sin exponer credenciales o datos de clientes

Entornos Separados

• No utilice credenciales de producción para pruebas locales rutinarias.
• Use configuraciones específicas para cada entorno.
• Registre qué escenarios se simularon.
• Registre qué escenarios se verificaron con servicios reales.

Mantener Revisión Humana

• Configurar credenciales de producción
• Habilitar mensajes visibles para clientes
• Implementar cambios en Webhooks
• Cambiar el comportamiento de reintentos o recuperación
• Habilitar una nueva capacidad de WhatsApp

Limitaciones y Notas Importantes

Instalación y Acceso a la Cuenta

• Conecta Codex a una cuenta de YCloud
• Valida credenciales de API
• Configura números de teléfono o plantillas
• Habilita características a nivel de cuenta
• Implementa la aplicación

Cobertura de Simulación

• Envío exitoso de mensaje
• Rechazo de la API y eventos de fallo posteriores
• Tiempo de espera de la solicitud
• Eventos de estado duplicados
• Webhooks inválidos

• Autenticación en vivo
• Configuración de cuenta real o plantilla
• Entrega real de Webhooks
• Entrega real de mensajes de WhatsApp
• Confiabilidad a escala de producción

Iniciando la Simulación Local

node --test --test-concurrency=1 test/*.test.js

Límites de Validación

• Una solicitud API exitosa no prueba la entrega del mensaje.
• El código generado debe revisarse y ejecutarse.
• La validación local no equivale a la validación en producción.
• El soporte de funciones en el Kit no garantiza disponibilidad a nivel de cuenta.
• Los resultados de las pruebas solo aplican a los escenarios y entorno probados.

Límites de Versión e Implementación

¿Cuándo deben los equipos usar YCloud Developer Kit?

• Planificar una nueva integración de WhatsApp
• Agregar notificaciones por WhatsApp a un producto existente
• Implementar Webhooks de estado de mensajes
• Revisar una integración parcialmente completada
• Identificar escenarios faltantes de fallos y recuperación
• Preparar un resumen de implementación para otro equipo de ingeniería
• Crear una lista de verificación de preparación para producción
• Coordinar un flujo de trabajo entre múltiples capacidades de YCloud

¡Reflexiones finales!

Comience con un flujo de trabajo de WhatsApp

Use $ycloud-integration-architect to plan a WhatsApp
[workflow name] integration.