Generación de PDF

SDK

	import { PGSClient } from '@ircg/pgs'
	
	const apiKey = process.env.IRCG_PGS_API_KEY
	if (!apiKey) throw new Error('IRCG_PGS_API_KEY is required')
	
	const pgs = new PGSClient({ apiKey })

El método generate devuelve { response, billing } o { error }. Usa generateUnsafe si prefieres recibir la respuesta directamente y controlar las excepciones.

Dry run

Configura dryRun: true para recibir un PDF sintético válido y facturación en cero, sin cargar la URL, realizar solicitudes HTTP ni consumir créditos. El nombre respeta el formato público de fileName y la respuesta incluye Cache-Control: no-store.

	const pgs = new PGSClient({ apiKey: 'unused', dryRun: true })
	const result = await pgs.generate({ fileName: 'invoice.pdf', url: 'https://example.com/invoice' })
	if (result.error) throw new Error(result.error.message)
	const pdf = await result.response.arrayBuffer()
	console.log(result.billing, pdf.byteLength)

API REST

• La ruta usa Authorization: Bearer con una API key de PGS.
• El cuerpo requiere Content-Type: application/json.
• PGS no habilita CORS. Llama la API desde tu servidor y nunca publiques una API key.

Generar PDF POST

POST /api/v1/pdfs

	import { writeFile } from 'node:fs/promises'
	
	const input = {
	  url: 'https://example.com/invoices/123',
	  fileName: 'invoice-123.pdf',
	  timeoutSeconds: 10,
	  pdfOptions: { format: 'a4', printBackground: true }
	}
	
	// SDK
	const result = await pgs.generate(input)
	if (result.error) throw new Error(result.error.message)
	await writeFile('invoice-123.pdf', Buffer.from(await result.response.arrayBuffer()))
	console.log(result.billing)
	
	// REST
	const response = await fetch('https://ircg.dev/api/v1/pdfs', {
	  method: 'POST',
	  headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
	  body: JSON.stringify(input)
	})
	if (!response.ok) throw new Error(`PGS failed: ${response.status}`)
	await writeFile('invoice-123.pdf', Buffer.from(await response.arrayBuffer()))
	console.log({
	  billableSeconds: Number(response.headers.get('X-IRCG-Billable-Seconds')),
	  creditsConsumed: Number(response.headers.get('X-IRCG-Credits-Consumed')),
	  requestId: response.headers.get('X-IRCG-Request-ID')
	})

Encabezados

Cuerpo

format no puede combinarse con width o height. Si defines dimensiones personalizadas debes enviar ambas.

Encabezados de respuesta

Los tres encabezados X-IRCG-* también aparecen en errores que alcanzaron el navegador. Un rechazo anterior al navegador consume cero créditos.

PGS no conserva el PDF y todavía no ofrece una clave de idempotencia que permita repetir el binario. No reintentes automáticamente una generación: una nueva solicitud puede iniciar otro render y consumir créditos.

Respuestas

Límites y costos

• Cada segundo iniciado de navegador cuesta 3 créditos. Por ejemplo, 1,250 ms se redondean a 2 segundos y consumen 6 créditos.
• Los fallos, timeouts e intentos solo se cobran cuando se registra tiempo de navegador facturable. Las validaciones y rechazos previos no se cobran.
• timeoutSeconds controla el tiempo máximo de cada solicitud: permite cortar una carga atascada y ajustar el límite a lo que normalmente tarda el recurso. También limita el costo máximo posible a timeoutSeconds × 3 créditos. Acepta enteros entre 5 y 60; su valor predeterminado es 10.
• El límite de tiempo del render se comporta igual en suscripciones free y de paga. En free se reservan al inicio timeoutSeconds × 3 créditos y al terminar se devuelve la parte que no corresponda a segundos facturables registrados. En suscripciones de paga no hay reserva previa.
• La URL debe usar HTTPS y su hostname debe añadirse previamente a la lista de hosts permitidos de PGS. No se admiten comodines, credenciales en la URL, puertos personalizados ni destinos locales o privados.
• PGS transmite el PDF y no lo conserva. Para persistirlo, sube la respuesta a FSS como una operación y un cargo independientes.