Skip to main content

ANYMARKET Backoffice API Guide

Skill that teaches the AI assistant how to integrate correctly with the ANYMARKET v2 Backoffice API. It covers authentication, environments, the 17 API domains (products, SKUs, orders, stock, prices, listings, NF-e, callbacks, campaigns, monitoring, users, roles and more), the domain dependency graph, error pattern, pagination, rate limit and the greenfield vs brownfield flow.

Target audience: developers integrating an ERP (TOTVS, Winthor, Protheus, SAP, custom ERP) with ANYMARKET. This is not an end-user skill — the focus is correct integration code on the first attempt.

What it solves​

API integrations have two classic pitfalls:

  1. Writing a request "from memory" — wrong field name, missing required field, wrong HTTP verb for a status transition. Costs a 400/422 on the spot.
  2. Ignoring project context — introducing a second HTTP client, a second retry strategy or a second log format into a codebase that already has all of that. Costs a failed code review.

The skill guards against both: it forces a Spec API lookup before generating code and distinguishes greenfield (new project) from brownfield (existing project) in the very first message.

How to invoke​

Two ways:

  1. Command: type /anymarket-backoffice-api-guide in your harness (the AI client/IDE you use) — the exact command format may vary from harness to harness.
  2. Natural language: any request related to ERP ↔ ANYMARKET integration triggers the skill. Examples:
    • "I need to integrate product registration with ANYMARKET via TOTVS."
    • "How do I implement order polling using /orders/feeds?"
    • "What do I have to send to publish a SKU on Mercado Livre?"
    • "Which fields are required in POST /products?"
    • "NF-e issuance through the ANYMARKET API."

What the skill will ask before acting​

The skill won't fire the first call or generate code without confirming three points — by design, to prevent rework:

  1. Environment — Sandbox (sandbox-api.anymarket.com.br/v2) or Production (api.anymarket.com.br/v2)? A sandbox token returns 401 on production and vice-versa.
  2. Authentication — Is the gumgaToken for the chosen environment available? Which value goes in the platform header (TOTVS, WINTHOR, ERP_PROPRIO, etc.)? Without both headers = 401 on every request.
  3. Project context (Greenfield vs Brownfield) — New project or integration into an existing codebase? If brownfield, it opens a checklist to discover what to reuse (HTTP client, config, retry, logging etc.) before writing a single line of code.

Answering all three at once saves several round trips.

Golden rule — spec before code​

The skill carries business rules and routing, not the field contract of each endpoint. For any new request, the order is:

  1. Open the domain sub-reference (map below).
  2. Look up the contract in the Spec API before coding: GET https://developers.anymarket.com.br/specs/backoffice/pt-BR/operations/<operationId>.json — read requestBody.application/json.schema (especially the required array) and use the examples as a base payload.
  3. Write the code from the resolved schema.
  4. Call the API only to test — never to discover the contract by trial and error.

Real cases the skill prevents:

  • The product name is title, not name.
  • priceFactor must be > 0 even when pricing is per SKU.
  • Order status transitions are PUT with paths (/faturado, /enviado, /concluido, /cancelado), not POST.
  • Pagination limit is 5–100; totals live in page.totalPages / page.number.
  • Headers gumgaToken and platform are mandatory on every call.

Covered domains (17)​

The skill maps each domain to a sub-reference (overview.md in each folder), which the assistant opens on demand:

Catalog (product prerequisites)​

DomainCovers
brandsCRUD of brands
categoriesCRUD of categories
variationsVariation types and values (for variable products)

Product and SKU​

DomainCovers
productsSimple product, variable product, read, update
skusAdd variant, update EAN/title/price, deactivate SKU
imagesUpload, processing status, image removal

Post-catalog​

DomainCovers
stockStock, locations (MultiCDs), reservations
listingsMarketplace listings, transmissions, feeds
pricesPrices per marketplace, in bulk

Orders and after-sales​

DomainCovers
ordersRead/create/update orders, status transitions, feeds
returnsReturns
fiscal-documentsNF-e submission, reading fiscal documents

Configuration and support​

DomainCovers
callbacksNotification webhooks
campaignsDiscount campaigns
monitoringIntegration errors
usersUsers
rolesAccess profiles (permissions)

Cross-cutting references​

TopicWhere
Pagination, filters, sortingreferences/pagination.md
Rate limit, throttling, retryreferences/rate-limit.md
HTTP errors (400, 401, 404, 422, 429)references/errors.md
Glossary (API terms and acronyms)references/glossary.md

Dependency graph — catalog​

The ANYMARKET API enforces a registration order. Creating a product without its prerequisites returns 422. The skill follows this graph:

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

Recommended integration order:

  1. Brands
  2. Categories
  3. Variations (if variable product)
  4. Products
  5. Additional SKUs (post-creation, if needed)
  6. Images
  7. Stock
  8. Listings (publishing to marketplaces)

Feed pattern (polling)​

Several domains expose feeds to detect changes without depending on a webhook. The pattern is always the same:

1. GET /{domain}/feeds          → array of unread {id, token}
2. Process each item
3. PUT /{domain}/feeds/batch    → mark them all as read at once
   OR
   PUT /{domain}/feeds/{id}     → mark individually
4. Repeat

Items not marked as read remain available for 30 days.

Feeds covered:

  • /orders/feeds — new orders and changes
  • /transmissions/feeds — listing changes
  • /transmissions-price/feeds — price changes
  • /reservations/feeds — stock reservations

Installing the skill​

  1. Clone the internal anymarket-backoffice-api-guide repository.
  2. Copy the folder into the skills directory your harness reads (the default path varies per harness — check the official docs).
  3. Reload the harness (restart, reload command, or equivalent).
  4. Confirm the skill shows up in your harness's list of available skills (/help, settings panel, etc., depending on the case).

Best practices when using it​

  • Answer the three initial questions in one go. Environment, authentication and greenfield/brownfield — it saves several round trips.
  • Let the skill open the sub-reference. Don't say "bring me the contract of POST /products" — let the assistant identify the domain and open the right reference. The field contract comes from the Spec API.
  • Test in sandbox before production. The skill reminds you, but worth reinforcing: a sandbox gumgaToken returns 401 on production and vice-versa.
  • In brownfield, offer the repository for inspection. If you can't tell which HTTP client / retry / logging the project uses, ask the skill to read pom.xml / package.json / pyproject.toml before generating code.

References​