Produtos

CRUD do catálogo de produtos via API Key — para sincronizar com ERP/e-commerce. Mesmos dados e regras do cadastro feito no painel; paginação por página (não por cursor).

GET /merchant/products → 200

Requer scope READ_PRODUCTS.

Query:

Campo	Tipo	Obrigatório	Regras / Default
q	string	não	busca em name, description e externalRef
status	enum	não	ACTIVE | INACTIVE
page	int	não	default 1
pageSize	int	não	máx 100, default 20

Resposta (200):

{
  "items": [
    {
      "id": "uuid",
      "externalRef": "SKU-123",
      "name": "Camiseta azul P",
      "description": "string | null",
      "unitPriceCents": 4990,
      "currency": "BRL",
      "status": "ACTIVE",
      "createdAt": "2026-07-16T12:00:00.000Z",
      "updatedAt": "2026-07-16T12:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1
}

POST /merchant/products → 201

Requer scope WRITE_PRODUCTS.

Body:

Campo	Tipo	Obrigatório	Regras / Default
externalRef	string	não	máx 255; único por empresa — repetido gera 409
name	string	sim	1–255
description	string	não	máx 500
unitPriceCents	int	sim	≥ 0
currency	string	não	3 chars; default "BRL"
metadata	object	não	pares chave/valor arbitrários

Resposta (201): o produto criado, no formato de detalhe (item de listagem + metadata).

Exemplo — criar (ou reconhecer via 409) um produto do seu catálogo:

Criar produto

curl -s -X POST https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/products \
  -H "X-Api-Key: <SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "SKU-123",
    "name": "Camiseta azul P",
    "unitPriceCents": 4990
  }'

GET /merchant/products/:id → 200

Requer scope READ_PRODUCTS. De outra empresa ou inexistente → 404.

PATCH /merchant/products/:id → 200

Requer scope WRITE_PRODUCTS. Todos os campos do body são opcionais (mesmas regras do POST), mas ao menos um precisa ser enviado (400 se o body estiver vazio). externalRef continua único por empresa (409 em conflito). Não encontrado → 404.

Exemplo — reajustar preço e desativar um produto:

Atualizar produto

curl -s -X PATCH https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/products/<PRODUCT_ID> \
  -H "X-Api-Key: <SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "unitPriceCents": 5490, "status": "INACTIVE" }'

Dica

Não há idempotencyKey no POST: para evitar duplicar produtos em re-tentativas, use um externalRef estável e trate o 409 de conflito como “já existe” (não é um erro fatal).