MyDinaup

El SDK de Dinaup para .NET te permite conectar tus aplicaciones directamente con la plataforma Dinaup.

Esta guía explica, paso a paso, cómo usar el SDK de Dinaup en .NET para conectarte al servicio, consultar informes, gestionar archivos, añadir anotaciones, generar documentos dinámicos, leer/escribir datos de secciones y trabajar con paginación y filtros.

Dinaup .NET

Antes de empezar necesitarás instalar el paquete Dinaup, que incluye el Cliente base: conexión, autenticación, sesiones, archivos, anotaciones, WriteOperations, etc.

Dinaup 9.2.0.4nuget

MyDinaup

Dinaup es una plataforma flexible: cada empresa cuenta con su propio modelo de datos (secciones, informes y documentos dinámicos). Para trabajar de forma tipada con ese modelo, necesitas la biblioteca MyDinaup específica de tu organización. MyDinaup incluye modelos y utilidades tipadas (Reports, SectionsD y DynamicDocuments) con los nombres reales de tus secciones y depende del paquete base Dinaup.

Genéricos

Modelo Ready to Go

Este Nuget únicamente incluye la modelización de la estructura Ready to Go. Ideal para desarrollos compatibles con varias empresas.

ReadyToGo.MyDinaup 9.1.0.58nuget

Modelo DemoUp

Este es un modelo de Pre-Producción que utiliza internamente el equipo de Dinaup. Su uso está desaconsejado ya que puede contener errores y estructuras incompatibles.

DemoUp.MyDinaup 9.1.2.47nuget

Personalizado

1. Para actualizar MyDinaup debes Acceder con el usuario Sistema a Dinaup Desktop

2. Navega hacia Configuración > Generar MyDinaup y pulsa sobre Commit

Iniciar: crear e inicializar el cliente

Básico

Para interactuar con Dinaup, primero crea una instancia de cliente, inicialízala y actualiza la sesión por defecto. Se recomienda reutilizar una única instancia del cliente durante todo el ciclo de vida de tu aplicación.

// Parámetros de conexión
var endpointUrl   = "https://api.dinaup.com/v2/xxxx";
var apiPublicKey  = "xxx";
var apiSecretKey  = "xxx";
var defaultUserId = "*"; // * = Usuario de Sistema

// Crear e inicializar el cliente
var dinaupClient = new Dinaup.DinaupClientC(
    endpoint: endpointUrl,
    apiPublicKey: apiPublicKey,
    apiSecretKey: apiSecretKey,
    defaultUserId: defaultUserId
);

await dinaupClient.InitializeAsync(timeoutseconds: 120);
await dinaupClient.DefaultSessionUpdateAsync();

// Verificar conexión
if (dinaupClient.IsConnected)
    Console.WriteLine("Conectado. PING OK.");
else
    Console.WriteLine("No se pudo conectar al endpoint.");

Blazor (DI)

En aplicaciones Blazor (o ASP.NET Core) registra el cliente como singleton en el contenedor de dependencias para reutilizar la misma instancia en toda la app.

// Crear e inicializar el cliente ANTES de registrarlo en DI
var endpointUrl   = "https://api.dinaup.com/v2/xxxx";
var apiPublicKey  = "xxx";
var apiSecretKey  = "xxx";
var defaultUserId = "*";

var dinaupClient = new Dinaup.DinaupClientC(
    endpoint: endpointUrl,
    apiPublicKey: apiPublicKey,
    apiSecretKey: apiSecretKey,
    defaultUserId: defaultUserId
);

await dinaupClient.InitializeAsync(timeoutseconds: 120);
await dinaupClient.DefaultSessionUpdateAsync();

// Registrar como Singleton para inyección de dependencias
builder.Services.AddSingleton(dinaupClient);

builder.Services.AddHealthChecks()
    .AddCheck<Dinaup.DinaupClientC>("DinaupClient")

Singleton es el ciclo de vida sugerido para clientes de API tipo SDK: reduce el overhead de reconexiones y mantiene el estado de sesión.

Informes

Los informes son consultas predefinidas y tipadas para acceder a datos de manera eficiente. Están en el espacio de nombres:

• {Empresa}.MyDinaup.Reports.{CategoriaD}

• Convención de nombres de clases: API + NombreDeSeccion + C

• Los nombres de secciones/clases están en español porque se generan a partir de tu licencia (por ejemplo, “Ventas”, “Impuestos”, etc.).

Ejemplos de clases:

• DemoUp.MyDinaup.Reports.FuncionalidadD.APISeccionDePruebasAPIC

• DemoUp.MyDinaup.Reports.FuncionalidadD.APIEntidadesC

• DemoUp.MyDinaup.Reports.VentasD.APIVentasC

• DemoUp.MyDinaup.Reports.ImpuestosD.APIImpuestosC

Consultar un informe

Usa ExecuteQueryAsync para obtener resultados paginados. Accede a filas fuertemente tipadas desde report.Rows.

using DemoUp.MyDinaup.Reports.FuncionalidadD;

var report = new APISeccionDePruebasAPIC(); // 

await report.ExecuteQueryAsync(dinaupClient, page: 1, pageSize: 10);

Console.WriteLine($"Total resultados: {report.TotalResults}");

if (report.Rows.IsNotEmpty())
{
    foreach (var fila in report.Rows)
    {
        // Accede a propiedades tipadas de cada fila
        // Ej.: fila.TextoPrincipal, fila.ValorEntero, etc.
    }
}

Ajusta pageSize a tus necesidades. Si esperas muchos resultados, usa paginación.

Filtrar y Ordenar

• Filtrar resultados Filtro simple por campo de la misma sección

  var report = new APISeccionDePruebasAPIC();
  
  // Igualdad estricta
  report.AddFilter(
      SeccionDePruebasAPIES.ValorEntero,
      "=", 
      3);
  
  await report.ExecuteQueryAsync(dinaupClient, page: 1, pageSize: 10);
  
  if (report.Rows.IsNotEmpty())
  {
      foreach (var fila in report.Rows)
      {
          // Usar fila...
      }
  }

• Filtrar utilizando datos relacionados (composición de rutas):

  Construye una clave de relación combinando el ID de sección y el campo de interés en la entidad relacionada.

  // Clave de relación (ruta compuesta)
  var relationKey =
       SeccionDePruebasAPIES._SectionID.STR() + "." +
       SeccionDePruebasAPIES.ReferenciaAutorDelAlta + "." +
       EntidadesBaseES._SectionID.STR() + "." +
       EntidadesBaseES.VIP;
   
   
  var report = new APISeccionDePruebasAPIC();
  report.AddFilter(relationKey, "=", 3);
  
  await report.ExecuteQueryAsync(dinaupClient, page: 1, pageSize: 10);
  
  if (report.Rows.IsNotEmpty())
  {
      foreach (var fila in report.Rows)
      {
          // Usar fila...
      }
  }

• Filtrado Between

  // Between (ej.: 1 a 2999)
  var reportBetween = new APISeccionDePruebasAPIC();
  reportBetween.AddFilterBetween(
     SeccionDePruebasAPIES.ValorEntero,
      1,
      2999
  );
  
  await reportBetween.ExecuteQueryAsync(dinaupClient, page: 1, pageSize: 10);

• Solapamiento de rangos de fechas (overlap)

  var eventosReport = new APIEventosDeCRMC();
  
  var campoInicio = EventosDeCRMES.InicioEvento_UTC;
  var campoFin    = EventosDeCRMES.FinEvento_UTC;
  
  var rangoInicio = DateOnly.FromDateTime(new DateTime(2000, 1, 1));
  var rangoFin    = DateOnly.FromDateTime(DateTime.Today.AddYears(50));
  
  eventosReport.AddFilterDateRangeOverlapFilter(campoInicio, campoFin, rangoInicio, rangoFin);
  
  await eventosReport.ExecuteQueryAsync(dinaupClient, page: 1, pageSize: 25);

Paginación

Cuando el informe tiene muchos resultados, recorre página a página con ExecuteQuery_NextPage_Async.

 var report = new APISeccionDePruebasAPIC();
 await report.ExecuteQueryAsync(_dinaupClient, 1, 300);

 if (report.Rows.IsNotEmpty())
 {
     do
     {


         foreach (var row in report.Rows)
         {
              
         }   


     } while (await report.ExecuteQuery_NextPageAsync());
 }

Archivos

Dinaup permite subir archivos desde memoria o URL y obtener URLs firmadas para su consumo.

Básico

• Subir desde un array de bytes

  var bytes = System.Text.Encoding.UTF8.GetBytes("hola " + Guid.NewGuid());
  var upload = await dinaupClient.File_UploadBytesAsync(
      dinaupClient.DefaultSession,
      bytes,
      "prueba.txt"
  );
  
  Guid fileId = upload.FileId;

• Subir desde una URL

  var upload = await dinaupClient.File_UploadURLAsync(
      dinaupClient.DefaultSession,
      "https://cdn.dinaup.com/dinaup/web/portal/img/dinabot_marca.png",
      "dinabot.png"
  );
  
  Guid fileId = upload.FileId;

• Obtener una URL firmada (lectura)

  var signed = await dinaupClient.File_SignURLGetAsync(fileId);
  var url = signed?.url_original; // URL lista para usar

Buscar duplicados

Calcula el SHA1 en cliente y consulta antes de subir. Ahorra almacenamiento y ancho de banda.

private async Task<Dinaup.DinaupFileDTO> GetExistingFileAsync(string sha1)
{
    var report = new MyDinaup.Reports.FuncionalidadD.APIIndiceDeArchivosEnSistemaC();
    report.AddFilter("crcbase", "=", sha1);
    await report.ExecuteQueryAsync(_dinaupClient, 1, 1, "", true, true); 
    return report.Files.Values.FirstOrDefault();
}

private async Task<Dinaup.DinaupFileDTO> GetExistingFileAsync(byte[] data)
{
    string sha1 = Dinaup.extensions.ToSHA1(data);
    return await GetExistingFileAsync(sha1);
}

Anotaciones

Todas las filas (registros) de Dinaup soportan 3 tipos de anotaciones:

• AnnotationTypeE.Comments: Mensajería tipo chat para el equipo, dentro del contexto del registro.

• AnnotationTypeE.PublicGallery: Archivos públicos en el CDN (p. ej., fotos de productos).

• AnnotationTypeE.Files: Documentos privados asociados (contratos, presupuestos, soportes, etc.).

Los archivos en PublicGallery son públicos: cualquiera con el enlace puede verlos.

A continuación, ejemplos usando AnnotationTypeE.Comments.

Ejemplos

• Agregar un comentario (solo texto)

  Guid sectionId = /* tu sección */;
  Guid rowId     = /* registro al que agregas el comentario */;
  
  await dinaupClient.Annotation_PutAsync(
      dinaupClient.DefaultSession,
      sectionId,
      rowId.STR(), 
      Guid.Empty,       // sin archivo adjunto
      "¡Hola mundo! Este es mi primer comentario.",
      AnnotationTypeE.Comments
  );

• Agregar un comentario con archivo adjunto

  var bytes = System.Text.Encoding.UTF8.GetBytes("contenido adjunto");
  var upload = await dinaupClient.File_UploadBytesAsync(
      dinaupClient.DefaultSession,
      bytes,
      "nota.txt"
  );
  
  await dinaupClient.Annotation_PutAsync(
      dinaupClient.DefaultSession,
      sectionId,
      rowId.ToString(),
      upload.FileId, // adjuntamos el archivo
      "Comentario con adjunto",
      AnnotationTypeE.Comments
  );

• Leer anotaciones

  var resultado = await dinaupClient.Annotations_GetAsync(
      dinaupClient.DefaultSession,
      sectionId,
      rowId,
      AnnotationTypeE.Comments
  );
  
  foreach (var anotacion in resultado.Annotations)
  {
      var texto    = anotacion.Text;
      var adjuntos = anotacion.AttachedFiles; // si hay archivos adjuntos
  }

Documentos dinámicos

Los Documentos Dinámicos permiten:

• Agrupar varias consultas en una sola operación para reducir latencia.

• Generar documentos de impresión (facturas, albaranes) delegando la composición en Dinaup.

Recomendación:

• Para consultar datos en general, usa Reports siempre que sea posible. Documentos Dinámicos son útiles para orquestar múltiples consultas y componer resultados.

Ejemplo

• Ejecutar un documento dinámico

  var documentoSesionExecutor = new DynamicDocuments.APID.SesionC();
  
  // Pasa la sesión actual.
  // Si dispones de una sesión de usuario distinta, úsala; en caso contrario, usa la sesión por defecto.
  await documentoSesionExecutor.ExecuteAsync(dinaupClient, dinaupClient.DefaultSession);
  

Secciones

Las secciones son el equivalente a tablas/entidades por empresa (Clientes, Facturas, Empleados, etc.). En MyDinaup existen utilidades tipadas para trabajar con ellas:

• Espacio de nombres: MyDinaup.SectionsD

• Incluye métodos para leer registros por Id o por criterios.

Advertencia de rendimiento:

• Las operaciones de lectura en SectionsD consultan todos los datos de la sección y los textos principales de los datos relacionados (p. ej., en una venta también recupera empleados, clientes, productos, impuestos, etc.). Esto tiene mayor coste computacional.

• Para rendimiento óptimo, usa Reports. Para escenarios “super optimizados”, usa PGSync.

• Usa SectionsD cuando el código se ejecute con poca frecuencia o para prototipos rápidos.

Leer datos

• Recibir un dato por Id

  Guid paisId = /* Id del país */;
  
  var pais = await MyDinaup.SectionsD.PaisesD.GetRowByIdAsync(dinaupClient, paisId);
  
  // Usa pais.Propiedad...

• Recibir una lista

  var filtros = new List<FilterCondition>
  {
      new FilterCondition(
          MyDinaup.SectionsD.PaisesD.PaisesES.CodigoDePaisAlfabeticoDe2Caracteres,
          "=",
          "ES"
      )
  };
  
  var parametros = new RowsRequestParameters(filtros.ToArray());
  
  var paises = await MyDinaup.SectionsD.PaisesD.GetRowsAsync(
      dinaupClient,
      parametros,
      dinaupClient.DefaultSession
  );
  
  // Iterar resultados
  foreach (var p in paises.Rows)
  {
      // p.Propiedad...
  }

Escritura

Las operaciones de escritura usan WriteOperation para altas y ediciones.

• El ID vacío ("") indica alta

• Un ID válido indica edición.

• Un ID que no existe provocará una excepción.

Básico

• Alta simple (crear un registro)

  Guid sectionId = /* sección destino */;
  
  var data = new Dictionary<string, string>
  {
      {
          SeccionDePruebasAPIES.TextoPrincipal,
          $"Prueba {Guid.NewGuid()}"
      }
  };
  
  var wOp = new WriteOperation("", data); // "" => alta
  
  var result= dinaupClient.RunWriteOperation(
      dinaupClient.DefaultSession,
      SeccionDePruebasAPIES.SectionId,
      wOp,
      false  
  );
  
  // Lanza excepción si hubo errores globales
  result.EnsureSuccess();
  
  Guid newId = wOp.WriteOperationResult.RowID;

• Edición (actualizar un registro existente)

  Guid rowId = /* Id del registro a editar */;
  
  var data = new Dictionary<string, string>
  {
      {
          SeccionDePruebasAPIES.TextoPrincipal,
          $"Prueba {Guid.NewGuid()}"
      }
  };
  
  var wOp= new WriteOperation(rowId, data);
  
  var result= dinaupClient.RunWriteOperation(
      dinaupClient.DefaultSession,
      sectionId,
      wOp,
      false
  );
  
  // Lanza excepción si hubo errores globales
  result.EnsureSuccess();
  
  Guid updatedId = wOp.WriteOperationResult.RowID;

Acciones por lote

• Alta 10 registros de golpe

  var operaciones = new List<WriteOperation>();
  
  for (int i = 0; i < 10; i++)
  {
      var fila = new Dictionary<string, string>
      {
          {
              SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal,
              $"Lote {i}: {Guid.NewGuid()}"
          }
      };
  
      operaciones.Add(new WriteOperation("", fila)); // alta
  }
  
  var batchAdd = dinaupClient.RunWriteOperation(
      dinaupClient.DefaultSession,
      sectionId,
      operaciones,
      false
  );
  
  var ids = operaciones.Select(o => o.WriteOperationResult.RowID).ToList();

• Editar 10 registros

  // Partiendo de la lista 'ids' creada en el ejemplo anterior
  var operacionesEdicion = new List<WriteOperation>();
  
  foreach (var id in ids)
  {
      var actualizado = new Dictionary<string, string>
      {
          {
              SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal,
              $"Editado {DateTime.UtcNow.Ticks}"
          }
      };
  
      operacionesEdicion.Add(new WriteOperation(id.ToString(), actualizado)); // edición
  }
  
  var batchEdit = dinaupClient.RunWriteOperation(
      dinaupClient.DefaultSession,
      sectionId,
      operacionesEdicion,
      false
  );

Escritura Virtualizada

La escritura virtualizada permite que Dinaup ejecute automáticamente la lógica de negocio definida en una sección. Al activarla, cualquier operación de escritura se comporta como si se hubiera realizado desde la interfaz web: con scripts, validaciones, eventos, y cálculos incluidos.

¿Qué hace la virtualización?

Cuando se activa la virtualización en una operación de escritura (RunWriteOperationAsync con virtualized: true), Dinaup:

• Ejecuta scripts personalizados de la sección (onBeforeSave, onAfterSave, etc.)

• Recalcula campos automáticos (ej. totales, impuestos)

• Aplica reglas de validación y lógica de negocio

• Dispara eventos definidos en la sección

Cuando se desactiva (virtualized: false), simplemente se guardan los valores tal como se reciben (Creando histórico). No se ejecuta ningún comportamiento adicional.

La escritura virtualizada es más costosa en términos de rendimiento. Cada operación implica ejecutar scripts del backend y lógica personalizada, lo que puede afectar la velocidad si estás procesando muchos registros o usas esta opción innecesariamente.

¿Cuándo usar virtualización?

✅ Usa escritura virtualizada cuando la sección contiene lógica de negocio activa que debe ejecutarse. Esto incluye cálculos automáticos de totales en ventas, generación de fechas de vencimiento, o scripts que actualizan otras entidades relacionadas. Por ejemplo, al registrar una nueva venta, al cerrar un pedido o al generar una factura, la virtualización asegura que todo se procese correctamente.

¿Cuándo evitar virtualización?

⛔ Evita la virtualización cuando realizas modificaciones simples que no requieren ejecutar lógica adicional. Esto incluye acciones como cambiar el estado de una venta, asignar un técnico a un ticket de soporte, registrar una nota interna o marcar una tarea como completada. En estos casos, desactivarla mejora el rendimiento sin afectar el comportamiento esperado.

Ejemplos

Ejemplo: Agregar un Recambio en Dinaup (.NET)Ejemplo: Ejecucción WriteOperations por Lotes (.NET)Ejemplo: Agregar un Cliente desde Dinaup (.NET)