Recursos

Importaciones

Todos los endpoints de Importaciones, con el ámbito que imponen, el cuerpo que admiten, una respuesta legible y los rechazos que pueden devolver.

Iniciar una importación masiva asíncrona.

post/organizations/{organization}/imports
Ámbito
passports:write
Idempotency-Key
Se acepta
Devuelve
202

Parámetros de ruta

organizationstringObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Cuerpo de la solicitud

rowsarray of objectsObligatorio

Entre 1 y 500 filas. Superar el tope se rechaza con su propia regla max_rows, que es el rechazo por el que ramifica un bucle de lotes. Una clave no reconocida en cualquier punto de una fila es un error, no un campo descartado en silencio.

categorystringObligatorio

Un id de categoría de GET /categories.

dataobjectObligatorio

El documento del pasaporte, exactamente como lo admite POST /passports.

external_idstringOpcional

Su identificador para la fila. Se devuelve tal cual en el resultado de esa fila, que es como se concilia una fila fallida.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
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"
      }
    }
  ]
}'
Respuesta · 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

Listar los trabajos de importación.

get/organizations/{organization}/imports
Ámbito
passports:read
Idempotency-Key
No se acepta
Devuelve
200

Parámetros de ruta

organizationstringObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Parámetros de consulta

limitstringOpcional

Cuántos registros devolver. El servidor puede devolver menos.

cursorstringOpcional

El next_cursor de la página anterior. Un cursor codifica los filtros con los que se emitió; enviarlo con otros filtros se rechaza con cursor_invalid.

statusstringOpcional

Devuelve solo los trabajos que estén en este estado.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

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

Obtener un trabajo de importación y su progreso.

get/organizations/{organization}/imports/{id}
Ámbito
passports:read
Idempotency-Key
No se acepta
Devuelve
200

Parámetros de ruta

organizationstringObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idstringObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Parámetros de consulta

row_limitstringOpcional

Cuántos resultados por fila incluir junto con el trabajo.

after_row_indexstringOpcional

Devuelve los resultados por fila posteriores a este índice de fila, de modo que un trabajo grande pueda recorrerse por partes.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
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"
Respuesta · 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

Importaciones — referencia de la API de PassportCraft | PassportCraft