{
 "openapi": "3.1.0",
 "info": {
  "title": "FarejaLeads — dados abertos",
  "version": "1.0.0",
  "description": "Empresas ativas no Brasil por setor, estado, município, porte e ano de abertura (base de CNPJ da Receita Federal) e contratos públicos por categoria, fornecedores e compradores (PNCP). Somente leitura, sem chave, CORS liberado. Cite a fonte primária e o FarejaLeads.\n\nErros: application/problem+json (RFC 9457) com `code` estável e `hint`. Limite: 120 requisições por 60 s por IP, informado nos cabeçalhos RateLimit e RateLimit-Policy; no 429, Retry-After.\n\nVersionamento: Versão no caminho (/api/v1). Dentro de uma versão só entram mudanças compatíveis (campos e rotas novos). Mudança incompatível sai numa versão nova (/api/v2), e a anterior continua no ar por pelo menos 6 meses, anunciada com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594) e um aviso em https://farejaleads.com/developers#versoes. Toda resposta traz o cabeçalho API-Version.",
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/deed.pt_BR"
  },
  "contact": {
   "url": "https://farejaleads.com/developers"
  },
  "x-api-version": "v1",
  "x-versioning-policy": "Versão no caminho (/api/v1). Dentro de uma versão só entram mudanças compatíveis (campos e rotas novos). Mudança incompatível sai numa versão nova (/api/v2), e a anterior continua no ar por pelo menos 6 meses, anunciada com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594) e um aviso em https://farejaleads.com/developers#versoes. Toda resposta traz o cabeçalho API-Version."
 },
 "externalDocs": {
  "description": "Portal do desenvolvedor",
  "url": "https://farejaleads.com/developers"
 },
 "servers": [
  {
   "url": "https://farejaleads.com"
  }
 ],
 "paths": {
  "/api/v1": {
   "get": {
    "operationId": "indice",
    "summary": "Índice da API v1",
    "responses": {
     "200": {
      "description": "Rotas, versão e documentação",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  },
  "/api/v1/conjuntos": {
   "get": {
    "operationId": "listarConjuntos",
    "summary": "Catálogo de conjuntos de dados",
    "responses": {
     "200": {
      "description": "Lista de conjuntos com links JSON e CSV",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  },
  "/api/v1/conjuntos/{conjunto}.{formato}": {
   "get": {
    "operationId": "baixarConjuntoV1",
    "summary": "Um conjunto de dados inteiro",
    "parameters": [
     {
      "name": "conjunto",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "empresas-ativas-por-setor-e-uf",
        "empresas-ativas-por-setor-e-municipio",
        "empresas-ativas-por-setor-uf-e-porte",
        "empresas-ativas-por-setor-uf-e-ano-de-abertura",
        "novas-empresas-por-setor-e-uf",
        "contratos-publicos-por-categoria-e-uf",
        "maiores-fornecedores-do-governo-por-categoria"
       ]
      }
     },
     {
      "name": "formato",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "O conjunto. JSON traz id, titulo, descricao, fonte, licenca, atualizado, colunas e linhas.",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  },
  "/api/v1/paginas/{caminho}.{formato}": {
   "get": {
    "operationId": "baixarPaginaV1",
    "summary": "Os números de uma página de dados (ex.: empresas/software/pe ou contratos-publicos/software-e-ti/sp)",
    "parameters": [
     {
      "name": "caminho",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "empresas/software/pe/recife"
     },
     {
      "name": "formato",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Os dados da página",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  },
  "/dados/arquivo/{conjunto}.{formato}": {
   "get": {
    "operationId": "baixarConjunto",
    "summary": "Mesmo conteúdo de /api/v1/conjuntos/{conjunto}.{formato} (endereço de download citado nas páginas; mantido)",
    "parameters": [
     {
      "name": "conjunto",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "empresas-ativas-por-setor-e-uf",
        "empresas-ativas-por-setor-e-municipio",
        "empresas-ativas-por-setor-uf-e-porte",
        "empresas-ativas-por-setor-uf-e-ano-de-abertura",
        "novas-empresas-por-setor-e-uf",
        "contratos-publicos-por-categoria-e-uf",
        "maiores-fornecedores-do-governo-por-categoria"
       ]
      }
     },
     {
      "name": "formato",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "O conjunto",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  },
  "/dados/arquivo/pagina/{caminho}.{formato}": {
   "get": {
    "operationId": "baixarPagina",
    "summary": "Mesmo conteúdo de /api/v1/paginas/{caminho}.{formato} (mantido)",
    "parameters": [
     {
      "name": "caminho",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "empresas/software/pe/recife"
     },
     {
      "name": "formato",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Os dados da página",
      "headers": {
       "API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       },
       "RateLimit": {
        "$ref": "#/components/headers/RateLimit"
       },
       "RateLimit-Policy": {
        "$ref": "#/components/headers/RateLimitPolicy"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       },
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NaoEncontrado"
     },
     "405": {
      "$ref": "#/components/responses/MetodoNaoPermitido"
     },
     "429": {
      "$ref": "#/components/responses/LimiteExcedido"
     },
     "500": {
      "$ref": "#/components/responses/ErroInterno"
     },
     "503": {
      "$ref": "#/components/responses/Indisponivel"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Problem": {
    "type": "object",
    "description": "Erro no formato RFC 9457 (Problem Details), com código estável e dica.",
    "required": [
     "type",
     "title",
     "status",
     "code"
    ],
    "properties": {
     "type": {
      "type": "string",
      "format": "uri",
      "description": "Link para a explicação do código em /developers"
     },
     "title": {
      "type": "string"
     },
     "status": {
      "type": "integer"
     },
     "detail": {
      "type": "string"
     },
     "instance": {
      "type": "string",
      "description": "O caminho que falhou"
     },
     "code": {
      "type": "string",
      "enum": [
       "rota_inexistente",
       "formato_invalido",
       "conjunto_inexistente",
       "pagina_inexistente",
       "metodo_nao_permitido",
       "limite_excedido",
       "indisponivel",
       "erro_interno"
      ],
      "description": "Código estável para máquina"
     },
     "hint": {
      "type": "string",
      "description": "O que fazer para resolver"
     },
     "docs": {
      "type": "string",
      "format": "uri"
     }
    }
   }
  },
  "headers": {
   "ApiVersion": {
    "description": "Versão da API que respondeu",
    "schema": {
     "type": "string",
     "example": "v1"
    }
   },
   "RateLimit": {
    "description": "Cota restante (r) e segundos até renovar (t), draft-ietf-httpapi-ratelimit-headers. Ex.: \"padrao\";r=119;t=60",
    "schema": {
     "type": "string"
    }
   },
   "RateLimitPolicy": {
    "description": "Política: \"padrao\";q=120;w=60",
    "schema": {
     "type": "string"
    }
   },
   "RetryAfter": {
    "description": "Segundos para tentar de novo",
    "schema": {
     "type": "integer"
    }
   }
  },
  "responses": {
   "NaoEncontrado": {
    "description": "Rota, conjunto, página ou formato inexistente (codes: rota_inexistente, conjunto_inexistente, pagina_inexistente, formato_invalido)",
    "headers": {
     "RateLimit": {
      "$ref": "#/components/headers/RateLimit"
     },
     "RateLimit-Policy": {
      "$ref": "#/components/headers/RateLimitPolicy"
     }
    },
    "content": {
     "application/problem+json": {
      "schema": {
       "$ref": "#/components/schemas/Problem"
      }
     }
    }
   },
   "MetodoNaoPermitido": {
    "description": "A API é só leitura (code: metodo_nao_permitido)",
    "headers": {
     "RateLimit": {
      "$ref": "#/components/headers/RateLimit"
     },
     "RateLimit-Policy": {
      "$ref": "#/components/headers/RateLimitPolicy"
     },
     "Allow": {
      "schema": {
       "type": "string"
      }
     }
    },
    "content": {
     "application/problem+json": {
      "schema": {
       "$ref": "#/components/schemas/Problem"
      }
     }
    }
   },
   "LimiteExcedido": {
    "description": "Limite de requisições excedido (code: limite_excedido)",
    "headers": {
     "RateLimit": {
      "$ref": "#/components/headers/RateLimit"
     },
     "RateLimit-Policy": {
      "$ref": "#/components/headers/RateLimitPolicy"
     },
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/problem+json": {
      "schema": {
       "$ref": "#/components/schemas/Problem"
      }
     }
    }
   },
   "ErroInterno": {
    "description": "Erro do nosso lado (code: erro_interno)",
    "headers": {
     "RateLimit": {
      "$ref": "#/components/headers/RateLimit"
     },
     "RateLimit-Policy": {
      "$ref": "#/components/headers/RateLimitPolicy"
     }
    },
    "content": {
     "application/problem+json": {
      "schema": {
       "$ref": "#/components/schemas/Problem"
      }
     }
    }
   },
   "Indisponivel": {
    "description": "Fonte indisponível agora (code: indisponivel)",
    "headers": {
     "RateLimit": {
      "$ref": "#/components/headers/RateLimit"
     },
     "RateLimit-Policy": {
      "$ref": "#/components/headers/RateLimitPolicy"
     },
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/problem+json": {
      "schema": {
       "$ref": "#/components/schemas/Problem"
      }
     }
    }
   }
  }
 }
}