Ressources

Imports

Chaque point de terminaison Imports, avec la portée qu'il impose, le corps qu'il accepte, une réponse lisible et les refus qu'il peut renvoyer.

Lancer un import en masse asynchrone.

post/organizations/{organization}/imports
Portée
passports:write
Idempotency-Key
Accepté
Renvoie
202

Paramètres de chemin

organizationstringObligatoire

L'organisation pour laquelle cette requête agit. La clé doit disposer d'une autorisation sur celle-ci.

Corps de la requête

rowsarray of objectsObligatoire

De 1 à 500 lignes. Dépasser ce plafond est refusé par une règle max_rows qui lui est propre : c'est sur ce refus qu'une boucle de découpage en lots s'aiguille. Une clé non reconnue, où qu'elle se trouve dans une ligne, est une erreur et non un champ discrètement ignoré.

categorystringObligatoire

Un identifiant de catégorie issu de GET /categories.

dataobjectObligatoire

Le document du passeport, exactement tel que POST /passports l'attend.

external_idstringFacultatif

Votre identifiant pour la ligne. Il est repris tel quel dans le résultat par ligne, ce qui permet de rapprocher une ligne en échec.

Erreurs

Tous les refus que ce point de terminaison peut renvoyer, avec le statut qui les accompagne.

Requête
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "external_id": "SKU-4471-BLK",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck",
        "manufacturer_country": "FR"
      }
    },
    {
      "external_id": "SKU-4471-NVY",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck Navy",
        "manufacturer_country": "FR"
      }
    }
  ]
}'
Réponse · 202
{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "queued",
  "total_rows": 2,
  "succeeded_rows": 0,
  "failed_rows": 0,
  "pending_rows": 2,
  "attempts": 0,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": null,
  "completed_at": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports

Lister les tâches d’import.

get/organizations/{organization}/imports
Portée
passports:read
Idempotency-Key
Non accepté
Renvoie
200

Paramètres de chemin

organizationstringObligatoire

L'organisation pour laquelle cette requête agit. La clé doit disposer d'une autorisation sur celle-ci.

Paramètres de requête

limitstringFacultatif

Le nombre d'enregistrements à renvoyer. Le serveur peut en renvoyer moins.

cursorstringFacultatif

Le next_cursor de la page précédente. Un curseur encode les filtres sous lesquels il a été émis ; l'envoyer avec d'autres filtres est refusé par cursor_invalid.

statusstringFacultatif

Ne renvoyer que les tâches dans ce statut.

Erreurs

Tous les refus que ce point de terminaison peut renvoyer, avec le statut qui les accompagne.

Requête
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Réponse · 200
{
  "object": "list",
  "data": [
    {
      "object": "import_job",
      "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "status": "completed",
      "total_rows": 2,
      "succeeded_rows": 1,
      "failed_rows": 1,
      "pending_rows": 0,
      "attempts": 1,
      "created_at": "2026-08-02T09:50:00.114Z",
      "started_at": "2026-08-02T09:50:03.902Z",
      "completed_at": "2026-08-02T09:50:05.441Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed

Récupérer une tâche d’import et son avancement.

get/organizations/{organization}/imports/{id}
Portée
passports:read
Idempotency-Key
Non accepté
Renvoie
200

Paramètres de chemin

organizationstringObligatoire

L'organisation pour laquelle cette requête agit. La clé doit disposer d'une autorisation sur celle-ci.

idstringObligatoire

L'identifiant de la ressource. Traitez-le comme une chaîne opaque.

Paramètres de requête

row_limitstringFacultatif

Le nombre de résultats par ligne à joindre à la tâche.

after_row_indexstringFacultatif

Ne renvoyer que les résultats situés après cet index de ligne, afin de parcourir une tâche volumineuse en plusieurs fois.

Erreurs

Tous les refus que ce point de terminaison peut renvoyer, avec le statut qui les accompagne.

Requête
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Réponse · 200
{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "completed",
  "total_rows": 2,
  "succeeded_rows": 1,
  "failed_rows": 1,
  "pending_rows": 0,
  "attempts": 1,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": "2026-08-02T09:50:03.902Z",
  "completed_at": "2026-08-02T09:50:05.441Z",
  "rows": {
    "object": "list",
    "data": [
      {
        "object": "import_row",
        "row_index": 0,
        "external_id": "SKU-4471-BLK",
        "status": "succeeded",
        "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "passport_name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "error": null,
        "processed_at": "2026-08-02T09:50:04.771Z"
      },
      {
        "object": "import_row",
        "row_index": 1,
        "external_id": "SKU-4471-NVY",
        "status": "failed",
        "passport_id": null,
        "passport_name": null,
        "error": {
          "code": "unknown_category",
          "detail": null
        },
        "processed_at": "2026-08-02T09:50:05.180Z"
      }
    ],
    "has_more": false,
    "next_after_row_index": null
  }
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50

Imports — référence de l’API PassportCraft | PassportCraft