SDK

Gli SDK ufficiali racchiudono l'API pubblica con le stesse funzioni in ogni linguaggio: generare un template, attendere i documenti grandi, leggere template e dataset, errori tipizzati con il correlation id, nuovi tentativi sicuri e verifica della firma dei webhook.

Installazione#

1dotnet add package Prynt.Client

Generare un documento#

RenderAsync / render inviano il codice del template, i parametri e l'ambiente, e restituiscono i byte del documento con i relativi metadati: versione, numero di pagine, ambiente, correlation id e l'esecuzione nei Log.

1using Prynt.Client;2 3using var prynt = new PryntClient(Environment.GetEnvironmentVariable("PRYNT_API_KEY")!);4 5var pdf = await prynt.Documents.RenderAsync(6    "DDT_STANDARD",7    new { DOCUMENT_ID = 82422 },   // i nomi dei parametri vengono inviati così come sono scritti8    environment: "production");9 10await pdf.SaveAsync("ddt-82422.pdf");11Console.WriteLine($"v{pdf.Version}, {pdf.PageCount} pages, correlation id {pdf.CorrelationId}");12 13// ASP.NET Core: builder.Services.AddPrynt(o => o.ApiKey = builder.Configuration["Prynt:ApiKey"]);14// poi inietta PryntClient.

Documenti grandi e job#

Quando un documento è troppo grande o lento per una risposta sincrona, l'API risponde 202 Accepted con un job. Gli SDK lo gestiscono per te: interrogano il job a intervalli crescenti e scaricano il documento tramite il suo link firmato, senza inviare la tua chiave. Per gestire il job in autonomia, avvialo esplicitamente:

1var job = await prynt.Documents.StartRenderJobAsync(new RenderRequest("DDT_STANDARD")2{3    Parameters = new { DOCUMENT_ID = 82422 },4    CorrelationId = "erp-ddt-82422",5});6 7var done = await prynt.Jobs.WaitAsync(job.JobId);         // lancia PryntJobFailedException in caso di errore8var document = await prynt.Documents.DownloadAsync(done); // rinnova da solo un link scaduto

Template e dataset#

1foreach (var template in await prynt.Templates.ListAsync())2    Console.WriteLine($"{template.Code} v{template.Version}");3 4var rows = await prynt.Datasets.ExecuteAsync("DDT_STANDARD", "RIGHE", new { DOCUMENT_ID = 82422 }, maxRows: 100);

Errori#

Ogni risposta di errore è un problem RFC 9457; gli SDK lo sollevano come errore tipizzato con errorCode, detail, lo stato HTTP, il correlationId da comunicare al supporto e, per i 429, l'attesa indicata da Retry-After.

1try2{3    await prynt.Documents.RenderAsync("DDT_STANDARD", new { DOCUMENT_ID = 82422 });4}5catch (PryntApiException e)6{7    // e.Status, e.ErrorCode, e.Detail, e.CorrelationId, e.RetryAfter, e.Extensions8    Console.Error.WriteLine($"{e.ErrorCode}: {e.Detail} (correlation id {e.CorrelationId})");9}

Nuovi tentativi#

• Le letture (job, template, download dei documenti, dataset) vengono ritentate in caso di 429, 502, 503, 504, errori di rete e timeout, con backoff esponenziale e jitter, rispettando sempre Retry-After.
• Le generazioni vengono ritentate solo quando Prynt garantisce che non è stato generato nulla: 429 RATE_LIMITED, 503 RENDER_BUSY o DATA_SOURCE_UNAVAILABLE. Dopo un errore di rete o un timeout il documento potrebbe già esistere, quindi l'errore viene restituito a te invece di generare due volte. Passa un tuo correlation id per ritrovare la generazione nei Log.

Webhook#

Entrambi gli SDK verificano l'header Prynt-Signature (HMAC-SHA256 di {t}.{raw body}, confronto in tempo costante, tolleranza di 5 minuti) prima che tu interpreti l'evento.

// Il corpo grezzo, prima di qualsiasi binding JSON.if (!WebhookSignature.Verify(rawBody, request.Headers["Prynt-Signature"], secret))    return Results.Unauthorized();var evt = PryntWebhookEvent.Parse(rawBody);   // deduplica su evt.Id

// Express: express.raw({ type: "application/json" }) conserva il corpo grezzo.if (!(await verifyWebhookSignature(req.body, req.get("Prynt-Signature"), secret))) return res.sendStatus(401);const event = parseWebhookEvent(req.body); // deduplica su event.id