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
-
#Lejupielādējiet šablonus
Viens fails katram veidam. Tajā ir kolonnu nosaukumi, nolaižamie saraksti, instrukcija, piemēru lapa un kodu saraksti.
Kam Šablons Rindas failā Lokācijas Lejupielādēt (.xlsx, latviski) English 500 Telpas Lejupielādēt (.xlsx, latviski) English 500 Attēli Lejupielādēt (.xlsx, latviski) English 50 -
#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.
-
#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ārbaudecurl -X POST "$API/v1/imports/locations?validate_only=true" \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -F "file=@boxlatvia-locations.xlsx"const API = "https://api.boxlatvia.lv"; const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`); const form = new FormData(); form.append("file", boxlatvia_locationsFile); // File vai Blob const res = await fetch(`${API}/v1/imports/locations?validate_only=true`, { method: "POST", headers: { Authorization: auth }, body: form, }); console.log(res.status, await res.json());import requests API = "https://api.boxlatvia.lv" r = requests.post( f"{API}/v1/imports/locations?validate_only=true", auth=(CLIENT_ID, CLIENT_SECRET), files=[("file", open("boxlatvia-locations.xlsx", "rb"))], ) print(r.status_code, r.json())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)" } ] } ] } -
#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.Importscurl -X POST "$API/v1/imports/boxes" \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -F "file=@boxlatvia-boxes.xlsx"const API = "https://api.boxlatvia.lv"; const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`); const form = new FormData(); form.append("file", boxlatvia_boxesFile); // File vai Blob const res = await fetch(`${API}/v1/imports/boxes`, { method: "POST", headers: { Authorization: auth }, body: form, }); console.log(res.status, await res.json());import requests API = "https://api.boxlatvia.lv" r = requests.post( f"{API}/v1/imports/boxes", auth=(CLIENT_ID, CLIENT_SECRET), files=[("file", open("boxlatvia-boxes.xlsx", "rb"))], ) print(r.status_code, r.json())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
| Kolonna | Tips | Apraksts |
|---|---|---|
external_id | teksts | vienmē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. |
name | teksts | jaunam ierakstam. Lokācijas nosaukums, līdz 100 rakstzīmēm. Obligāts jaunai lokācijai. |
description | teksts | Apraksts, līdz 250 rakstzīmēm. |
address | teksts | Adrese, līdz 250 rakstzīmēm. |
district | teksts | Rajona kods no lapas Kodi. |
latitude | skaitlis | Ģeogrāfiskais platums, skaitlis no -90 līdz 90. Norādiet kopā ar garumu. |
longitude | skaitlis | Ģeogrāfiskais garums, skaitlis no -180 līdz 180. Norādiet kopā ar platumu. |
features | kodi, 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
| Kolonna | Tips | Apraksts |
|---|---|---|
external_id | teksts | vienmēr. Jūsu pašu telpas identifikators (līdz 100 rakstzīmēm). Tas nosaka, vai rinda izveido jaunu telpu vai atjaunina esošu. |
name | teksts | jaunam ierakstam. Telpas nosaukums, līdz 255 rakstzīmēm. Obligāts jaunai telpai. |
location_external_id | teksts | jaunam ierakstam. Lokācijas external_id, kurā telpa atrodas. Obligāts jaunai telpai. Lokācijai jau jāeksistē (vispirms importējiet lokācijas). |
description | teksts | Apraksts, līdz 255 rakstzīmēm. |
price | skaitlis | Cena par periodu, lielāka par 0, ne vairāk kā 2 decimālzīmes. |
promotional_price | skaitlis | Akcijas cena. Jābūt zemākai par price. |
price_period_1 | skaitlis | Neobligāta fiksēta kopsumma par 1 perioda nomu. |
price_period_3 | skaitlis | Neobligāta fiksēta kopsumma par 3 periodu nomu. |
price_period_6 | skaitlis | Neobligāta fiksēta kopsumma par 6 periodu nomu. |
price_period_12 | skaitlis | Neobligāta fiksēta kopsumma par 12 periodu nomu. |
price_unit | teksts | Cenas mērvienības kods no lapas Kodi (mēnesī, nedēļā). |
size | skaitlis | Platība m², lielāka par 0. |
size_length | skaitlis | Iekšējais garums metros. |
size_width | skaitlis | Iekšējais platums metros. |
size_height | skaitlis | Iekšējais augstums metros. |
door_width | skaitlis | Durvju platums metros. |
door_height | skaitlis | Durvju augstums metros. |
total_units | vesels skaitlis | Cik identisku telpu jums ir, vesels skaitlis, 0 vai vairāk. |
available_units | vesels skaitlis | Cik telpu šobrīd ir brīvas. Nevar pārsniegt total_units. |
max_advance_days | vesels skaitlis | Cik dienas uz priekšu klients drīkst rezervēt, no 1 līdz 730. |
features | kodi, atdalīti ar komatiem | Ērtību kodi no lapas Kodi, atdalīti ar komatiem. Aizvieto visu kopu. |
#Attēli
| Kolonna | Tips | Apraksts |
|---|---|---|
owner | teksts | vienmēr. Kam attēls pieder: box (telpa) vai location (lokācija). |
external_id | teksts | vienmēr. Šīs telpas vai lokācijas external_id. Tai jau jāeksistē. |
picture_url | teksts | vienmē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
- Identifikators lemj. Rinda ar
external_id, ko esat lietojis iepriekš, atjaunina to ierakstu; jauns identifikators izveido ierakstu. Katrs identifikators failā var parādīties vienu reizi. - Tukša šūna nozīmē "atstāt". Tas ļauj viegli sūtīt pieejamību: fails tikai ar
external_idunavailable_unitsmaina tikai pieejamību. Saglabātu vērtību ar failu nevar notīrīt; to dara ar API. featuresaizvieto visu kopu, ja šūna ir aizpildīta: ierakstiet visus vēlamos kodus, atdalītus ar komatiem.- Skaitļus var rakstīt ar punktu vai komatu (
29.90vai29,90). Darbojas tās pašas pārbaudes kā API: cenām ne vairāk kā 2 decimālzīmes, akcijas cena ir zemāka par cenu, brīvo telpu skaits nepārsniedz kopējo. - Telpas sākas kā melnraksti. Imports nekad nepublicē: iesniedziet telpas izskatīšanai caur API vai partneru portālu.
- Der arī CSV. Saglabājiet kā CSV UTF-8; komati, semikoli (Excel latviešu valodā) un tabulācijas tiek atpazīti. Vecs
.xlsfails vispirms jāsaglabā kā.xlsx.
#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.
- JPEG, PNG, WebP vai GIF, katrs līdz 5 MB; tiek pārbaudīts saturs, nevis faila nosaukums. Ne vairāk kā 20 attēli vienai telpai vai lokācijai.
- Adresei jābūt publiskai:
httpsun resursdatora nosaukums (nevis IP adrese, nevis privāts tīkls). Novirzīšanām seko dažas reizes ar tām pašām pārbaudēm. - Tā paša attēla sūtīšana vēlreiz neko nemaina: tas tiek atpazīts un uzskatīts par nemainītu. Attēli tikai tiek pievienoti; lai vienu noņemtu, izmantojiet API.
curl -X POST "$API/v1/imports/pictures" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-pictures.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_picturesFile); // File vai Blob
const res = await fetch(`${API}/v1/imports/pictures`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/pictures",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-pictures.xlsx", "rb"))],
)
print(r.status_code, r.json()){
"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:
| Statuss | Nozīme |
|---|---|
created | Izveidots jauns ieraksts (attēliem: attēls pievienots). |
updated | Esošs ieraksts mainīts. |
unchanged | Nav ko mainīt: rindā nebija vērtību vai attēls jau bija. |
failed | Rinda netika saglabāta; errors uzskaita visas problēmas kā { field, message }. |
would_create / would_update | Tikai 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:
curl -X POST "$API/v1/imports/boxes" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-F "file=@boxlatvia-boxes.xlsx"const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
const form = new FormData();
form.append("file", boxlatvia_boxesFile); // File vai Blob
const res = await fetch(`${API}/v1/imports/boxes`, {
method: "POST",
headers: { Authorization: auth },
body: form,
});
console.log(res.status, await res.json());import requests
API = "https://api.boxlatvia.lv"
r = requests.post(
f"{API}/v1/imports/boxes",
auth=(CLIENT_ID, CLIENT_SECRET),
files=[("file", open("boxlatvia-boxes.xlsx", "rb"))],
)
print(r.status_code, r.json()){
"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"
}
]
}Idempotency-Key, ja pieprasījumam varētu būt beidzies gaidīšanas laiks.#Ierobežojumi
| Ierobežojums | Vērtība |
|---|---|
| Rindas failā | 500 lokācijām un telpām, 50 attēliem |
| Faila izmērs | 10 MB |
| Kolonnas | 60 |
| 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.