Hojas de cálculo

Convierte enlaces en toda una hoja de Google o un libro subido con el token bearer de tu cuenta. El resultado siempre es .xlsx, incluso con una entrada CSV. Los enlaces se reemplazan en su lugar, con la atribución de tu cuenta y los valores opcionales campaign y label descritos en Enlaces.

Entrada de Google SheetsCopiar enlace a esta sección

Envía una URL de Google Sheets que NinjaBuy pueda leer. La conversión lee todas las pestañas, no solo la vista previa, y fija una instantánea para este trabajo.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

Entrada XLSX o CSVCopiar enlace a esta sección

Primero reserva una carga. filename debe terminar en .xlsx o .csv y tener de 1 a 255 caracteres después de recortar espacios. bytes es el tamaño exacto del archivo en bytes, de 1 a 20.971.520.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

La respuesta 201 contiene upload_id, una url firmada para PUT, expires_at (milisegundos desde el inicio de la época Unix), max_bytes y request_id. La reserva vence después de 15 minutos. Envía el archivo sin modificar con PUT a la URL recibida y luego envía su identificador de carga:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

El PUT directo usa el contrato de respuesta del servicio de almacenamiento. NinjaBuy valida los bytes subidos cuando envías la conversión. Los identificadores de carga desconocidos o de otras cuentas devuelven 404. El objeto almacenado debe coincidir con el número de bytes declarado; un objeto mayor que el tamaño declarado o el máximo devuelve 413 upload-too-large, y un objeto más pequeño (truncado) devuelve 422 invalid-workbook con la explicación de la discrepancia en el número de bytes. Estas comprobaciones se realizan antes de la descarga y también se aplican si los bytes cambian después de comprobar los metadatos. Los archivos originales de las cargas rechazadas se eliminan, y los de las cargas aceptadas se eliminan una vez que se registra su instantánea validada.

Envía exactamente una fuente: url o upload_id. Ambas aceptan campaign y label opcionales; no hace falta un campo async. Ambas rutas POST aceptan Idempotency-Key y cada una consume un espacio de la ventana de creación compartida de 30 llamadas por minuto. Las conversiones de enlaces derivadas no consumen espacios adicionales.

Trabajo y descargaCopiar enlace a esta sección

El envío de una hoja devuelve 202 con Location: /api/v1/jobs/JOB_ID, Retry-After: 5 y este cuerpo:

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

Consulta Trabajos con el token de la misma cuenta hasta llegar a done o failed, respetando poll_after_seconds. Un job.result completado tiene kind: "sheet_conversion", counts y una download_url firmada válida por 15 minutos. Consulta de nuevo para obtener una firma de descarga nueva. Un trabajo fallido tiene error y no ofrece una descarga parcial.

Para una hoja de Google, job.result también puede incluir copy_url, un enlace de solo lectura a una copia exacta en Google Sheets con tus enlaces en su lugar; quien tenga el enlace puede guardar su propia copia con Archivo → Hacer una copia. copy_notes indica lo que debe saber quien lea esa copia, por ejemplo que las imágenes creadas con =IMAGE() necesitan un clic en Permitir acceso en su copia. download_url sigue devolviendo el XLSX. copy_counts da los mismos conteos para la copia; si el XLSX no se puede generar, el resultado conserva copy_url, no trae download_url y copy_notes explica el motivo. download_notes indica, línea por línea, lo que el XLSX no puede guardar de la hoja, como gráficos o un segundo enlace en una celda.

Las instantáneas y los archivos de resultados se conservan durante siete días después de que el trabajo termine o falle. Tras la limpieza, el trabajo sigue disponible para consulta con su estado y sus conteos, y se omite job.result.download_url. Las instantáneas compartidas se conservan mientras otro trabajo las necesite. Los archivos originales de las cargas abandonadas se eliminan una hora después de que venza la reserva de carga; una carga validada que nunca inicia un trabajo pierde su instantánea siete días después del vencimiento de la reserva. La limpieza se ejecuta cada hora.

La cobertura cumple links_found = converted + sum(left_by_host) + unresolved. Los enlaces sociales, de Google Sheets, de navegación dentro del mismo libro y los enlaces existentes de NinjaBuy permanecen sin cambios. Cada candidato a conversión debe recibir una respuesta antes de escribir el resultado; las respuestas faltantes hacen que el trabajo falle.

Conservación del libroCopiar enlace a esta sección

El resultado conserva los estilos, las celdas combinadas, los tamaños de filas y columnas y las imágenes tal como los representa la cuadrícula analizada. Los segmentos de texto enriquecido se conservan en celdas sin un hipervínculo de celda; las celdas con enlace usan una sola etiqueta de texto y un hipervínculo. Es un libro serializado de nuevo: no se conservan gráficos, macros ni otras funciones ajenas a esa cuadrícula.

XLSX admite un hipervínculo por celda. La conversión reemplaza los enlaces en su lugar en vez de agregar un segundo enlace al lado. Una celda con dos o más destinos de enlace distintos que no sean imágenes conserva el primero como hipervínculo y enumera los demás en la nota de la celda, para no perder ningún destino.

LímitesCopiar enlace a esta sección

Superar un límite del analizador o del generador produce un fallo explícito. Consulta Errores para invalid-workbook, upload-expired y upload-too-large.