Impor dan ekspor

Aturannya: dry run dulu

Setiap importer bekerja dalam dua langkah. Dry run membaca sumber Anda dan menghasilkan laporan: apa yang akan dibuat, diperbarui, atau dilewati, slug mana yang bentrok, gambar mana yang gagal, dan tautan mana yang putus. Tidak ada yang ditulis. Bila angkanya sudah benar, Anda menjalankan impor sungguhan, dan impor itu memakai ulang berkas yang sudah Anda unggah.

Impor aman diulang. Setiap item yang diimpor mengingat asalnya, jadi proses kedua memperbarui item yang berubah dan membiarkan sisanya.

Impor tidak pernah menerbitkan markup yang tidak aman

HTML hasil impor melewati sanitiser dan konverter block yang sama dengan konten lain. Skrip, atribut event, dan tautan javascript: tidak pernah masuk ke konten Anda, dan setiap tautan hasil impor melewati penjaga tautan.

Semua panggilan di bawah berada di https://api.atlascms.id/v1/manage/tools. Panggilan memerlukan sesi yang sudah masuk dan header X-Brand-Id.

Mengimpor ekspor WordPress atau CSV

Menampilkan sumber yang boleh Anda pakai: wordpress (ekspor .xml), csv, dan untuk admin url.

Kirim multipart form dengan kind (wordpress atau csv), file, dan options. Tambahkan ?dry_run=1 untuk dry run. Berkas boleh sampai 2 MB.

curl -s -X POST "https://api.atlascms.id/v1/manage/tools/imports?dry_run=1" \
  -H "X-Brand-Id: $BRAND_ID" --cookie "$SESSION" \
  -F kind=wordpress -F file=@export.xml \
  -F 'options={"locale":"id","status":"keep","download_images":true}'

Dry run dijawab dalam permintaan yang sama dengan 201 beserta laporannya. Impor sungguhan masuk antrean dan dijawab 202. Untuk menulis setelah dry run, kirim run (id dry run) sebagai ganti berkas:

curl -s -X POST "https://api.atlascms.id/v1/manage/tools/imports" \
  -H "X-Brand-Id: $BRAND_ID" --cookie "$SESSION" \
  -F kind=wordpress -F run=01m5200000000000000000000a

Hanya satu impor yang berjalan per brand dalam satu waktu. Pantau GET /v1/manage/tools/imports/{run} untuk laporan dan GET /v1/manage/tools/imports/{run}/items untuk hasil tiap entri.

Yang dilakukan impor WordPress

• Post dan halaman menjadi entri di permalink WordPress-nya. Tipe post lain, post di tempat sampah, dan lampiran dilewati dan dihitung. Komentar diabaikan.
• Penulis dicocokkan ke anggota brand lewat email, jika tidak ada maka pengguna yang mengimpor.
• Komentar Gutenberg dibuang, [caption] dan [gallery] menjadi figure, shortcode lain dibuang dengan peringatan.
• Dengan download_images, gambar diambil lewat HTTPS dari alamat publik saja (maksimal 15 MB per gambar), dicek sebagai gambar sungguhan, dan disimpan sekali.
• Slug ganda mempertahankan entri pertama. Yang berikutnya menjadi draf dengan path yang diberi akhiran.

Kolom CSV

title, slug, date, status, body, excerpt, category, tags, locale, image_url, meta_title, meta_description

Unduh templat siap pakai dari GET /v1/manage/tools/imports/csv-template. Satu baris dikenali dari tipe, bahasa, dan slug, sehingga mengunggah berkas yang sama lagi akan memperbarui entri yang sama.

Batas dan pembersihan

Berkas WordPress boleh berisi hingga 50.000 item, CSV hingga 20.000 baris, dan satu item dibatasi 5 MB. Arsip, berkas biner, dan XML dengan deklarasi entity ditolak sebelum diurai. Berkas yang diunggah disimpan secara privat dan dihapus saat impor sungguhan selesai, dengan DELETE /v1/manage/tools/imports/{run} (hanya untuk proses yang sudah selesai), atau otomatis setelah sehari.

Mengimpor situs web yang tayang (admin)

Pakai kind=url dengan url (alamat HTTPS dengan nama host) dan max_pages opsional (1 sampai 200, bawaan 50). Crawl diantrekan untuk dry run maupun penulisan, jadi pantau prosesnya.

• Crawl tetap di host awal dan varian www-nya, serta mematuhi robots.txt untuk agen AtlasImport, termasuk Crawl-delay.
• Crawl membaca sitemap bila ada, jika tidak maka mengikuti tautan internal hingga kedalaman 6.
• Jeda minimal satu detik antarpermintaan, dan berhenti setelah 10 menit.
• Halaman masuk sebagai entri dengan judul, isi yang sudah disanitasi, tag SEO, dan bahasa.

Mengimpor redirect dari CSV

Unggah CSV dengan kolom from, to, code (hingga 5000 baris, 2 MB). Jalankan dulu dengan ?dry_run=1: laporan menghitung baris create, update, dan unchanged, dan mendaftar setiap baris yang ditolak beserta alasannya (bukan path, target tidak aman, redirect ke diri sendiri, atau loop). Proses sungguhan menulis baris yang valid, meratakan rantai redirect, dan mengirim webhook purge.

Importer baris perintah

Perintah ini berjalan di server dan butuh akses ke server, jadi diperuntukkan bagi siapa pun yang mengoperasikan instalasi ATLAS Anda. Inilah cara memindahkan seluruh situs lama.

php artisan atlas:import botble --brand=lifefuture --dry-run --check-remote
php artisan atlas:import botble --brand=lifefuture --write

Aturan yang perlu diketahui:

• Untuk atlas:import dan atlas:import-assets, penulisan memerlukan dry run yang sudah selesai dari sumber yang sama.
• Brand hanya bisa ditulis oleh importer bila ada di daftar izin importer itu. Selain itu ditolak.
• atlas:import-assets hanya memanggil host situs dan host penyimpanan milik brand, lewat HTTPS, dan tidak pernah mengambil apa pun dari host lain. Ia melaporkan apa yang dilewati dan alasannya.
• Impor konten bersifat idempoten: proses ulang hanya menambah revisi bila isinya berubah, jadi proses delta terakhir di hari peralihan aman dijalankan.

Migrasi yang umum menjalankan atlas:import-assets (dry run, lalu tulis), kemudian atlas:import-site atau atlas:import, lalu pemeriksaan paritas, lalu memindahkan domain. Biarkan situs lama hanya-baca untuk sementara dan ubah hit 404 menjadi redirect.

Ekspor

POST /v1/manage/tools/exports (publisher atau admin) mengantrekan pembuatan berkas dan menjawab 202.

{ "kind": "csv", "filters": { "type": "post", "locale": "id", "status": ["published"], "from": "2026-01-01" } }

GET /v1/manage/tools/exports menampilkan daftar proses dan GET /v1/manage/tools/exports/{id} menunjukkan statusnya. Bila proses completed, respons memuat objek download:

{ "download": { "url": "https://api.atlascms.id/v1/tools/exports/01m5.../download?expires=...&signature=...", "expires_at": "2026-10-21T14:47:20+00:00" } }

Tautan ini bertanda tangan dan berlaku 5 menit. Baca proses itu lagi untuk mendapat tautan baru. Berkasnya sendiri privat dan disimpan 24 jam. Tautan berhenti berfungsi selama brand ditangguhkan. Sel CSV yang diawali =, +, -, atau @ diberi awalan tanda kutip, sehingga spreadsheet tidak menjalankannya sebagai rumus.

Ekspor lead dipisah: lihat Formulir dan lead.

Ekspor dan impor tema

GET /v1/manage/theme/export?theme={slug} (admin, 10 per menit) mengembalikan satu dokumen bundel untuk tema aktif atau tema yang Anda sebut: versi tema, nilai opsinya, dan override template serta part Anda. Draf tidak disertakan.

POST /v1/manage/theme/import (admin, 10 per menit) menerima bundel itu. Kirim "dry_run": true dulu untuk melihat apa yang akan berubah.

{ "data": { "dry_run": true, "theme": { "slug": "lifefuture", "version": "0.2.4" },
  "options": { "changes": 2, "unchanged": 14 },
  "templates": { "created": 0, "updated": 1, "unchanged": 5 },
  "parts": { "created": 0, "updated": 0, "unchanged": 2 }, "warnings": [] } }

Bundel adalah dokumen tertutup: kunci yang tidak dikenal ditolak, dan setiap opsi divalidasi terhadap manifes tema. Impor sungguhan membuang draf opsi tema itu (laporan memperingatkan Anda) dan hanya mem-purge cache bila bundel menyebut tema yang sedang dijalankan brand.

Progres secara real time

Progres impor disiarkan di kanal privat brand.{id}.imports sebagai import.progress dengan processed, total, dan status. Ekspor, backup, dan proses alat lain memakai brand.{id}.tools dengan tool.progress. Dasbor mendengarkan siaran ini, sehingga proses diperbarui sendiri. Bila Anda mengintegrasikan sendiri, melakukan polling pada endpoint proses juga bisa.