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, tipo de servicio y monto (para guías COD).

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

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"
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