PDF de Guía

GET`/api/v1/guias/{numeroGuia}/pdf`

Descarga el PDF de la guía directamente como archivo binario. El PDF contiene el código QR, datos del remitente, datos del destinatario y —según la modalidad de cobro— lo que el mensajero debe cobrar al entregar:

Modalidad	Qué imprime la etiqueta
`PREPAGADO`	Sello PREPAGADO, sin monto
`COD_PRODUCTO`	Monto del producto
`COD_PRODUCTO_ENVIO`	Total a cobrar, con el desglose producto + envío
`ENVIO_POR_COBRAR`	Costo del envío, rotulado “Envío por cobrar”

En empresas con plan personalizado (POSTPAGO) la etiqueta nunca imprime el costo del envío: se liquida en tu factura, no en la puerta.

Este endpoint retorna contenido binario (application/pdf), no JSON. Úsalo para descargar o almacenar el PDF, no para obtener una URL.

Alcance. Con un token de sucursal solo se puede consultar una guía de esa sucursal; cualquier otra responde 404 NOT_FOUND, igual que en el resto de endpoints. Ver tokens de sucursal.

Límite propio: 20 PDFs por minuto por token (empresa o sucursal), además del general de 100 req/min. Generar la etiqueta es la operación más costosa de la API: guarda el PDF de tu lado en vez de pedirlo de nuevo en cada impresión. Pasado el límite responde 429 RATE_LIMIT_EXCEEDED.

Ejemplo

curl


curl https://api.tpcxpress.com/api/v1/guias/TPCE123456789/pdf \
  -H "Authorization: Bearer TOKEN" \
  --output guia-TPCE123456789.pdf

JavaScript


// Node.js — descargar y guardar en disco
import fs from 'fs'
 
const res = await fetch('https://api.tpcxpress.com/api/v1/guias/TPCE123456789/pdf', {
  headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` },
})
if (!res.ok) throw new Error((await res.json()).error.message)
 
const buffer = await res.arrayBuffer()
fs.writeFileSync('guia-TPCE123456789.pdf', Buffer.from(buffer))

Python


import httpx, os
 
client = httpx.Client(
    base_url="https://api.tpcxpress.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['TPC_API_TOKEN']}"},
)
r = client.get("/guias/TPCE123456789/pdf")
r.raise_for_status()
 
with open("guia-TPCE123456789.pdf", "wb") as f:
    f.write(r.content)

Headers de respuesta


HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="TPCE123456789.pdf"
Cache-Control: private, no-store
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 86
X-RateLimit-Reset: 1751824200

Uso desde código


// Descargar y guardar en Node.js
import fs from 'fs'
 
const res = await fetch('https://api.tpcxpress.com/api/v1/guias/TPCE123456789/pdf', {
  headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` },
})
 
if (!res.ok) {
  const err = await res.json()
  throw new Error(err.error.message)
}
 
const buffer = await res.arrayBuffer()
fs.writeFileSync('guia.pdf', Buffer.from(buffer))


// Mostrar en navegador (Next.js route handler → iframe)
export async function GET(request, { params }) {
  const res = await fetch(
    `https://api.tpcxpress.com/api/v1/guias/${params.numeroGuia}/pdf`,
    { headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` } }
  )
 
  if (!res.ok) {
    return new Response('PDF no encontrado', { status: 404 })
  }
 
  const pdf = await res.arrayBuffer()
  return new Response(pdf, {
    headers: {
      'Content-Type': 'application/pdf',
      'Content-Disposition': `inline; filename="${params.numeroGuia}.pdf"`,
    },
  })
}


# Python — descargar PDF
import httpx
 
response = httpx.get(
    f"https://api.tpcxpress.com/api/v1/guias/{numero_guia}/pdf",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
response.raise_for_status()
 
with open(f"{numero_guia}.pdf", "wb") as f:
    f.write(response.content)

pdfUrl vs. endpoint PDF

Al crear una guía (POST /guias o POST /guias/batch), la respuesta incluye un campo pdfUrl:


{
  "data": {
    "numeroGuia": "TPCE123456789",
    "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCE123456789/pdf"
  }
}

	`pdfUrl` de la respuesta	`GET /guias/{numeroGuia}/pdf`
Autenticación	Requiere Bearer Token	Requiere Bearer Token
Uso típico	Construye la URL directamente desde la respuesta	Llama al endpoint directamente con tu token
Formato	URL al mismo endpoint	Binario PDF directo

pdfUrl es simplemente la URL completa al mismo endpoint. Úsala cuando quieras construir un link de descarga sin concatenar strings.

Contenido del PDF

El PDF generado incluye:

Código QR con el número de guía para escaneo rápido
Número de guía en grande (código de barras)
Tipo de servicio (ESTÁNDAR o COD)
Monto a cobrar (solo guías COD, en Quetzales)
Nombre, teléfono y dirección del destinatario
Instrucciones de entrega (obsDestinatario)
Nombre, teléfono y dirección del remitente
Fecha y hora de creación
Logo de la empresa de origen

Errores

HTTP	Código	Causa
`401`	`AUTH_REQUIRED`	Token ausente o inválido
`404`	`NOT_FOUND`	Guía no encontrada o pertenece a otra empresa