Dados B3 Screener API

openapi: 3.2.0
info:
  title: Dados B3 Screener API
  description: 'Dados fundamentalistas de companhias abertas brasileiras com metodologia 100% pública e invariantes de dado publicados. Fontes: CVM (dados abertos, ODbL) e B3 (COTAHIST fim-de-dia). Todo número carrega a conta CVM de origem; valor duvidoso carrega flag, nunca estimativa escondida.'
  version: 0.1.0
tags:
- name: Screener
paths:
  /screener:
    get:
      summary: Screener
      description: 'Filtra empresas por faixas de indicadores. Cada indicador aceita

        `_min` e/ou `_max` (ex.: ?roic_min=0.15&dl_ebitda_max=2).

        Sem `ano`, usa o último ano com dados de cada empresa. Só considera

        valores SEM flag (número que passou limpo pela bateria). Requer chave

        (é sobre todo o universo); parâmetros inválidos são recusados, não

        ignorados.


        P/L: `pl_min`/`pl_max` (anual, da DFP) e `pl_ttm_min`/`pl_ttm_max` (12

        meses, do ITR ou DFP mais recente). Com `as_of`, vale o documento mais

        recente já recebido na data (e com preço já negociado nela); sem `as_of`, o

        mais recente. P/L de lucro zero/negativo (flag `pl_negativo`), acima de 200

        (`pl_extremo`) ou nulo nunca passa. Cada linha traz `multiplos` com

        `dt_receb` e `data_preco` do valor usado.


        `rigor` (só para P/L): `padrao` aceita o P/L com ajuste já feito ou ressalva

        leve (listada em `multiplos..ressalvas`) e recusa ressalva impeditiva e

        flag desconhecida; `estrito` só aceita P/L sem nenhuma flag. Com filtro de

        P/L a resposta traz `fora_do_filtro`: quantas companhias ficaram de fora e

        por quê, com `resumo` em português simples.'
      operationId: screener_screener_get
      parameters:
      - name: ano
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ano
      - name: as_of
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: As Of
      - name: limite
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limite
      - name: recibo
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Recibo
      - name: rigor
        in: query
        required: false
        schema:
          type: string
          default: padrao
          title: Rigor
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Screener
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    ChaveApiNaUrl:
      type: apiKey
      in: query
      name: chave
      description: Alternativa ao cabeçalho para clientes que só abrem URL (navegação de IA). Fica no histórico e nos logs de quem a usa.
    ChaveApi:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Chave grátis (200 consultas/dia) ou Pro em /assinar. Abertos sem chave (limite por IP): fatos, indicadores, múltiplos e dividendos de qualquer ticker, ficha e ranking de FII. WEGE3, MXRF11, /hoje, /saude e a metodologia são abertos. Exigem chave: as_of, versões, preços, screener, /dump.'