BoxLatviaIzstrādātājiem
Pieprasīt piekļuvi
API atsauce

Imports

Nosūtiet Excel vai CSV failu; katra rinda izveido vai atjaunina lokāciju, telpu vai attēlu. Viss par failu aizpildīšanu ir importa pamācībā.

#Importa pārskats

NosaukumsTipsApraksts
kindstringlocations, boxes vai pictures.
validate_onlybooleantrue, ja fails tika tikai pārbaudīts.
summaryobject{ total, created, updated, unchanged, failed }. Attēliem created skaita pievienotos attēlus.
rowsobject[]Viens ieraksts katrai datu rindai: row (kā to rāda Excel), external_id, status, ieraksta id un errors neizdevušai rindai.

#Galapunkts

#Importēt failu

POST/v1/imports/{kind}imports:write

Izveido vai atjaunina lokācijas, telpas vai attēlus no Excel (.xlsx) vai CSV faila, katrai rindai vienu ierakstu. Atbilde parāda, kas notika ar katru rindu.

  • Sāciet ar attiecīgā veida šablonu: tā kolonnas ir tās, ko imports lasa.
  • Rindas external_id (jūsu pašu identifikators) lemj: ja tāds ir, rinda to atjaunina, tukša šūna atstāj vērtību nemainītu; ja tāda nav, rinda to izveido.
  • Rindas ir neatkarīgas. Rinda, kas neizdodas, neaptur pārējās, un atbildē ir visas tās problēmas uzreiz.
  • ?validate_only=true izpilda visas pārbaudes, lejupielādē attēlus un neko nesaglabā: izmantojiet to pirms īstā importa.
  • Līdz 500 rindām failā lokācijām un telpām, 50 attēliem. Lielākus failus sadaliet.

Ceļa parametri

NosaukumsTipsApraksts
kindstringlocations, boxes vai pictures.

Vaicājuma parametri

NosaukumsTipsApraksts
validate_onlybooleantrue: pārbaudīt visu un neko nesaglabāt. Statusi tad ir would_create / would_update.

Galvenes

NosaukumsTipsApraksts
Idempotency-KeystringNeobligāta. Atkārtots pieprasījums ar to pašu atslēgu atgriež pirmo atbildi, nevis importē vēlreiz.

Pieprasījuma saturs (multipart/form-data)

NosaukumsTipsApraksts
file obligātsfileViens .xlsx vai .csv fails. Tiek lasīta lapa ar nosaukumu Data (vai Dati), vai pirmā lapa.

Piemēri

Vispirms pārbaudiet lokāciju failu

Nekas netiek saglabāts: statusi parāda, kas notiktu, un tiek uzskaitītas visas katras rindas problēmas.

curl -X POST "$API/v1/imports/locations?validate_only=true" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-locations.xlsx"
200 OKX-Validate-Only: true
{
  "kind": "locations",
  "validate_only": true,
  "summary": {
    "total": 3,
    "created": 1,
    "updated": 1,
    "unchanged": 0,
    "failed": 1
  },
  "rows": [
    {
      "row": 2,
      "external_id": "WH-IMANTA",
      "status": "would_update",
      "id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
    },
    {
      "row": 3,
      "external_id": "WH-KENGARAGS",
      "status": "would_create"
    },
    {
      "row": 4,
      "external_id": "WH-NOWHERE",
      "status": "failed",
      "errors": [
        {
          "field": "district",
          "message": "\"atlantis\" is not a known district code (see the Codes sheet)"
        }
      ]
    }
  ]
}
Lokāciju imports
curl -X POST "$API/v1/imports/locations" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-locations.xlsx"
200 OK
{
  "kind": "locations",
  "validate_only": false,
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 1,
    "unchanged": 0,
    "failed": 0
  },
  "rows": [
    {
      "row": 2,
      "external_id": "WH-IMANTA",
      "status": "updated",
      "id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
    },
    {
      "row": 3,
      "external_id": "WH-KENGARAGS",
      "status": "created",
      "id": "3f502d49-40f5-43e8-8004-dc4bb2f28a99"
    }
  ]
}
Telpas: viena atjaunināta, viena izveidota, viena ar problēmām

Pirmā rinda sūta tikai available_units: pieejamības atjauninājums. Viss pārējais šai telpai paliek.

curl -X POST "$API/v1/imports/boxes" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-boxes.xlsx"
200 OK
{
  "kind": "boxes",
  "validate_only": false,
  "summary": {
    "total": 3,
    "created": 1,
    "updated": 1,
    "unchanged": 0,
    "failed": 1
  },
  "rows": [
    {
      "row": 2,
      "external_id": "SKU-3M",
      "status": "updated",
      "id": "c4883b4a-4e38-47bf-8a69-ef025917e022"
    },
    {
      "row": 3,
      "external_id": "SKU-8M",
      "status": "created",
      "id": "e8e189c3-3ac4-47d0-8ff1-584221c4e1ae"
    },
    {
      "row": 4,
      "external_id": "SKU-9M",
      "status": "failed",
      "errors": [
        {
          "field": "price_unit",
          "message": "\"gadsimts\" is not a known price unit code (see the Codes sheet)"
        },
        {
          "field": "price",
          "message": "must have at most 2 decimals"
        }
      ]
    }
  ]
}
Attēli pēc adreses
curl -X POST "$API/v1/imports/pictures" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-pictures.xlsx"
200 OK
{
  "kind": "pictures",
  "validate_only": false,
  "summary": {
    "total": 3,
    "created": 2,
    "updated": 0,
    "unchanged": 0,
    "failed": 1
  },
  "rows": [
    {
      "row": 2,
      "external_id": "WH-IMANTA",
      "status": "created",
      "id": "734e0d86-9a60-4107-9997-c9f0bcf77610"
    },
    {
      "row": 3,
      "external_id": "SKU-3M",
      "status": "created",
      "id": "d504c7e6-8458-456a-884d-0b4ba02be2d3"
    },
    {
      "row": 4,
      "external_id": "SKU-3M",
      "status": "failed",
      "errors": [
        {
          "field": "picture_url",
          "message": "the address answered HTTP 404"
        }
      ]
    }
  ]
}
Fails, ko nevar izmantot
curl -X POST "$API/v1/imports/boxes" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-boxes.xlsx"
422 Unprocessable Content
{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "88b1f62d-3509-4d1f-b542-ff67a35787ae",
  "errors": [
    {
      "field": "columns",
      "message": "unknown column(s): nane, colour. The columns of this file are: external_id, name, location_external_id, description, price, promotional_price, price_period_1, price_period_3, price_period_6, price_period_12, price_unit, size, size_length, size_width, size_height, door_width, door_height, total_units, available_units, max_advance_days, features"
    }
  ]
}

Kļūdas

StatussKad
403Piekļuves datiem nav tiesību imports:write.
404kind nav locations, boxes vai pictures.
415Nav multipart/form-data, vai vecs .xls fails: saglabājiet to kā .xlsx vai .csv.
422Failu kopumā nevar izmantot: nezināmas vai trūkstošas kolonnas, nav datu rindu, pārāk daudz rindu, nav nolasāms. Problēmas ar atsevišķām rindām ir atbildē (statuss 200), nevis šeit.