{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenCNPJ API",
    "version": "1.0.0",
    "description": "API pública para consulta de CNPJ numérico ou alfanumérico e metadados dos datasets publicados."
  },
  "servers": [
    {
      "url": "https://api.opencnpj.org",
      "description": "Produção"
    }
  ],
  "tags": [
    {
      "name": "Consulta",
      "description": "Consulta pontual por CNPJ."
    },
    {
      "name": "Metadados",
      "description": "Informações sobre publicação, schema e datasets."
    }
  ],
  "paths": {
    "/{cnpj}": {
      "get": {
        "tags": ["Consulta"],
        "summary": "Consultar CNPJ",
        "description": "Retorna os dados publicados para um CNPJ. O CNPJ deve ser tratado como string: 12 caracteres alfanuméricos seguidos de 2 dígitos verificadores.",
        "operationId": "getCnpj",
        "parameters": [
          {
            "name": "cnpj",
            "in": "path",
            "required": true,
            "description": "CNPJ sem máscara. Também aceita máscara no path, inclusive para CNPJ alfanumérico.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Z0-9]{12}\\d{2}$",
              "examples": ["12ABC34501DE35", "60701190000104"],
              "default": "12ABC34501DE35"
            },
            "examples": {
              "alfanumerico": {
                "summary": "CNPJ alfanumérico",
                "value": "12ABC34501DE35"
              },
              "numerico": {
                "summary": "CNPJ numérico",
                "value": "60701190000104"
              }
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "required": false,
            "description": "Um ou mais datasets separados por vírgula. Aceita receita, cno, rntrc, favorecidos_pj, ceis, cepim, cnep, acordos_leniencia, licitacoes, contratos, renuncias_fiscais, notas_fiscais, convenios, emendas_parlamentares e emendas_documentos. Se omitido, o retorno padrão é Receita Federal. dataset também é aceito como alias.",
            "schema": {
              "type": "string",
              "pattern": "^(receita|cno|rntrc|favorecidos_pj|ceis|cepim|cnep|acordos_leniencia|licitacoes|contratos|renuncias_fiscais|notas_fiscais|convenios|emendas_parlamentares|emendas_documentos)(,(receita|cno|rntrc|favorecidos_pj|ceis|cepim|cnep|acordos_leniencia|licitacoes|contratos|renuncias_fiscais|notas_fiscais|convenios|emendas_parlamentares|emendas_documentos))*$",
              "examples": ["receita", "ceis,cnep", "licitacoes"],
              "default": "receita"
            }
          }
        ],
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -s 'https://api.opencnpj.org/12ABC34501DE35?datasets=receita'"
          },
          {
            "lang": "JavaScript",
            "label": "fetch",
            "source": "const response = await fetch('https://api.opencnpj.org/12ABC34501DE35?datasets=receita', {\n  headers: { Accept: 'application/json' },\n});\n\nconst data = await response.json();\nconsole.log(data);"
          },
          {
            "lang": "Python",
            "label": "requests",
            "source": "import requests\n\nresponse = requests.get('https://api.opencnpj.org/12ABC34501DE35?datasets=receita', headers={'Accept': 'application/json'})\nresponse.raise_for_status()\nprint(response.json())"
          },
          {
            "lang": "C#",
            "label": "HttpClient",
            "source": "using var http = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"https://api.opencnpj.org/12ABC34501DE35?datasets=receita\");\nrequest.Headers.Accept.ParseAdd(\"application/json\");\n\nusing var response = await http.SendAsync(request);\nresponse.EnsureSuccessStatusCode();\n\nvar json = await response.Content.ReadAsStringAsync();\nConsole.WriteLine(json);"
          }
        ],
        "responses": {
          "200": {
            "description": "CNPJ encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CnpjResponse"
                },
                "examples": {
                  "simples": {
                    "summary": "Resposta simples",
                    "value": {
                      "cnpj": "12ABC34501DE35",
                      "updated_at": "2026-04-14T19:56:00Z",
                      "razao_social": "EMPRESA EXEMPLO LTDA",
                      "nome_fantasia": "EMPRESA EXEMPLO",
                      "situacao_cadastral": "ATIVA",
                      "data_inicio_atividade": "2026-01-15",
                      "cnae_principal": "6201501",
                      "codigo_natureza_juridica": "2062",
                      "natureza_juridica": "Sociedade Empresária Limitada",
                      "uf": "SP",
                      "municipio": "SAO PAULO",
                      "porte_empresa": "DEMAIS"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "CNPJ ou filtro de dataset inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCnpj": {
                    "summary": "CNPJ inválido",
                    "value": {
                      "error": "invalid cnpj"
                    }
                  },
                  "invalidDataset": {
                    "summary": "Dataset desconhecido",
                    "value": {
                      "error": "invalid dataset: desconhecido"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "CNPJ não encontrado no release publicado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "summary": "Não encontrado",
                    "value": {
                      "error": "not found"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Falha temporária ao carregar metadados ou shard.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidShard": {
                    "summary": "Falha de leitura",
                    "value": {
                      "error": "invalid shard payload"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/info": {
      "get": {
        "tags": ["Metadados"],
        "summary": "Consultar publicação atual",
        "operationId": "getInfo",
        "responses": {
          "200": {
            "description": "Metadados do release publicado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InfoResponse"
                },
                "examples": {
                  "info": {
                    "summary": "Metadados publicados",
                    "value": {
                      "total": 70852335,
                      "last_updated": "2026-04-14T19:56:00Z",
                      "datasets": {
                        "receita": {
                          "updated_at": "2026-04-14T19:56:00Z",
                          "source_snapshot_month": "2026-04",
                          "record_count": 70852335,
                          "zip_url": "https://file.opencnpj.org/releases/receita/data.zip",
                          "zip_size": 8270000000,
                          "zip_md5checksum": "e1a887293df69ace71eb8bf53e79a091"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Falha ao carregar metadados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "infoLoadFailed": {
                    "value": {
                      "error": "info load failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/schema": {
      "get": {
        "tags": ["Metadados"],
        "summary": "Consultar JSON Schema",
        "operationId": "getSchema",
        "responses": {
          "200": {
            "description": "JSON Schema 2020-12 do payload de CNPJ.",
            "content": {
              "application/schema+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CnpjResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "cnpj": {
            "type": "string",
            "pattern": "^[A-Z0-9]{12}\\d{2}$",
            "examples": ["12ABC34501DE35"]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Última atualização publicada da base da Receita Federal. O Worker deriva o valor do info.json sem duplicá-lo nos shards."
          },
          "razao_social": {
            "type": "string",
            "description": "Razão social. Para empresário individual (MEI), o CPF publicado no fim do nome é removido."
          },
          "nome_fantasia": {
            "type": "string"
          },
          "situacao_cadastral": {
            "type": "string"
          },
          "codigo_natureza_juridica": {
            "type": "string",
            "description": "Código da natureza jurídica conforme a tabela da Receita Federal.",
            "maxLength": 4,
            "examples": ["2062"]
          },
          "natureza_juridica": {
            "type": "string",
            "description": "Descrição da natureza jurídica.",
            "examples": ["Sociedade Empresária Limitada"]
          },
          "lgpd_anonimizado": {
            "type": "boolean",
            "description": "true quando campos pessoais deste CNPJ foram anonimizados a pedido do titular (LGPD)."
          },
          "cno": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CnoPayload"
              },
              {
                "type": "null"
              }
            ]
          },
          "rntrc": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RntrcPayload"
              },
              {
                "type": "null"
              }
            ]
          },
          "favorecidos_pj": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "ceis": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "cepim": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "cnep": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "acordos_leniencia": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "licitacoes": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "contratos": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "renuncias_fiscais": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "notas_fiscais": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "convenios": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "emendas_parlamentares": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          },
          "emendas_documentos": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PortalRecordCollection"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "PortalRecordCollection": {
        "type": "object",
        "description": "Coleção de registros normalizados do Portal da Transparência. O nome da propriedade de coleção depende do dataset.",
        "required": ["updated_at"],
        "properties": {
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            {
              "type": "string"
            }
          ]
        }
      },
      "CnoPayload": {
        "type": "object",
        "properties": {
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "obras": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "RntrcPayload": {
        "type": "object",
        "properties": {
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "numero_rntrc": {
            "type": "string"
          },
          "categoria": {
            "type": "string"
          },
          "situacao": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "InfoResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "last_updated": {
            "type": "string"
          },
          "datasets": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/PublishedDataset"
            }
          }
        }
      },
      "PublishedDataset": {
        "type": "object",
        "properties": {
          "updated_at": {
            "type": "string"
          },
          "source_snapshot_month": {
            "type": ["string", "null"],
            "pattern": "^\\d{4}-\\d{2}$",
            "description": "Somente em datasets.receita: competência (YYYY-MM) dos arquivos da Receita Federal usados na publicação. Ausente ou null em releases anteriores à inclusão do campo."
          },
          "record_count": {
            "type": "integer"
          },
          "zip_url": {
            "type": "string",
            "format": "uri"
          },
          "zip_size": {
            "type": "integer"
          },
          "zip_md5checksum": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}