openapi: 3.0.3
info:
  title: cnpj/ob API
  description: |
    API oficial de dados de empresas brasileiras contendo 67 milhões de CNPJs integrados com a base da Receita Federal.
    Oferece endpoints para consulta de CNPJ, busca por razão social, listagem de empresas por CNAE e busca de sócios.
  version: 1.0.0
  contact:
    name: Suporte cnpj/ob
    email: suporte@cnpjob.com.br
    url: https://cnpjob.com.br
servers:
  - url: https://api.cnpjob.com.br/api
    description: Servidor de Produção
security:
  - ApiKeyAuth: []
paths:
  /cnpj/{cnpj}:
    get:
      summary: Consulta Completa de CNPJ
      description: Retorna os dados completos de um CNPJ (matriz ou filial), incluindo endereço, atividades secundárias e porte.
      parameters:
        - name: cnpj
          in: path
          required: true
          description: O CNPJ que deseja consultar (apenas números ou formatado).
          schema:
            type: string
            example: "33000167000101"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Empresa'
        '404':
          description: CNPJ não encontrado
  /cnpj/{cnpj}/socios:
    get:
      summary: Sócios do CNPJ
      description: Retorna o quadro de sócios e administradores de um determinado CNPJ.
      parameters:
        - name: cnpj
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /empresa/busca:
    get:
      summary: Busca por Razão Social
      description: (Requer Plano PRO) Busca empresas utilizando pesquisa fonética e trigramas por parte do nome, razão social ou nome fantasia.
      parameters:
        - name: q
          in: query
          required: true
          description: Razão social ou nome fantasia para buscar.
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Lista de empresas correspondentes.
  /empresas:
    get:
      summary: Filtrar Empresas Avançado
      description: (Requer Plano PRO) Filtre a base inteira usando CNAE, UF, município e situação cadastral.
      parameters:
        - name: cnae
          in: query
          description: Código CNAE de 7 dígitos.
          schema:
            type: string
        - name: uf
          in: query
          schema:
            type: string
        - name: municipio
          in: query
          schema:
            type: string
        - name: situacao
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
  /cnae/{codigo}/empresas:
    get:
      summary: Captação de Leads por CNAE
      description: (Requer Plano PRO) Retorna uma lista de todas as empresas (ativas ou inativas) que possuem o CNAE principal correspondente ao especificado. Útil para prospecção B2B.
      parameters:
        - name: codigo
          in: path
          required: true
          description: O código CNAE de 7 dígitos, apenas números.
          schema:
            type: string
            example: "6204000"
      responses:
        '200':
          description: Lista de CNPJs e dados de contato básico das empresas que atuam com esse CNAE.
  /socio/busca:
    get:
      summary: Busca por Sócio
      description: (Requer Plano PRO) Retorna a lista de empresas das quais uma determinada pessoa (por nome ou CPF/CNPJ parcial) faz parte do quadro societário.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Empresa:
      type: object
      properties:
        cnpj:
          type: string
        razao_social:
          type: string
        nome_fantasia:
          type: string
        situacao:
          type: string
        porte:
          type: string
        cnae_principal:
          type: object
          properties:
            codigo:
              type: string
            descricao:
              type: string
        endereco:
          type: object
          properties:
            uf:
              type: string
            municipio:
              type: string
            logradouro:
              type: string
            cep:
              type: string
        data_abertura:
          type: string
          format: date