API de PDFs para Shopify en apps y flujos backend
Llame a gPdf desde una app Shopify o flujo backend para generar PDF de pedidos, facturas, notas de empaque, devoluciones y etiquetas desde datos Shopify mapeados.
/api/v1/pdf/render Usar una app Shopify o backend ecommerce para mapear datos de pedido, cliente, producto, fulfillment y devolución a JSON de gPdf o datos de plantilla, y devolver PDF deterministas sin afirmar una integración nativa en Shopify App Store.
Cuándo usar esta API
- Está construyendo una app Shopify, backend privado o flujo de fulfillment que puede llamar APIs externas.
- Su app ya recibe datos de pedidos, fulfillment, clientes o productos de Shopify.
- Necesita facturas, notas de empaque, documentos de devolución, etiquetas de almacén o adjuntos PDF.
- Quiere un contrato `template_id` estable para diseños de documento específicos de cada comerciante.
Qué no sustituye
- Espera que gPdf sea una app oficial de Shopify o un listado en Shopify App Store.
- Necesita que gPdf se instale en una tienda de comerciante, gestione OAuth o se suscriba directamente a webhooks.
- Necesita tarifas de envío, compra de portes, gestión de inventario o funciones de UI para comerciantes desde gPdf.
Qué endpoint llamar
/api/v1/pdf/render
JSON Render es la ruta predeterminada para este flujo.
/api/v1/template-render
Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.
Solicitud mínima
POST /api/v1/template-render - el backend de la app envía datos de pedido Shopify mapeados a una plantilla publicada.
{
"template_id": "packing_list",
"data": [
{
"order_number": "#1042",
"customer_name": "Example Buyer",
"ship_to": "1200 Market St, San Francisco, CA",
"items": [
{ "sku": "TSHIRT-BLK-M", "name": "Black T-shirt", "quantity": 2 },
{ "sku": "MUG-WHT", "name": "White mug", "quantity": 1 }
]
}
]
}
Qué gestiona gPdf
- Renderizado PDF a partir de datos JSON derivados de Shopify y mapeados por el backend de su app.
- Template Render para diseños de documento específicos de comerciante o marca.
- Códigos de barras, códigos QR, tablas, totales, imágenes, etiquetas y estructuras de notas de empaque.
- Generación PDF stateless mediante las APIs públicas de gPdf.
Qué controla su sistema
- Código de app Shopify, OAuth, webhooks, UI de comerciante y distribución en app store.
- Mapeo de datos de pedido, fulfillment, cliente, devolución, producto e impuestos.
- Configuración del comerciante, selección de plantilla, entrega, almacenamiento y reintentos.
Checklist de producción
- Mantenga credenciales Shopify y tokens de API gPdf en el backend, no en código de navegador.
- Mapee datos Shopify a una solicitud de renderizado explícita o a un esquema de datos de plantilla.
- Use Template Render para diseños específicos de comerciante después de aprobarlos.
- Guarde PDF generados o datos fuente según el flujo del comerciante.
- Documente que la integración es su app llamando a gPdf, no una app Shopify oficial de gPdf.
Límites de la promesa
- No afirme que existe una app pública oficial de Shopify salvo que exista.
- gPdf no ejecuta OAuth de Shopify, instalación de apps, webhooks ni ajustes de comerciante.
- El sistema que llama controla el mapeo de datos Shopify y las reglas empresariales ecommerce.
Modelo de integración
El modelo limpio de integración Shopify es backend a backend. Su app recibe o
consulta datos Shopify, los mapea a un DocumentRequest de gPdf o a un objeto
de datos de plantilla, llama a gPdf y devuelve o almacena el PDF según el flujo
del comerciante.
Esto mantiene precisa la afirmación pública: gPdf es la API de generación PDF a la que puede llamar su app Shopify. No es una app pública oficial de Shopify salvo que exista ese producto separado.
Template Render encaja con layouts de comerciantes
Los PDF ecommerce suelen volverse específicos de cada comerciante: marca, tablas de artículos, instrucciones de devolución, bloques de etiqueta, notas de regalo y texto localizado. Template Render permite que su app mantenga esos diseños en plantillas publicadas mientras la app envía solo los datos de pedido mapeados.
Mantenga la lógica de plataforma en la app
OAuth, webhooks, ajustes de comerciante, estado de fulfillment, inventario, reglas de devolución y distribución en app store permanecen en su app Shopify. gPdf debe recibir los datos finales de renderizado y producir el PDF.
FAQ
- ¿gPdf es una app oficial de Shopify?
- No. Esta página es para apps y backends que llaman a gPdf. No presente gPdf como integración oficial en Shopify App Store salvo que ese producto exista.
- ¿Dónde debe ocurrir la llamada a la API de gPdf?
- Llame a gPdf desde su backend o servidor de app, donde las credenciales de Shopify y los tokens de API de gPdf estén protegidos.
- ¿Los PDF de Shopify deberían usar JSON Render o Template Render?
- Use JSON Render para diseños personalizados generados por código. Use Template Render cuando el diseño de un comerciante o marca esté aprobado y los clientes solo deban enviar datos.
- ¿gPdf gestiona webhooks de Shopify?
- No. Su app recibe webhooks, mapea los datos y decide cuándo renderizar. gPdf solo renderiza la solicitud PDF que recibe.