marketplace-integration

Plans and implements new marketplace sales-channel integrations in a Next.js and Firebase monorepo.

Updated May 13, 2026
One-click install
npx skills add https://github.com/Hinten/next_erp --skill marketplace-integration-hinten
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: marketplace-integration
Source: https://github.com/Hinten/next_erp/tree/main/.claude/skills/marketplace-integration
Command: npx skills add https://github.com/Hinten/next_erp --skill marketplace-integration-hinten

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building a new marketplace channel (Shopee, Amazon SP-API, Magalu, Loja Integrada) in this monorepo is error-prone: there is deliberately no shared channel interface, capability claims must be evidence-based, and stock sync can silently burn Firestore Enterprise budget. This Skill enforces a docs-first, capability-driven process so a new channel is planned from the provider's own documentation rather than copied from Mercado Livre. ## Core Features & Use Cases - Four-phase workflow: survey the provider's documentation, fill the MARKETPLACE_TIPO_CAPS row with three-valued capabilities, generate a ~20-step master plan, then plan each step at implementation time. - Reference catalogue: carries the Mercado Livre implementation capability-by-capability, explicitly marking which decisions are ML-specific evidence (orderML mirror, tokenDuravel, unsigned webhooks) versus generic patterns. - Cost and concurrency guardrails: stock-sync read/write cost axes, watermark unit rules, shared seams (notification pipeline, OAuth state, read cache, findOrCreateCliente) that must be reused instead of re-rolled. - Use Case: When asked to add Shopee as a new sales channel, use this Skill to produce the capability survey, the caps row, and the ordered master plan of issues before writing any code. ## Quick Start Use the marketplace-integration skill to plan a new Shopee sales channel, starting with a capability survey of Shopee's official API documentation.

Frequently Asked Questions about marketplace-integration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new marketplace sales channel to this monorepo?

Follow the four phases: survey the provider's official documentation, fill the channel's MARKETPLACE_TIPO_CAPS row with 'sim', 'nao', or 'desconhecido' values, generate a master plan of roughly 20 capability-gated steps, then plan each step at implementation time. Never copy Mercado Livre code by analogy.

Why is there no shared MarketplaceChannel interface in this codebase?

The interface was deleted (ADR 0015, issue #815) because a channel built against it implemented three of four members as throws, since the work needed Firestore access a package cannot have. Capabilities now live in MARKETPLACE_TIPO_CAPS and behavior in per-channel apps.

How should webhook signature verification differ between marketplace providers?

Mercado Livre does not sign notifications, so its receiver fails open using an application_id comparison. Providers that sign, such as Shopee, Mercado Pago, and Meta, must fail closed: if the secret is unset the receiver returns 503 and never skips verification.

What makes marketplace stock sync expensive on Firestore Enterprise?

Firestore Enterprise bills data scanned, so an unindexed sweep predicate silently full-scans. The skill mandates declared composite indexes, an anchor pre-filter via integracoesComProduto, an IO-free plan core, a change-window ledger, and a durable cursor with continuation.

Can I reuse Mercado Livre's orderML mirror pattern for a new channel?

No. The orderML mirror exists only because the migrated legacy corpus is stored in that shape. A channel with no legacy corpus has nothing to be compatible with, so resolve provider order ids with a field on the pedido plus an index instead.

When should a marketplace integration use an async feed for stock updates?

Choose feed-assincrono when the provider accepts bulk submissions with deferred results. It needs a submission record plus a polling sweep, because the notification pipeline contract only supports deterministic returns or transient throws, not submitted-but-unknown states.