ANYMARKET Backoffice API Guide

Skill que ensina o assistente de IA a integrar corretamente com a API v2 Backoffice do ANYMARKET. Cobre autenticação, ambientes, os 17 domínios da API (produtos, SKUs, pedidos, estoque, preços, listings, NF-e, callbacks, campanhas, monitoring, users, roles e mais), o grafo de dependências entre domínios, padrão de erro, paginação, rate limit e o fluxo greenfield vs brownfield.

Público-alvo: desenvolvedores integrando ERP (TOTVS, Winthor, Protheus, SAP, ERP próprio) com o ANYMARKET. Não é uma skill para usuário final — o foco é código de integração correto na primeira tentativa.

O que ela resolve

Integração com API tem duas armadilhas clássicas:

1. Escrever request "de memória" — nome de campo errado, campo obrigatório faltando, status transition disparada pelo verbo HTTP errado. Custa 400/422 na hora.
2. Ignorar contexto de projeto — introduzir um segundo HTTP client, uma segunda estratégia de retry ou um segundo formato de log num codebase que já tem tudo isso resolvido. Custa code review reprovado.

A skill blinda contra as duas: ela força consulta ao Spec API antes de gerar código e diferencia greenfield (projeto novo) de brownfield (projeto existente) já na primeira mensagem.

Como invocar

Duas formas:

1. Comando: digite /anymarket-backoffice-api-guide no seu harness (o cliente/IDE de IA que você usa) — o formato do comando pode variar conforme o harness.
2. Linguagem natural: qualquer pedido relacionado a integração ERP ↔ ANYMARKET dispara a skill. Exemplos:
   • "Preciso integrar cadastro de produtos com o ANYMARKET via TOTVS."
   • "Como implementar polling de pedidos usando /orders/feeds?"
   • "O que preciso mandar para publicar um SKU no Mercado Livre?"
   • "Quais campos são obrigatórios em POST /products?"
   • "Emissão de NF-e pela API do ANYMARKET."

O que a skill vai perguntar antes de agir

A skill não faz a primeira chamada nem gera código sem confirmar três pontos — de propósito, para evitar retrabalho:

1. Ambiente — Sandbox (sandbox-api.anymarket.com.br/v2) ou Produção (api.anymarket.com.br/v2)? Token de sandbox retorna 401 em produção e vice-versa.
2. Autenticação — O gumgaToken do ambiente escolhido está disponível? Qual valor vai no header platform (TOTVS, WINTHOR, ERP_PROPRIO etc.)? Sem os dois headers = 401 em toda requisição.
3. Contexto do projeto (Greenfield vs Brownfield) — Projeto novo ou integração em codebase existente? Se for brownfield, ela abre um checklist para descobrir o que reutilizar (HTTP client, config, retry, logging etc.) antes de escrever uma linha de código.

Responder as três de uma vez economiza várias idas e vindas.

Regra de ouro — spec antes de código

A skill carrega regras de negócio e roteamento, não o contrato de campo de cada endpoint. Para qualquer request novo, a ordem é:

1. Abrir a sub-referência do domínio (mapa abaixo).
2. Buscar o contrato no Spec API antes de codar: GET https://developers.anymarket.com.br/specs/backoffice/pt-BR/operations/<operationId>.json — ler requestBody.application/json.schema (especialmente o array required) e usar os examples como payload base.
3. Escrever o código a partir do schema resolvido.
4. Chamar a API só para testar — nunca para descobrir o contrato por tentativa e erro.

Casos reais que a skill previne:

• Nome do produto é title, não name.
• priceFactor precisa ser > 0 mesmo quando o preço é por SKU.
• Transições de status de pedido são PUT com paths (/faturado, /enviado, /concluido, /cancelado), não POST.
• limit de paginação é 5–100; totais ficam em page.totalPages / page.number.
• Headers gumgaToken e platform são obrigatórios em todas as chamadas.

Domínios cobertos (17)

A skill mapeia cada domínio para uma sub-referência (overview.md em cada pasta), que o assistente abre sob demanda:

Catálogo (pré-requisitos do produto)

Domínio	Cobre
brands	CRUD de marcas
categories	CRUD de categorias
variations	Tipos e valores de variação (para produto variável)

Produto e SKU

Domínio	Cobre
products	Produto simples, produto variável, leitura, atualização
skus	Adicionar variante, atualizar EAN/título/preço, desativar SKU
images	Upload, status de processamento, remoção de imagens

Pós-catálogo

Domínio	Cobre
stock	Estoque, locais (MultiCDs), reservas
listings	Anúncios em marketplaces, transmissões, feeds
prices	Preços por marketplace, em lote

Pedidos e pós-venda

Domínio	Cobre
orders	Ler/criar/atualizar pedidos, transições de status, feeds
returns	Devoluções
fiscal-documents	Envio de NF-e, leitura de documentos fiscais

Configuração e apoio

Domínio	Cobre
callbacks	Webhooks de notificação
campaigns	Campanhas de desconto
monitoring	Erros de integração
users	Usuários
roles	Perfis de acesso (permissões)

Referências transversais

Assunto	Onde
Paginação, filtros, ordenação	references/pagination.md
Rate limit, throttling, retry	references/rate-limit.md
Erros HTTP (400, 401, 404, 422, 429)	references/errors.md
Glossário (termos e siglas da API)	references/glossary.md

Grafo de dependência — catálogo

A API do ANYMARKET impõe uma ordem de cadastro. Criar produto sem pré-requisito retorna 422. A skill segue este grafo:

brands       ──┐
categories   ──┼──▶  products  ──▶  skus  ──▶  listings
variations   ──┘        │              │            │
  (só para variáveis)   └──▶  images   │            ▼
                                       └──▶  stock
                                       └──▶  prices

Ordem recomendada de integração:

1. Brands
2. Categories
3. Variations (se produto variável)
4. Products
5. SKUs adicionais (pós-criação, se necessário)
6. Images
7. Stock
8. Listings (publicação em marketplaces)

Padrão de feed (polling)

Vários domínios expõem feeds para detectar mudanças sem depender de webhook. O padrão é sempre o mesmo:

1. GET /{dominio}/feeds          → array de {id, token} não lidos
2. Processar cada item
3. PUT /{dominio}/feeds/batch    → marcar tudo como lido de uma vez
   OU
   PUT /{dominio}/feeds/{id}     → marcar individualmente
4. Repetir

Itens não marcados como lidos ficam disponíveis por 30 dias.

Feeds cobertos:

• /orders/feeds — novos pedidos e mudanças
• /transmissions/feeds — mudanças em listings
• /transmissions-price/feeds — mudanças de preço
• /reservations/feeds — reservas de estoque

Instalação da skill

A forma mais rápida: baixe a skill já compactada e envie no seu assistente (em Skills / Capacidades, conforme o harness).

⬇ Baixar skill pronta (.zip)

Ou instale manualmente a partir do repositório:

1. Clone o repositório interno anymarket-backoffice-api-guide.
2. Copie a pasta para o diretório de skills que o seu harness lê (o caminho padrão varia por harness — consulte a documentação oficial).
3. Recarregue o harness (reinício, comando de reload ou equivalente).
4. Confirme que a skill aparece na lista de skills disponíveis do harness (/help, painel de configurações etc., conforme o caso).

Boas práticas ao usar

• Responda as três perguntas iniciais de uma vez. Ambiente, autenticação e greenfield/brownfield — economiza várias idas e vindas.
• Deixe a skill abrir a sub-referência. Não peça "me traga o contrato do POST /products" — deixe o assistente identificar o domínio e abrir a referência certa. O contrato de campo vem do Spec API.
• Teste em sandbox antes de produção. A skill lembra disso, mas vale reforçar: gumgaToken de sandbox retorna 401 em produção e vice-versa.
• Em brownfield, ofereça o repositório para inspeção. Se você não souber dizer qual HTTP client / retry / logging o projeto usa, peça para a skill ler o pom.xml / package.json / pyproject.toml antes de gerar código.

Referências

• Spec API (contrato oficial): https://developers.anymarket.com.br/specs
• Docs de desenvolvedor: https://developers.anymarket.com.br/
• Repositório interno da skill: anymarket-backoffice-api-guide (com SKILL.md + pasta references/ por domínio).