Resumen

Cotizaciones y facturas de Cord dentro de tu producto, con React, Vue, Web Components o Vanilla JS.

¿Qué son los Elements?

Cord Elements es el SDK oficial (@flouviahq/elements) que te permite integrar toda la experiencia de interacción comercial de Cord directamente en tu propio portal web corporativo.

En lugar de enviar al cliente a cordhq.app, tus clientes pueden ver cotizaciones, negociar en el chat interno, aprobar y firmar documentos, o pagar facturas sin abandonar tu marca. Todo ocurre de forma segura bajo tus propios dominios.

Métodos de Integración

Dependiendo de tu stack tecnológico, Cord ofrece tres maneras de consumir Elements:

1. El SDK de NPM (Recomendado)

Para aplicaciones modernas construidas en React, Next.js, Vue, o Nuxt, puedes instalar el paquete oficial de NPM. Este paquete provee componentes nativos, hooks (useQuoteBuilder) y tipos completos de TypeScript.

Instalación:

npm install @flouviahq/elements

Explora nuestras guías específicas:

2. Etiqueta Script (embed.js)

Para sitios sin bundlers, WordPress, o arquitecturas legacy, puedes cargar el entorno usando una sola etiqueta script y definir atributos data- en tu HTML.

<script src="https://cordhq.app/embed.js" async></script>
<div data-cord-token="a1b2c3d4e5f60718"></div>

Este script se encarga de inyectar dinámicamente un iframe y ajustar automáticamente su altura para evitar barras de desplazamiento.

3. Framer y Webflow

El SDK también exporta wrappers específicos listos para ser pegados como Code Components en editores visuales modernos. Revisa la documentación de Web Components para más detalles.

Arquitectura de Seguridad

Cord Elements utiliza seguridad de grado bancario. Por defecto, tu clave publicable (pk_live_...) expuesta en el frontend nunca podrá leer el directorio de tus clientes (para evitar fugas de datos de CRM). Si deseas funciones avanzadas, puedes operar el SDK a través de un backend proxy.

Explora la sección de Seguridad CSP para configurar tus dominios permitidos (allowlist) y evitar ataques de Clickjacking.

Errores de integración

Cuando algo de tu integración está mal, Elements lo dice en la consola del navegador con un código estable y un enlace a su explicación en esta sección, en el locale de tu <CordProvider> (Builder y hooks) o en el lang de tu página (lo demás):

[Cord] missing_token: Falta el token del documento. https://docs.cordhq.app/docs/desarrolladores/herramientas/elements/resumen#missing_token

Lo que impide montar o configurar un componente se lanza como CordIntegrationError, con code y docUrl; lo demás solo avisa y el componente sigue. Maneja cada caso por su code, nunca por el texto, que cambia con el idioma. Importa la clase del mismo paquete que usas (@flouviahq/elements, /react, /vue o /headless): cada uno trae la suya.

import { mountCotizador, CordIntegrationError } from '@flouviahq/elements';

try {
  mountCotizador(document.querySelector('#cotizacion'), { token });
} catch (error) {
  if (error instanceof CordIntegrationError && error.code === 'invalid_target') {
    // El contenedor no existe en esta página.
  }
}

Los errores que manda la API llegan como CordError y su docUrl lleva a Manejo de errores.

Del documento embebido

missing_token: Falta el token público de la cotización (/q/{token}) o de la factura (/i/{token}). mountCotizador() y el <CordCotizador> de Vue lanzan, <cord-quote> y <cord-invoice> avisan, y el <CordCotizador> de React muestra el aviso en su lugar.
invalid_target: mountCotizador() recibió null en vez de un elemento: el selector no encontró el contenedor en la página. Lanza.
invalid_appearance_json: El atributo appearance de <cord-quote> o el data-cord-appearance de embed.js no es JSON válido. Avisa y el documento se monta sin esa appearance.
appearance_dropped: Uno o más valores de appearance no pasan la validación (una variable que no existe, un color mal escrito, una fuente fuera de Google Fonts o Bunny Fonts) y Cord los descarta. El aviso los nombra, por ejemplo variables.colorPrimary. No avisa en una compilación con NODE_ENV=production. Ver Apariencia.
appearance_too_big: La appearance pesa más de 8192 bytes como JSON. Cord la ignora completa y el documento conserva la que tenía.
not_found: No existe un documento con ese token, o ya no está disponible. También llega como cord:error; ver Eventos.
frame_blocked: El iframe cargó y Cord no respondió: tu dominio no está en Ajustes › Cotizador embebible, o baseUrl no es el origen de Cord. El aviso nombra tu dominio. También llega como cord:error.
timeout: No llegó cord:ready dentro de readyTimeout (10 segundos por defecto). También llega como cord:error; si el documento carga después, el error se limpia.

De React, Vue y headless

missing_provider: Un hook o componente de Cord quedó fuera de su <CordProvider>, o una pieza del Builder (<CordBuilder.Items> y las demás) fuera de <CordBuilder>. Lanza. El visor (<CordCotizador>) no necesita Provider.
missing_key: El Builder necesita publishableKey o proxyUrl, solo uno. useQuoteBuilder() y createCordClient() lanzan sin ninguno, y createCordClient() también con los dos; useCreateQuote() lo deja en su error como CordError.
invalid_publishable_key: La llave del navegador no empieza con pk_. Una secreta (sk_, rk_) va solo en tu servidor, detrás de proxyUrl; ver Proxy de servidor. Si ya la publicaste, revócala. <CordProvider> y createCordClient() lanzan.
clients_require_proxy: useCordClients() con una llave publicable: una pk_ no puede leer tus clientes. Configura proxyUrl o pasa clients a <CordBuilder>. Llega como CordError en su error, sin pedir nada a Cord.
iva_pct_deprecated: <CordProvider ivaPct> ya no se usa: cada línea toma su tasa del catálogo de impuestos de tu organización. Quita la prop. Solo avisa.

De la barra de depuración

debug_live_key: Activaste debug con una llave pk_live_. La barra solo se dibuja con pk_test_, para que tus clientes nunca la vean. Solo avisa.