Cliente Dinaup

DinaupClientC es el cliente de la API de Dinaup en el paquete Dinaup. Con él consultas informes y lees, exportas y escribes secciones. También maneja archivos, anotaciones, documentos dinámicos, correo, la configuración de la empresa, sesiones, fichajes y la estructura Flex.

Antes de empezar

• Dos paquetes NuGet: Dinaup (el cliente) y tu biblioteca MyDinaup, con las clases de tus secciones e informes. Los ejemplos usan DemoUp.MyDinaup, un modelo de ejemplo; en tu proyecto cambia el prefijo por el de tu empresa.
• Tres credenciales: ConnectAsync pide endPoint, publicKey y secretKey. El endpoint es https://api.dinaup.com/v2/<clave de conexión>. La clave de conexión de tu licencia está en la app Desarrollo de Play. La clave pública y la secreta salen de una clave API creada en Administración → Claves API, que hereda los permisos del usuario al que se asocia. Ver Claves API.
• Los using:

using Dinaup;                                   // DinaupClientC, WriteOperation, extensiones
using Dinaup.Vault;                             // VaultData
using static DemoUp.MyDinaup.Reports.FuncionalidadD;   // informes tipados (APIVentasC, APIEntidadesC...)
using static DemoUp.MyDinaup.SectionsD;         // secciones tipadas (EntidadesD, ProductosD...)

Conectar y operar

dotnet add package Dinaup
dotnet add package DemoUp.MyDinaup

var client = await DinaupClientC.ConnectAsync(
    endPoint: "https://api.dinaup.com/v2/tu-codigo",
    publicKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    secretKey: "tu-secret-key-aqui"
);

if (client == null || client.IsConnected == false)
{
    throw new Exception("No se pudo conectar a Dinaup");
}

using Dinaup;
using Dinaup.Vault;

// Las únicas credenciales en variables de entorno son las del Vault
var vault = new VaultData("VAULT_URL", "VAULT_PASSWORD");
vault.Initialize();

// Todo lo demás viene del Vault
var client = await DinaupClientC.ConnectAsync(
    endPoint: vault.Read("dinaup.endpoint"),
    publicKey: vault.Read("dinaup.publickey"),
    secretKey: vault.Read("dinaup.secretkey")
);

if (client == null || client.IsConnected == false)
{
    throw new Exception("No se pudo conectar a Dinaup");
}

using Dinaup;
using Dinaup.Vault;

var builder = WebApplication.CreateBuilder(args);

var vault = new VaultData("VAULT_URL", "VAULT_PASSWORD");
vault.Initialize();

var client = await DinaupClientC.ConnectAsync(
    endPoint: vault.Read("dinaup.endpoint"),
    publicKey: vault.Read("dinaup.publickey"),
    secretKey: vault.Read("dinaup.secretkey")
);

if (client == null || client.IsConnected == false)
    throw new Exception("No se pudo conectar a Dinaup");

// Un cliente para toda la app
builder.Services.AddSingleton(client);

var app = builder.Build();

using static DemoUp.MyDinaup.Reports.FuncionalidadD;

// Un informe tipado de tu MyDinaup
var ventasReport = new APIVentasC();
await ventasReport.ExecuteQueryAsync(
    dinaupClient: client,
    page: 1,
    resultsPerPage: 50
);

Console.WriteLine($"{ventasReport.Rows.Count} filas en esta página");
foreach (var row in ventasReport.Rows)
{
    Console.WriteLine($"- {row.NumeroDeFacturaCompleto}: {row.Total}");
}

using static DemoUp.MyDinaup.SectionsD;

var data = new Dictionary<string, string>
{
    { SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, $"Prueba {Guid.NewGuid()}" }
};

var wOp = new WriteOperation("", data); // "" => alta

await client.RunWriteOperationAsync(SeccionDePruebasAPID._SectionIDGUID, wOp, false);

// Lanza excepción si la operación falló o no se ejecutó
wOp.EnsureSuccess();

// Tras EnsureSuccess, WriteOperationResult no es nulo
Guid newId = wOp.WriteOperationResult.RowID;

Guid rowId = /* Id del registro a editar */;

var data = new Dictionary<string, string>
{
    { SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, $"Prueba {Guid.NewGuid()}" }
};

var wOp = new WriteOperation(rowId, data);

await client.RunWriteOperationAsync(SeccionDePruebasAPID._SectionIDGUID, wOp, false);
wOp.EnsureSuccess();

Guid updatedId = wOp.WriteOperationResult.RowID;

Tiempos de espera y reintentos

CONFIG_TIMEOUT (30.000 ms por defecto) es lo que espera cada petición que no fija su propio tiempo. Las que lo fijan, como ExecuteRawFunctionAsync(functionName, params, timeout) con un timeout positivo, esperan ese tiempo en su lugar.

Si el servidor responde 429, el cliente espera lo que diga Retry-After y repite la petición una vez. Un 503 solo se repite en las lecturas; una escritura no, porque el servidor pudo guardarla. Sin Retry-After espera 1 segundo. Si pide más de 5, o la espera no cabe en el tiempo que queda, devuelve el error sin repetir.

Informes

Los informes son consultas predefinidas y tipadas. MyDinaup genera una clase API{Nombre}C por informe, en el namespace {Empresa}.MyDinaup.Reports.{Categoria}D, que hereda de DinaupReportBase. La categoría es la carpeta del informe en Flex: en DemoUp.MyDinaup, los informes de la API están en Reports.FuncionalidadD (APIVentasC, APIEntidadesC, APIImpuestosC, APISeccionDePruebasAPIC). Los nombres salen de tu esquema, así que suelen estar en español.

using static DemoUp.MyDinaup.Reports.FuncionalidadD;

var report = new APISeccionDePruebasAPIC();
await report.ExecuteQueryAsync(client, page: 1, resultsPerPage: 10);

foreach (var fila in report.Rows)
{
    // fila.TextoPrincipal, fila.ValorEntero
}

const int filasPorPagina = 300;
var report = new APISeccionDePruebasAPIC();
report.RequestParams.GetPageSummary = false;   // sin recuento: para recorrer no hace falta

for (int pagina = 1; ; pagina++)
{
    await report.ExecuteQueryAsync(client, pagina, filasPorPagina);
    foreach (var row in report.Rows)
    {
        // procesar la fila
    }
    if (report.Rows.Count < filasPorPagina) break;
}

var report = new APISeccionDePruebasAPIC();
var todas = await report.LoadAllRowsAsync(client, pageSize: 10000, adminMode: true);

Console.WriteLine($"{todas.Count} filas volcadas");

Columnas ausentes en la respuesta

Si el modelo tipado declara una columna que el servidor ya no devuelve, el informe lanza una excepción: así detectas de inmediato un desajuste entre tu MyDinaup y la estructura real. Para tolerarlo (registrar un aviso y dejar esas propiedades en su valor por defecto), activa TolerateMissingColumns:

// Por informe
var report = new APISeccionDePruebasAPIC();
report.TolerateMissingColumns = true;

// O para todo el proceso, una vez al arrancar
DinaupReportSettings.TolerateMissingColumns = true;

Cada informe hereda DinaupReportSettings.TolerateMissingColumns (false por defecto) al crearse y puede sobrescribirlo por instancia.

Sin MyDinaup

Report_GetAsync(new ReportRequestParameters(reportId)) ejecuta cualquier informe por su GUID y devuelve un ReportResponse sin tipar (Report con la definición, DataList con las filas). ListReportsAsync(filtroCategoria) lista los informes disponibles. Es lo que usan los componentes de DinaZen por dentro.

Archivos

Sube archivos desde memoria o desde una URL y obtén URLs firmadas para servirlos. El tamaño máximo es Limits.MaxFileSizeInBytes: 150 MB.

private async Task<Dinaup.DinaupFileDTO> GetExistingFileAsync(string sha1)
{
    var report = new APIIndiceDeArchivosEnSistemaC();
    report.AddFilter("crcbase", "=", sha1);
    await report.ExecuteQueryAsync(client, 1, 1, "", true, true);   // includeFiles: 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 de Dinaup admiten tres tipos de anotaciones, en el enum AnnotationTypeE:

• Files (1): documentos privados asociados al registro (contratos, presupuestos, soportes).
• Comments (2): mensajería tipo chat para el equipo, dentro del contexto del registro.
• PublicGallery (3): archivos públicos en el CDN, como fotos de producto.

• Agregar un comentario de texto

  var anotacion = new AnotationParameters(sectionId, rowId, AnnotationTypeE.Comments)
      .WithText("Primer comentario desde la API.");
  
  await client.Annotation_PutAsync(anotacion);

• Agregar un comentario con archivo adjunto

  var bytes = System.Text.Encoding.UTF8.GetBytes("contenido adjunto");
  var upload = await client.File_UploadBytesAsync(bytes, "nota.txt");
  
  var anotacion = new AnotationParameters(sectionId, rowId, AnnotationTypeE.Comments)
      .WithText("Comentario con adjunto")
      .WithFile(upload.FileId);
  
  await client.Annotation_PutAsync(anotacion);

• Leer anotaciones

  var resultado = await client.Annotations_GetAsync(sectionId, rowId, AnnotationTypeE.Comments);
  
  foreach (var anotacion in resultado.Annotations)
  {
      var texto    = anotacion.Text;
      var autor    = anotacion.Autor;
      var fecha    = anotacion.AnnotationDate;
      var adjuntos = anotacion.AttachedFiles;   // List<DinaupFileDTO>
  }

Documentos dinámicos

Un documento dinámico es un guion que se ejecuta en el servidor y devuelve HTML, JSON u otro formato: una factura, un correo, un volcado de datos. Úsalos para componer documentos de impresión o para agrupar varias consultas en una llamada; para leer datos, un informe es más barato.

MyDinaup genera una clase por documento bajo DynamicDocuments.{Categoria}D, heredera de DinaupDynamicDocumentBase:

using DemoUp.MyDinaup;

var doc = new DynamicDocuments.APID.SesionC();
doc.SetVariableValue("ventaId", ventaId);          // string, Guid, int, decimal, bool o DateOnly

var response = await doc.ExecuteAsync(client);

var html = response.Content;                       // el documento generado
// response.URL, response.Name, response.Status y response.Metadata completan la respuesta

Sin MyDinaup, DynamicDocuments_ExecuteAsync(documentId) o DynamicDocuments_ExecuteAsync(documentId, parametros) ejecutan el documento por su GUID, y DynamicDocumentsList() devuelve los documentos disponibles.

Secciones

Las secciones son las tablas de tu empresa (Clientes, Facturas, Empleados). MyDinaup genera una clase {Seccion}D por sección con lectura directa:

• Un registro por id

  var pais = await PaisesD.GetRowByIdAsync(client, paisId);

• Una lista por criterios

  var parametros = new RowsRequestParameters(PaisesD.PaisesES.CodigoDePaisAlfabeticoDe2Caracteres, "=", "ES");
  var paises = await PaisesD.GetRowsAsync(client, parametros);   // List<PaisesC>

  RowsRequestParameters se construye con un id, una lista de ids, un campo con operador y valor, o varios FilterCondition (new FilterCondition(campo, operador, valor)); varios arrays de condiciones se combinan con OR. QuerySearch, Limit, Skip e IncludeAnnotationsComments afinan la petición. Limit vale 100 por defecto. Para leer muchas filas, pagina con Skip.

• Cabecera y líneas en una llamada. En secciones con lista (una factura y sus líneas), GetRowsWithListAsync devuelve cada registro como MainRow más su colección ListRows.

  var filas = await AsientosContablesD.GetRowsWithListAsync(client, new RowsRequestParameters(asientoId));
  var asiento = filas.FirstOrDefault();
  foreach (var apunte in asiento.ListRows) { }

Los campos de referencia de una fila tipada llegan como DinaupBasicInformation: Id y SectionID del registro relacionado y su texto principal en Title (Label devuelve lo mismo). ToWriteOperationValue() da el texto que espera una escritura.

var ventas = await VentasIngresosD.GetRowsAsync(client, new RowsRequestParameters(ventaId));
foreach (var v in ventas)
{
    Console.WriteLine($"{v.ReferenciaCliente.Title} ({v.ReferenciaCliente.Id})");
}

Sin MyDinaup, RowsGetAsync(sectionId, includeList, parameters) devuelve las filas sin tipar. GetHistoryChanges(sectionId, rowId, campo) lista el histórico de cambios de un registro y GetBacklinksAsync(sectionId, rowId) quién lo referencia.

Exportar una sección a CSV

ExportAsync vuelca una sección a un CSV en el servidor y devuelve un ExportDTO con su URL firmada. Es la única lectura del cliente sin tope de filas.

// La sección entera, con todas sus columnas exportables
var export = await client.ExportAsync(ProductosD._SectionIDGUID);

// Solo esas columnas y solo las filas que cumplen el filtro
var columnas = new[] { ProductosD.ProductosES.TextoPrincipal, ProductosD.ProductosES.ReferenciaCodigoDeBarras };
var filtro = new List<FilterCondition> { new FilterCondition(ProductosD.ProductosES.Eliminado, "=", "0") };
var parcial = await client.ExportAsync(ProductosD._SectionIDGUID, columnas, filtro);

// Lo que cambió desde el export anterior: encadena siempre con NextFromUtc
var cambios = await client.ExportAsync(ProductosD._SectionIDGUID, export.NextFromUtc);

if (cambios.State == ExportStateE.Ready)
{
    var csv = await client.DownloadExportAsync(cambios);
    foreach (var fila in csv.Rows)
    {
        var nombre = fila[ProductosD.ProductosES.TextoPrincipal];
    }
}

ExportDTO trae State (Working, Ready, Failed o Busy), ExportId, Url, Rows, Bytes, NextFromUtc, Filter y Message. Dinaup hace una exportación a la vez por empresa: ExportAsync espera turno un rato. Si el fichero no está listo, devuelve Working con su ExportId; consulta su estado con ExportStateAsync y descárgalo al estar Ready, que el resultado no se guarda indefinidamente.

En el CSV no salen la lista de la sección ni los campos de contraseña, confidenciales, eliminados u obsoletos. Para las líneas, exporta la sección de lista y crúzala con su registro principal. Con fromUtc y filtro a la vez, una fila que deja de cumplir el filtro no sale en el siguiente incremental: para sincronizar, filtra en destino.

Escritura

Las altas y las ediciones viajan en un WriteOperation: el id del registro más un diccionario campo a valor. Un id vacío ("" o Guid.Empty) es un alta; un id existente, una edición; un id que no existe, un error.

Los valores viajan como texto y el formato importa: decimal con punto y sin separador de miles ("1234.5"), booleano "1" o "0", fecha y hora "yyyy-MM-dd HH:mm:ss", fecha "yyyy-MM-dd", hora "HH:mm:ss" y una referencia vacía como cadena vacía. En .NET, .STR() sobre Guid, bool, DateTime y DateOnly y .ToSQL() sobre números y fechas ya dan ese formato.

Si falla, el motivo está en UserError

RunWriteOperationAsync devuelve un WriteOperationResponse. UserError agrega el error de cada fila y, si no hubo respuesta, usa el error HTTP. resp.EnsureSuccess() lanza ese texto; wOp.EnsureSuccess() lanza el error de esa fila (WriteOperationResult.AError) o "No se ha ejecutado la operación." si no llegó resultado.

var resp = await client.RunWriteOperationAsync(sectionId, wOp, true);
if (resp.IsSuccess == false)
{
    throw new Exception(resp.UserError);
}

Las filas tipadas de MyDinaup ({Seccion}C) también se escriben directamente: RunWriteOperationAsync(fila, withsSripts) acepta un DinaupRowBase, una lista de ellos, o una cabecera con su lista de líneas, y fila.ToWriteOperation() construye el WriteOperation equivalente.

Contexto de ejecución

Cuando la app conecta con credenciales de aplicación, las operaciones no tienen un usuario detrás. DinaupContext.WithUser establece uno para todo lo que ocurra dentro del bloque using: afecta al autor del alta, al histórico y a las anotaciones.

// Solo userId
using (DinaupContext.WithUser(userId))
{
    await client.RunWriteOperationAsync(sectionId, wOp, false);
}

// Con IP y UserAgent del usuario final (quedan en el histórico)
using (DinaupContext.WithUser(userId, "192.168.1.1", "Mozilla/5.0"))
{
    await client.RunWriteOperationAsync(sectionId, wOp, false);
}

El contexto es AsyncLocal: vale para el flujo asíncrono en curso y se restaura al salir del using. DinaupContext.CurrentSession devuelve la sesión activa.

Fichajes

Dos familias de métodos registran tiempo:

• Jornada. Timesheet_StatusAsync(employeeIdentifier) devuelve el estado del fichaje del empleado y Timesheet_ClockAsync(employeeIdentifier, fingerprintIp, fingerprintBrowser, fingerprintUrl, fingerprintId, fingerprintRaw) ficha entrada o salida con la huella del dispositivo.
• Pausas. Break_StatusAsync, Break_StartAsync(employeeIdentifier, breakTypeId, ...) y Break_StopAsync abren y cierran una pausa con la misma huella.

Correo

SendEmailAsync(parameters, timeoutMS) envía un correo desde Dinaup. El cuerpo es HTML y sale tal cual, sin plantilla ni firma. timeoutMS vale 30.000 por defecto.

var upload = await client.File_UploadBytesAsync(pdf, "factura.pdf");

var correo = new SendEmailParameters("cliente@ejemplo.com", "Tu factura", cuerpoHtml)
{
    Sender = "facturacion@miempresa.com",
    ReplyTo = "facturacion@miempresa.com",
    AttachmentIds = new List<Guid> { upload.FileId }
};

var resp = await client.SendEmailAsync(correo);
if (resp.Sent == false)
{
    throw new Exception(resp.PendingReason);
}

SendEmailParameters recibe destinatario, asunto y cuerpo, y admite RecipientName, Cc, Bcc, ReplyTo, Sender, SenderName, AttachmentIds, EntityId, RelatedSectionId y RelatedRowId.

• Sender tiene que ser de un dominio verificado de tu licencia; si no, el correo no sale y PendingReason dice por qué. Sin Sender, el remitente es el noreply@ del primer dominio verificado, nunca una dirección @dinaup.com.
• Como mucho 50 direcciones contando las copias y 10 adjuntos. Los adjuntos van por id de un archivo ya subido.
• Comprueba siempre Sent. El SDK compara el eco del servidor (destinatario, copias, adjuntos, dirección de respuesta y remitente) con lo pedido. Si no coincide, deja Sent en false con el motivo en PendingReason. Result.From dice desde qué dirección salió.
• En una instalación local (on-premise) el envío no está disponible y PendingReason lo indica.

Clave-valor de la empresa

KV_GetAsync(space, key) y KV_SetAsync(space, key, value) guardan pares en la sección Dinaup KV de la empresa. Es configuración de tu app, visible y editable como cualquier otro dato. No caduca: el valor queda hasta que alguien lo reescribe.

bool guardado = await client.KV_SetAsync("miapp", "modo", "produccion");
string modo = await client.KV_GetAsync("miapp", "modo");   // "" si no existe

// Un objeto viaja como JSON y se lee con la sobrecarga genérica
await client.KV_SetAsync("miapp", "ajustes", ajustes);
var leidos = await client.KV_GetAsync<AjustesDTO>("miapp", "ajustes");

• El espacio es libre y "" es el global. Dos apps que escriben en el mismo espacio sobrescriben los valores de la otra.
• Espacio y clave admiten hasta 200 caracteres; el valor, hasta 100.000. Por encima, el SDK lanza ArgumentException sin llamar al servidor.
• Escribir "" deja el par vacío, no lo borra.

MyAppKVClient es otro almacén: el de tu app, compartido por todas las empresas. Ver Apps multi-tenant.

Patrones

• Servicio con inyección de dependencias

  public class ProductosService(DinaupClientC client)
  {
      public async Task<List<APIProductosC.APIProductos_RowC>> GetProductosAsync()
      {
          var report = new APIProductosC();
          await report.ExecuteQueryAsync(client, 1, 1000);
          return report.Rows;
      }
  }

• Sincronizar desde una API externa. Mismo método para crear y para actualizar: id vacío crea, id existente actualiza. Divide la lista por el tope del lote.

  public async Task SyncProductosAsync(List<ProductoExterno> externos)
  {
      var operaciones = externos.Select(e => new WriteOperation(e.DinaupId ?? Guid.Empty, new Dictionary<string, string>
      {
          { ProductosD.ProductosES.ReferenciaCodigoDeBarras, e.SKU },
          { ProductosD.ProductosES.TextoPrincipal, e.Nombre }
      })).ToList();
  
      foreach (var lote in operaciones.Chunk(DinaupClientC.MaxItemsPerWriteOperation))
      {
          var resp = await client.RunWriteOperationAsync(ProductosD._SectionIDGUID, lote, false);
          resp.EnsureSuccess();
      }
  }

• Servicio en segundo plano

  public class TareasWorker(DinaupClientC client) : BackgroundService
  {
      protected override async Task ExecuteAsync(CancellationToken ct)
      {
          while (ct.IsCancellationRequested == false)
          {
              var pendientes = new APITareasDeProyectosC();
              await pendientes.ExecuteQueryAsync(client, 1, 100);
              foreach (var tarea in pendientes.Rows)
                  await ProcesarAsync(tarea);
  
              await Task.Delay(TimeSpan.FromMinutes(5), ct);
          }
      }
  }

Todos los métodos del cliente

Referencia por familias. Cada método público de DinaupClientC está en una fila.

Otros canales

Los mismos datos salen de Dinaup por otras vías cuando el SDK .NET no encaja:

Después

• Las primeras escrituras, sin afectar a datos reales, en la Zona de pruebas de Play.
• Los IDs de secciones, campos e informes, en Esquema.
• Qué pasa en el servidor al escribir (autorrellenados, orden de los campos, scripts), en Escribir en secciones.
• Los mismos datos por REST desde cualquier lenguaje, en Referencia de la API REST.