{
  "openapi": "3.1.0",
  "info": {
    "title": "API pública de catálogo e preços - Automação Curitiba",
    "version": "1.0.0",
    "description": "API REST pública da loja https://automacaocuritiba.com.br, a mesma que a loja usa para exibir etiquetas e produtos. Não há autenticação nem chave de API: qualquer cliente pode chamar (`security: []`). A leitura e o cálculo de preço (POST) não têm efeito colateral e são seguros de repetir. A única operação que grava é `POST /cart/drafts`, que guarda um carrinho para o cliente abrir por link (veja `createCartDraft`). Valores monetários em centavos de real. Respostas de sucesso vêm no envelope {\"data\": ...}; erros vêm como {\"error\": \"mensagem\"} com o status HTTP correspondente. CORS aberto (`*`) para GET e POST. Listas usam paginação por `limit` e `offset`. Versionamento: a versão está no caminho (/api/v1); mudanças que quebram o contrato sairão em uma nova versão no caminho (/api/v2), sem alterar a v1. Política de depreciação: um recurso só é removido de uma versão depois de anunciado nesta especificação (campo `deprecated: true` na operação) e de passar a responder com os cabeçalhos `Deprecation` e `Sunset` (RFC 9745 e RFC 8594), com pelo menos 90 dias entre o aviso e a remoção. Hoje nada está depreciado. Limite de uso: 120 requisições por minuto por IP. Ao passar disso a resposta é 429 com o cabeçalho Retry-After (segundos até poder tentar de novo). As respostas de leitura são cacheáveis por 60 s. Um 502 significa que a loja está indisponível; tente de novo em instantes. Carrinho, checkout e conta não fazem parte desta API. Guia com exemplos: https://automacaocuritiba.com.br/developers.",
    "contact": {
      "name": "Automação Curitiba",
      "url": "https://automacaocuritiba.com.br/contato"
    }
  },
  "servers": [
    {
      "url": "https://automacaocuritiba.com.br/api/v1",
      "description": "Produção"
    }
  ],
  "paths": {
    "/catalog/knives": {
      "get": {
        "operationId": "listKnives",
        "summary": "Lista as facas (medidas de etiqueta) ativas",
        "description": "Cada faca é uma combinação de largura × altura (mm), formato e número de colunas no rolo.",
        "responses": {
          "200": {
            "description": "Facas ativas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "width": {
                            "type": "number",
                            "description": "Largura em mm."
                          },
                          "height": {
                            "type": "number",
                            "description": "Altura em mm."
                          },
                          "columns": {
                            "type": "integer"
                          },
                          "center_margin": {
                            "type": "number",
                            "description": "Espaço entre colunas em mm."
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "retangular",
                              "quadrada",
                              "redonda",
                              "oval",
                              "joia",
                              "lacre",
                              "gondola",
                              "serrilha",
                              "conjugada",
                              "tag",
                              "especial"
                            ]
                          },
                          "sku": {
                            "type": "string"
                          },
                          "price_surcharge_cents": {
                            "type": "integer",
                            "description": "Valor em centavos de real (BRL)."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/pricing/papers": {
      "get": {
        "operationId": "listPapers",
        "summary": "Lista os papéis (materiais) ativos",
        "responses": {
          "200": {
            "description": "Papéis ativos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "material": {
                            "type": "string",
                            "enum": ["couche", "bopp", "termico", "cartao"]
                          },
                          "thickness_um": {
                            "type": "integer"
                          },
                          "colors": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "custom_colors": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "allowed_knife_types": {
                            "type": ["array", "null"],
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/catalog/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "Lista produtos da loja (ribbons, bobinas, impressoras)",
        "description": "Resposta de preço por cliente: não deve ser compartilhada em cache.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ID da categoria."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["name", "newest", "price_asc", "price_desc"],
              "default": "name"
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Centavos. Só considera produtos padrão (ribbons ficam de fora)."
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Centavos. Só considera produtos padrão (ribbons ficam de fora)."
          }
        ],
        "responses": {
          "200": {
            "description": "Página de produtos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "sku": {
                            "type": ["string", "null"]
                          },
                          "name": {
                            "type": "string"
                          },
                          "seo_slug": {
                            "type": ["string", "null"],
                            "description": "Slug de SEO; sem ele a URL pública é /produtos/{id}-{nome-em-slug}."
                          },
                          "kind": {
                            "type": "string",
                            "enum": ["standard", "ribbon"]
                          },
                          "available": {
                            "type": "boolean",
                            "description": "false = 'Sob consulta', sem preço."
                          },
                          "price": {
                            "oneOf": [
                              {
                                "type": "integer",
                                "description": "Valor em centavos de real (BRL)."
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Preço de tabela em centavos; em ribbons, o preço unitário a partir de 1 rolo."
                          },
                          "promotional_price": {
                            "oneOf": [
                              {
                                "type": "integer",
                                "description": "Valor em centavos de real (BRL)."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "price_tiers": {
                            "type": "array",
                            "description": "Só em ribbons: faixas por quantidade de rolos.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "min_rolls": {
                                  "type": "integer"
                                },
                                "unit_price_cents": {
                                  "type": "integer",
                                  "description": "Valor em centavos de real (BRL)."
                                }
                              }
                            }
                          },
                          "category_id": {
                            "type": ["integer", "null"]
                          },
                          "category_name": {
                            "type": ["string", "null"]
                          },
                          "attachments": {
                            "type": ["array", "null"],
                            "items": {
                              "type": "object",
                              "properties": {
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/catalog/products/{slug}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Detalhe de um produto",
        "description": "Aceita o ID numérico ou o slug; em '123-nome', o número antes do primeiro hífen identifica o produto.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Produto.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "sku": {
                          "type": ["string", "null"]
                        },
                        "name": {
                          "type": "string"
                        },
                        "seo_slug": {
                          "type": ["string", "null"],
                          "description": "Slug de SEO; sem ele a URL pública é /produtos/{id}-{nome-em-slug}."
                        },
                        "kind": {
                          "type": "string",
                          "enum": ["standard", "ribbon"]
                        },
                        "available": {
                          "type": "boolean",
                          "description": "false = 'Sob consulta', sem preço."
                        },
                        "price": {
                          "oneOf": [
                            {
                              "type": "integer",
                              "description": "Valor em centavos de real (BRL)."
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Preço de tabela em centavos; em ribbons, o preço unitário a partir de 1 rolo."
                        },
                        "promotional_price": {
                          "oneOf": [
                            {
                              "type": "integer",
                              "description": "Valor em centavos de real (BRL)."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "price_tiers": {
                          "type": "array",
                          "description": "Só em ribbons: faixas por quantidade de rolos.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "min_rolls": {
                                "type": "integer"
                              },
                              "unit_price_cents": {
                                "type": "integer",
                                "description": "Valor em centavos de real (BRL)."
                              }
                            }
                          }
                        },
                        "category_id": {
                          "type": ["integer", "null"]
                        },
                        "category_name": {
                          "type": ["string", "null"]
                        },
                        "attachments": {
                          "type": ["array", "null"],
                          "items": {
                            "type": "object",
                            "properties": {
                              "url": {
                                "type": "string",
                                "format": "uri"
                              }
                            }
                          }
                        },
                        "brand_name": {
                          "type": ["string", "null"]
                        },
                        "stock_quantity": {
                          "type": ["number", "null"]
                        },
                        "seo_title": {
                          "type": ["string", "null"]
                        },
                        "seo_description": {
                          "type": ["string", "null"]
                        },
                        "complementary_description": {
                          "type": ["string", "null"],
                          "description": "HTML vindo do ERP."
                        },
                        "updated_at": {
                          "type": ["string", "null"],
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/catalog/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Busca produtos por texto",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Produtos encontrados (lista vazia sem q).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "sku": {
                            "type": ["string", "null"]
                          },
                          "name": {
                            "type": "string"
                          },
                          "seo_slug": {
                            "type": ["string", "null"],
                            "description": "Slug de SEO; sem ele a URL pública é /produtos/{id}-{nome-em-slug}."
                          },
                          "kind": {
                            "type": "string",
                            "enum": ["standard", "ribbon"]
                          },
                          "available": {
                            "type": "boolean",
                            "description": "false = 'Sob consulta', sem preço."
                          },
                          "price": {
                            "oneOf": [
                              {
                                "type": "integer",
                                "description": "Valor em centavos de real (BRL)."
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Preço de tabela em centavos; em ribbons, o preço unitário a partir de 1 rolo."
                          },
                          "promotional_price": {
                            "oneOf": [
                              {
                                "type": "integer",
                                "description": "Valor em centavos de real (BRL)."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "price_tiers": {
                            "type": "array",
                            "description": "Só em ribbons: faixas por quantidade de rolos.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "min_rolls": {
                                  "type": "integer"
                                },
                                "unit_price_cents": {
                                  "type": "integer",
                                  "description": "Valor em centavos de real (BRL)."
                                }
                              }
                            }
                          },
                          "category_id": {
                            "type": ["integer", "null"]
                          },
                          "category_name": {
                            "type": ["string", "null"]
                          },
                          "attachments": {
                            "type": ["array", "null"],
                            "items": {
                              "type": "object",
                              "properties": {
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/pricing/calculate": {
      "post": {
        "operationId": "calculatePrice",
        "summary": "Cota uma faca em todos os papéis",
        "description": "Sem efeito colateral. Devolve, por papel, as faixas de preço por quantidade de rolos.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["knife_id", "color", "label_quantity"],
                "properties": {
                  "knife_id": {
                    "type": "integer",
                    "description": "ID de /catalog/knives."
                  },
                  "color": {
                    "type": "string",
                    "description": "Cor da arte, por exemplo branca, colorida, personalizada_2cores."
                  },
                  "label_quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Quantidade total de etiquetas."
                  },
                  "is_custom": {
                    "type": "boolean",
                    "default": false
                  },
                  "paper_id": {
                    "type": "integer",
                    "description": "Opcional; usado com tubete_id para validar o tamanho do rolo."
                  },
                  "tubete_id": {
                    "type": "integer",
                    "description": "Opcional; rejeita (422) rolos maiores que o tubete permite."
                  },
                  "finishing_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cotação.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "labels_per_roll": {
                          "type": "integer"
                        },
                        "paper_width_mm": {
                          "type": "number"
                        },
                        "papers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "paper_id": {
                                "type": "integer"
                              },
                              "paper_name": {
                                "type": "string"
                              },
                              "min_rolls": {
                                "type": "integer"
                              },
                              "tiers": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "rolls": {
                                      "type": "integer"
                                    },
                                    "by_roll": {
                                      "type": "integer",
                                      "description": "Valor em centavos de real (BRL)."
                                    },
                                    "total": {
                                      "type": "integer",
                                      "description": "Valor em centavos de real (BRL)."
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Erro. Corpo: {\"error\": \"mensagem\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/catalog/tubetes": {
      "get": {
        "operationId": "listTubetes",
        "summary": "Tubetes (núcleos) disponíveis",
        "description": "Diâmetro do núcleo do rolo e limites de tamanho do rolo para cada tubete.",
        "responses": {
          "200": {
            "description": "Lista de tubetes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "nome": {
                            "type": "string"
                          },
                          "diametro_pol": {
                            "type": "number"
                          },
                          "warn_outer_diameter_mm": {
                            "type": "integer",
                            "description": "Acima deste diâmetro externo o rolo pode não caber em impressoras de mesa."
                          },
                          "max_outer_diameter_mm": {
                            "type": "integer",
                            "description": "Acima deste diâmetro externo não produzimos."
                          },
                          "min_roll_labels": {
                            "type": "integer"
                          },
                          "min_roll_length_m": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cart/drafts": {
      "post": {
        "operationId": "createCartDraft",
        "summary": "Guarda um carrinho para o cliente abrir por link",
        "description": "Valida e cota de 1 a 10 linhas e guarda o carrinho por 7 dias sob um token imprevisível. O cliente abre https://automacaocuritiba.com.br/carrinho/c/{token}: os itens entram no carrinho dele (somando ao que já tinha; reabrir o link não duplica) e ele paga no site. Não recebe dados pessoais nem faz pagamento. Os preços devolvidos são informativos: são calculados de novo para quem abre o link.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["items"],
                "properties": {
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "required": ["item_type", "quantity"],
                      "description": "Mesmo formato de uma linha do carrinho da loja. Nunca leva preço: o preço é sempre calculado pela loja.",
                      "properties": {
                        "item_type": {
                          "type": "string",
                          "enum": ["label", "product"]
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10000,
                          "description": "Rolos (etiqueta) ou unidades (produto)."
                        },
                        "product_id": {
                          "type": "integer",
                          "description": "Obrigatório em produtos."
                        },
                        "knife_id": {
                          "type": "integer",
                          "description": "Obrigatório em etiquetas."
                        },
                        "paper_id": {
                          "type": "integer",
                          "description": "Obrigatório em etiquetas."
                        },
                        "tubete_id": {
                          "type": "integer",
                          "description": "Obrigatório em etiquetas; de /catalog/tubetes."
                        },
                        "label_quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Etiquetas por rolo; obrigatório em etiquetas."
                        },
                        "color": {
                          "type": "string",
                          "description": "Cor da arte; padrão branca."
                        },
                        "is_custom": {
                          "type": "boolean",
                          "default": false
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Carrinho guardado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string",
                          "description": "Vai no link /carrinho/c/{token}."
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "total_cents": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "unit_price_cents": {
                                "type": "integer"
                              },
                              "total_cents": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Corpo inválido ou mais de 10 itens."
          },
          "422": {
            "description": "Linha que a loja não vende (medida, papel, tubete ou produto indisponível)."
          },
          "503": {
            "description": "Muitos carrinhos em aberto; tente mais tarde."
          }
        }
      }
    }
  },
  "security": [],
  "externalDocs": {
    "description": "Portal de desenvolvedores",
    "url": "https://automacaocuritiba.com.br/developers"
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Mensagem legível do erro."
          }
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Limite de 120 requisições por minuto por IP excedido. Espere o número de segundos de Retry-After.",
        "headers": {
          "Retry-After": {
            "description": "Segundos até o próximo período.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
