Batch — Creación masiva de guías

POST`/api/v1/guias/batch`

Crea hasta 50 guías en una sola operación atómica. Si cualquier guía del lote falla validación o hay un error de base de datos, ninguna guía se crea (rollback total).

Cuándo usar batch vs. individual

Escenario	Recomendación
1–5 guías	`POST /api/v1/guias` individual
6–50 guías (misma operación)	`POST /api/v1/guias/batch`
Más de 50 guías	Dividir en múltiples lotes de ≤ 50

Batch es más eficiente porque:

Usa una sola transacción de base de datos para todo el lote
Consume un solo request contra el rate limit de 100 req/min
Reserva todos los créditos al inicio para evitar situaciones de crédito parcial
Precarga los costos de todos los municipios en una sola consulta (sin N+1)

Body


{
  "guias": [
    {
      "tipoServicio": "ESTANDAR",
      "ciudadDestino": "Mixco",
      "nombreDestinatario": "Ana García",
      "telefonoDestinatario": "55554321",
      "direccionDestinatario": "8va Avenida 12-34 zona 11"
    },
    {
      "tipoServicio": "COD",
      "ciudadDestino": "Villa Nueva",
      "nombreDestinatario": "Carlos López",
      "telefonoDestinatario": "55559876",
      "direccionDestinatario": "10ma Calle 5-66 zona 3",
      "costoProducto": 450.00
    }
  ]
}

Cada ítem del array acepta exactamente los mismos campos que POST /api/v1/guias. Ver CRUD de Guías para el detalle completo de campos.

Restricciones del array guias:

Mínimo: 1 guía
Máximo: 50 guías por request

Ejemplo completo

curl


curl -X POST https://api.tpcxpress.com/api/v1/guias/batch \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guias": [
      {
        "tipoServicio": "ESTANDAR",
        "ciudadDestino": "Mixco",
        "nombreDestinatario": "Ana García",
        "telefonoDestinatario": "55554321",
        "direccionDestinatario": "8va Avenida 12-34 zona 11",
        "obsDestinatario": "Llamar antes de llegar"
      },
      {
        "tipoServicio": "ESTANDAR",
        "ciudadDestino": "Guatemala",
        "nombreDestinatario": "Pedro Ruiz",
        "telefonoDestinatario": "55557890",
        "direccionDestinatario": "5ta Avenida 20-10 zona 1"
      },
      {
        "tipoServicio": "COD",
        "ciudadDestino": "Villa Nueva",
        "nombreDestinatario": "María López",
        "telefonoDestinatario": "55556543",
        "direccionDestinatario": "10ma Calle 5-66 zona 3",
        "costoProducto": 299.99
      }
    ]
  }'

JavaScript


const res = await fetch('https://api.tpcxpress.com/api/v1/guias/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TPC_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    guias: [
      {
        tipoServicio: 'ESTANDAR',
        ciudadDestino: 'Mixco',
        nombreDestinatario: 'Ana García',
        telefonoDestinatario: '55554321',
        direccionDestinatario: '8va Avenida 12-34 zona 11',
        obsDestinatario: 'Llamar antes de llegar',
      },
      {
        tipoServicio: 'ESTANDAR',
        ciudadDestino: 'Guatemala',
        nombreDestinatario: 'Pedro Ruiz',
        telefonoDestinatario: '55557890',
        direccionDestinatario: '5ta Avenida 20-10 zona 1',
      },
      {
        tipoServicio: 'COD',
        ciudadDestino: 'Villa Nueva',
        nombreDestinatario: 'María López',
        telefonoDestinatario: '55556543',
        direccionDestinatario: '10ma Calle 5-66 zona 3',
        costoProducto: 299.99,
      },
    ],
  }),
})
const { data } = await res.json()
// data.created === 3
// data.guias[0].numeroGuia, data.guias[0].pdfUrl

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.post("/guias/batch", json={
    "guias": [
        {
            "tipoServicio": "ESTANDAR",
            "ciudadDestino": "Mixco",
            "nombreDestinatario": "Ana García",
            "telefonoDestinatario": "55554321",
            "direccionDestinatario": "8va Avenida 12-34 zona 11",
            "obsDestinatario": "Llamar antes de llegar",
        },
        {
            "tipoServicio": "ESTANDAR",
            "ciudadDestino": "Guatemala",
            "nombreDestinatario": "Pedro Ruiz",
            "telefonoDestinatario": "55557890",
            "direccionDestinatario": "5ta Avenida 20-10 zona 1",
        },
        {
            "tipoServicio": "COD",
            "ciudadDestino": "Villa Nueva",
            "nombreDestinatario": "María López",
            "telefonoDestinatario": "55556543",
            "direccionDestinatario": "10ma Calle 5-66 zona 3",
            "costoProducto": 299.99,
        },
    ]
})
data = r.raise_for_status().json()["data"]
# data["created"] == 3

Respuesta 201


{
  "success": true,
  "data": {
    "created": 3,
    "guias": [
      {
        "numeroGuia": "TPCE111222333",
        "estado": "SIN_RECOLLECTAR",
        "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCE111222333/pdf"
      },
      {
        "numeroGuia": "TPCE111222334",
        "estado": "SIN_RECOLLECTAR",
        "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCE111222334/pdf"
      },
      {
        "numeroGuia": "TPCP111222335",
        "estado": "SIN_RECOLLECTAR",
        "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCP111222335/pdf"
      }
    ]
  }
}

El orden del array guias en la respuesta corresponde al orden enviado en el request.

Comportamiento ante errores

Situación	Código	Efecto
Validación falla en ítem N	`400 VALIDATION_ERROR`	Ninguna guía creada
Array vacío o más de 50	`400 VALIDATION_ERROR`	Ninguna guía creada
Lote supera límite diario de la cuenta	`429 DAILY_GUIDE_LIMIT`	Ninguna guía creada
Sin créditos suficientes	`402 PAYMENT_REQUIRED`	Ninguna guía creada
Error interno de base de datos	`500 INTERNAL_ERROR`	Rollback total, ninguna creada

Error de validación — ejemplo


{
  "success": false,
  "error": {
    "message": "[{\"path\":[\"guias\",1,\"costoProducto\"],\"message\":\"costoProducto es requerido para guías COD.\"}]",
    "code": "VALIDATION_ERROR"
  }
}

El mensaje indica el índice del ítem con error (guias[1]).

Rate limit y créditos

El sistema verifica antes de iniciar la transacción:

Que el lote completo cabe dentro del límite diario de tu cuenta (por defecto 500/día — contacta a TPC para aumentarlo)
Que la empresa tiene créditos suficientes para todas las guías del lote
Reserva todos los créditos de forma atómica (evita sobreconsumo por requests concurrentes)

Si quedan 10 créditos y envías un lote de 20 guías → 402 PAYMENT_REQUIRED, ninguna guía creada.

Webhooks en batch

Tras crear el lote, TPC dispara el evento GUIA_CREADA por cada guía de forma asíncrona (no bloquea la respuesta). Si tienes webhooks configurados, recibirás N notificaciones, una por guía.