Spec API — OpenAPI por operationId

A Spec API expõe os contratos OpenAPI das APIs ANYMARKET de forma machine-readable, para que ferramentas e automações consumam endpoints, parâmetros, corpos de requisição e exemplos por operationId — sem fixar (hardcode) objetos no código e sem depender de uma versão congelada da documentação.

Para humano? Use os guias e a API Reference. A Spec API é para consumo programático (ex.: uma automação que monta a request a partir do contrato).

Características

• Pública, sem autenticação: os endpoints /specs/* respondem a GET direto, sem token.
• Sempre atual: reflete a versão vigente do contrato das APIs.
• $ref resolvido: no fragmento de uma operação, os schemas de request/response já vêm desreferenciados (objeto inline).
• Por língua: cada API está disponível em pt-BR, en e es; escolha a língua no URL. Se a língua não estiver disponível para uma API, use pt-BR como fallback.

Base URL

https://developers.anymarket.com.br/specs

APIs e línguas disponíveis

São 9 combinações (id x língua) publicadas:

id	Língua	URL do spec completo
backoffice	pt-BR	/specs/backoffice.pt-BR.json
backoffice	en	/specs/backoffice.en.json
backoffice	es	/specs/backoffice.es.json
marketplace	pt-BR	/specs/marketplace.pt-BR.json
marketplace	en	/specs/marketplace.en.json
marketplace	es	/specs/marketplace.es.json
remote	pt-BR	/specs/remote.pt-BR.json
remote	en	/specs/remote.en.json
remote	es	/specs/remote.es.json

Endpoints

Método / rota	Retorna
GET /specs/index.json	Manifesto: lista todas as combinações (id, lang, nº de operações, operationHrefs, url do spec).
GET /specs/{id}.{lang}.json	Documento OpenAPI completo da API na língua especificada.
GET /specs/{id}/{lang}/operations.json	Lista de operações para esse par (id, lang): operationId, método, path, summary, tags e href (caminho do fragmento resolvido).
GET /specs/{id}/{lang}/operations/{slug}.json	Referência resolvida da operação: método, path, parâmetros, requestBody (schema com $ref desreferenciado) + exemplos, e responses.

Importante — use o href retornado pela API, não adivinhe o slug. O campo href em /specs/{id}/{lang}/operations.json já contém o caminho completo relativo à raiz do site (com o prefixo specs/, o .json e o slug exato) — resolva-o contra https://developers.anymarket.com.br/, sem concatenar /specs de novo. operationIds com caracteres especiais são slugificados; consumir o href diretamente elimina qualquer ambiguidade.

Exemplo de consumo (por operationId e língua)

# 1) Descobrir as combinações disponíveis (id x lang) e suas operações
curl -s https://developers.anymarket.com.br/specs/index.json

# 2) Escolher a língua e listar as operações — capturar o href da operação desejada
#    (substitua "post-products" pelo operationId real; ajuste a língua conforme necessário)
LANG=en
ROOT=https://developers.anymarket.com.br

curl -s "$ROOT/specs/backoffice/$LANG/operations.json" \
  | jq '.[] | select(.operationId == "post-products") | .href'
# exemplo de saída: "specs/backoffice/en/operations/post-products.json"

# 3) Buscar a referência resolvida usando o href retornado no passo 2
#    O href é relativo à RAIZ do site (já vem com o prefixo "specs/", o .json e o
#    slug correto — nunca reconstrua o caminho nem concatene com /specs de novo)
HREF=$(curl -s "$ROOT/specs/backoffice/$LANG/operations.json" \
  | jq -r '.[] | select(.operationId == "post-products") | .href')
curl -s "$ROOT/$HREF"

Fallback de língua: se a língua desejada não estiver disponível para um par (id, lang), use pt-BR. Consulte o index.json para confirmar quais línguas existem por id.

A resposta do passo 3 traz tudo que a integração precisa para montar a chamada:

{
  "operationId": "post-brands",
  "method": "POST",
  "path": "/brands",
  "summary": "...",
  "parameters": [ /* name, in, required, schema (resolvido) */ ],
  "requestBody": {
    "application/json": {
      "schema": { /* BrandAdd inline (sem $ref) */ },
      "examples": { /* exemplos de payload */ }
    }
  },
  "responses": { "200": { "schema": { /* resolvido */ } } }
}

Padrão recomendado: buscar a referência a cada uso (cacheando localmente se necessário) e montar a request a partir do contrato, em vez de manter os objetos fixos — assim a integração acompanha a API automaticamente quando o contrato muda.