{
  "openapi": "3.0.3",
  "info": {
    "title": "PrintBee - Designs do Cliente",
    "version": "1.1.0",
    "description": "Os **designs** da sua conta — as estampas que você montou no portal sobre um produto PrintBee — para cadastrar e manter os produtos da sua **loja virtual**: a lista traz o básico e a foto de capa; os detalhes de cada design trazem as variações à venda (com o `sku` que o pedido usa), o preço que você definiu, as medidas e as fotos.\n\n**Autenticação:** envie o header `Authorization: Bearer <token>` em cada requisição. O token é obtido via `POST /api/Auth/Token` com client_credentials (seção **Autenticação**). A credencial só enxerga os designs da própria conta.\n\n**Quais designs aparecem:** os ativos com ao menos uma variação ativa com preço de venda (aba **Preços** do design no portal). Nos detalhes vêm só as variações à venda com preço; as fotos são as marcadas na aba **Publicar na loja**, na ordem de lá — a primeira é a capa. Em caso raro um design da lista responde `204` nos detalhes (o escopo de cores/tamanhos mudou e a variação com preço saiu dele): trate-o como fora de venda.\n\n**Fotos:** são as guardadas no portal. Se você editar o design, gere as fotos de novo na aba **Publicar na loja** — a API devolve sempre as guardadas.\n\n**Campos nulos:** campo sem valor (ex.: `promotionalPrice` sem promoção, `color` em produto sem cor, `coverPhotoUrl` antes de as fotos serem geradas) não vem na resposta — trate ausente como nulo.\n\n## Jornada: sua loja vendendo os designs\n\nSua loja carrega os designs pela API, vende, e manda o pedido de volta com o `sku` da variação vendida. O item do pedido entra já com o design, a variação e a arte.\n\n![Diagrama de sequência da loja vendendo os designs: sua loja chama GET /api/Customers/Designs/Catalog e recebe a lista com a foto de capa; para cada design, chama GET /api/Customers/Designs/Catalog/{id} e recebe as variações com o sku de cada uma e as fotos; o comprador compra na sua loja; sua loja envia POST /api/Customers/Integrations/Orders com items[].sku igual ao sku da variação; a API reconhece o SKU, o item entra com o design, a variação e a arte, e responde 202 com o rascunho; o rascunho chega ao portal, onde sua equipe confere o frete e converte em pedido de produção. SKU que não é de um design seu entra sem vínculo e é vinculado no portal.](/openapi/diagrams/jornada-loja-designs.svg)\n\n1. **Liste os designs** — `GET /api/Customers/Designs/Catalog`, paginado (até 50 por página): percorra de `currentPage` 1 até `totalPages`. Cada item traz `id`, `code`, `name`, `productName` e `coverPhotoUrl` — o suficiente para a vitrine.\n2. **Leia os detalhes** — `GET /api/Customers/Designs/Catalog/{id}` para cada design: `descriptionHtml`, `attributes`, `variations` e `photos`.\n3. **Cadastre na sua loja** — um produto por design e uma variação por item de `variations`: `values` na ordem de `attributes`, `price`, `promotionalPrice` e medidas para o frete. **Guarde o `sku` de cada variação** no produto da sua loja.\n4. **Venda e crie o pedido** — quando o comprador fechar a compra, envie `POST /api/Customers/Integrations/Orders` (seção **Pedidos**) com um item por variação vendida, `items[].sku` = o `sku` dela. Campos e exemplo completo na descrição desse endpoint.\n5. **O item entra com o design** — a API reconhece o SKU: o item do rascunho já sai vinculado ao design, à variação e à arte, sem vínculo manual no portal.\n6. **Conversão e acompanhamento** — o rascunho é convertido em pedido de produção no portal, onde sua equipe confere o frete. Acompanhe pelos webhooks `integration_order.*` e `order.*` (seção **Webhooks**) ou por `GET /api/Customers/Orders/{identificador}`.\n\n**Item do pedido de um design:**\n\n```json\n{\n  \"name\": \"Camiseta Abelha · Branca · P\",\n  \"sku\": \"D3-0000002-1A2B3C4D\",\n  \"quantity\": 2,\n  \"unitPrice\": 110.00\n}\n```\n\n**Mantendo a loja em dia:** preço, fotos e variações mudam no portal. Sincronize de tempos em tempos (por exemplo, de hora em hora). Design que sumiu da lista — desativado, excluído ou sem preço — deve sair de venda na sua loja (os detalhes dele respondem `204`); variação que sumiu de `variations` também.\n\n**Item sem vínculo:** SKU que não é de um design seu, ou de variação que o design não vende mais (fora do escopo de cores/tamanhos ou sem estampa aplicável), entra no rascunho **sem vínculo** — sua equipe vincula no portal antes de converter. Venda já feita de variação que perdeu o preço, ou de design desativado depois, ainda entra com o design: o pedido é de algo que você vendeu. O `unitPrice` do item é o valor que você cobrou na sua loja (referência); a produção segue a tabela PrintBee.\n\n**Mesma regra da Nuvemshop:** variações, SKU e medidas saem do mesmo montador que a publicação de design na Nuvemshop usa — um design vendido nas duas lojas tem o mesmo SKU nas duas.",
    "contact": {
      "name": "Suporte PrintBee",
      "url": "https://api.printbee.com.br"
    }
  },
  "servers": [
    {
      "url": "https://api.printbee.com.br",
      "description": "Produção"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/Customers/Designs/Catalog": {
      "get": {
        "tags": [
          "Designs"
        ],
        "summary": "Listar designs",
        "description": "Designs ativos da sua conta com ao menos uma variação com preço de venda — o básico e a foto de capa, para a vitrine da sua loja. Variações e fotos vêm em `GET /api/Customers/Designs/Catalog/{id}`. Restringe automaticamente à conta da credencial.\n\nCredencial sem conta válida recebe a lista vazia (`200`, `items: []`), nunca os designs de outra conta.\n\n**Tabela de erros:**\n\n| Código | HTTP | Descrição |\n|--------|------|----------|\n| - | 401 | Token ausente ou inválido. Obtenha novo token via POST /api/Auth/Token |\n| - | 403 | Acesso negado. Endpoint exclusivo para a credencial de API (ApiClient) e a área do cliente |",
        "operationId": "getDesignCatalog",
        "parameters": [
          {
            "name": "pageNumber",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Número da página (inicia em 1). Página além de totalPages devolve a página 1 — confira currentPage na resposta"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            },
            "description": "Designs por página (máximo 50; acima disso vale 50)"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "CreatedAt DESC",
                "CreatedAt ASC",
                "Name ASC",
                "Name DESC"
              ],
              "default": "CreatedAt DESC"
            },
            "description": "Ordenação. Valor fora da lista vale o padrão (CreatedAt DESC)"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Busca pelo nome do design — palavras em qualquer ordem, sem diferenciar acento"
          }
        ],
        "responses": {
          "200": {
            "description": "Designs da página",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignCatalogPaginatedResponse"
                },
                "example": {
                  "items": [
                    {
                      "id": "3f2b6c1e-8a4d-4c2b-9f1e-2d7a5b9c0e11",
                      "code": "D000003",
                      "name": "Camiseta Abelha",
                      "productName": "Camiseta Unissex Algodão 30.1",
                      "coverPhotoUrl": "https://cdn.exemplo.com/designs/d000003/branca-frente.webp"
                    }
                  ],
                  "currentPage": 1,
                  "totalPages": 1,
                  "pageSize": 20,
                  "totalCount": 1,
                  "hasPrevious": false,
                  "hasNext": false
                }
              }
            }
          },
          "401": {
            "description": "Token inválido ou ausente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorPayload"
                }
              }
            }
          },
          "403": {
            "description": "Acesso negado - endpoint exclusivo para a credencial de API e a área do cliente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorPayload"
                }
              }
            }
          }
        }
      }
    },
    "/api/Customers/Designs/Catalog/{id}": {
      "get": {
        "tags": [
          "Designs"
        ],
        "summary": "Detalhes do design",
        "description": "Tudo para cadastrar o design como produto na sua loja: descrição, atributos, **variações à venda** (com o `sku` que você manda em `items[].sku` do `POST /api/Customers/Integrations/Orders`), preço, medidas e **fotos**.\n\nResponde `204` sem conteúdo quando o design não é da sua conta, foi desativado ou excluído, ou não tem mais variação à venda com preço — tire-o de venda na sua loja.\n\n**Tabela de erros:**\n\n| Código | HTTP | Descrição |\n|--------|------|----------|\n| - | 204 | Design fora da sua conta, desativado/excluído ou sem variação à venda com preço |\n| - | 401 | Token ausente ou inválido. Obtenha novo token via POST /api/Auth/Token |\n| - | 403 | Acesso negado. Endpoint exclusivo para a credencial de API (ApiClient) e a área do cliente |",
        "operationId": "getDesignCatalogDetail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id do design (campo id da lista)"
          }
        ],
        "responses": {
          "200": {
            "description": "Detalhes do design",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignCatalogDetail"
                },
                "example": {
                  "id": "3f2b6c1e-8a4d-4c2b-9f1e-2d7a5b9c0e11",
                  "code": "D000003",
                  "name": "Camiseta Abelha",
                  "descriptionHtml": "<p>Camiseta com a estampa da abelha.</p>",
                  "productName": "Camiseta Unissex Algodão 30.1",
                  "attributes": [
                    "Cor",
                    "Tamanho"
                  ],
                  "variations": [
                    {
                      "sku": "D3-0000002-1A2B3C4D",
                      "values": [
                        "Branca",
                        "P"
                      ],
                      "color": "Branca",
                      "price": 110,
                      "promotionalPrice": 99.9,
                      "weightKg": 0.2,
                      "widthCm": 30,
                      "heightCm": 2,
                      "depthCm": 40
                    },
                    {
                      "sku": "D3-0000003-1A2B3C4D",
                      "values": [
                        "Branca",
                        "M"
                      ],
                      "color": "Branca",
                      "price": 110,
                      "weightKg": 0.22,
                      "widthCm": 32,
                      "heightCm": 2,
                      "depthCm": 42
                    }
                  ],
                  "photos": [
                    {
                      "url": "https://cdn.exemplo.com/designs/d000003/branca-frente.webp",
                      "color": "Branca",
                      "placement": "Frente"
                    },
                    {
                      "url": "https://cdn.exemplo.com/designs/d000003/branca-costas.webp",
                      "color": "Branca",
                      "placement": "Costas"
                    }
                  ]
                }
              }
            }
          },
          "204": {
            "description": "Design fora da sua conta, desativado/excluído ou sem variação à venda com preço"
          },
          "401": {
            "description": "Token inválido ou ausente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorPayload"
                }
              }
            }
          },
          "403": {
            "description": "Acesso negado - endpoint exclusivo para a credencial de API e a área do cliente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorPayload"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Token obtido via POST /api/Auth/Token. Header: Authorization: Bearer <token>"
      }
    },
    "schemas": {
      "DesignCatalogPaginatedResponse": {
        "type": "object",
        "description": "Resposta paginada da lista de designs",
        "properties": {
          "items": {
            "type": "array",
            "description": "Designs da página atual",
            "items": {
              "$ref": "#/components/schemas/DesignCatalogListItem"
            }
          },
          "currentPage": {
            "type": "integer",
            "description": "Número da página retornada"
          },
          "pageSize": {
            "type": "integer",
            "description": "Designs por página (máximo 50)"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total de designs que atendem aos filtros"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total de páginas disponíveis"
          },
          "hasPrevious": {
            "type": "boolean",
            "description": "Existe página anterior à atual"
          },
          "hasNext": {
            "type": "boolean",
            "description": "Existe página seguinte à atual"
          }
        }
      },
      "DesignCatalogListItem": {
        "type": "object",
        "description": "Design na lista: o básico e a foto de capa",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identificador do design — use em GET /api/Customers/Designs/Catalog/{id}"
          },
          "code": {
            "type": "string",
            "description": "Código do design no portal",
            "example": "D000003"
          },
          "name": {
            "type": "string",
            "description": "Nome do design (título do produto na sua loja)"
          },
          "productName": {
            "type": "string",
            "description": "Produto PrintBee em que o design é estampado"
          },
          "coverPhotoUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Foto de capa (a primeira marcada no portal); ausente enquanto as fotos não forem geradas"
          }
        }
      },
      "DesignCatalogDetail": {
        "type": "object",
        "description": "Design da sua conta como produto da loja virtual",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identificador do design"
          },
          "code": {
            "type": "string",
            "description": "Código do design no portal",
            "example": "D000003"
          },
          "name": {
            "type": "string",
            "description": "Nome do design (título do produto na sua loja)"
          },
          "descriptionHtml": {
            "type": "string",
            "description": "Descrição em HTML sanitizado — pode ir direto para a página do produto"
          },
          "productName": {
            "type": "string",
            "description": "Produto PrintBee em que o design é estampado"
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nomes dos atributos das variações, Cor primeiro (ex.: [\"Cor\", \"Tamanho\"]). Lista vazia quando o produto não tem variação"
          },
          "variations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignCatalogVariation"
            },
            "description": "Variações à venda: só as que têm preço de venda no portal"
          },
          "photos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignCatalogPhoto"
            },
            "description": "Fotos marcadas na aba Publicar na loja, na ordem de lá; a primeira é a capa. Vazia enquanto as fotos não forem geradas no portal"
          }
        }
      },
      "DesignCatalogVariation": {
        "type": "object",
        "description": "Variação à venda do design",
        "properties": {
          "sku": {
            "type": "string",
            "description": "SKU PrintBee da variação do design (D{NSU}-{SKU da variação}-{marca da sua conta}). Envie este valor em items[].sku do POST /api/Customers/Integrations/Orders: o item entra já com o design, a variação e a arte",
            "example": "D3-0000002-1A2B3C4D"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Valores dos atributos, na ordem de attributes (ex.: [\"Branca\", \"P\"]). \"Único\" quando a variação não tem o atributo"
          },
          "color": {
            "type": "string",
            "nullable": true,
            "description": "Cor da variação (liga a foto da mesma cor); ausente quando o produto não varia por cor"
          },
          "price": {
            "type": "number",
            "format": "decimal",
            "description": "Preço de venda definido por você no portal"
          },
          "promotionalPrice": {
            "type": "number",
            "format": "decimal",
            "nullable": true,
            "description": "Preço promocional; ausente sem promoção"
          },
          "weightKg": {
            "type": "number",
            "format": "decimal",
            "description": "Peso em kg (0 = não cadastrado)"
          },
          "widthCm": {
            "type": "number",
            "format": "decimal",
            "description": "Largura em cm"
          },
          "heightCm": {
            "type": "number",
            "format": "decimal",
            "description": "Altura em cm"
          },
          "depthCm": {
            "type": "number",
            "format": "decimal",
            "description": "Profundidade (comprimento) em cm"
          }
        }
      },
      "DesignCatalogPhoto": {
        "type": "object",
        "description": "Foto do design — mockup na cor ou foto enviada por você",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL pública da foto"
          },
          "color": {
            "type": "string",
            "nullable": true,
            "description": "Cor mostrada; ausente = foto geral"
          },
          "placement": {
            "type": "string",
            "description": "Lado ou área estampada (ex.: Frente)"
          }
        }
      },
      "ErrorPayload": {
        "type": "object",
        "description": "Resposta padrão de erro da API",
        "required": [
          "code",
          "errors"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Código HTTP do erro (400, 401, 403, etc.)"
          },
          "errors": {
            "type": "array",
            "description": "Lista de erros detalhados",
            "items": {
              "type": "object",
              "properties": {
                "errorCode": {
                  "type": "string",
                  "description": "Código interno do erro (ex: ATH0008, CRD0003)"
                },
                "message": {
                  "type": "string",
                  "description": "Mensagem descritiva do erro"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Designs",
      "description": "Designs da sua conta para cadastrar e manter os produtos da sua loja virtual."
    }
  ]
}