{
  "openapi": "3.1.0",
  "info": {
    "title": "FonteIA Reforma Tributária API",
    "version": "1.0.0",
    "description": "API da Reforma Tributária para consultar fontes oficiais tributárias, gerar respostas com evidências e integrar ERPs fiscais, agentes e sistemas próprios."
  },
  "servers": [
    {
      "url": "https://api.fonteia.ai",
      "description": "Produção"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/evidence/search": {
      "post": {
        "summary": "Buscar evidências oficiais",
        "description": "Endpoint evidence-first da FonteIA V2 publicado no caminho estável da API. Use primeiro este endpoint para localizar trechos oficiais.",
        "operationId": "searchEvidence",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V2EvidenceSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evidências oficiais retornadas",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2EvidenceSearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/answers": {
      "post": {
        "summary": "Gerar resposta rápida com evidências",
        "description": "Endpoint FonteIA V2 answer.fast publicado no caminho estável da API. Use para perguntas curtas e objetivas; perguntas amplas devem começar por searchEvidence.",
        "operationId": "createAnswer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V2AnswerFastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resposta V2 gerada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2AnswerFastResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/impact/brief": {
      "post": {
        "summary": "Gerar briefing de impacto",
        "description": "Gera um briefing operacional com base em fontes oficiais da Reforma Tributária.",
        "operationId": "createImpactBrief",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImpactBriefRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Briefing gerado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImpactBriefResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/changes/recent": {
      "get": {
        "summary": "Listar mudanças recentes",
        "description": "Lista mudanças detectadas em fontes oficiais monitoradas.",
        "operationId": "listRecentChanges",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "reforma_tributaria"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mudanças recentes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecentChangesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/timeline": {
      "post": {
        "summary": "Gerar linha do tempo regulatória",
        "description": "Monta uma linha do tempo sobre tema, norma ou documento com eventos oficiais e citações.",
        "operationId": "createTimeline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimelineRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Linha do tempo gerada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimelineResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/documents/lookup": {
      "post": {
        "summary": "Localizar documento ou trecho oficial",
        "description": "Localiza documento, artigo, seção ou trecho oficial de forma controlada.",
        "operationId": "lookupDocument",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Documento localizado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentLookupResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Chave ausente ou inválida"
      },
      "BadRequest": {
        "description": "Payload inválido ou contrato rejeitado"
      },
      "SourceRequired": {
        "description": "Fonte oficial insuficiente para responder"
      }
    },
    "schemas": {
      "V2EvidenceSearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Consulta curta e objetiva para localizar evidências oficiais.",
            "example": "documentos fiscais IBS CBS 2026"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "source_groups": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IDs opcionais de grupos de fontes oficiais."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 5
          },
          "profile": {
            "type": "string",
            "enum": [
              "sources_only",
              "interactive_fast"
            ],
            "default": "sources_only"
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "V2EvidenceSearchResponse": {
        "type": "object",
        "required": [
          "contract_version",
          "request_id",
          "status",
          "latency_ms",
          "query",
          "items",
          "total_returned"
        ],
        "properties": {
          "contract_version": {
            "type": "string",
            "const": "v2.0"
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "partial",
              "no_evidence",
              "failed"
            ]
          },
          "latency_ms": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V2EvidenceItem"
            }
          },
          "total_returned": {
            "type": "integer"
          }
        }
      },
      "V2AnswerFastRequest": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "description": "Pergunta curta e objetiva. Para perguntas compostas, use primeiro `/v2/evidence/search` por eixo factual.",
            "example": "Como ficam PIS e Cofins com a CBS?"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "mode": {
            "type": "string",
            "enum": [
              "fast"
            ],
            "default": "fast",
            "description": "A primeira entrega V2 aceita apenas answer.fast."
          },
          "source_groups": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "max_citations": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "default": 3
          },
          "profile": {
            "type": "string",
            "enum": [
              "interactive_fast",
              "sources_only"
            ],
            "default": "interactive_fast"
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "V2AnswerFastResponse": {
        "type": "object",
        "required": [
          "contract_version",
          "request_id",
          "status",
          "confidence",
          "confidence_reason",
          "latency_ms",
          "answer",
          "citations",
          "coverage_matrix",
          "limitations"
        ],
        "properties": {
          "contract_version": {
            "type": "string",
            "const": "v2.0"
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "partial",
              "no_evidence"
            ]
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low",
              "none"
            ]
          },
          "confidence_reason": {
            "type": "string"
          },
          "latency_ms": {
            "type": "integer"
          },
          "answer": {
            "type": "string"
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V2Citation"
            }
          },
          "coverage_matrix": {
            "type": "object",
            "additionalProperties": true
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "V2Citation": {
        "type": "object",
        "properties": {
          "marker": {
            "type": "integer"
          },
          "evidence_id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "date": {
            "type": [
              "string",
              "null"
            ]
          },
          "locator": {
            "type": [
              "string",
              "null"
            ]
          },
          "excerpt": {
            "type": "string"
          }
        }
      },
      "V2EvidenceItem": {
        "type": "object",
        "properties": {
          "marker": {
            "type": "integer"
          },
          "evidence_id": {
            "type": "string"
          },
          "source_group": {
            "type": "string"
          },
          "source_name": {
            "type": "string"
          },
          "source_org": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "date": {
            "type": [
              "string",
              "null"
            ]
          },
          "locator": {
            "type": [
              "string",
              "null"
            ]
          },
          "excerpt": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "quality_score": {
            "type": "number"
          },
          "selection_reason": {
            "type": "string"
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AnswerRequest": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "description": "Pergunta fiscal. Perguntas compostas são avaliadas por eixos de evidência; pontos sem trecho oficial suficiente retornam como lacuna, não como conclusão.",
            "example": "Como funciona a apuração assistida da CBS?"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "mode": {
            "type": "string",
            "enum": [
              "api",
              "fast"
            ],
            "default": "fast",
            "description": "Use fast em ChatGPT Actions. Este modo evita síntese lenta e retorna evidências/cobertura para o GPT redigir apenas o que estiver suportado."
          },
          "include_legal_synthesis": {
            "type": "boolean",
            "default": false,
            "description": "Mantenha false em ChatGPT Actions para baixa latência. Quando true, a API tenta montar síntese jurídica adicional, mas ainda deve respeitar a matriz de cobertura."
          },
          "audience": {
            "type": "string",
            "enum": [
              "contador",
              "tributarista",
              "erp",
              "fiscal",
              "juridico",
              "executive"
            ]
          },
          "answer_style": {
            "type": "string",
            "enum": [
              "concise",
              "executive",
              "technical",
              "checklist"
            ]
          },
          "require_citations": {
            "type": "boolean",
            "default": true
          },
          "max_citations": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 3
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "AnswerResponse": {
        "type": "object",
        "properties": {
          "answer_id": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "legal_synthesis": {
            "$ref": "#/components/schemas/LegalSynthesis"
          },
          "claim_plan": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence_matrix": {
            "type": "object",
            "description": "Matriz de cobertura por eixo factual. Se algum eixo vier partial ou unsupported, o GPT deve apresentar esse ponto como lacuna, não como conclusão.",
            "additionalProperties": true
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Citation"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Limitation"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "EvidenceSearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Consulta curta para localizar evidências oficiais. Para análises longas, use uma chamada por tema específico.",
            "example": "documentos fiscais IBS CBS 2026"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 5
          },
          "filters": {
            "type": "object",
            "additionalProperties": true
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "EvidenceSearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "description": "Resumo textual curto do resultado da busca, útil para ChatGPT Actions antes de percorrer items."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "total_returned": {
            "type": "integer"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ImpactBriefRequest": {
        "type": "object",
        "required": [
          "topic"
        ],
        "properties": {
          "topic": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "audience": {
            "type": "string"
          },
          "output": {
            "type": "string"
          },
          "include_sources": {
            "type": "boolean",
            "default": true
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "ImpactBriefResponse": {
        "type": "object",
        "properties": {
          "brief_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "action_items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Citation"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Limitation"
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "RecentChangesResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Change"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "TimelineRequest": {
        "type": "object",
        "required": [
          "topic"
        ],
        "properties": {
          "topic": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "include_future_effects": {
            "type": "boolean",
            "default": true
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "TimelineResponse": {
        "type": "object",
        "properties": {
          "timeline_id": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TimelineItem"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Limitation"
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "DocumentLookupRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "default": "reforma_tributaria"
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "DocumentLookupResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "LegalSynthesis": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "Síntese jurídica pronta para uso, construída somente a partir das evidências oficiais retornadas."
          },
          "foundation_answer": {
            "type": "string"
          },
          "limitations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Limitation"
            }
          },
          "answer_quality": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Citation": {
        "type": "object",
        "properties": {
          "citation_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "official_url": {
            "type": "string",
            "format": "uri"
          },
          "source_date": {
            "type": "string",
            "format": "date"
          },
          "locator": {
            "type": "object",
            "additionalProperties": true
          },
          "excerpt": {
            "type": "string"
          },
          "excerpt_is_literal": {
            "type": "boolean"
          }
        }
      },
      "Evidence": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Citation"
          },
          {
            "type": "object",
            "properties": {
              "evidence_id": {
                "type": "string"
              },
              "score": {
                "type": "number"
              },
              "quality": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        ]
      },
      "Limitation": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "citations_returned": {
            "type": "integer"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Change": {
        "type": "object",
        "properties": {
          "change_id": {
            "type": "string"
          },
          "change_type": {
            "type": "string"
          },
          "detected_at": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "official_url": {
            "type": "string",
            "format": "uri"
          },
          "summary": {
            "type": "string"
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TimelineItem": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "event_type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "official_url": {
            "type": "string",
            "format": "uri"
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Citation"
            }
          }
        }
      }
    }
  }
}