d1-cli — Tiendas D1 커맨드라인 사용하기
D1은 콜롬비아 최대의 하드디스카운트 식료품 체인입니다. 이 매장은 VTEX IO(계정 d1tiendas)로 운영되므로, 사이트 자체의 공개 API가 통합 인터페이스 역할을 합니다. 스크래핑이나 관리자 자격 증명이 필요하지 않습니다.
실행
cd skills/commerce/d1-cli
# 1. 먼저 배송 지점을 설정하세요 — 다른 모든 것은 이에 의존합니다
bun run src/cli.ts region --lat 4.6486 --lng=-74.0628
# 2. 그런 다음 검색: 가격과 재고는 이제 국가 단위가 아닌 해당 매장 기준입니다
bun run src/cli.ts search leche entera --count 5
bun run src/cli.ts search --facets category-1/lacteos-y-huevos --sort price:asc
# 3. 장바구니에 담지 않고 장바구니 가격 산정
bun run src/cli.ts quote 262:2 892:1
# 3b. 또는 예산으로 품목 결정 — SKU 대신 검색어 사용
bun run src/cli.ts basket --budget 30000 arroz leche aceite huevos
# 4. 또는 실제 장바구니를 만든 후 사람이 결제하도록 전달
bun run src/cli.ts cart add 262 --qty 2
bun run src/cli.ts cart deliver-to
bun run src/cli.ts cart checkout # URL 출력; 결제하지 않음
에이전트가 읽을 수 있는 출력을 원하면 명령어에 --json을 추가하세요. 종료 코드는 계약이며, 이 목록이 유일한 사본입니다:
| 코드 | 의미 | 재시도? |
|---|---|---|
0 | 성공 | — |
1 | D1이 거부했거나 연결 불가능 — 배송 불가 지점, 사용 불가 또는 알 수 없는 SKU, 중단 | 예, 도움이 될 수 있음 |
2 | 명령어가 잘못 호출됨 | 재시도해도 소용없음 |
3 | 성공했지만 결과가 "없음" (substitute, basket) | 재시도해도 소용없음 |
이를 구분하지 못하는 에이전트는 오타를 계속 재시도하거나 일시적 중단을 포기하게 됩니다. 3이 존재하는 이유는 빈 카테고리가 둘 중 어느 것에도 해당하지 않기 때문입니다.
cart add는 해당 라인을 --qty로 설정하며, 추가하지 않는다는 점에 유의하세요. 이는 실제로 확인된 D1 자체의 의미 체계입니다.
순진한 D1 자동화를 실패하게 만드는 두 가지 요소
재고는 지역화되어 있습니다. 지역 없이 카탈로그를 조회하면 D1은 전국 카탈로그에서 응답하여 가상 판매자 1에 대해 10,000개의 품목을 편안하게 보고합니다. 실제 주소로 체크아웃 시뮬레이션을 실행하면 동일한 SKU가 withoutStock으로 반환되는데, 이는 해당 상품을 배송할 실제 매장에 재고가 없기 때문입니다. 항상 먼저 d1 region을 실행하세요; CLI는 전국 가격을 보여줄 때 일반 텍스트로 경고합니다.
지역 설정은 API에서 가장 추측하기 어려운 부분이기도 합니다: 좌표는 geoCoordinates={경도};{위도} — 세미콜론으로 구분, 경도 먼저 입력합니다. VTEX 자체 JSON 본문에서 동일한 쌍에 사용하는 쉼표는 CHK0119("주소에는 우편번호 또는 지리좌표가 포함되어야 합니다") 오류로 거부됩니다. 이는 매개변수가 잘못된 형식이라기보다 누락된 것처럼 읽히는 메시지입니다. test/region.test.ts에서 이 동작을 고정하여 정리 과정에서 실수로 변경되지 않도록 합니다.
가격은 두 가지 단위로 제공됩니다. SKU 262(Leche Entera Latti 900ml, 매장 가격 COP 3,500)의 경우:
| API | 필드 | 값 | 단위 |
|---|---|---|---|
| intelligent-search | Price | 3500 | 페소 |
| catalog_system | Price | 3500.0 | 페소 |
| checkout orderForm | sellingPrice | 350000 | 1/100 단위 |
어느 것도 자체 단위를 표시하지 않습니다. catalog.ts는 경계에서 모든 것을 1/100 단위로 정규화하여 나머지 코드가 하나의 단위만 사용하도록 하며, 검색에서 가져온 가격이 체크아웃에서 가져온 가격과 동일하게 표시되는지 테스트를 통해 확인합니다.
하지 않는 작업
d1은 장바구니를 구성하고 가격을 산정합니다. 결제는 하지 않습니다. d1 cart checkout은 사람이 총액을 확인하고 결제를 완료할 URL을 출력합니다.
이 경계는 한 목록(src/endpoints.ts)에서 두 곳에서 확인됩니다: 런타임에서 D1Client.request는 요청의 확인된 URL이 D1 자체 출처와 18개의 승인된 경로 중 하나에 속하지 않으면 요청이 프로세스를 떠나기 전에 거부합니다; 정적으로 test/safety.test.ts는 src/ 아래에 있는 모든 /api/ 리터럴이 승인되지 않으면 실패합니다. 결제나 다른 엔드포인트를 추가하려면 목록에 등록되어야 하므로, 기본적으로 허용되는 것이 아니라 결정을 내리게 됩니다.
런타임 부분은 중요하며, 정적 스캔만으로는 충분하지 않다는 검토 후에 추가되었습니다: --facets '../../../..'는 모든 소스 리터럴이 승인된 상태에서 검색 엔드포인트를 벗어나 주문 결제로 이어질 수 있었습니다.
정확히 말하면, 이전 버전의 이 파일이 과장된 표현을 썼습니다: 여기에 있는 어떤 것도 쓰기 권한이 있는 커미터가 허용 목록을 편집하는 것을 막을 수 없습니다. 저장소 내 테스트로는 불가능합니다.
저장하는 유일한 자격 증명은 스토어프론트 세션 토큰(로그인된 브라우저가 보유하는 것과 동일하며, 소유자의 주문 및 장바구니로 범위가 지정됨)이며, ~/.config/d1-cli/session.json에 모드 0600으로 기록됩니다. VTEX 관리자 appKey/appToken은 어디에서도 읽지 않습니다. 로그인은 일회용 이메일 코드를 통해 이루어집니다; 비밀번호 인증은 의도적으로 구현되지 않았습니다.
체크아웃 게이트 — 항상 여기서 종료
모든 장바구니는 d1 cart checkout으로 마무리하고 종료 코드에 따라 행동하세요. 형식적인 것이 아닙니다: 이것은 장바구니 전체를 D1의 현재 상태와 다시 확인하는 유일한 명령어이며, 장바구니는 다른 어떤 방법으로도 표면화되지 않는 방식으로 오래될 수 있습니다.
0 모든 라인 배송 가능 — URL을 안전하게 전달 가능
1 하나 이상의 라인을 배송할 수 없음; URL은 출력되지만 장바구니가 깨짐
2 명령어가 잘못 호출됨
이것은 실제 장바구니에서 각각 발생했기 때문에 존재합니다:
- 한 라인이 밤새 품절되었습니다.
PAN ARTESANAL INTEGRAL이 추가된 지 몇 시간 만에no tiene inventario가 되었습니다. 장바구니는 여전히 렌더링되었고, 합계도 있었지만 — 죽은 라인이 합계에서 빠지면서 합계가 6.490페소 부족했습니다. - 주소 변경으로 모든 라인이 좌초되었습니다. 9개 품목이
cannotBeDelivered로 반환되었지만, 각각 여전히 유효한 SLA를 가지고 있었고 장바구니는 지불 가능한 합계를 표시했습니다. - 배송비가 라인별 할당으로 12배 과소 보고되었으며, 이는 총액처럼 보였습니다.
세 경우 모두 장바구니는 정상처럼 보였습니다. 세션 초기에 가져온 견적은 현재 장바구니에 대한 증거가 아니므로, 마지막 변경 전에 얻은 체크아웃 URL을 절대 전달하지 마십시오 — 게이트를 다시 실행하세요.
1을 반환하면 --json은 라인을 명명하는 undeliverable[]과 readyToCheckout: false를 제공합니다. 해당 라인을 제거하거나 교체한 후 다시 실행하세요.
D1이 공급할 수 없는 라인 교체
d1 substitute 192 --limit 5 # 동일한 카테고리에서 재고가 있는 제품 순위 지정
종료 0은 제안할 것이 있음을 의미합니다; 3은 없음을 의미합니다 — d1 basket과 함께 3을 사용하는 두 명령어 중 하나입니다.
1이 아닌 3이며, 그 구분이 중요합니다: 1은 CLI의 다른 모든 곳에서 *"D1이 거부했거나 연결할 수 없음"*을 의미하며 재시도를 유도합니다. 빈 카테고리는 재시도해도 절대 채워지지 않으므로, 1에 재시도 정책을 가진 에이전트는 영원히 루프에 빠집니다. 빈 목록과 함께 0을 반환하는 것은 또 다른 잘못된 답변입니다 — 성공으로 읽혀서 조치가 취해집니다.
각 후보는 무엇이 변경되는지를 명명합니다: 브랜드, 팩 크기, $/kg 또는 $/L, 팩 가격, 그리고 얻거나 잃은 Ley 2120 경고. 이것은 점수가 아니라 출력입니다. 동일한 900ml와 동일한 라벨에 대해 리터당 -12%는 Exceso en Azúcares가 추가된 제안과는 다른 제안이며, 델타만이 그것들을 구분할 수 있습니다.
제안만 하고, 적용하지 마세요. substitute는 절대 쓰기 작업을 하지 않습니다 — 사람이 승인할 d1 cart add를 출력합니다. 이것은 자체 목적을 위한 주의가 아닙니다: 고객은 두 번 잘못된 대체품보다 라인 제거를 선호했으며, 명시적으로 그렇게 말했고, 두 번 모두 옳았습니다. 후보와 절충점을 제시하세요; 사람이 결정하게 하고, 라인을 포기할 의사를 가지세요.
알아둘 가치가 있는 세 가지 정보:
- "이 품목은 귀하의 매장에 재고가 있습니다." 재고는 매장별로 다르므로, 다른 곳에서 실패한 라인이 여기서는 괜찮을 수 있습니다. 교체하기 전에 확인하세요.
--lat/--lng가 없으면 추측하는 대신 그렇게 말합니다 — 매장별 주장을 할 기준 매장이 없습니다. - "레벨 2/3으로 확장됨" — 하위 카테고리에 재고가 없어서 더 넓은 통로에서 제안이 오며, 따라서 덜 정확합니다.
- "N개만 비교됨" — 카테고리가 한 페이지보다 큽니다.
--count를 늘리세요. 빈 결과에서도 이 메시지가 출력되는데, 부분 스캔에 대해 *"여기 재고가 있는 것은 아무것도 없습니다"*라고 주장하는 것은 더 많은 주의가 필요하기 때문입니다.
요청이 모호할 때 찾기
"SKU 1092를 사라"보다는 "쌀이 필요해"라는 요청에 대해 두 가지 축이 중요하며, 어느 것도 기본값이 아닙니다:
팩 가격이 아닌 단위 가격으로 정렬하세요. --sort per-unit은 콜롬비아 법이 D1에 게시하도록 요구하는 PUM 데이터를 사용합니다. 두 순위는 실제로 일치하지 않습니다: ARROZ ESTÁNDAR 500 GRS는 $1.550에 가장 저렴한 팩이며 kg당 $3.100이지만, 동일한 결과에서 최고의 가치는 kg당 $2.775입니다 — $5.550 봉지로 팩 가격 상위 5위에는 전혀 나타나지 않습니다. 팩 가격으로 정렬하면 옳게 보이면서도 더 나쁜 답변을 제공합니다.
D1의 검색이 이 기준으로 정렬할 수 없기 때문에 --sort per-unit은 전체 결과 집합이 아닌, 가져온 페이지를 정렬합니다. --count(최대 50)를 늘려 범위를 넓히세요. 출력은 지원할 수 없는 최상급을 암시하는 대신 그렇게 말하며, 크기를 게시하지 않아 전혀 비교할 수 없는 결과가 몇 개인지 명명합니다.
멀티팩의 선언된 크기는 팩 전체이며, 개별 품목이 아닙니다 — "수정"하지 마세요. 모든 1,600개 제품을 조사한 결과, 이름이 일치하는 멀티팩 중 D1이 결정하기에 충분한 정보를 제공하는 46개 중 44개는 팩 전체 합계를 선언했습니다. 제품 이름에서 N UN을 구문 분석하여 곱하면 2개를 수정하기 위해 44개를 손상시킬 수 있습니다. 이름의 개수는 PUM이 의미하는 바에 대한 증거가 아닙니다.
따라서 resolvePackSize는 이름보다 설명을 읽습니다. PUM을 가지고 있는 모든 1,548개 제품 중에서 설명에 개별 항목 크기와 개수가 모두 명시된 10개에 대해 작동합니다: 3개는 수정되고(SKU 718, 510, 1008), 7개는 이미 팩 크기를 명시한 것으로 확인되며, 나머지는 선언된 대로 유지됩니다.
경고 라벨을 읽으세요. 제품에는 콜롬비아의 전면 패키지 경고(Exceso en Azúcares, Exceso en sodio, Exceso en grasas saturadas, Exceso en grasas trans, Contiene Edulcorantes)가 --json 아래 warnings[]에 포함되어 있습니다. 적용 범위는 부분적입니다(카테고리별 약 70–90%). 따라서 부재는 "안전함"이 아니라 "선언되지 않음"을 의미합니다.
그런 다음 페이지를 매기기 전에 d1 facets <query>(카테고리, 브랜드, 하위 카테고리별 개수)로 범위를 좁히세요: 검색은 최대 50페이지로 제한되므로, 광범위한 쿼리는 전체를 탐색하기보다 패싯으로 자르는 것이 좋습니다.
명령어
| 명령어 | 기능 |
|---|---|
region --lat --lng | 배송 지점 확인 및 저장 |
search <query> | 제품 찾기 (--facets --sort --count --page --available) |
suggest <partial> · trending | 자동완성 · 콜롬비아에서 검색 중인 항목 |
categories · facets [query] | 부서 트리 · 쿼리용 필터 |
substitute <sku> | 대신 구매할 항목과 변경 사항 (--limit --count) |
quote <sku>[:qty]... | 장바구니 변형 없이 장바구니 가격 산정 |
cart [show|add|set|clear|deliver-to|checkout] | 장바구니 구성 |
login --email / --from-cookie · whoami · logout | 계정 |
orders · order <id> | 주문 내역 (세부 정보는 허용 목록으로 편집됨; --raw 옵트인) |
stores near | 지점 주변 D1 매장 — 위치만 제공, D1은 픽업 서비스 없음 |
테스트
bun test # 화폐 단위, 세미콜론 함정, 견적 내 수량, 알 수 없는 SKU 공백,
# 장바구니 정규화, 주문 편집, 결제 범위를 제한하는 엔드포인트 허용 목록
bun run lint && bun run typecheck
종료 코드는 장식이 아니라 계약입니다 — 위의 실행 섹션 아래 표가 유일한 사본입니다.
전체 엔드포인트 맵, 배송 등급 동작 및 공개 API가 제공하지 않는 사항은 README.md를 참조하세요.