Holded Invoice Component

El Holded Invoice Component te permite interactuar con la API de Holded para gestionar todos los recursos relacionados con facturación. Puedes listar, crear o obtener información de cuentas de tesorería, contactos, productos, canales de venta, entre otros, directamente desde tu dashboard de Nappai.

¿Cómo funciona?

Cuando configuras el componente, seleccionas el recurso que quieres manejar (por ejemplo, “Contacts”) y la operación que deseas realizar (“List”, “Create” o “Get”). El componente se conecta a la API de Holded usando la clave API que has guardado en la credencial Holded Task API. Internamente, el componente envía una solicitud HTTP al endpoint correspondiente y devuelve la respuesta como un objeto Message que puedes usar en tu flujo de trabajo. Si el componente se usa como herramienta para un agente, también puede exportar la respuesta como un objeto Tool.

Operaciones

(Esta sección se omite porque el componente no define operaciones separadas; la operación se selecciona en el campo “Operation”.)

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

• Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
• Resource: Selecciona el tipo de recurso de facturación que quieres gestionar (por ejemplo, “Treasury Accounts”, “Contacts”, “Products”, etc.).
• Operation: Define la acción que quieres ejecutar sobre el recurso seleccionado (“List”, “Create”, “Get”).
• Tool Name: El nombre que aparecerá ante el agente cuando este componente se utilice como herramienta.
• Tool Description: Descripción detallada de lo que hace esta herramienta para que el agente la comprenda correctamente.
• Tools arguments metadata: Metadatos que describen los argumentos que la herramienta aceptará.

Nota: Los campos relacionados con la credencial (por ejemplo, la clave API) no aparecen aquí porque se configuran en la sección de credenciales de Nappai.

Salidas

• Response: Devuelve la respuesta de la API de Holded como un objeto Message. Puedes usarla para mostrar datos, guardarlos en una base de datos o pasarlos a otro componente.
• Tool: Exporta la respuesta como un objeto Tool cuando el componente se conecta a un agente. Esto permite que el agente invoque la herramienta y reciba la respuesta directamente.

Ejemplo de Uso

1. Configura la credencial

   • Ve a la sección de credenciales de Nappai y crea una credencial de tipo Holded Task API.
   • Ingresa tu Holded Api Key y guarda la credencial.
   • En el componente, selecciona esta credencial en el campo “Credential”.

2. Listar contactos

   • Resource: Contacts
   • Operation: List
   • Haz clic en “Run”.
   • La salida Response mostrará un listado de todos los contactos registrados en Holded.

3. Crear un nuevo producto (modo de mapeo activado)

   • Activa “Mapping Mode”.
   • Conecta la salida de un componente que genere datos de productos (por ejemplo, un CSV) al campo “Mapping Data”.
   • Resource: Products
   • Operation: Create
   • Cada registro del CSV se enviará a Holded como un nuevo producto.
   • La salida Response contendrá la confirmación de cada creación.

Componentes Relacionados

• Holded Customer Component – Gestiona clientes y sus datos de facturación.
• Holded Order Component – Crea y actualiza órdenes de venta.
• Holded Payment Component – Registra y consulta pagos realizados.

Consejos y Mejores Prácticas

• Usa Mapping Mode cuando necesites procesar listas grandes de datos; evita ejecutar el componente manualmente para cada registro.
• Revisa la respuesta antes de usarla en otro componente; la API puede devolver errores que deben manejarse.
• Mantén tu clave API segura: nunca la expongas en el código ni la compartas públicamente.
• Prueba con “List” primero para asegurarte de que la conexión a Holded funciona antes de crear o obtener datos.

Consideraciones de Seguridad

• La clave API se almacena en la credencial Holded Task API y no se muestra en el panel de configuración del componente.
• Asegúrate de que solo usuarios autorizados tengan acceso a la sección de credenciales y al componente.
• Si compartes el flujo de trabajo, evita incluir la salida Response en archivos públicos, ya que puede contener información sensible.