--- title: "YCloud Developer Kit: Construye y prueba integraciones de WhatsApp API con Codex" description: "Descubre cómo el Kit de Desarrollo de YCloud ayuda a los equipos a planificar, construir y probar integraciones de WhatsApp API localmente utilizando Codex." canonical: "https://www.ycloud.com/es/blog/ycloud-developer-kit-whatsapp-api-integration" language: "es" datePublished: "2026-10-08T17:29:24.218Z" dateModified: "2026-10-08T17:35:41.570Z" author: "Team YCloud" categories: - "Desarrolladores👨‍💻" --- # YCloud Developer Kit: Construye y prueba integraciones de WhatsApp API con Codex ![YCloud Developer Kit](https://static-blog.ycloud.com/YC_Developer_Kit_f8afe596e1.png) Una API de mensajería acepta una solicitud de confirmación de pedido. Pero, ¿ha recibido el cliente el mensaje? **No necesariamente.** Una integración de WhatsApp debe responder varias preguntas antes de poder funcionar de manera confiable: - *¿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?* Estos problemas afectan tanto la experiencia del cliente como la precisión de los registros internos del negocio. Por lo tanto, los desarrolladores deben planificar lo que sucede antes, durante y después de cada solicitud de mensaje. **Aquí es donde YCloud Developer Kit puede ayudar.** > *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.* Basado en esos requisitos, el Kit puede ayudar a identificar las capacidades necesarias de YCloud, estructurar la implementación y definir escenarios de prueba relevantes. **En este artículo, usaremos un flujo de trabajo de confirmación de pedido por WhatsApp para explicar cómo:** - *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* El Kit soporta el proceso de desarrollo dentro de Codex. La configuración de la cuenta YCloud, la implementación en producción y las pruebas en entorno real siguen siendo pasos separados. Antes de comenzar el flujo de trabajo, veamos primero qué es YCloud Developer Kit, con qué puede ayudar y dónde termina su alcance. ## 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? El Kit de Desarrollo YCloud es un plugin de Codex que contiene habilidades específicas de YCloud para el desarrollo de integraciones. > Este artículo cubre **versión 0.7.9**. Añade guía específica de YCloud a Codex para seleccionar capacidades API, diseñar lógica empresarial e implementar flujos de trabajo en un proyecto local. **Los desarrolladores pueden usarlo para convertir requisitos empresariales en:** - *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* El Kit puede apoyar tanto nuevas integraciones como revisiones de implementaciones existentes. ### Alcance y Acceso a Cuenta El Kit de Desarrollo YCloud soporta el proceso de desarrollo dentro de Codex. Las operaciones de mensajería y gestión de campañas usan herramientas separadas. **El Kit puede ayudar con:** - *Planificación de integración* - *Implementación local autorizada* - *Prueba de escenarios definidos con datos simulados* Instalar el Kit no conecta Codex a una cuenta de YCloud, configura recursos de la cuenta ni implementa una aplicación. El Kit puede ayudar a los desarrolladores a escribir código de aplicación que llame a las API de YCloud. Sin embargo, el flujo de trabajo cubierto en este artículo no ejecuta solicitudes reales de API. Las pruebas en vivo requieren autorización separada, acceso a la cuenta, credenciales del lado del servidor y configuración del entorno. La disponibilidad de funciones a nivel de cuenta también debe confirmarse antes de la implementación. Los resultados de las pruebas locales aplican solo a los escenarios probados y no reemplazan la verificación con YCloud. ![YCloud Developer Kit Plugin Overview](https://static-blog.ycloud.com/2_Y_Cloud_Developer_Kit_Plugin_Overview_5c150eef48.png) Con el propósito y los límites del Kit establecidos, la siguiente sección explica lo que debe manejar una integración confiable de WhatsApp. ## Qué necesita manejar una integración de WhatsApp Enviar un mensaje es solo una parte de una integración de WhatsApp. La aplicación también debe rastrear lo que sucede antes de la solicitud, después de que se acepta y cuando llegan actualizaciones posteriores. ### El envío y la entrega son etapas separadas Una solicitud de API aceptada confirma que el mensaje fue aceptado para su procesamiento. No confirma la entrega. **Por lo tanto, la aplicación debería:** - *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* Siempre consultar la documentación actual de YCloud antes de implementar valores de estado específicos. ### Los Webhooks introducen procesamiento asincrónico Los eventos de estado del mensaje pueden llegar más tarde, más de una vez o en un orden diferente al esperado. **Los manejadores de webhooks deberían:** - *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* Por ejemplo, un registro de pedido debe permanecer conectado a su solicitud de mensaje y a todas las actualizaciones de estado posteriores. ### Las plantillas y la configuración de la cuenta tienen dependencias externas Los flujos de trabajo basados en plantillas requieren que la plantilla correcta esté aprobada y disponible. La cuenta de YCloud y el número de teléfono de WhatsApp también deben estar configurados correctamente. Algunas capacidades pueden no estar habilitadas para todas las cuentas. Estas dependencias deben confirmarse antes de las pruebas de integración o la implementación. ### La integración también necesita operaciones confiables **Un flujo de trabajo de producción debería incluir:** - *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* YCloud Developer Kit ayuda a los desarrolladores a identificar y estructurar estos requisitos durante la planificación, implementación y pruebas. La siguiente sección asigna estos requisitos a las capacidades de YCloud cubiertas por el Kit. ## ¿Qué capacidades de YCloud cubre el Kit? YCloud Developer Kit versión 0.7.9 cubre **88 operaciones de API y dos capacidades transversales**. La tabla siguiente las agrupa por área de integración. Estas capacidades pueden combinarse en flujos de trabajo como notificaciones de pedidos, actualizaciones de envíos, sincronización de contactos y enrutamiento de mensajes entrantes.
Área de Integración
Cómo Puede Ayudar el Developer Kit
Mensajes de WhatsApp
Planificar e implementar el envío directo o en cola de mensajes, la recuperación de mensajes y el manejo de estado
Medios
Implementar subidas de medios y pasar referencias de medios subidos a flujos de trabajo de mensajes
Plantillas
Planificar la creación, recuperación, actualización, eliminación y análisis de plantillas
Cuentas y números de teléfono
Identificar requisitos previos e implementar operaciones soportadas de configuración de cuentas, registro, perfil y números de teléfono
Webhooks
Diseñar la gestión de puntos finales, la recepción de eventos, la validación de origen y el manejo de eventos duplicados
Mensajes entrantes
Dirija eventos de mensajes entrantes verificados a la lógica de la aplicación e implemente confirmaciones compatibles
Contactos
Diseñe flujos de trabajo para la gestión de contactos, atributos y notas
Bajas voluntarias
Agregue verificaciones de baja voluntaria y gestione registros de exclusión
Grupos
Planee operaciones compatibles con grupos de WhatsApp, participantes, configuraciones y enlaces de invitación
Flujos de WhatsApp
Diseñe e implemente operaciones compatibles del ciclo de vida de los flujos
Llamadas de WhatsApp
Planee el manejo de llamadas y las operaciones compatibles de sesión de llamada
Autenticación
Estructure una autenticación API segura del lado del servidor
Saldo
Recupere y utilice información de saldo de la cuenta cuando sea necesario
Eventos personalizados
Defina y envíe eventos comerciales asociados con contactos, por separado de los eventos de Webhook entrantes
Aquí, **compatible** significa que el Kit puede ayudar con el diseño de la integración, la implementación local y la evaluación. No significa que todas las capacidades estén habilitadas para la cuenta de un cliente o validadas en producción. La versión cubierta en este artículo se centra en las integraciones de WhatsApp y las API relacionadas de YCloud. **SMS, Verify, YCloud Voice y Email están fuera de su alcance.** YCloud Voice es un área de producto separada y no debe confundirse con WhatsApp Calling. Ahora que las capacidades disponibles están claras, la siguiente sección explica cómo los desarrolladores pueden usarlas en un flujo de trabajo de integración estructurado. ## Cómo funciona el flujo de trabajo del Kit de desarrollo de YCloud El Kit sigue una ruta de desarrollo de cinco etapas: > **Describa el flujo de trabajo → Revise el plan → Implemente en su proyecto → Pruebe localmente → Verifique con YCloud e implemente** ![YCloud Developer Kit Five Stage Workflow.png](https://static-blog.ycloud.com/Y_Cloud_Developer_Kit_Five_Stage_Workflow_e08a34db99.png) ### 1\. Definir el Objetivo del Negocio Comience con el resultado comercial requerido en lugar de seleccionar APIs primero. **Proporcionar:** - *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* Ejemplos comunes incluyen confirmaciones de pedidos, notificaciones de envío, mensajes de soporte al cliente, sincronización de contactos y verificación de baja. ### 2\. Confirmar el Diseño de la Integración **El Kit puede mapear el objetivo del negocio a:** - *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* Revisar estos puntos antes de la implementación ayuda a evitar dependencias faltantes o trabajos de desarrollo innecesarios. ### 3\. Implementar en su Proyecto **Una vez que el plan esté aprobado, especifique exactamente qué puede cambiar Codex:** - *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* Una solicitud de implementación clara puede autorizar el trabajo local definido. No autoriza cambios en archivos no relacionados o sistemas externos. ### 4\. Ejecutar Pruebas Simuladas **Pruebe tanto escenarios normales como de fallos, incluyendo:** - *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 **Antes del lanzamiento, el equipo técnico debe configurar y verificar:** - *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* El desarrollo local prepara la integración, mientras que esta etapa final la verifica en el entorno autorizado de YCloud. Antes de iniciar este flujo de trabajo, la siguiente sección enumera la información requerida sobre el entorno y la planificación. ## Antes de Comenzar Prepara el entorno de desarrollo y la información básica del flujo de trabajo antes de usar el Kit. ### Requisitos del Entorno **Necesitas:** - *Un entorno Codex soportado por la versión documentada* - [*El Kit de Desarrollo de YCloud*](https://chatgpt.com/plugins/plugins_6a9669d9e57c8191a04a3c8951e44401?search=ycloud) *instalado* - *Acceso al proyecto de aplicación local cuando sea necesaria la implementación* - *Un entorno adecuado para desarrollo y pruebas* Verifica los requisitos de instalación para la versión que estás utilizando antes de continuar. ### Información que ayuda con la planificación Comienza con el caso de uso, la pila tecnológica y el flujo de trabajo deseado. Cualquier requisito faltante puede identificarse al revisar el plan. **Proporciona:** - *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 **No proporciones:** - *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. Una vez que estos requisitos estén listos, el siguiente paso es instalar el Kit de Desarrollo de YCloud y confirmar que Codex puede acceder a él. ## Cómo instalar y verificar el Kit de Desarrollo de YCloud El Kit de Desarrollo de YCloud 0.7.9 puede instalarse a través de la página del complemento de ChatGPT o directamente desde su repositorio. Usa el método compatible con tu entorno de Codex; no necesitas ambos. ### Instala el Kit de Desarrollo **Opción 1: Instalar desde ChatGPT** 1. Abre la [página del complemento de YCloud Developer Kit](https://chatgpt.com/plugins/plugins_6a9669d9e57c8191a04a3c8951e44401?search=ycloud). 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. ![Find and Enable YCloud Developer Kit](https://static-blog.ycloud.com/1_Find_and_Enable_Y_Cloud_Developer_Kit_8b834184cc.png) ![YCloud Developer Kit Plugin Overview](https://static-blog.ycloud.com/2_Y_Cloud_Developer_Kit_Plugin_Overview_5c150eef48.png) **Opción 2: Instalar desde el Repositorio** Sigue las [instrucciones de instalación del README](https://github.com/YCloud-Developers/YCloud-Developer-Kit?tab=readme-ov-file#一次安装整套技能). **Desde el directorio del proyecto objetivo, ejecuta:** ```plaintext Bash npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*' -a codex --copy -y ``` *Este comando instala las 17 habilidades de YCloud para Codex en el proyecto actual. Inicia una nueva sesión de Codex después de la instalación para que las habilidades puedan ser detectadas.* ### Ejecuta la Prueba de Humo En la nueva tarea de Codex, ingresa: ```plaintext Plain Text Use $ycloud-developer-kit-smoke-test to check whether the plugin is ready. ``` **Respuesta esperada:** ```plaintext Plain Text YCloud Developer Kit is ready. No external API was called. ``` ![Verify the Plugin with the Smoke Test](https://static-blog.ycloud.com/3_Verify_the_Plugin_with_the_Smoke_Test_9486615e28.png) ### **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 Una vez que la prueba de humo tiene éxito, el siguiente paso es usar el Kit para un flujo de trabajo de integración de WhatsApp definido. ## Ejemplo paso a paso: Crear una integración de confirmación de pedidos por WhatsApp Este ejemplo utiliza un flujo de trabajo a lo largo de los pasos restantes. ### Requisito comercial Un cliente ficticio realiza un pedido **DEMO-1001** a través de una aplicación construida con **Node.js, Express y SQLite**. **La integración debe:** - 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 Las transmisiones de marketing y las respuestas de los clientes están fuera del alcance actual. ### Paso 1: Solicitar un plan de integración Comienza pidiendo al arquitecto de integración que convierta el requisito comercial en un plan técnico. ```plaintext 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. ``` **El plan debe cubrir:** - *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* ![Generate the WhatsApp Integration Plan](https://static-blog.ycloud.com/4_Generate_the_Whats_App_Integration_Plan_c22a1e267a.png) ### Paso 2: Confirmar el Alcance Antes de la implementación, pídele a Codex que defina el límite exacto del trabajo. ```plaintext 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 ``` **La confirmación del alcance ayuda al equipo a:** - *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 Después de aprobar el plan, autoriza explícitamente los cambios dentro del proyecto local. ```plaintext 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. ``` **Los entregables esperados son:** - *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* Esta autorización se aplica solo al proyecto local y módulos definidos. ![Run Local Implementation and Simulated Tests](https://static-blog.ycloud.com/5_Run_Local_Implementation_and_Simulated_Tests_3e49d06721.png) ### 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. Ejecute pruebas tanto de flujo exitoso como de fallo: ```plaintext 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. ``` **Verifique que la implementación proporcione:** - *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* Una solicitud agotada puede haber sido aceptada antes de que se perdiera la conexión. Debe permanecer sin resolver hasta que los identificadores disponibles, eventos de estado posteriores o comportamientos de recuperación documentados proporcionen más información. ![Run Local Implementation and Simulated Tests](https://static-blog.ycloud.com/5_Run_Local_Implementation_and_Simulated_Tests_3e49d06721.png) ### Paso 5: Preparar la Entrega Técnica Finalmente, solicite a Codex que separe el trabajo local completado de las tareas restantes del entorno real. ```plaintext 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. ``` **La entrega debe identificar:** - *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* ![6. Technical Handoff and Production Requirements.png](https://static-blog.ycloud.com/6_Technical_Handoff_and_Production_Requirements_1eb2fea647.png) La siguiente sección explica cómo distinguir el código generado, los resultados de pruebas locales, la validación simulada y las pruebas contra YCloud. ## Entendiendo los diferentes niveles de validación Cada etapa de desarrollo proporciona un nivel de evidencia diferente. Una etapa completada no debe tratarse como prueba de la siguiente.
Resultado
Lo que confirma
Lo que no confirma
Código generado
La implementación solicitada ha sido escritaEl código se ejecuta correctamente
Pruebas locales aprobadas
Los casos de prueba locales definidos produjeron los resultados esperadosLa API real de YCloud se comporta de manera idéntica
Simulación local completada
Los escenarios seleccionados se ejecutaron a través del adaptador falso de YCloud y firmaron eventos sintéticos de WebhookToda capacidad de YCloud o escenario de producción funciona
Integración probada con YCloud
El flujo de trabajo especificado fue probado en un entorno autorizado de YCloudSe validaron otros flujos de trabajo, escenarios o entornos de implementació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. La siguiente sección explica qué habilidad del YCloud Developer Kit usar para cada tarea de desarrollo. ## Habilidades del YCloud Developer Kit y cuándo usarlas YCloud Developer Kit dirige cada tarea de desarrollo a una habilidad dedicada.
Tarea de desarrollo
Habilidad recomendada
Planificar una integración de extremo a extremo
$ycloud-integration-architect
Implementar envío y recuperación de mensajes de WhatsApp
$ycloud-whatsapp-messages
Implementar flujos de trabajo de gestión de plantillas
$ycloud-whatsapp-templates
Implementar carga de medios
$ycloud-whatsapp-media
Configurar Webhook y manejo de eventos
$ycloud-webhook-endpoints
Implementar sincronización de contactos
$ycloud-contacts
Implementar comprobación de bajas
$ycloud-unsubscribers
Diseñar autenticación del lado del servidor
$ycloud-api-authentication
**Los desarrolladores no necesitan memorizar cada habilidad.** - 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. Habilidades adicionales cubren Cuentas de WhatsApp Business, números de teléfono, Grupos, Flujos, eventos personalizados y llamadas de WhatsApp. Elegir la habilidad correcta define el área técnica. La siguiente sección explica cómo proporcionar el contexto empresarial, alcance y resultado esperado mediante un prompt efectivo. ## Cómo escribir prompts efectivos para integración con la API de YCloud Un prompt de integración útil debe contener cinco partes: > **Objetivo empresarial + Sistema actual + Alcance + Acciones autorizadas + Resultado requerido** ### 1\. Objetivo Empresarial Explica qué debería ocurrir para el cliente o equipo interno. **Por ejemplo:** enviar una confirmación de pedido después del checkout y registrar actualizaciones posteriores del estado del mensaje. ### 2\. Sistema Actual **Proporciona suficiente contexto del proyecto para que Codex sitúe correctamente la integración:** - *Proyecto existente o nuevo* - *Stack tecnológico* - *Servicios y bases de datos relevantes* - *Implementación de mensajes o Webhooks existentes* ### 3\. Alcance Indique qué incluye y excluye la tarea actual. **Por ejemplo**: incluir confirmaciones de pedidos y Webhooks de estado, pero excluir transmisiones de marketing y respuestas de clientes. ### 4\. Acciones Autorizadas **Especifique qué puede hacer Codex:** - 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 La autorización clara evita suposiciones sobre cambios de archivos u operaciones externas. ### 5\. Salida Requerida **Solicite entregables que puedan ser revisados:** - *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 ```plaintext 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. ``` Un prompt claro define tanto la integración esperada como los límites de la tarea. La siguiente sección cubre las prácticas de seguridad y desarrollo que deben aplicarse durante su implementación. ## Prácticas de Seguridad y Desarrollo Empresarial El código de integración generado debe seguir los mismos estándares de seguridad y revisión que el código escrito manualmente. ### 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. Las credenciales no deben aparecer en el código del lado del cliente, URLs, registros o ejemplos generados. ### Verifica con la Documentación Oficial de la API **Antes de usar ejemplos generados en producción, confirma lo siguiente:** - Endpoints de la API y métodos de solicitud - Campos requeridos y opcionales - Requisitos de autenticación - Formatos de respuesta y errores - Comportamiento soportado **El ejemplo local en este artículo puede usar la etiqueta:** ```plaintext synthetic_unverified ``` Esto significa que el resultado se produjo con datos sintéticos y algunos campos o comportamientos de la API aún requieren confirmación. No es un estado de mensaje de YCloud ni evidencia de una prueba en vivo de la API. La revisión de la documentación confirma el contrato esperado de la API. Las pruebas contra YCloud confirman cómo se comporta el flujo de trabajo definido en un entorno autorizado. Estas son verificaciones separadas. ### Diseña Webhooks para Confiabilidad **Los manejadores de Webhooks deben:** - 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 Mantenga separadas las configuraciones de desarrollo, pruebas y producción. - 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 **Revise el código generado y la evidencia de prueba antes de:** - 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 Estas acciones deben seguir el proceso normal de revisión, lanzamiento y reversión de la organización. La siguiente sección resume las limitaciones del Kit y los controles que aún quedan fuera del desarrollo local. ## Limitaciones y Notas Importantes Tenga en cuenta las siguientes limitaciones al utilizar YCloud Developer Kit. ### Instalación y Acceso a la Cuenta **Instalar el Kit solo hace que sus habilidades estén disponibles en Codex. No:** - *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* Las plantillas, números de teléfono y otros recursos externos pueden requerir configuración, aprobación o permisos de cuenta por separado. ### Cobertura de Simulación La cobertura de simulación varía según la capacidad. Consulte los [materiales de la versión 0.7.9](https://github.com/YCloud-Developers/YCloud-Developer-Kit/releases/tag/v0.7.9) y los archivos de prueba del proyecto generado antes de indicar qué escenarios son compatibles. **El ejemplo de confirmación de pedido cubre:** - *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* **No verifica:** - *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 Instalar el complemento no inicia automáticamente un entorno de simulación. Este ejemplo utiliza un adaptador falso y accesorios de Webhook sintéticos dentro del proyecto local. **La simulación se ejecuta mediante el comando de prueba:** ```plaintext node --test --test-concurrency=1 test/*.test.js ``` No se requiere un servicio de simulador separado para este ejemplo grabado. Otros flujos de trabajo pueden usar diferentes accesorios o herramientas de simulación opcionales, así que sigue las instrucciones proporcionadas con esa implementación. ### 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 La versión 0.7.9 excluye **SMS, Verify, YCloud Voice y Email** integraciones. La versión se centra en integraciones de WhatsApp y APIs relacionadas de YCloud. La configuración en producción, pruebas de integración, despliegue, monitoreo y reversión siguen siendo responsabilidad de la organización. Con estas limitaciones establecidas, la siguiente sección explica cuándo los equipos deberían usar YCloud Developer Kit. ## ¿Cuándo deben los equipos usar YCloud Developer Kit? **YCloud Developer Kit es adecuado cuando los equipos necesitan:** - *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* Los equipos pueden detenerse después de la etapa de arquitectura y planificación. Cuando se requiere implementación local, pueden continuar autorizando cambios a un proyecto definido y ejecutando pruebas simuladas. El nivel de trabajo debe coincidir con la etapa actual del proyecto, su alcance y proceso de aprobación. A continuación, la sección final resume cómo los equipos pueden comenzar con un flujo de trabajo controlado de integración de WhatsApp. ## ¡Reflexiones finales! YCloud Developer Kit proporciona un camino estructurado desde un requisito empresarial hasta un plan de integración, código local y pruebas simuladas. Ayuda a los desarrolladores a considerar plantillas, autenticación, Webhooks, estados de mensajes y manejo de fallos durante el desarrollo. El Kit complementa, no reemplaza, la revisión de ingeniería, la documentación oficial de la API de YCloud, la configuración en producción y la validación en entorno real. Comience con un flujo de trabajo claramente definido, como una confirmación de pedido. Desarrolle su plan, impleméntelo dentro de un alcance local aprobado, pruebe los escenarios requeridos y documente lo que todavía necesita verificación con YCloud. ## Comience con un flujo de trabajo de WhatsApp [**Instale YCloud Developer Kit usando las instrucciones de configuración del repositorio**](https://github.com/YCloud-Developers/YCloud-Developer-Kit?tab=readme-ov-file#%E4%B8%80%E6%AC%A1%E5%AE%89%E8%A3%85%E6%95%B4%E5%A5%97%E6%8A%80%E8%83%BD)**.** **Luego abre una nueva tarea en Codex y comienza con un flujo de trabajo definido:** ```plaintext Use $ycloud-integration-architect to plan a WhatsApp [workflow name] integration. ``` Especifica el desencadenante, el resultado esperado y el alcance de la implementación. Completa la configuración de la cuenta y la validación en entorno real por separado antes del lanzamiento. La siguiente sección responde preguntas comunes sobre el acceso a la cuenta, mensajes reales, cambios en el proyecto y preparación para producción. ## Frequently Asked Questions ### ¿Es el YCloud Developer Kit lo mismo que el Panel de Control de YCloud? No. YCloud Developer Kit es un asistente de desarrollo de integraciones utilizado dentro de Codex. Las operaciones de mensajería y la gestión de campañas utilizan herramientas separadas. ### ¿La instalación del kit lo conecta a una cuenta de YCloud? No. El acceso a la cuenta de YCloud, las credenciales y los recursos externos deben configurarse por separado. ### ¿Puede enviar mensajes reales de WhatsApp? No por sí solo. La versión 0.7.9 puede ayudar a los desarrolladores a escribir código de aplicación que envíe mensajes a través de YCloud. Sin embargo, el Kit no lee credenciales en vivo, llama a las API de YCloud ni envía mensajes reales durante su flujo de trabajo. El envío real ocurre por separado a través de la aplicación configurada en un entorno autorizado. ### ¿Los desarrolladores necesitan proporcionar una clave API durante la planificación? No. La planificación, los ejemplos de código y las pruebas simuladas pueden usar marcadores de posición y datos sintéticos. ### ¿Puede modificar un proyecto existente? Sí. El desarrollador debe autorizar explícitamente los cambios en los archivos locales y definir el proyecto, los módulos y el alcance permitido. ### ¿Significa una simulación exitosa que la integración está lista para producción? No. Una simulación solo valida los escenarios locales definidos. Aún es necesaria la configuración y prueba en producción con YCloud. ### ¿Puede ayudar a manejar mensajes entrantes? Sí. Puede ayudar a implementar manejadores de Webhook que validen y dirijan los eventos de mensajes entrantes a la lógica de negocio de la aplicación. ### ¿Admite plantillas, contactos y gestión de cancelación de suscripción? Sí. La versión 0.7.9 incluye orientación dedicada para flujos de trabajo de plantillas, contactos y cancelación de suscripciones. ### ¿Admite SMS, Voice, Verify o correo electrónico? Las integraciones de SMS, Verify, YCloud Voice y correo electrónico están fuera del alcance declarado de la versión 0.7.9. WhatsApp Calling es compatible y es independiente de YCloud Voice. ### ¿Qué sucede si la documentación oficial de la API no puede ser verificada? Marque el ejemplo como no verificado e identifique los endpoints, campos o comportamientos que aún requieren confirmación. Si el Kit devuelve: **"synthetic\_unverified"** Significa que el resultado se produjo con datos sintéticos y los detalles del contrato indicados no se verificaron por completo. No es un estado de la API de YCloud ni una evidencia de pruebas de integración reales. --- Canonical HTML: https://www.ycloud.com/es/blog/ycloud-developer-kit-whatsapp-api-integration