Documentación Completa de Funciones del Sistema de Plantillas de Kuenta

Este documento proporciona una referencia exhaustiva de todas las funciones disponibles en el sistema de plantillas de Kuenta, detallando su sintaxis, uso, disponibilidad por servicio y ejemplos prácticos.

Índice

1. Funciones Nativas de Go Templates
2. Funciones Específicas de Kuenta
   • Formateo de Valores
   • Manipulación de Fechas
   • Acceso a Datos
   • Operaciones Matemáticas
   • Manipulación de Colecciones
   • Funciones de Crédito
   • Funciones de Conversión y Formateo
3. Funciones de Sprig
   • Disponibilidad por Servicio
   • Categorías de Funciones Sprig
4. Funciones Específicas por Servicio
   • Documentos
   • Webhooks
   • Email
   • Voz
   • Firma

Funciones Nativas de Go Templates

Estas funciones están disponibles en todos los servicios de plantillas de Kuenta, ya que son parte de la implementación estándar de Go Templates.

Función	Descripción	Ejemplo
if...else...end	Condicionales	{{ if eq .Value 1 }}Uno{{ else }}Otro{{ end }}
range...end	Iteración sobre colecciones	{{ range .Items }}{{ .Name }}{{ end }}
with...end	Establece contexto	{{ with .User }}{{ .Name }}{{ end }}
eq	Igualdad	{{ if eq .Status "active" }}Activo{{ end }}
ne	Desigualdad	{{ if ne .Status "active" }}No activo{{ end }}
lt	Menor que	{{ if lt .Value 10 }}Menor a 10{{ end }}
le	Menor o igual que	{{ if le .Value 10 }}Menor o igual a 10{{ end }}
gt	Mayor que	{{ if gt .Value 10 }}Mayor a 10{{ end }}
ge	Mayor o igual que	{{ if ge .Value 10 }}Mayor o igual a 10{{ end }}
and	Operador lógico AND	{{ if and .Value (gt .Count 5) }}...{{ end }}
or	Operador lógico OR	{{ if or .Value .Default }}...{{ end }}
not	Negación lógica	{{ if not .Disabled }}Habilitado{{ end }}
print	Concatena e imprime	{{ print "Valor: " .Value }}
printf	Imprime con formato	{{ printf "%.2f" .Value }}
len	Longitud de array/slice/map/string	{{ if gt (len .Items) 0 }}...{{ end }}
index	Acceso por índice	{{ index .Array 0 }}

Funciones Específicas de Kuenta

Estas funciones son implementadas específicamente por Kuenta y están disponibles a través de domain.Funcs().

Formateo de Valores

Función	Descripción	Disponibilidad	Ejemplo
currency	Formatea valor como moneda	Todos los servicios	{{ currency .Credit.Amount }} → $1,000,000
currencyEntity	Formatea como moneda según config. de entidad	Documentos, PDF	{{ currencyEntity .Value }} → $1,000,000
currencyCredit	Formatea como moneda según config. de crédito	Documentos, Webhooks	{{ currencyCredit .Value .Credit }} → $1,000,000
currencyNotRounded	Formatea como moneda sin redondear	Documentos, Webhooks	{{ currencyNotRounded .Value }} → $1,000,000.50
percentage	Formatea como porcentaje	Todos los servicios	{{ percentage .Credit.Rate }} → 12.50%

Manipulación de Fechas

Función	Descripción	Disponibilidad	Ejemplo
date	Formatea fecha (día/mes/año)	Todos los servicios	{{ date .Credit.CreatedAt }} → 15/enero/2023
localDate	Formatea fecha con zona horaria local	Todos los servicios	{{ localDate .Credit.CreatedAt }} → 15/enero/2023
dateAAAAMMDD	Formatea fecha en formato AAAAMMDD	Todos los servicios	{{ dateAAAAMMDD .Credit.CreatedAt }} → 20230115

Acceso a Datos

Función	Descripción	Disponibilidad	Ejemplo
commonData	Acceso a campos comunes de perfil	Todos los servicios	{{ commonData .Profile "Name" }} → Juan Pérez o Empresa S.A.
customFields	Acceso a campos personalizados	Documentos, Webhooks	{{ customFields .Object.CustomFields "campo1" }}
references	Formatea referencias de perfil	Documentos, Webhooks	{{ references .Profile.References }}
legalNested	Acceso a datos anidados de entidades legales	Documentos, Webhooks	{{ legalNested .Profile.Legal.Representatives }}
allReferences	Combina referencias personales/familiares/comerciales	Documentos, Webhooks	{{ allReferences .PeReferences .FamReferences .ComReferences }}
dataXts	Acceso a datos de fuentes externas	Documentos, Webhooks	{{ dataXts .Sources "VALOR1" }}

Operaciones Matemáticas

Función	Descripción	Disponibilidad	Ejemplo
divide	División de enteros	Todos los servicios	{{ divide 10 2 }} → 5
decimalAdd	Suma de decimales	Todos los servicios	{{ decimalAdd .Value1 .Value2 }}
decimalSub	Resta de decimales	Todos los servicios	{{ decimalSub .Value1 .Value2 }}

Manipulación de Colecciones

Función	Descripción	Disponibilidad	Ejemplo
installments	Procesa cuotas de crédito	Documentos, Webhooks	{{ installments .Credit.Installments "1" "Payment" }}
scoreAcierta	Obtiene puntaje Acierta	Documentos, Webhooks	{{ scoreAcierta .Credit.Analysis }}
checkNut	Verifica NUT	Documentos, Webhooks	{{ checkNut .Credit }}
frecuencyUnit	Muestra unidad de frecuencia	Documentos, Webhooks	{{ frecuencyUnit .Credit.Frequency }} → días o meses

Funciones de Crédito

Función	Descripción	Disponibilidad	Ejemplo
tcea	Calcula TCEA del crédito	Documentos, Webhooks	{{ tcea .Credit }} → 15.25%
rateMV	Convierte tasa EA a tasa mensual vencida	Documentos, Webhooks	{{ rateMV .Credit.Rate }} → 1.19
consecutiveEB	Obtiene consecutivo de documento EB	Documentos	{{ consecutiveEB .Documents }} → CD-000123

Funciones de Conversión y Formateo

Función	Descripción	Disponibilidad	Ejemplo
fixed	Formatea número con decimales fijos	Todos los servicios	{{ fixed .Value 2 }} → 123.45
operation	Realiza operaciones matemáticas básicas	Todos los servicios	{{ operation .Value "+" 10 2 }} → 133.45
zeroFields	Convierte valor 99 a 0	Todos los servicios	{{ zeroFields .Field }} → 0

Funciones de Listado y Formateo Avanzado

Función	Descripción	Disponibilidad	Ejemplo
listPDF	Formatea listas para PDF (sin HTML)	Documentos	{{ listPDF .CustomFields "campo1" }} → valor1, valor2
incomes	Genera HTML de ingresos	Documentos	{{ incomes .Profile.Incomes .Config }} → <div>...</div>
expenses	Genera HTML de gastos	Documentos	{{ expenses .Profile.Expenses .Config }} → <div>...</div>

Funciones de Configuración y Crédito

Además de las funciones principales, Kuenta proporciona funciones especializadas que se configuran según el contexto específico del crédito o la configuración de la entidad.

Funciones de Configuración (ConfigurationFuncs)

Estas funciones están disponibles cuando se pasa un objeto Configuration al template:

Función	Descripción	Disponibilidad	Ejemplo
currency	Formatea moneda según configuración de país	Con configuración	{{ currency .Amount }} → €1,000.00 o $1,000.00

Funciones de Crédito (CreditFuncs)

Estas funciones están disponibles cuando se pasa un objeto Credit al template:

Función	Descripción	Disponibilidad	Ejemplo
currency	Formatea moneda según moneda del crédito	Con crédito	{{ currency .Amount }} → COP 1,000,000
currencyNotRounded	Formatea moneda sin redondear según crédito	Con crédito	{{ currencyNotRounded .Value }} → COP 1,000,000.50

Uso de Funciones de Configuración

// En el código Go
funcs := domain.ConfigurationFuncs(config)
tmpl.Funcs(funcs)

// En la plantilla
{{ currency .Amount }}  // Usa símbolo de moneda del país configurado

Uso de Funciones de Crédito

// En el código Go
funcs := domain.CreditFuncs(credit)
tmpl.Funcs(funcs)

// En la plantilla
{{ currency .Amount }}  // Usa símbolo de moneda del crédito

Funciones de Sprig

La biblioteca Sprig proporciona más de 70 funciones adicionales para manipulación de datos. Su disponibilidad varía según el servicio.

Disponibilidad de Sprig por Servicio

Servicio	Disponibilidad de Sprig	Implementación
Documentos	✅ Completo	Integrado directamente con sprig.FuncMap()
Webhooks	✅ Completo	Integrado directamente con sprig.FuncMap()
Email	❌ Parcial	Solo funciones a través de domain.Funcs()
Voz	❌ No	Solo funciones básicas de Go Templates

Categorías de Funciones Sprig

Manipulación de Strings

Función	Descripción	Ejemplo
trim	Elimina espacios en blanco	{{ trim " hola " }} → "hola"
upper	Convierte a mayúsculas	{{ upper "hola" }} → "HOLA"
lower	Convierte a minúsculas	{{ lower "HOLA" }} → "hola"
title	Primera letra de cada palabra a mayúscula	{{ title "hola mundo" }} → "Hola Mundo"
contains	Verifica si contiene substring	{{ contains "hola" "o" }} → true
hasPrefix	Verifica si comienza con substring	{{ hasPrefix "hola" "ho" }} → true
hasSuffix	Verifica si termina con substring	{{ hasSuffix "hola" "la" }} → true
replace	Reemplaza substring	{{ replace "hola" "o" "0" -1 }} → "h0la"

Operaciones con Números

Función	Descripción	Ejemplo
add	Suma	{{ add 1 2 }} → 3
sub	Resta	{{ sub 5 2 }} → 3
mul	Multiplicación	{{ mul 2 3 }} → 6
div	División	{{ div 6 3 }} → 2
mod	Módulo (resto)	{{ mod 5 2 }} → 1
max	Máximo valor	{{ max 1 2 }} → 2
min	Mínimo valor	{{ min 1 2 }} → 1
ceil	Redondeo hacia arriba	{{ ceil 1.2 }} → 2
floor	Redondeo hacia abajo	{{ floor 1.8 }} → 1
round	Redondeo	{{ round 1.5 }} → 2

Manipulación de Fechas

Función	Descripción	Ejemplo
now	Fecha/hora actual	{{ now }}
date_format	Formatea fecha	{{ date_format "2006-01-02" .Date }} → "2023-01-15"
date_modify	Modifica fecha	{{ .Date | date_modify "+24h" }}
date_in_zone	Cambia zona horaria	{{ date_in_zone "UTC" .Date "America/Bogota" }}

Diccionarios y Colecciones

Función	Descripción	Ejemplo
dict	Crea diccionario	{{ $dict := dict "key1" "value1" "key2" "value2" }}
get	Obtiene valor de diccionario	{{ get $dict "key1" }} → "value1"
set	Establece valor en diccionario	{{ $dict := set $dict "key3" "value3" }}
unset	Elimina clave de diccionario	{{ $dict := unset $dict "key1" }}
hasKey	Verifica si existe clave	{{ hasKey $dict "key1" }} → true
list	Crea lista	{{ $list := list 1 2 3 }}
first	Primer elemento	{{ first $list }} → 1
last	Último elemento	{{ last $list }} → 3
append	Añade a lista	{{ $list := append $list 4 }}

Conversión y Codificación

Función	Descripción	Ejemplo
toJson	Convierte a JSON	{{ toJson $dict }}
fromJson	Convierte de JSON	{{ $obj := fromJson $jsonString }}
toYaml	Convierte a YAML	{{ toYaml $dict }}
fromYaml	Convierte de YAML	{{ $obj := fromYaml $yamlString }}
toString	Convierte a string	{{ toString 123 }} → "123"
toInt	Convierte a entero	{{ toInt "123" }} → 123
toFloat	Convierte a float	{{ toFloat "123.45" }} → 123.45
base64	Codifica en base64	{{ base64 "hello" }}
base64Decode	Decodifica base64	{{ base64Decode $encoded }}

Criptografía y Funciones Aleatorias

Función	Descripción	Ejemplo
sha256sum	Hash SHA256	{{ sha256sum "dato" }}
sha1sum	Hash SHA1	{{ sha1sum "dato" }}
md5sum	Hash MD5	{{ md5sum "dato" }}
uuidv4	Genera UUID v4	{{ uuidv4 }}
randAlpha	Cadena aleatoria con letras	{{ randAlpha 5 }}
randNumeric	Cadena aleatoria con números	{{ randNumeric 5 }}
randAlphaNum	Cadena aleatoria alfanumérica	{{ randAlphaNum 10 }}

Funciones Específicas por Servicio

Algunas funciones son exclusivas de ciertos servicios y no están disponibles en otros.

Funciones Específicas de Documentos

Función	Descripción	Ejemplo
signedAt	Obtiene fecha de firma de documento	{{ signedAt .EntityID .TemplateID }} → 15/enero/2023
currencyEntity	Formatea moneda según config. entidad	{{ currencyEntity .Value }} → $1,000,000
incomes	Formatea ingresos según configuración	{{ incomes .Value }} → $1,000,000
expenses	Formatea gastos según configuración	{{ expenses .Value }} → $1,000,000
listPDF	Formatea listas para PDF	{{ listPDF .CustomFields "campo1" }} → valor1, valor2
consecutiveEB	Obtiene consecutivo de documento EB	{{ consecutiveEB .Documents }} → CD-000123
tcea	Calcula TCEA del crédito	{{ tcea .Credit }} → 15.25%
rateMV	Convierte tasa EA a mensual vencida	{{ rateMV .Credit.Rate }} → 1.19

Funciones Específicas de Webhooks

Webhooks utilizan todas las funciones de Sprig y Kuenta, sin añadir funciones específicas adicionales.

Funciones Específicas de Email

Función	Descripción	Ejemplo
pin	Genera/muestra PIN de autenticación	{{ pin }} → 123456
summary	Genera resumen HTML del crédito	{{ summary }} → <div>...</div>
amortization	Genera tabla HTML de amortización	{{ amortization }} → <table>...</table>

Funciones Específicas de Voz

El servicio de voz no implementa funciones específicas adicionales, solo tiene acceso a las funciones básicas de Go Templates y algunas funciones comunes de Kuenta.

Funciones Específicas de Firma

Función	Descripción	Ejemplo
formatDate	Formatea fecha en formato específico	{{ formatDate .Date "format" }} → 15/01/2023
formatDateTime	Formatea fecha y hora	{{ formatDateTime .Date "format" }} → 15/01/2023 10:30
html	Marca contenido como HTML seguro	{{ html .HtmlContent }}

Notas de Uso

1. Cuando usar commonData: Siempre que necesites acceder a campos comunes entre perfiles naturales y legales (Name, Email, Address, AddressCity, IDNumber, Initials).

2. Diferencia entre currency y currencyEntity: Estas funciones tienen un comportamiento ligeramente distinto:

   • currency: Utiliza símbolo de moneda fijo ($)
   • currencyEntity: Utiliza el símbolo de moneda configurado para la entidad

3. Verificación de Existencia: Siempre verifica que una variable existe antes de utilizarla:

{{ if .Credit.ApprovedAt }}
    {{ date .Credit.ApprovedAt }}
{{ else }}
    No aprobado
{{ end }}

Explicación: Este código verifica si la fecha de aprobación del crédito existe. Si existe, la formatea y la muestra; de lo contrario, muestra "No aprobado". Es un ejemplo de uso de condicionales (if, else) y la función date.

4. Uso eficiente de Sprig: En Documentos y Webhooks, aproveche las potentes funciones de transformación de Sprig. Para otros servicios, utilice alternativas con funciones básicas.

5. Rendimiento: Las funciones de plantilla se ejecutan en el servidor. Las operaciones complejas o bucles grandes pueden afectar el rendimiento.

6. Errores comunes: Si ve can't evaluate field X in type Y, significa que está intentando acceder a un campo que no existe en el objeto actual. Use condicionales (if) para verificar la existencia.

7. Funciones de Configuración: Para usar funciones que dependen de configuración específica (como currencyEntity o incomes), asegúrese de que el objeto Configuration esté disponible en el contexto del template.

8. Funciones de Crédito: Las funciones como tcea, rateMV y consecutiveEB requieren que el objeto Credit esté disponible y tenga los datos necesarios.

9. Formateo de Listas: Use listPDF para formatear listas en documentos PDF (sin HTML) y customFields para formatear listas con HTML en otros contextos.

10. Operaciones Matemáticas: La función operation soporta operadores básicos (+, -, *, /) y puede ser útil para cálculos con dinero simples en plantillas. Nota: Ambos parámetros numéricos aceptan cualquier tipo (string, int, float, decimal) y se convierten automáticamente.