ANYMARKET Backoffice API Guide

Skill que le enseña al asistente de IA a integrar correctamente con la API v2 Backoffice de ANYMARKET. Cubre autenticación, entornos, los 17 dominios de la API (productos, SKUs, pedidos, stock, precios, listings, NF-e, callbacks, campañas, monitoring, users, roles y más), el grafo de dependencia entre dominios, patrón de error, paginación, rate limit y el flujo greenfield vs brownfield.

Público objetivo: desarrolladores integrando ERP (TOTVS, Winthor, Protheus, SAP, ERP propio) con ANYMARKET. No es una skill para usuario final — el foco es código de integración correcto en el primer intento.

Qué resuelve

Las integraciones con API tienen dos trampas clásicas:

1. Escribir un request "de memoria" — nombre de campo equivocado, campo obligatorio faltante, verbo HTTP incorrecto para una transición de estado. Cuesta un 400/422 al instante.
2. Ignorar el contexto del proyecto — introducir un segundo HTTP client, una segunda estrategia de retry o un segundo formato de log en un codebase que ya tiene todo eso resuelto. Cuesta un code review reprobado.

La skill blinda contra ambas: fuerza consultar el Spec API antes de generar código y distingue greenfield (proyecto nuevo) de brownfield (proyecto existente) ya en el primer mensaje.

Cómo invocarla

Dos formas:

1. Comando: escribe /anymarket-backoffice-api-guide en tu harness (el cliente/IDE de IA que uses) — el formato exacto del comando puede variar de un harness a otro.
2. Lenguaje natural: cualquier pedido relacionado con integración ERP ↔ ANYMARKET dispara la skill. Ejemplos:
   • "Necesito integrar el registro de productos con ANYMARKET vía TOTVS."
   • "¿Cómo implemento polling de pedidos usando /orders/feeds?"
   • "¿Qué necesito enviar para publicar un SKU en Mercado Libre?"
   • "¿Qué campos son obligatorios en POST /products?"
   • "Emisión de NF-e mediante la API de ANYMARKET."

Qué preguntará la skill antes de actuar

La skill no hace la primera llamada ni genera código sin confirmar tres puntos — a propósito, para evitar retrabajo:

1. Entorno — Sandbox (sandbox-api.anymarket.com.br/v2) o Producción (api.anymarket.com.br/v2)? Un token de sandbox devuelve 401 en producción y viceversa.
2. Autenticación — ¿Está disponible el gumgaToken del entorno elegido? ¿Qué valor va en el header platform (TOTVS, WINTHOR, ERP_PROPRIO, etc.)? Sin los dos headers = 401 en cada request.
3. Contexto del proyecto (Greenfield vs Brownfield) — ¿Proyecto nuevo o integración en un codebase existente? Si es brownfield, abre un checklist para descubrir qué reutilizar (HTTP client, config, retry, logging, etc.) antes de escribir una sola línea de código.

Responder las tres de una vez ahorra varias idas y vueltas.

Regla de oro — spec antes del código

La skill carga reglas de negocio y ruteo, no el contrato de campos de cada endpoint. Para cualquier request nuevo, el orden es:

1. Abrir la sub-referencia del dominio (mapa abajo).
2. Buscar el contrato en el Spec API antes de codear: GET https://developers.anymarket.com.br/specs/backoffice/pt-BR/operations/<operationId>.json — leer requestBody.application/json.schema (especialmente el array required) y usar los examples como payload base.
3. Escribir el código a partir del schema resuelto.
4. Llamar a la API solo para testear — nunca para descubrir el contrato por prueba y error.

Casos reales que la skill previene:

• El nombre del producto es title, no name.
• priceFactor debe ser > 0 incluso cuando el precio es por SKU.
• Las transiciones de estado del pedido son PUT con paths (/faturado, /enviado, /concluido, /cancelado), no POST.
• El limit de paginación es 5–100; los totales están en page.totalPages / page.number.
• Los headers gumgaToken y platform son obligatorios en todas las llamadas.

Dominios cubiertos (17)

La skill mapea cada dominio a una sub-referencia (overview.md en cada carpeta), que el asistente abre bajo demanda:

Catálogo (prerrequisitos del producto)

Dominio	Cubre
brands	CRUD de marcas
categories	CRUD de categorías
variations	Tipos y valores de variación (para producto variable)

Producto y SKU

Dominio	Cubre
products	Producto simple, producto variable, lectura, actualización
skus	Agregar variante, actualizar EAN/título/precio, desactivar SKU
images	Upload, estado de procesamiento, eliminación de imágenes

Post-catálogo

Dominio	Cubre
stock	Stock, ubicaciones (MultiCDs), reservas
listings	Anuncios en marketplaces, transmisiones, feeds
prices	Precios por marketplace, en lote

Pedidos y post-venta

Dominio	Cubre
orders	Leer/crear/actualizar pedidos, transiciones de estado, feeds
returns	Devoluciones
fiscal-documents	Envío de NF-e, lectura de documentos fiscales

Configuración y apoyo

Dominio	Cubre
callbacks	Webhooks de notificación
campaigns	Campañas de descuento
monitoring	Errores de integración
users	Usuarios
roles	Perfiles de acceso (permisos)

Referencias transversales

Tema	Dónde
Paginación, filtros, ordenación	references/pagination.md
Rate limit, throttling, retry	references/rate-limit.md
Errores HTTP (400, 401, 404, 422, 429)	references/errors.md
Glosario (términos y siglas de la API)	references/glossary.md

Grafo de dependencia — catálogo

La API de ANYMARKET impone un orden de registro. Crear un producto sin prerrequisitos devuelve 422. La skill sigue este grafo:

brands       ──┐
categories   ──┼──▶  products  ──▶  skus  ──▶  listings
variations   ──┘        │              │            │
  (solo variables)      └──▶  images   │            ▼
                                       └──▶  stock
                                       └──▶  prices

Orden recomendado de integración:

1. Brands
2. Categories
3. Variations (si producto variable)
4. Products
5. SKUs adicionales (post-creación, si es necesario)
6. Images
7. Stock
8. Listings (publicación en marketplaces)

Patrón de feed (polling)

Varios dominios exponen feeds para detectar cambios sin depender de un webhook. El patrón siempre es el mismo:

1. GET /{dominio}/feeds          → array de {id, token} no leídos
2. Procesar cada item
3. PUT /{dominio}/feeds/batch    → marcarlos todos como leídos de una vez
   O
   PUT /{dominio}/feeds/{id}     → marcar individualmente
4. Repetir

Los items no marcados como leídos permanecen disponibles por 30 días.

Feeds cubiertos:

• /orders/feeds — pedidos nuevos y cambios
• /transmissions/feeds — cambios en listings
• /transmissions-price/feeds — cambios de precio
• /reservations/feeds — reservas de stock

Instalación de la skill

1. Clona el repositorio interno anymarket-backoffice-api-guide.
2. Copia la carpeta al directorio de skills que tu harness lee (la ruta por defecto varía según el harness — consulta su documentación oficial).
3. Recarga el harness (reinicio, comando de reload o equivalente).
4. Confirma que la skill aparece en la lista de skills disponibles del harness (/help, panel de configuración, etc., según el caso).

Buenas prácticas al usarla

• Responde las tres preguntas iniciales de una vez. Entorno, autenticación y greenfield/brownfield — ahorra varias idas y vueltas.
• Deja que la skill abra la sub-referencia. No pidas "tráeme el contrato de POST /products" — deja que el asistente identifique el dominio y abra la referencia correcta. El contrato de campos viene del Spec API.
• Prueba en sandbox antes de producción. La skill lo recuerda, pero vale reforzarlo: un gumgaToken de sandbox devuelve 401 en producción y viceversa.
• En brownfield, ofrece el repositorio para inspección. Si no sabes qué HTTP client / retry / logging usa el proyecto, pídele a la skill que lea pom.xml / package.json / pyproject.toml antes de generar código.

Referencias

• Spec API (contrato oficial): https://developers.anymarket.com.br/specs
• Docs de desarrollador: https://developers.anymarket.com.br/
• Repositorio interno de la skill: anymarket-backoffice-api-guide (con SKILL.md + carpeta references/ por dominio).