Recursos

Unidades

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

Listar unidades serializadas.

get/organizations/{organization}/passports/{id}/units

Ámbito: units:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

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

idcadenaObligatorio

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

Parámetros de consulta

limitcadenaOpcional

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

cursorcadenaOpcional

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.

statuscadenaOpcional

Devuelve solo las unidades que estén en este estado.

unit_serialcadenaOpcional

Devuelve la única unidad que lleva este número de serie.

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/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z",
      "values": {
        "status": {
          "value": "original",
          "source": "brand_statement",
          "observed_on": "2026-08-02",
          "reading_id": "a1100000-0000-4000-8000-000000000001",
          "unit_added_on": null
        }
      },
      "missing_fields": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25

Crear unidades serializadas.

post/organizations/{organization}/passports/{id}/units

Ámbito: units:write
Idempotency-Key: Se acepta
Devuelve: 201

Parámetros de ruta

organizationcadenaObligatorio

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

idcadenaObligatorio

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

Cuerpo de la solicitud

unitslista de objetosObligatorio

Entre 1 y 1000 unidades. El pasaporte padre debe estar en la categoría battery: las unidades serializadas son un concepto de baterías, y cualquier otro pasaporte padre se rechaza con invalid_request. Un número de serie repetido dentro de una misma solicitud se rechaza fila por fila en lugar de deduplicarse, para que un importador masivo nunca dé por creada una fila que no llegó a crearse.

unit_serialcadenaObligatorio

El número de serie que lleva este artículo físico, hasta 70 caracteres. Único dentro del pasaporte.

statuscadenaOpcional

Estado opcional de la batería: original, repurposed, re-used, remanufactured o waste. Omítalo para crear una batería sin estado. Los demás valores se rechazan para todas las credenciales.

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/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "units": [
    {
      "unit_serial": "BAT-2026-000117",
      "status": "original"
    },
    {
      "unit_serial": "BAT-2026-000118"
    }
  ]
}'

Respuesta · 201

{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z",
      "values": {
        "status": {
          "value": "original",
          "source": "brand_statement",
          "observed_on": "2026-08-02",
          "reading_id": "a1100000-0000-4000-8000-000000000001",
          "unit_added_on": null
        }
      },
      "missing_fields": []
    },
    {
      "object": "unit",
      "id": "5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000118",
      "status": null,
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z",
      "values": {},
      "missing_fields": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units