{
  "openapi": "3.0.3",
  "info": {
    "title": "API News - v1",
    "version": "1.0.0",
    "description": "API de integracao do SMI para o clipping: consulta de noticias.\n\n## Autenticacao\nToken de acesso no header `Authorization: Bearer <token>`. O token e' obtido em `POST /auth`, trocando `usuario` + `chave_publica` + `timestamp` + `assinatura`. O header `X-Auth-Token` tambem e' aceito (clientes legados).\n\nDepois do token a rota e' conferida: rota nao liberada em *Admin > TI > Usuarios da API* responde 403, inclusive rota nova fora do catalogo.\n\n## Envelope\nToda resposta e' JSON com `success` e `data`:\n- sucesso: `{ \"success\": true, \"data\": ... }`\n- erro: `{ \"success\": false, \"data\": [ { \"error_code\": \"...\", \"message_error\": \"...\" } ] }`\n\n## Convencoes\n- Rotas aceitam com ou sem barra no fim.\n- Entrada por `application/x-www-form-urlencoded`; a query string tambem e' aceita para os mesmos nomes.\n- Datas saem em ISO 8601 (`aaaa-mm-ddThh:nn:ss`) e entram como `aaaa-mm-dd` (`dd/mm/aaaa` tambem e' aceito)."
  },
  "servers": [
    {
      "url": "/",
      "description": "Raiz do site dedicado a API (https://api.exemplo.com.br). As rotas comecam na raiz do host."
    }
  ],
  "tags": [
    {
      "name": "Autenticacao",
      "description": "Troca de assinatura por token."
    },
    {
      "name": "Noticia",
      "description": "Clipping: consulta e verificacao de materias."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/auth": {
      "post": {
        "tags": [
          "Autenticacao"
        ],
        "summary": "Troca a assinatura por um token de acesso",
        "description": "Rota PUBLICA (nao exige token). Troca o par chave publica/assinatura por um token temporario, usado no header `Authorization: Bearer <token>` nas demais rotas.\n\nA assinatura e' `MD5hex(32)` ou `SHA-256hex(64)` de `timestamp & chave_privada`, com `timestamp` em segundos UTC.\n\nO token fica preso ao IP de origem: usado de outro IP responde 403.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "usuario": {
                    "type": "string",
                    "description": "Login do usuario de API.",
                    "maxLength": 20
                  },
                  "chave_publica": {
                    "type": "string",
                    "description": "Chave publica do usuario de API."
                  },
                  "timestamp": {
                    "type": "string",
                    "description": "Unix timestamp (segundos, UTC) usado no calculo da assinatura."
                  },
                  "assinatura": {
                    "type": "string",
                    "description": "MD5hex(32) ou SHA-256hex(64) de timestamp & chave_privada."
                  }
                },
                "required": [
                  "usuario",
                  "chave_publica",
                  "timestamp",
                  "assinatura"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token emitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespostaToken"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Erro400"
          },
          "401": {
            "description": "Usuario/chave publica invalidos, assinatura invalida ou credenciais invalidas."
          },
          "403": {
            "description": "Origem nao autorizada para este usuario de API."
          },
          "405": {
            "$ref": "#/components/responses/Erro405"
          },
          "500": {
            "$ref": "#/components/responses/Erro500"
          }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "tags": [
          "Autenticacao"
        ],
        "summary": "Revoga o token enviado",
        "description": "Revoga o token do header `Authorization`; as chamadas seguintes com ele recebem 401.",
        "responses": {
          "200": {
            "description": "Token revogado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespostaVazia"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Erro401"
          },
          "403": {
            "$ref": "#/components/responses/Erro403"
          },
          "405": {
            "$ref": "#/components/responses/Erro405"
          },
          "500": {
            "$ref": "#/components/responses/Erro500"
          }
        }
      }
    },
    "/noticia/lista": {
      "post": {
        "tags": [
          "Noticia"
        ],
        "summary": "Lista as noticias do clipping",
        "description": "Lista as materias do sistema (`sistema`) aplicando os filtros informados. O `sistema` vem no corpo do POST; `?sistema=` na query string tambem e' aceito.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "sistema": {
                    "type": "string",
                    "description": "Sigla/diretorio do clipping.",
                    "example": "mec"
                  },
                  "palavra_chave": {
                    "type": "string",
                    "description": "Trecho do texto/titulo."
                  },
                  "ultima_noticia": {
                    "type": "integer",
                    "description": "Trazer somente materias com id maior que este."
                  },
                  "data": {
                    "type": "string",
                    "description": "Data inicial (aaaa-mm-dd ou dd/mm/aaaa)."
                  },
                  "data_fim": {
                    "type": "string",
                    "description": "Data final (aaaa-mm-dd ou dd/mm/aaaa)."
                  },
                  "categoria": {
                    "type": "string",
                    "description": "Codigo da categoria."
                  },
                  "veiculo": {
                    "type": "string",
                    "description": "Codigo do veiculo."
                  },
                  "midia": {
                    "type": "string",
                    "description": "Tipo/midia do veiculo (IMP, RAD, TVS...)."
                  },
                  "tp_avaliacao": {
                    "type": "string",
                    "description": "Tipo de avaliacao."
                  }
                },
                "required": [
                  "sistema"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Noticias encontradas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespostaNoticiaLista"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Erro400"
          },
          "401": {
            "$ref": "#/components/responses/Erro401"
          },
          "403": {
            "$ref": "#/components/responses/Erro403"
          },
          "405": {
            "$ref": "#/components/responses/Erro405"
          },
          "500": {
            "$ref": "#/components/responses/Erro500"
          }
        }
      }
    },
    "/noticia/get": {
      "post": {
        "tags": [
          "Noticia"
        ],
        "summary": "Detalhe de uma noticia",
        "description": "Devolve a materia pelo `cd_noticia` dentro do `sistema` informado. Materia de outro sistema nao e' devolvida: `data` vem vazio.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "sistema": {
                    "type": "string",
                    "description": "Sigla/diretorio do clipping.",
                    "example": "mec"
                  },
                  "cd_noticia": {
                    "type": "string",
                    "description": "Codigo da noticia (o `id` de noticia/lista)."
                  },
                  "id": {
                    "type": "string",
                    "description": "Nome antigo de `cd_noticia`, aceito por compatibilidade."
                  }
                },
                "required": [
                  "sistema",
                  "cd_noticia"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Noticia (0 ou 1 item).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespostaNoticiaGet"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Erro400"
          },
          "401": {
            "$ref": "#/components/responses/Erro401"
          },
          "403": {
            "$ref": "#/components/responses/Erro403"
          },
          "405": {
            "$ref": "#/components/responses/Erro405"
          },
          "500": {
            "$ref": "#/components/responses/Erro500"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token obtido em `POST /auth`. Alternativa: header `X-Auth-Token`."
      }
    },
    "responses": {
      "Erro400": {
        "description": "Requisicao invalida (parametro obrigatorio ausente ou fora do formato).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErroResposta"
            }
          }
        }
      },
      "Erro401": {
        "description": "Token ausente, expirado ou nao reconhecido.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErroResposta"
            }
          }
        }
      },
      "Erro403": {
        "description": "Sem permissao: rota nao liberada para o usuario, rota fora do catalogo (`api_rota`) ou IP nao autorizado.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErroResposta"
            }
          }
        }
      },
      "Erro405": {
        "description": "Metodo nao permitido (a rota aceita GET ou POST, conforme indicado).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErroResposta"
            }
          }
        }
      },
      "Erro500": {
        "description": "Erro ao processar no servidor (`error_code` 50000; com `api_debug` ligado vem o erro real).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErroResposta"
            }
          }
        }
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "Envelope de resposta da API.",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "description": "true na resposta de sucesso; false no erro."
          },
          "data": {
            "description": "Conteudo. O tipo depende da rota."
          }
        }
      },
      "Erro": {
        "type": "object",
        "required": [
          "error_code",
          "message_error"
        ],
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Codigo do erro (HTTP na validacao do endpoint, numero do erro de banco/SQL Server)."
          },
          "message_error": {
            "type": "string",
            "description": "Mensagem pronta para exibir ao usuario."
          }
        }
      },
      "ErroResposta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          }
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Token": {
        "type": "object",
        "properties": {
          "token_type": {
            "type": "string",
            "description": "Sempre \"Bearer\".",
            "example": "Bearer"
          },
          "access_token": {
            "type": "string",
            "description": "Token a enviar no header Authorization."
          },
          "expires_in": {
            "type": "integer",
            "description": "Validade em segundos (60 minutos)."
          }
        }
      },
      "Noticia": {
        "type": "object",
        "description": "Item de noticia do clipping. O conjunto de campos vem da procedure p_api_lista_noticia e varia com o sistema; os listados sao os estaveis.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Codigo da noticia."
          },
          "data": {
            "type": "string",
            "description": "Data da noticia (ISO 8601).",
            "format": "date-time"
          },
          "titulo": {
            "type": "string",
            "description": "Titulo."
          },
          "veiculo": {
            "type": "string",
            "description": "Nome do veiculo."
          },
          "id_veiculo": {
            "type": "integer",
            "description": "Codigo do veiculo."
          },
          "abrangencia": {
            "type": "string",
            "description": "Abrangencia do veiculo."
          },
          "tier": {
            "type": "string",
            "description": "Tier do veiculo no contrato."
          },
          "resumo": {
            "type": "string",
            "description": "Resumo.",
            "nullable": true
          },
          "midia": {
            "type": "string",
            "description": "Tipo/midia do veiculo."
          },
          "conteudo": {
            "type": "string",
            "description": "Texto da materia.",
            "nullable": true
          },
          "link_noticia": {
            "type": "string",
            "description": "URL da materia.",
            "nullable": true
          },
          "categorias": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Categorias."
          },
          "avaliacoes": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Avaliacoes."
          },
          "nr_latitude": {
            "type": "number",
            "nullable": true
          },
          "nr_longitude": {
            "type": "number",
            "nullable": true
          },
          "qt_publico": {
            "type": "integer",
            "description": "Publico estimado.",
            "nullable": true
          },
          "vl_publicitario": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "RespostaToken": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          }
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Token"
            }
          }
        }
      },
      "RespostaVazia": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          }
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {}
          }
        },
        "description": "Lista vazia."
      },
      "RespostaNoticiaLista": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          }
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Noticia"
            }
          }
        }
      },
      "RespostaNoticiaGet": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          }
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Noticia"
            }
          }
        }
      }
    }
  }
}
