openapi: 3.2.0
info:
  title: PontoFato Empresas API
  version: 2d690e87
  description: 'Ponto e fato de um lugar no Brasil. Índice: GET /api/.'
servers:
- url: https://pontofato.com
tags:
- name: Empresas
paths:
  /api/empresas:
    get:
      operationId: empresas
      summary: Estabelecimentos da Receita neste CEP (join no c3, teto 50)
      description: 'Devolve: { items[{cnpj,cnpjFormatted,razaoSocial,nomeFantasia,situacao,uf,municipio,bairro,cnae}], total, hasMore, page }'
      parameters:
      - name: cep
        in: query
        required: true
        schema:
          type: string
        description: 8 dígitos, com ou sem hífen.
        example: '01310100'
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Página 0-based da origem CNPJ (50 por página).
      responses:
        '200':
          description: '{ items[{cnpj,cnpjFormatted,razaoSocial,nomeFantasia,situacao,uf,municipio,bairro,cnae}], total, hasMore, page }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Empresas'
        '400':
          description: CEP inválido.
        '503':
          description: API de CNPJ indisponível.
      tags:
      - Empresas
components:
  schemas:
    Empresas:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Empresa'
          description: Cards da origem CNPJ (teto 50 por página).
        total:
          type: integer
          description: Tamanho desta página, ou total se a origem mandar.
        hasMore:
          type: boolean
          description: '`true` quando a origem tem mais estabelecimentos além do teto.'
        page:
          type: integer
          description: Página 0-based pedida à origem.
      required:
      - items
      - total
      - hasMore
      - page
      description: Estabelecimentos da Receita neste CEP, via api-cnpj no c3.
    Empresa:
      type: object
      properties:
        cnpj:
          type: string
          description: 14 dígitos, sem máscara.
        cnpjFormatted:
          type: string
          description: CNPJ com pontuação.
        razaoSocial:
          type: string
          description: Razão social na Receita.
          nullable: true
        nomeFantasia:
          type: string
          description: Nome fantasia, se houver.
          nullable: true
        situacao:
          type: object
          description: '`codigo` numérico e `label` (Ativa, Inapta, Baixada…).'
          nullable: true
        uf:
          type: string
          description: UF do estabelecimento.
          nullable: true
        municipio:
          type: string
          description: Município da Receita.
          nullable: true
        bairro:
          type: string
          description: Bairro do estabelecimento.
          nullable: true
        cnae:
          type: object
          description: '`codigo` e `descricao` da atividade principal.'
          nullable: true
      required:
      - cnpj
      - cnpjFormatted
      - razaoSocial
      - nomeFantasia
      - situacao
      - uf
      - municipio
      - bairro
      - cnae
      description: Card da busca por CEP na origem CNPJ — não é a ficha completa do Radar.