POST /api/v1/links/bulk
Envía un array items o links con un máximo de 100 entradas.
Guía para desarrolladores
Crea enlaces cortos por lotes con la API de tt.vg
Usa el endpoint de producción, gestiona éxitos parciales, reutiliza claves de idempotencia y conecta eventos con Webhooks.
links:bulk:create
La clave API debe incluir el permiso de creación por lotes.
Idempotency-Key
Reutiliza el mismo UUID al reintentar el mismo lote para evitar duplicados.
Copia y adapta
Ejemplos en curl, JavaScript y Python
Sustituye la clave API y los destinos. Cada elemento admite los campos de la API individual.
curl -X POST https://tt.vg/api/v1/links/bulk \
-H "Authorization: Bearer ttvg_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"items": [
{ "destinationUrl": "https://example.com/a", "description": "Campaign A" },
{ "destinationUrl": "https://example.com/b", "key": "campaign-b" }
]
}'Gestión de respuestas
Procesa cada resultado por separado
Un lote puede contener enlaces creados y errores. Guarda el índice devuelto junto a tu entrada.
Todos los elementos correctos
Lee items y summary; errors está vacío.
Éxito parcial
Guarda los elementos correctos y reintenta solo las entradas fallidas.
Error de solicitud o acceso
Corrige validación, autenticación, verificación de correo o permisos.
Cuota o límite de frecuencia
Detén el lote y espera; respeta Retry-After cuando esté presente.
Fallo temporal del servidor
Reintenta con espera exponencial y la misma Idempotency-Key.
Cuotas y límites del lote
Cada solicitud admite hasta 100 enlaces. Cada creación correcta consume una unidad diaria links:create del plan; los fallos no.
Continúa con Webhooks
Suscríbete a link.created, link.updated o link.clicked. La entrega firmada es asíncrona y se reintenta sin bloquear la API.
Preguntas frecuentes
Preguntas sobre la API por lotes
¿La creación por lotes es todo o nada?
No. Unos elementos pueden tener éxito y otros devolver errores con índice; los resultados mixtos usan HTTP 207.
¿Qué ocurre si se agota la cuota a mitad del lote?
El elemento actual y los restantes reciben un error 429 y el proceso se detiene.
¿Cómo evito duplicados al reintentar?
Envía una Idempotency-Key aleatoria y reutilízala solo para reintentos del mismo lote.