Risorse

Importazioni

Tutti gli endpoint Importazioni, con l'ambito che impongono, il corpo che accettano, una risposta leggibile e i rifiuti che possono restituire.

Avviare un’importazione massiva asincrona.

post/organizations/{organization}/imports
Ambito
passports:write
Idempotency-Key
Accettata
Restituisce
202

Parametri di percorso

organizationstringObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

Corpo della richiesta

rowsarray of objectsObbligatorio

Da 1 a 500 righe. Superare il tetto viene rifiutato con una regola max_rows dedicata, ed è su quel rifiuto che ramifica un ciclo di suddivisione in lotti. Una chiave non riconosciuta in un punto qualsiasi di una riga è un errore, non un campo scartato in silenzio.

categorystringObbligatorio

Un id di categoria fra quelli di GET /categories.

dataobjectObbligatorio

Il documento del passaporto, esattamente nella forma che accetta POST /passports.

external_idstringFacoltativo

Il Suo identificativo per la riga. Viene restituito nel risultato di quella riga: è così che si riconcilia una riga fallita.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
      }
    }
  ]
}'
Risposta · 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

Elencare i lavori di importazione.

get/organizations/{organization}/imports
Ambito
passports:read
Idempotency-Key
Non accettata
Restituisce
200

Parametri di percorso

organizationstringObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

Parametri di query

limitstringFacoltativo

Quanti record restituire. Il server può restituirne meno.

cursorstringFacoltativo

Il next_cursor della pagina precedente. Un cursore codifica i filtri con cui è stato emesso; inviarlo con filtri diversi viene rifiutato con cursor_invalid.

statusstringFacoltativo

Restituisce solo i lavori in questo stato.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Risposta · 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

Recuperare un lavoro di importazione e il suo avanzamento.

get/organizations/{organization}/imports/{id}
Ambito
passports:read
Idempotency-Key
Non accettata
Restituisce
200

Parametri di percorso

organizationstringObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Parametri di query

row_limitstringFacoltativo

Quanti risultati per singola riga includere insieme al lavoro.

after_row_indexstringFacoltativo

Restituisce i risultati per riga successivi a questo indice di riga, così da poter percorrere un lavoro di grandi dimensioni.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
Risposta · 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

Importazioni — riferimento dell'API di PassportCraft | PassportCraft