Zoppy Partners API

Skills para IA

Agent Skills que ensinam a IA de código do seu time (Claude Code, Antigravity, Codex, Cursor, GitHub Copilot) o contrato da Partners API: campos, valores, datas, reenvio e erros. Cada skill traz exemplos executáveis e um validador de payload que a IA roda antes de enviar os dados.

O plugin é público, com licença MIT, e fica no GitHub: https://github.com/Zoppy-crm/zoppy-partners-ai-plugin

Skills

Cada skill cobre uma parte do contrato, e a IA aciona a certa conforme a tarefa. Comece pela zoppy-partners-api.

Skill	Use para
`zoppy-partners-api`	Autenticação, ambientes, paginação, datas, erros e ordem de envio. Comece por aqui.
`zoppy-partners-lojas`	Lojas e filiais: reaproveitar as existentes, storeId no pedido, loja padrão "Integrador Externo" e correção de pedidos na loja errada.
`zoppy-partners-vendedores`	Vendedores: cadastro, e-mail único, telefone e como o pedido acha o vendedor (userId ou seller).
`zoppy-partners-clientes`	Criar, atualizar e buscar clientes; telefone, endereço e deduplicação.
`zoppy-partners-produtos`	Criar, atualizar e buscar produtos; vínculo com os itens do pedido.
`zoppy-partners-pedidos`	Pedidos: status, subtotal/discount/shipping, datas, reenvio pelo PUT.
`zoppy-partners-carrinho-abandonado`	Carrinhos abandonados e a recuperação.
`zoppy-partners-cupons-webhooks`	Cupons (individual e compartilhado) e webhooks de cupom criado.

Instalação

Claude Code

Adicione o marketplace e instale o plugin:

/plugin marketplace add Zoppy-crm/zoppy-partners-ai-plugin
/plugin install zoppy-partners@zoppy

Antigravity (CLI agy e IDE)

Instale como plugin a partir de um clone do repositório:

git clone https://github.com/Zoppy-crm/zoppy-partners-ai-plugin
agy plugin install ./zoppy-partners-ai-plugin

Instalado como plugin, ele também traz rules/zoppy-partners.md, regra que o Antigravity aplica em toda conversa (credenciais, validador e dados de teste). Ou copie só as skills para .agents/skills/ no seu projeto, como abaixo; cada SKILL.md repete essas regras.

Codex, Cursor, GitHub Copilot e outras ferramentas compatíveis com Agent Skills

Copie as pastas de skills/ para .agents/skills/ no seu projeto:

git clone https://github.com/Zoppy-crm/zoppy-partners-ai-plugin /tmp/zoppy-skills
mkdir -p .agents/skills && cp -r /tmp/zoppy-skills/skills/* .agents/skills/

Cada pasta funciona sozinha, então você pode copiar só as skills que usar. Para valer em todos os seus projetos, use a pasta de usuário da sua ferramenta (por exemplo ~/.agents/skills/ no Codex, Cursor e Copilot).

Gemini CLI

Desde 18/06/2026 o Gemini CLI atende só licenças Gemini Code Assist Standard/Enterprise e chaves de API pagas do Google Cloud; nos demais casos o caminho é o Antigravity, acima. Com Gemini CLI ativo, copie as skills para .agents/skills/ como nas outras ferramentas.

Credenciais

Os exemplos e a IA leem três variáveis de ambiente. Nunca coloque esses valores no código: carregue-os no ambiente do seu shell.

Variável	Conteúdo
`ZOPPY_PARTNERS_TOKEN`	Token da sua empresa (vai em Authorization: Bearer)
`ZOPPY_ACCESS`	Valor do header zoppy-access
`ZOPPY_PARTNERS_BASE_URL`	URL base: https://api-partners-staging.zoppy.com.br (homologação, com token e chave próprios) ou https://api-partners.zoppy.com.br

export ZOPPY_PARTNERS_TOKEN="<token>"
export ZOPPY_ACCESS="<zoppy-access>"
export ZOPPY_PARTNERS_BASE_URL="https://api-partners-staging.zoppy.com.br"

Comece pela homologação

Para testes, use o ambiente de homologação https://api-partners-staging.zoppy.com.br , com as mesmas rotas. O token e a chave zoppy-access de homologação são diferentes dos de produção: peça os dois ao time da Zoppy.

Teste numa conta sem fluxos de mensagem ativos: pedidos e carrinhos enviados disparam os fluxos da conta, e apagar os dados depois não desfaz mensagem já enviada.

Validar um payload

Cada skill traz um validador sem dependências, que exige Node 18 ou mais novo. A IA roda o validador antes de devolver código, e você também pode rodar à mão:

node skills/zoppy-partners-pedidos/scripts/validate.mjs --schema=pedido.create --file=pedido.json

Saída 0 sem erro (avisos podem aparecer), 1 com erro, 2 uso incorreto. --list-schemas lista os payloads da skill, --json devolve o resultado para máquina e --help mostra o uso. Dentro de uma skill instalada, scripts/ é relativo à pasta da skill, não ao seu projeto.

Código e suporte

Achou algo errado ou que falta numa skill? Abra uma issue no repositório.

Repositório no GitHub → Reportar um problema →