> ## Documentation Index > Fetch the complete documentation index at: https://help.chateea.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Integraciones privadas > Conecta Chateea con tus propios sistemas mediante tokens con permisos controlados, y rótalos o revócalos con seguridad. > [!NOTE] > > **Disponible en los planes Pro y Business.** Las integraciones privadas te permiten conectar tu cuenta de Chateea con cualquier aplicación externa o sistema interno mediante un token que tú generas y cuyos permisos tú decides. Son ideales para herramientas propias, sincronizaciones internas y automatizaciones a medida que necesitan acceso a la API sin construir una aplicación pública. ## Cuándo la necesitas Si quieres conectar tu cuenta con una aplicación externa, tienes dos caminos: > **Instalar una aplicación existente** > > Buscas la aplicación en el Marketplace de aplicaciones y la instalas. No requiere desarrollo. > > Si existe, es siempre la opción más simple. > **Crear tu propia integración** > > Cuando no existe una aplicación para lo que necesitas, construyes la conexión tú o con un desarrollador, usando la API. > > Para eso están las integraciones privadas. Sus dos ventajas principales: * **Sencillez.** Generas y administras los tokens desde la configuración de tu cuenta, sin escribir código para obtenerlos. * **Seguridad.** Defines exactamente a qué partes de tu cuenta puede acceder ese desarrollador o esa aplicación. ## Diferencia con las claves API Las integraciones privadas son la alternativa moderna y más segura a las claves API tradicionales. | | Integraciones privadas | Claves API | | - | - | - | | **Seguridad** | Restringes los permisos a los que puede acceder un desarrollador en tu cuenta | El desarrollador obtiene acceso sin restricciones a todos los datos de tu cuenta | | **Tecnología** | Acceden a la API v2.0, la versión actual y mantenida | Funcionan con la API v1.0, que llegó al final de su ciclo de vida y ya no recibe mantenimiento | | **Funciones** | La v2.0 es más potente y admite webhooks, que notifican a una aplicación externa cuando ocurre algo en tu cuenta | La v1.0 tiene funcionalidad limitada | ### Por qué usar tokens de integración privada para credenciales nuevas Los tokens de integración privada son el reemplazo recomendado de las claves API heredadas: * **Ya no se pueden crear claves v1 nuevas.** Cualquier credencial nueva debe ser un token de integración privada. * **Las claves heredadas sin uso caducan.** Una clave API que pasa más de 90 días sin usarse puede aparecer como **Caducada** en la configuración. > [!WARNING] > > Si todavía dependes de una clave API, migra esa conexión a una integración privada en cuanto puedas. La v1.0 no recibe mantenimiento, y una clave filtrada expone **toda** tu cuenta sin que puedas limitar el daño. ## Diferencia con los tokens OAuth2 En pocas palabras: una integración privada **es** un token de acceso OAuth2, pero estático. | | Integraciones privadas | Tokens de acceso OAuth2 | | - | - | - | | **Cómo se generan** | Desde la interfaz, en unos clics | De forma programática, intercambiando el código de autorización por el token mediante la API | | **Vigencia** | Estáticos y fijos. No se renuevan solos: solo cambian si tú los rotas desde la interfaz | Caducan a diario y hay que renovarlos automáticamente | > [!TIP] > > Por eso las integraciones privadas son la opción práctica para conexiones internas: no tienes que programar la lógica de renovación de tokens. Para una aplicación pública destinada a muchas cuentas, OAuth2 sigue siendo el camino correcto. ## Cómo se usa el token El token viaja en el encabezado de autorización de cada petición a la API de Chateea, igual que cualquier otro token de acceso. > [!NOTE] > > Para obtener la URL base de la API de Chateea y la documentación de los endpoints disponibles, escribe a soporte en **[help@chateea.com](mailto:help@chateea.com)** o por WhatsApp al **+1 829-580-7071**. En los ejemplos, reemplaza `URL_BASE_DE_LA_API` por esa dirección. Ejemplo consultando un contacto: ```bash theme={null} curl --request GET \ --url https://URL_BASE_DE_LA_API/contacts/ID_DEL_CONTACTO \ --header 'Accept: application/json' \ --header 'Authorization: Bearer TU_TOKEN_DE_INTEGRACION_PRIVADA' \ --header 'Version: 2021-07-28' ``` Tres encabezados son obligatorios en cada llamada: | Encabezado | Para qué sirve | | - | - | | `Authorization` | Tu token de integración privada | | `Version` | La versión de la API que estás usando | | `Accept` | El formato de respuesta que esperas | > [!WARNING] > > Si omites el encabezado `Version`, la petición falla. Es el error más común al hacer la primera llamada. ## Prueba tu integración creando un contacto Una forma sencilla de comprobar que el token funciona es crear un contacto de prueba: ```bash theme={null} curl --request POST \ --url https://URL_BASE_DE_LA_API/contacts/ \ --header 'Authorization: Bearer TU_TOKEN_DE_INTEGRACION_PRIVADA' \ --header 'Content-Type: application/json' \ --header 'Version: 2021-07-28' \ --data '{ "firstName": "Juan", "lastName": "Pérez", "email": "juan.perez@ejemplo.com", "phone": "+18095550123", "locationId": "ID_DE_TU_CUENTA" }' ``` Antes de ejecutarlo: * Reemplaza `ID_DE_TU_CUENTA` por el identificador de tu cuenta de Chateea. * Reemplaza `TU_TOKEN_DE_INTEGRACION_PRIVADA` por el token que generaste. * Asegúrate de que el token tenga permiso de escritura de contactos. Si la llamada funciona, el contacto aparece en **Contactos**. Bórralo después de la prueba. ## Quién puede crearlas Por defecto, **todos los administradores** de la cuenta pueden crear y gestionar integraciones privadas. Puedes restringir ese permiso usuario por usuario en **Configuración → Mi personal → editar el administrador → Roles y permisos**, activando o desactivando **Integraciones privadas** para esa persona. > [!TIP] > > Vale la pena restringirlo. Un administrador que puede crear tokens puede otorgar acceso a tus datos sin pasar por nadie más. ## Dónde encontrarlas En **Configuración**, desplázate hasta la sección **Otras configuraciones** del menú lateral izquierdo y abre **Integraciones privadas**. > [!NOTE] > > Si no aparece la opción, verifica que la función esté habilitada en **Labs**. ## Crear una integración privada **1. Pulsa Crear nueva integración** Desde la pantalla de integraciones privadas. **2. Ponle nombre y descripción** Para que tú y tu equipo identifiquen para qué sirve. Nombra por sistema, no por persona: `Sincronización con sistema contable` es mejor que `Integración de Juan`. Dentro de un año necesitarás saber qué se rompe si eliminas ese token. **3. Selecciona los permisos** Marca los ámbitos a los que quieres que esta integración tenga acceso en tu cuenta. > [!WARNING] > > **Selecciona únicamente los permisos necesarios.** Si el sistema solo consulta contactos, no le des permiso de escritura ni de eliminación. El día que ese token se filtre, el daño queda limitado a lo que autorizaste. **4. Copia el token generado** Y compártelo solo con el desarrollador de tu aplicación externa. > [!WARNING] > > **El token se muestra una sola vez.** No podrás volver a verlo después. Cópialo y guárdalo en un lugar seguro en ese momento. > > Compártelo únicamente con personas de confianza y nunca de forma pública. > [!NOTE] > > Puedes tener hasta **20 tokens de integración privada** por cuenta. ## Rota tus tokens cada 90 días Es la práctica recomendada para mantener la seguridad, incluso cuando no ha pasado nada. Rotar significa generar un token nuevo dando un plazo para actualizar la aplicación externa antes de que el anterior deje de servir. **1. Abre la integración** En integraciones privadas, pulsa sobre la que creaste. **2. Elige Rotar y hacer caducar este token más tarde** Es la opción para rotación preventiva, sin urgencia. **3. Confirma la advertencia** Pulsa **Continuar** si estás seguro. **4. Copia el token nuevo y actualiza tu aplicación** Tienes **7 días** en los que **ambos tokens funcionan**, el viejo y el nuevo. Es el margen para que tu desarrollador haga el cambio sin que nada deje de operar. Durante esos 7 días puedes: * **Cancelar rotación**, si tu desarrollador necesita más tiempo * **Caducar ahora**, si la aplicación ya quedó actualizada con el token nuevo Pasados los 7 días, el token anterior caduca automáticamente. > [!NOTE] > > Recuerda copiar el token nuevo en el momento: tampoco podrás verlo después. ## Si tu token quedó expuesto Aquí no hay periodo de gracia: se corta de inmediato. **1. Abre la integración afectada** En integraciones privadas, pulsa sobre ella. **2. Elige Rotar y caducar este token ahora** A diferencia de la rotación preventiva, esta opción **invalida el token anterior al instante**. **3. Confirma la advertencia** Pulsa **Continuar**. **4. Copia el token nuevo y actualiza tu aplicación** Cuanto antes, porque la integración está caída desde el momento en que rotaste. > [!WARNING] > > Úsala solo ante una sospecha real de exposición: token publicado en un repositorio, enviado por un canal inseguro, o en manos de alguien que ya no debería tenerlo. Todo lo que dependa de ese token deja de funcionar en el acto. ## Editar permisos sin cambiar el token Puedes modificar el nombre, la descripción y los permisos de una integración en cualquier momento después de crearla. **1. Selecciona Editar** Desde el menú de tres puntos de la integración. **2. Actualiza nombre y descripción** Si hace falta. Pulsa **Siguiente**. **3. Ajusta los permisos** Marca o desmarca los ámbitos. Mantén el criterio de dar solo lo necesario. Pulsa **Actualizar**. > [!NOTE] > > **Editar una integración no genera un token nuevo.** El token existente sigue funcionando, ahora con los permisos actualizados. No tienes que tocar tu aplicación externa. > [!TIP] > > Esto permite algo útil: empezar con permisos mínimos y agregar solo los que resulten necesarios, sin interrumpir nada. ## Eliminar una integración Cuando dejes de usar la aplicación externa, elimina la integración desde el menú de tres puntos, opción **Eliminar**. > [!WARNING] > > Al eliminarla, el token deja de funcionar de forma permanente. Confirma antes qué sistemas lo están usando: si una sincronización corre en segundo plano, se detiene sin avisar a nadie. ## Buenas prácticas > **Un token por sistema** > > No reutilices el mismo token en varios lugares. Si tienes que rotarlo o eliminarlo, quieres que caiga una sola cosa. > **Nunca lo pongas en código público** > > Ni en un repositorio, ni en el código de tu sitio web, ni en nada que se ejecute en el navegador del usuario. Cualquiera puede leerlo ahí. > **Guárdalo como variable de entorno** > > En el servidor que lo usa, nunca escrito directamente en el archivo del programa. > **Compártelo por un canal seguro** > > Si tienes que dárselo a un desarrollador, usa un gestor de contraseñas, no WhatsApp ni correo. > **Documenta cada integración** > > Qué sistema la usa, quién la mantiene y qué hace. Un token sin dueño conocido es un riesgo que nadie se atreve a eliminar. > **Revisa la lista cada seis meses** > > Y elimina lo que ya no se usa. Recuerda que el límite es de 20 tokens por cuenta. ## Solución de problemas > **Error de autorización** > > El token está mal copiado, fue rotado o eliminado, o le falta el permiso para esa operación concreta. > **Funciona para leer pero no para escribir** > > Falta el permiso de escritura en esa área. Lectura y escritura son permisos independientes. Edítalos sin necesidad de generar un token nuevo. > **La petición falla sin mensaje claro** > > Verifica que estés enviando el encabezado `Version`. Sin él, la llamada no se procesa. > **Dejó de funcionar de golpe** > > Revisa si alguien rotó o eliminó el token, si pasaron los 7 días de una rotación pendiente, o si la cuenta cambió a un plan que no incluye esta función. > **Mi clave API antigua aparece como caducada** > > Las claves API heredadas que pasan más de 90 días sin uso pueden marcarse como caducadas, y ya no se pueden crear claves nuevas. Crea una integración privada con los permisos necesarios y actualiza tu sistema con el nuevo token. > **No puedo crear más tokens** > > Llegaste al límite de 20 tokens por cuenta. Elimina los que ya no se usan. > **No veo la opción en Configuración** > > Busca en la sección **Otras configuraciones** del menú lateral. Si sigue sin aparecer, habilita la función en **Labs**, o confirma que tu usuario tenga el permiso activado. ## ¿Necesitas ayuda? Esta función requiere conocimientos técnicos. Si no tienes un desarrollador, escríbenos a **[help@chateea.com](mailto:help@chateea.com)** o por WhatsApp al **+1 829-580-7071** y evaluamos si lo que necesitas se resuelve con una [automatización](https://help.chateea.com/docs/automatizaciones/introduccion.md), con [Zapier](https://help.chateea.com/docs/integraciones/conectar-zapier.md) o con una [integración existente](https://help.chateea.com/docs/integraciones/introduccion.md), que casi siempre es más simple y no requiere mantenimiento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.