BoxLatviaIzstrādātājiem
Pieprasīt piekļuvi
Pamācības

Imports no Excel

Labāk tabula nekā izsaukumi? Aizpildiet Excel failu, nosūtiet to uz API, un jūsu lokācijas, telpas un attēli tiek izveidoti vai atjaunināti vienā reizē. Šo pašu failu var sūtīt atkal, kad kaut kas mainās.

#Kā tas darbojas

  1. #Lejupielādējiet šablonus

    Viens fails katram veidam. Tajā ir kolonnu nosaukumi, nolaižamie saraksti, instrukcija, piemēru lapa un kodu saraksti.

  2. #Aizpildiet lapu Dati

    Viena rinda katrai lokācijai, telpai vai attēlam. Saglabājiet kolonnu nosaukumus pirmajā rindā. Atstājiet šūnu tukšu, lai šī vērtība paliktu nemainīta. Importējiet šādā secībā: lokācijas, tad telpas, tad attēli, jo telpai vajadzīga tās lokācija, bet attēlam — tā telpa.

  3. #Vispirms pārbaudiet

    Nosūtiet failu ar ?validate_only=true. Tiek izpildītas visas pārbaudes, nekas netiek saglabāts, un atbildē ir redzams, kas notiktu ar katru rindu un visas tajā esošās problēmas.

    Faila pārbaude
    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)"
            }
          ]
        }
      ]
    }
  4. #Nosūtiet

    Tas pats pieprasījums bez ?validate_only=true. Izlabojiet rindas, kas neizdevās, un nosūtiet failu vēlreiz: rindas, kas jau ir pareizas, tiek atrastas kā nemainītas.

    Imports
    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"
            }
          ]
        }
      ]
    }

#Kolonnas

Kolonnu nosaukumi ir paša API lauku nosaukumi, tāpēc kolonna šeit nozīmē to pašu, kas telpu, lokāciju un attēlu atsaucē. Kodi nāk no atsauces datiem, un tie ir uzskaitīti šablona lapā Kodi.

#Lokācijas

KolonnaTipsApraksts
external_idtekstsvienmēr. Jūsu pašu lokācijas identifikators (līdz 100 rakstzīmēm). Tas nosaka, vai rinda izveido jaunu lokāciju vai atjaunina esošu.
nametekstsjaunam ierakstam. Lokācijas nosaukums, līdz 100 rakstzīmēm. Obligāts jaunai lokācijai.
descriptiontekstsApraksts, līdz 250 rakstzīmēm.
addresstekstsAdrese, līdz 250 rakstzīmēm.
districttekstsRajona kods no lapas Kodi.
latitudeskaitlisĢeogrāfiskais platums, skaitlis no -90 līdz 90. Norādiet kopā ar garumu.
longitudeskaitlisĢeogrāfiskais garums, skaitlis no -180 līdz 180. Norādiet kopā ar platumu.
featureskodi, atdalīti ar komatiemĒrtību kodi no lapas Kodi, atdalīti ar komatiem. Aizvieto visu kopu. Lai klienti lokāciju varētu atrast, vajadzīgas vismaz 5.

#Telpas

KolonnaTipsApraksts
external_idtekstsvienmēr. Jūsu pašu telpas identifikators (līdz 100 rakstzīmēm). Tas nosaka, vai rinda izveido jaunu telpu vai atjaunina esošu.
nametekstsjaunam ierakstam. Telpas nosaukums, līdz 255 rakstzīmēm. Obligāts jaunai telpai.
location_external_idtekstsjaunam ierakstam. Lokācijas external_id, kurā telpa atrodas. Obligāts jaunai telpai. Lokācijai jau jāeksistē (vispirms importējiet lokācijas).
descriptiontekstsApraksts, līdz 255 rakstzīmēm.
priceskaitlisCena par periodu, lielāka par 0, ne vairāk kā 2 decimālzīmes.
promotional_priceskaitlisAkcijas cena. Jābūt zemākai par price.
price_period_1skaitlisNeobligāta fiksēta kopsumma par 1 perioda nomu.
price_period_3skaitlisNeobligāta fiksēta kopsumma par 3 periodu nomu.
price_period_6skaitlisNeobligāta fiksēta kopsumma par 6 periodu nomu.
price_period_12skaitlisNeobligāta fiksēta kopsumma par 12 periodu nomu.
price_unittekstsCenas mērvienības kods no lapas Kodi (mēnesī, nedēļā).
sizeskaitlisPlatība m², lielāka par 0.
size_lengthskaitlisIekšējais garums metros.
size_widthskaitlisIekšējais platums metros.
size_heightskaitlisIekšējais augstums metros.
door_widthskaitlisDurvju platums metros.
door_heightskaitlisDurvju augstums metros.
total_unitsvesels skaitlisCik identisku telpu jums ir, vesels skaitlis, 0 vai vairāk.
available_unitsvesels skaitlisCik telpu šobrīd ir brīvas. Nevar pārsniegt total_units.
max_advance_daysvesels skaitlisCik dienas uz priekšu klients drīkst rezervēt, no 1 līdz 730.
featureskodi, atdalīti ar komatiemĒrtību kodi no lapas Kodi, atdalīti ar komatiem. Aizvieto visu kopu.

#Attēli

KolonnaTipsApraksts
ownertekstsvienmēr. Kam attēls pieder: box (telpa) vai location (lokācija).
external_idtekstsvienmēr. Šīs telpas vai lokācijas external_id. Tai jau jāeksistē.
picture_urltekstsvienmēr. Attēla faila publiskā adrese (https): JPEG, PNG, WebP vai GIF, līdz 5 MB. BoxLatvia to lejupielādē un saglabā savu kopiju.

#Noteikumi, ko zināt

#Attēli

Attēla rindā norāda owner (box vai location), tā external_id un attēla adresi (https). BoxLatvia attēlu lejupielādē un glabā savu kopiju, tāpēc jūsu fails nav jāatstāj pieejams.

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"
        }
      ]
    }
  ]
}

#Atbildes izlasīšana

Atbilde ir 200, kad vien failu bija iespējams nolasīt, pat ja dažas rindas neizdevās. Skatiet summary kopsummām un katru rows ierakstu:

StatussNozīme
createdIzveidots jauns ieraksts (attēliem: attēls pievienots).
updatedEsošs ieraksts mainīts.
unchangedNav ko mainīt: rindā nebija vērtību vai attēls jau bija.
failedRinda netika saglabāta; errors uzskaita visas problēmas kā { field, message }.
would_create / would_updateTikai ar validate_only: kas notiktu.

row ir rindas numurs, kā to rāda Excel (galvene ir 1. rinda), tāpēc varat uzreiz atrast šūnu. Problēma ar visu failu ir 422:

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"
    }
  ]
}
Padoms
Pēc labošanas nosūtiet failu vēlreiz: rindas, kas jau tika saglabātas, tiek atrastas kā nemainītas, tāpēc imports ir droši atkārtojams. Izmantojiet Idempotency-Key, ja pieprasījumam varētu būt beidzies gaidīšanas laiks.

#Ierobežojumi

IerobežojumsVērtība
Rindas failā500 lokācijām un telpām, 50 attēliem
Faila izmērs10 MB
Kolonnas60
Teksts šūnā5000 rakstzīmes (lauku ierobežojumi ir zemāki)

Vajadzīgas tiesības imports:write, kas ļauj ar piekļuves datiem izveidot un mainīt lokācijas, telpas un attēlus, izmantojot failus. BoxLatvia tās piešķir pēc pieprasījuma: pieprasīt piekļuvi.