{
  "openapi": "3.0.3",
  "info": {
    "title": "API do Tabela Cutter",
    "version": "1.0",
    "description": "Gera o código Cutter-Sanborn (notação de autor) com as mesmas regras do site www.tabelacutter.com. Gratuita, sem chave; limite de 60 consultas por minuto por endereço IP.",
    "contact": { "name": "Even3 Publicações", "url": "https://www.tabelacutter.com/api" }
  },
  "servers": [{ "url": "https://www.tabelacutter.com" }],
  "paths": {
    "/api/v1/cutter": {
      "get": {
        "summary": "Gera um código Cutter-Sanborn",
        "parameters": [
          { "name": "entrada", "in": "query", "required": true, "description": "Entrada principal: Sobrenome, Prenome do autor ou, sem autor, o título da obra. Até 300 caracteres.", "schema": { "type": "string", "maxLength": 300 }, "example": "Saint-Exupéry, Antoine de" },
          { "name": "complemento", "in": "query", "required": false, "description": "Título da obra, para a letra da obra no fim do código. Até 300 caracteres.", "schema": { "type": "string", "maxLength": 300 }, "example": "O pequeno príncipe" },
          { "name": "formato", "in": "query", "required": false, "description": "Use 'texto' para receber só o código, em texto simples.", "schema": { "type": "string", "enum": ["texto"] } }
        ],
        "responses": {
          "200": {
            "description": "Código gerado",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Resultado" } },
              "text/plain": { "schema": { "type": "string", "example": "S137p" } }
            }
          },
          "400": { "description": "Entrada ausente, longa demais, sem letra de A a Z no início ou começando por número cujo gênero muda o código (2: dois ou duas) ou por algarismo romano, que precisam vir por extenso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "429": { "description": "Limite de consultas atingido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } },
          "500": { "description": "Falha temporária", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Linha": {
        "type": "object",
        "properties": {
          "parte": { "type": "string", "description": "Texto da linha na tabela", "example": "Saint E" },
          "numero": { "type": "string", "example": "137" }
        }
      },
      "Passo": {
        "type": "object",
        "properties": {
          "etapa": { "type": "string", "enum": ["entrada", "busca", "obra"] },
          "regra": { "type": "string", "description": "Identificador da regra (por exemplo tabela-2, nbr6033-3.1, conv-hifen)" },
          "tipo": { "type": "string", "enum": ["regra-tabela", "norma", "pratica", "convencao"] },
          "texto": { "type": "string" }
        }
      },
      "Resultado": {
        "type": "object",
        "properties": {
          "codigo": { "type": "string", "example": "S137p" },
          "letra": { "type": "string", "example": "S" },
          "numero": { "type": "string", "example": "137" },
          "letraObra": { "type": "string", "nullable": true, "example": "p" },
          "entrada": { "type": "string" },
          "complemento": { "type": "string", "nullable": true },
          "entradaNormalizada": { "type": "string", "example": "SAINT EXUPERY, ANTOINE DE" },
          "linhaUsada": { "$ref": "#/components/schemas/Linha" },
          "linhaSeguinte": { "$ref": "#/components/schemas/Linha" },
          "trilha": { "type": "array", "items": { "$ref": "#/components/schemas/Passo" } },
          "avisos": { "type": "array", "items": { "type": "string" } },
          "metodologia": { "type": "object", "properties": { "versao": { "type": "string", "example": "1.0" } } },
          "referencia": { "type": "string", "description": "Referência da ferramenta em ABNT NBR 6023, com a data da consulta" }
        }
      },
      "Erro": {
        "type": "object",
        "properties": {
          "erro": { "type": "string" },
          "campo": { "type": "string", "nullable": true }
        }
      }
    }
  }
}