Feuilles de calcul

Convertissez les liens de l'ensemble d'une feuille Google ou d'un classeur téléversé avec le jeton bearer de votre compte. La sortie est toujours au format .xlsx, même pour une entrée CSV. Les liens sont remplacés sur place, avec l'attribution de votre compte et les valeurs facultatives campaign et label décrites dans Liens.

Entrée Google SheetsCopier le lien de la section

Envoyez une URL Google Sheets que NinjaBuy peut lire. La conversion lit tous les onglets, pas seulement l'aperçu affiché, et fige un instantané pour cette tâche.

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

Entrée XLSX ou CSVCopier le lien de la section

Réservez d'abord un téléversement. filename doit se terminer par .xlsx ou .csv et contenir de 1 à 255 caractères après suppression des espaces aux extrémités. bytes est la taille exacte du fichier en octets, de 1 à 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 réponse 201 contient upload_id, une url signée pour PUT, expires_at (millisecondes depuis le début de l'époque Unix), max_bytes et request_id. La réservation expire après 15 minutes. Envoyez le fichier brut par PUT à l'URL reçue, puis soumettez son identifiant de téléversement :

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

Le PUT direct utilise le contrat de réponse du service de stockage. NinjaBuy valide les octets téléversés lors de la soumission de la conversion. Les identifiants inconnus ou appartenant à d'autres comptes renvoient 404. L'objet stocké doit correspondre au nombre d'octets déclaré ; un objet dont la taille dépasse la taille déclarée ou le maximum renvoie 413 upload-too-large, et un objet plus petit (tronqué) renvoie 422 invalid-workbook avec une explication de l'écart du nombre d'octets. Ces vérifications ont lieu avant le téléchargement et s'appliquent aussi si les octets changent après la vérification des métadonnées. Les fichiers bruts des téléversements refusés sont supprimés, et ceux des téléversements acceptés sont supprimés une fois leur instantané validé enregistré.

Envoyez exactement une source : url ou upload_id. Les deux acceptent campaign et label facultatifs ; aucun champ async n'est nécessaire. Les deux routes POST acceptent Idempotency-Key et consomment chacune une place dans la fenêtre de création partagée de 30 appels par minute. Les conversions de liens dérivées ne consomment aucune place supplémentaire.

Tâche et téléchargementCopier le lien de la section

La soumission d'une feuille renvoie 202 avec Location: /api/v1/jobs/JOB_ID, Retry-After: 5 et ce corps :

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

Interrogez Tâches avec le jeton du même compte jusqu'à done ou failed, en respectant poll_after_seconds. Un job.result terminé contient kind: "sheet_conversion", counts et une download_url signée valable 15 minutes. Interrogez à nouveau pour obtenir une nouvelle signature de téléchargement. Une tâche ayant échoué contient error et ne propose aucun téléchargement partiel.

Pour une feuille Google, job.result peut aussi contenir copy_url, un lien en lecture seule vers une copie Google Sheets exacte avec vos liens à leur place ; toute personne disposant du lien peut en garder sa propre copie via Fichier → Créer une copie. copy_notes indique ce que le lecteur de cette copie doit savoir, par exemple que les images créées avec =IMAGE() demandent un clic sur Autoriser l'accès dans sa copie. download_url renvoie toujours le fichier XLSX. copy_counts donne les mêmes compteurs pour la copie ; si le fichier XLSX ne peut pas être produit, le résultat garde copy_url, n'a pas de download_url et copy_notes en donne la raison. download_notes indique, ligne par ligne, ce que le fichier XLSX ne peut pas contenir de la feuille, comme des graphiques ou un deuxième lien dans une cellule.

Les instantanés et les fichiers de résultats sont conservés pendant sept jours après la fin ou l'échec de la tâche. Après le nettoyage, la tâche reste consultable avec son statut et ses compteurs, et job.result.download_url est omis. Les instantanés partagés sont conservés tant qu'une autre tâche en a encore besoin. Les fichiers bruts des téléversements abandonnés sont supprimés une heure après l'expiration de la réservation de téléversement ; un téléversement validé qui ne lance jamais de tâche perd son instantané sept jours après l'expiration de la réservation. Le nettoyage s'exécute toutes les heures.

La couverture respecte links_found = converted + sum(left_by_host) + unresolved. Les liens sociaux, les liens Google Sheets, la navigation dans le même classeur et les liens NinjaBuy existants restent inchangés. Chaque candidat à la conversion doit recevoir une réponse avant l'écriture du résultat ; les réponses manquantes font échouer la tâche.

Conservation du classeurCopier le lien de la section

Le résultat conserve les styles, les cellules fusionnées, les dimensions des lignes et colonnes et les images tels que représentés par la grille analysée. Les segments de texte enrichi sont conservés dans les cellules sans lien hypertexte de cellule ; les cellules avec lien utilisent un seul libellé de texte et un lien hypertexte. Le classeur est sérialisé à nouveau : les graphiques, macros et autres fonctions extérieures à cette grille ne sont pas conservés.

XLSX accepte un seul lien hypertexte par cellule. La conversion remplace les liens sur place au lieu d'ajouter un second lien à côté. Une cellule comportant deux cibles de liens différentes ou plus, autres que des images, garde la première comme lien hypertexte et liste les autres dans la note de la cellule : aucune cible n'est perdue.

LimitesCopier le lien de la section

Le dépassement d'une limite d'analyse ou d'écriture provoque un échec explicite. Consultez Erreurs pour invalid-workbook, upload-expired et upload-too-large.