К основному содержанию
скилл CX Codex

label-purchase — скилл для Claude Code: покупка доставки

Скилл label-purchase для создания и покупки почтовых этикеток через Shippo API. Поддерживает внутренние и международные отправления, таможенные декларации, возвратные этикетки и отмену покупок.

MIT 1 установок ★ 3 обновлён 2026-10-09

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add goshippo/ai --skill label-purchase -a claude-code
Открыть на GitHub

Что делает label-purchase

Скилл интегрирует API Shippo в ваш редактор кода и позволяет программно покупать этикетки для доставки. Перед каждой покупкой требует явного подтверждения пользователя — скилл выводит перевозчика, уровень сервиса, стоимость и сроки доставки, и продолжает только после согласия.

Для внутренних отправлений скилл валидирует адреса, создаёт отправление, выбирает из предложенных тарифов, подтверждает и покупает этикетку. Для международных добавляет этап таможни: вы указываете тип содержимого (товар, подарок, образец, возврат или документы), создаёте декларацию с деталями товаров и правилами оплаты пошлин, затем следует стандартный процесс. Скилл также генерирует возвратные этикетки — просто меняет отправителя и получателя местами.

В ответе скилл возвращает номер отслеживания и ссылку на этикетку. Для S3-ссылок на этикетки важно передать полный адрес: обрезанная ссылка не будет работать. Если заказ отправляется в очередь вместо мгновенной обработки, скилл ждёт результата автоматически.

Какие задачи решает

  • купить этикетку для внутренней доставки через API
  • оформить международную отправку с таможенной декларацией
  • создать возвратную этикетку для клиента
  • отменить и вернуть средства за купленную этикетку
  • выбрать правильный тариф и сроки доставки перед покупкой

Примеры запросов агенту

  • Создай этикетку для отправки письма из Нью-Йорка в Лос-Анджелес весом 500 г
  • Оформи международную доставку подарка в Германию, я выберу самый дешёвый вариант
  • Сгенерируй возвратную этикетку: пусть клиент отправит покупку обратно на наш склад

Как установить label-purchase

1Через Skills CLI (Vercel)

npx skills add goshippo/ai --skill label-purchase -a claude-code

2Вручную: положить файлы

~/.claude/skills/label-purchase/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/label-purchase/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о label-purchase

Как установить label-purchase в Claude Code?

Выполните команду npx skills add goshippo/ai --skill label-purchase -a claude-code. После этого откройте файл ~/.claude/skills/label-purchase/SKILL.md для проверки установки.

Что делает скилл label-purchase?

Позволяет покупать почтовые этикетки через Shippo API прямо из редактора кода. Поддерживает внутренние и международные отправления, таможенные декларации, возвратные этикетки и отмену покупок с возвратом средств.

Нужен ли мне аккаунт Shippo?

Да, скилл работает через ваш аккаунт Shippo и заряжает его за каждую купленную этикетку. Перед покупкой всегда требуется явное подтверждение.

Исходный текст

SKILL.md · MIT
---
name: label-purchase
description: Purchase domestic and international shipping labels, handle customs declarations, return labels, and void/refund labels via the Shippo API
---

# Label Purchase

## Purchases Are Live

Label purchases charge the authorized Shippo account for real. **Before purchasing, explicitly state "this will charge your Shippo account" with the carrier, service, and cost, and require the user to acknowledge.** Do not purchase without that confirmation.

---

## Purchase Confirmation Gate

Before every call to `CreateTransaction`, summarize the following and ask the user for explicit confirmation:
- Carrier and service level
- Estimated cost
- Estimated delivery time
- Origin and destination

**Do not proceed without explicit user confirmation.**

---

## Domestic Label

1. Optionally validate both addresses with `ValidateAddress` (see Address Validation).
2. Call `CreateShipment` with `address_from`, `address_to` (as inline address objects using v1 field names -- `street1`, `city`, `state`, `zip`, `country`), `parcels`, and `async: false`.
3. Present rates to the user. Let them choose.
4. **Confirm purchase** (see Purchase Confirmation Gate above).
5. Call `CreateTransaction` with: `rate` (selected rate object_id), `label_file_type` (default `PDF_4x6`), `async: false`.
6. Check response `status`:
   - `SUCCESS`: return `tracking_number`, `label_url` (display the COMPLETE URL -- S3 signed URLs break if truncated), and `tracking_url_provider`.
   - `QUEUED`/`WAITING`: poll `GetTransaction` until resolved.
   - `ERROR`: report messages from the `messages` array.

---

## International Label

All domestic steps apply, plus customs handling before shipment creation. See `shippo/references/customs-guide.md` for the full customs workflow.

1. Optionally validate addresses with `ValidateAddress`. Sender must include `email` and `phone`. Ask if missing.
2. Create customs items: call `CreateCustomsItem` per item (description, quantity, net_weight, mass_unit, value_amount, value_currency, origin_country, tariff_number). Alternatively, you can skip this step and pass inline item objects directly in the declaration (step 3).
3. Create the customs declaration: call `CreateCustomsDeclaration` with contents_type, non_delivery_option, certify: true, certify_signer, and the items (either object_ids from step 2, or inline item objects). See `shippo/references/customs-guide.md` for field details.
4. Call `CreateShipment` with all standard fields plus `customs_declaration` (the declaration object_id).
5. Present rates, **confirm purchase** (see Purchase Confirmation Gate), then purchase label and return results as in the domestic flow.

### Contents Type Decision Tree

Use this to determine the correct `contents_type` value:

| Scenario | Value |
|---|---|
| Selling to the recipient (commercial sale) | `MERCHANDISE` |
| Sending a free gift | `GIFT` |
| Sending a product sample | `SAMPLE` |
| Paper documents only | `DOCUMENTS` |
| Customer returning a purchased item | `RETURN_MERCHANDISE` |
| Charitable donation | `HUMANITARIAN_DONATION` |
| None of the above | `OTHER` (requires `contents_explanation`) |

### Incoterms Decision Logic

The `incoterm` field on the customs declaration controls who pays duties and taxes:

- **B2C / e-commerce (default):** Use `DDU` (Delivered Duty Unpaid) -- recipient pays duties at delivery.
- **Seller prepays duties:** Use `DDP` (Delivered Duty Paid) -- seller covers all duties and taxes.
- **FedEx/DHL only:** `FCA` (Free Carrier) is available for advanced trade scenarios.

If the user does not specify, default to `DDU` for standard e-commerce shipments.

---

## Return Labels

To generate a return label, swap `address_from` and `address_to` so the original recipient becomes the sender and the original sender becomes the recipient. All other steps (shipment creation, rate selection, label purchase) remain the same.

---

## Label Format Options

Default to `PDF_4x6` unless the user specifies otherwise. Supported formats: `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A5`, `PDF_A6`, `PDF`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII`.

---

## Label Customization Options

When purchasing a label via `CreateTransaction`, the following options may be set on the shipment or rate:

- **Signature confirmation**: set `signature_confirmation` on the shipment's `extra` field. Values: `STANDARD`, `ADULT`, `CERTIFIED`, `INDIRECT`, `CARRIER_CONFIRMATION`.
- **Insurance**: set `insurance` on the shipment's `extra` field with `amount`, `currency`, and `provider`.
- **Saturday delivery**: set `saturday_delivery` to `true` in the shipment's `extra` field. Only supported by certain carriers and service levels.
- **Reference fields**: pass `metadata` on the transaction for order numbers or internal references.

---

## Label from Existing Rate

If the user already has a rate object_id: optionally call `GetRate` to confirm details, then **confirm purchase** (see Purchase Confirmation Gate), then call `CreateTransaction` directly.

---

## Voiding a Label

Call `CreateRefund` with the transaction object_id.

**Refund limitations:** Void/refund eligibility depends on carrier and timing. Not all labels can be refunded after purchase. If `CreateRefund` fails, advise the user to contact Shippo support.

---

## Quick Reference

**Domestic label:**
(optional) `ValidateAddress` (x2) -> `CreateShipment` (with inline addresses) -> user picks rate -> confirm -> `CreateTransaction`

**International label:**
(optional) `ValidateAddress` (x2) -> `CreateCustomsItem` (per item) -> `CreateCustomsDeclaration` -> `CreateShipment` (with inline addresses + customs_declaration) -> user picks rate -> confirm -> `CreateTransaction`

**Return label:**
Same as domestic/international, but swap `address_from` and `address_to`.

**Order-to-label:**
`CreateOrder` -> `CreateShipment` (using order address/item data) -> user picks rate -> confirm -> `CreateTransaction` -> packing slip (REST fallback, see below)

---

## Orders and Packing Slips

Use orders to represent e-commerce fulfillment requests. An order captures the shipping address, line items, and totals -- then feeds into the standard label purchase workflow.

### Tools

- **`CreateOrder`**: Create an order with line items, shipping address, and order details.
- **`GetOrder`**: Retrieve an order by its object_id.
- **`ListOrders`**: List all orders.
- **Packing slip (known gap):** Generate a packing slip PDF for an order. There is no packing-slip tool in the MCP catalog. The underlying REST endpoint exists at `GET /orders/{ORDER_ID}/packingslip/` (returns a 24-hour S3 PDF link). Fall back to a direct REST call, or advise the user to use the Shippo dashboard until the MCP gap is closed.

### Workflow

1. Call `CreateOrder` with the shipping address, line items (title, quantity, sku, total_price, etc.), and order-level fields.
2. Use the order's address and item data to call `CreateShipment`, then follow the standard label purchase flow (rate selection, confirmation, `CreateTransaction`).
3. After purchasing the label, generate a packing slip via the REST fallback (see Tools above for the known MCP gap).

© goshippo · MIT · goshippo/ai

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
linkfox-shopee-store-logistics linkfox-ai Скилл linkfox-shopee-store-logistics для Claude Code, Codex и Cursor. Управляет доставкой в Shopee: отправляет посылки, создаёт накладные и отслеживает трек-номера. CX Codex +1 231установок mcp-skydropx codespar Подключает Skydropx к ИИ-агенту для работы с отправлениями, тарифами, этикетками и трекингом. Автоматизирует доставку в Мексике. CX Codex +1 ★ 279звёзд репо Multi-Carrier Shipping API — powered by Secureship secureship MCP-сервер Multi-Carrier Shipping API — powered by Secureship для Claude Code открывает живые схемы 150+ эндпоинтов Secureship для интеграции доставки. CX Codex +1 6 130установок mcp-andreani codespar Подключает к агенту API аргентинского курьера Andreani: создание отправлений, трекинг, тарифы и этикетки прямо из чата. CX Codex +1 ★ 279звёзд репо Plain Freight plainfreight-com MCP-сервер Plain Freight рассчитывает стоимость доставки грузов из Китая в США с учётом таможенного оформления, пошлин и доставки до двери. Помогает оценить расходы до отправки и запросить коммерческое предложение. CX Codex +1 FreightUtils MCP Server SoapyRED FreightUtils MCP Server — MCP-сервер для Claude Code: считает объёмный вес, LDM и пошлины, проверяет опасные грузы по ADR и указывает источник ответа. CX Codex +1 ★ 8звёзд репо

Из того же набора6

shippo Скилл подключает Shippo к ИИ-агенту: расчёт тарифов, покупка этикеток, проверка адресов и отслеживание отправлений. CX Codex +1 1установок rate-shopping Скилл rate-shopping помогает запрашивать тарифы служб доставки через Shippo API, сравнивать сроки со стоимостью и подбирать варианты отправлений прямо в чате с агентом. CX Codex +1 1установок batch-shipping Скилл batch-shipping обрабатывает отправки из CSV через Shippo API: проверяет строки, покупает групповые этикетки и создаёт манифесты. Подходит для пакетной отправки заказов. CX Codex +1 1установок Shippo Удалённый MCP-сервер Shippo логистики: сравнивает тарифы 30+ перевозчиков, валидирует адреса и оформляет почтовые этикетки в диалоге с агентом. CX Codex +1 ★ 3звёзд репо shippo Плагин shippo для Claude Code помогает оформлять отправления, сравнивать тарифы перевозчиков и отслеживать посылки. Навыки также проверяют адреса и обрабатывают CSV с отправлениями. ★ 3звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой