{"openapi":"3.1.0","info":{"title":"API dadosdecnpj.com.br","version":"1.0.0","summary":"Consulta de CNPJ e pesquisa de empresas brasileiras (dados abertos da Receita Federal).","description":"Todas as respostas usam o mesmo envelope JSON: `{success, data, meta}` no sucesso e `{success: false, error: {code, message, details}, meta}` no erro. `meta.dataset` informa a versão/competência da base e `meta.request_id` identifica a requisição (também no cabeçalho `X-Request-Id`).\n\nAutenticação: `Authorization: Bearer ddc_live_…` (gere a chave no painel, em /painel/api). Não há sessão nem cookies.\n\nLimites: por chave, requisições por minuto (janela deslizante; cabeçalhos `X-RateLimit-Limit` e `X-RateLimit-Remaining`); por conta, requisições por mês (`X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`). Estourar qualquer um devolve 429 com `Retry-After`. Requisição barrada não consome a cota.\n\nCréditos: só `GET /cnpj/{cnpj}?include=contacts` usa créditos (1 por CNPJ novo; 0 se o CNPJ já foi desbloqueado, pela API ou pelo site). O cabeçalho `X-Credits-Used` informa o gasto de cada requisição.","contact":{"name":"dadosdecnpj.com.br","url":"https://dadosdecnpj.com.br/contato"}},"servers":[{"url":"https://dadosdecnpj.com.br/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Empresas","description":"Consulta de CNPJ e pesquisa com filtros."},{"name":"Referência","description":"CNAEs, municípios, UFs e códigos usados nos filtros."},{"name":"Conta","description":"Saldo de créditos e cota do mês."}],"paths":{"/cnpj/{cnpj}":{"get":{"tags":["Empresas"],"operationId":"getCompany","summary":"Dados de um CNPJ","description":"Ficha completa de um estabelecimento (numérico ou alfanumérico, com ou sem máscara). `include=partners` traz o quadro societário; `include=contacts` desbloqueia telefones e e-mail com créditos. Se os contatos foram ocultados a pedido do titular (LGPD) ou a empresa não tem contato, nada é cobrado.","parameters":[{"name":"cnpj","in":"path","required":true,"schema":{"type":"string","examples":["00000000000191"]},"description":"14 caracteres (máscara opcional)."},{"name":"include","in":"query","schema":{"type":"string","examples":["partners,contacts"]},"description":"Lista separada por vírgula: partners, contacts."}],"responses":{"200":{"description":"Dados do CNPJ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Company"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"credits":{"$ref":"#/components/schemas/CreditsUsed"}}}]}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"503":{"$ref":"#/components/responses/Unavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/companies/search":{"get":{"tags":["Empresas"],"operationId":"searchCompanies","summary":"Pesquisa de empresas","description":"Filtros do FilterSchema v1 em querystring achatada (mesma validação do site). Paginação por cursor: repita os mesmos filtros e `limit` com o `meta.next_cursor` da página anterior; o cursor vale por 5 minutos sem uso. Navegação até 10.000 resultados. Não traz telefone nem e-mail e não usa créditos.","parameters":[{"name":"q","in":"query","description":"Texto livre (razão social, nome fantasia).","schema":{"type":"string","maxLength":120}},{"name":"cnpj","in":"query","description":"CNPJ completo (14) ou raiz (8 posições: todos os estabelecimentos).","schema":{"type":"string"}},{"name":"legal_name","in":"query","description":"Razão social contém.","schema":{"type":"string","maxLength":120}},{"name":"trade_name","in":"query","description":"Nome fantasia contém.","schema":{"type":"string","maxLength":120}},{"name":"cnae_text","in":"query","description":"Palavras da descrição da atividade.","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","description":"Situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada. Padrão: 02. Use `any` para qualquer situação. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["02","02,04","any"]}},{"name":"cnae","in":"query","description":"Códigos CNAE de 7 dígitos. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["4930202"]}},{"name":"cnae_scope","in":"query","description":"Onde procurar os CNAEs: atividade principal (padrão), secundárias ou qualquer.","schema":{"type":"string","enum":["main","secondary","any"],"default":"main"}},{"name":"uf","in":"query","description":"UFs. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["MG","MG,SP"]}},{"name":"city_id","in":"query","description":"Código do município na Receita (4 dígitos; veja /cities). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["5403"]}},{"name":"zip_prefix","in":"query","description":"Começo do CEP (1 a 8 dígitos). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["384"]}},{"name":"ddd","in":"query","description":"DDD do telefone. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["34"]}},{"name":"company_size","in":"query","description":"Porte: 00 não informado, 01 ME, 03 EPP, 05 demais. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["01,03"]}},{"name":"legal_nature","in":"query","description":"Natureza jurídica (4 dígitos; veja /legal-natures). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["2062"]}},{"name":"headquarters","in":"query","description":"Matriz ou filial.","schema":{"type":"string","enum":["any","headquarters","branch"],"default":"any"}},{"name":"opened_from","in":"query","description":"Aberta a partir de (AAAA-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"opened_to","in":"query","description":"Aberta até (AAAA-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"age_years_min","in":"query","description":"Idade mínima em anos.","schema":{"type":"integer","minimum":0}},{"name":"age_years_max","in":"query","description":"Idade máxima em anos.","schema":{"type":"integer","minimum":0}},{"name":"share_capital_min","in":"query","description":"Capital social mínimo (R$).","schema":{"type":"number","minimum":0}},{"name":"share_capital_max","in":"query","description":"Capital social máximo (R$).","schema":{"type":"number","minimum":0}},{"name":"simples","in":"query","description":"Optante pelo Simples Nacional.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"mei","in":"query","description":"Optante pelo MEI.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"has_phone","in":"query","description":"Tem telefone na base.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"has_email","in":"query","description":"Tem e-mail na base.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"sort","in":"query","description":"Ordenação.","schema":{"type":"string","default":"legal_name:asc","enum":["legal_name:asc","legal_name:desc","opened_at:asc","opened_at:desc","share_capital:asc","share_capital:desc"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página (alias: page_size)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`meta.next_cursor` da página anterior."}],"responses":{"200":{"description":"Uma página de empresas.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchRow"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"max_results":{"type":"integer"},"filters":{"type":"object","description":"Filtros normalizados, no formato achatado."}}}]}}}}}},"410":{"description":"Cursor expirado (`cursor_expired`): volte para a primeira página.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"503":{"$ref":"#/components/responses/Unavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/companies/search/count":{"get":{"tags":["Empresas"],"operationId":"countCompanies","summary":"Contagem e facets","description":"Total de empresas para os filtros e a distribuição por UF, porte, situação, matriz/filial, Simples e MEI.","parameters":[{"name":"q","in":"query","description":"Texto livre (razão social, nome fantasia).","schema":{"type":"string","maxLength":120}},{"name":"cnpj","in":"query","description":"CNPJ completo (14) ou raiz (8 posições: todos os estabelecimentos).","schema":{"type":"string"}},{"name":"legal_name","in":"query","description":"Razão social contém.","schema":{"type":"string","maxLength":120}},{"name":"trade_name","in":"query","description":"Nome fantasia contém.","schema":{"type":"string","maxLength":120}},{"name":"cnae_text","in":"query","description":"Palavras da descrição da atividade.","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","description":"Situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada. Padrão: 02. Use `any` para qualquer situação. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["02","02,04","any"]}},{"name":"cnae","in":"query","description":"Códigos CNAE de 7 dígitos. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["4930202"]}},{"name":"cnae_scope","in":"query","description":"Onde procurar os CNAEs: atividade principal (padrão), secundárias ou qualquer.","schema":{"type":"string","enum":["main","secondary","any"],"default":"main"}},{"name":"uf","in":"query","description":"UFs. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["MG","MG,SP"]}},{"name":"city_id","in":"query","description":"Código do município na Receita (4 dígitos; veja /cities). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["5403"]}},{"name":"zip_prefix","in":"query","description":"Começo do CEP (1 a 8 dígitos). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["384"]}},{"name":"ddd","in":"query","description":"DDD do telefone. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["34"]}},{"name":"company_size","in":"query","description":"Porte: 00 não informado, 01 ME, 03 EPP, 05 demais. Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["01,03"]}},{"name":"legal_nature","in":"query","description":"Natureza jurídica (4 dígitos; veja /legal-natures). Separe por vírgula ou repita o parâmetro.","schema":{"type":"string","examples":["2062"]}},{"name":"headquarters","in":"query","description":"Matriz ou filial.","schema":{"type":"string","enum":["any","headquarters","branch"],"default":"any"}},{"name":"opened_from","in":"query","description":"Aberta a partir de (AAAA-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"opened_to","in":"query","description":"Aberta até (AAAA-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"age_years_min","in":"query","description":"Idade mínima em anos.","schema":{"type":"integer","minimum":0}},{"name":"age_years_max","in":"query","description":"Idade máxima em anos.","schema":{"type":"integer","minimum":0}},{"name":"share_capital_min","in":"query","description":"Capital social mínimo (R$).","schema":{"type":"number","minimum":0}},{"name":"share_capital_max","in":"query","description":"Capital social máximo (R$).","schema":{"type":"number","minimum":0}},{"name":"simples","in":"query","description":"Optante pelo Simples Nacional.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"mei","in":"query","description":"Optante pelo MEI.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"has_phone","in":"query","description":"Tem telefone na base.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"has_email","in":"query","description":"Tem e-mail na base.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"sort","in":"query","description":"Ordenação.","schema":{"type":"string","default":"legal_name:asc","enum":["legal_name:asc","legal_name:desc","opened_at:asc","opened_at:desc","share_capital:asc","share_capital:desc"]}}],"responses":{"200":{"description":"Total e facets.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/CountResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"503":{"$ref":"#/components/responses/Unavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/cnae":{"get":{"tags":["Referência"],"operationId":"searchCnaes","summary":"Busca de CNAEs","description":"Por código (prefixo) ou por palavras da descrição. Até 20 resultados.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"examples":["transporte rodoviário"]}}],"responses":{"200":{"description":"CNAEs encontrados.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Cnae"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/cnae/{code}":{"get":{"tags":["Referência"],"operationId":"getCnae","summary":"Um CNAE e sua hierarquia","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","examples":["4930202"]},"description":"Subclasse com 7 dígitos (máscara opcional)."}],"responses":{"200":{"description":"CNAE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Cnae"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/cities":{"get":{"tags":["Referência"],"operationId":"listCities","summary":"Municípios","description":"Com `q`: busca pelo nome (até 20). Só com `uf`: todos os municípios da UF. O `id` é o código da Receita, usado no filtro `city_id`.","parameters":[{"name":"uf","in":"query","schema":{"type":"string","enum":["AC","AL","AM","AP","BA","CE","DF","ES","GO","MA","MG","MS","MT","PA","PB","PE","PI","PR","RJ","RN","RO","RR","RS","SC","SE","SP","TO"]}},{"name":"q","in":"query","schema":{"type":"string","minLength":2}}],"responses":{"200":{"description":"Municípios.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/City"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/states":{"get":{"tags":["Referência"],"operationId":"listStates","summary":"Unidades da federação","responses":{"200":{"description":"Unidades da federação.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CodeName"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/statuses":{"get":{"tags":["Referência"],"operationId":"listStatuses","summary":"Situações cadastrais (filtro status)","responses":{"200":{"description":"Situações cadastrais (filtro status).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CodeName"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/company-sizes":{"get":{"tags":["Referência"],"operationId":"listCompanySizes","summary":"Portes (filtro company_size)","responses":{"200":{"description":"Portes (filtro company_size).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CodeName"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/legal-natures":{"get":{"tags":["Referência"],"operationId":"listLegalNatures","summary":"Naturezas jurídicas (filtro legal_nature)","responses":{"200":{"description":"Naturezas jurídicas (filtro legal_nature).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CodeName"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/credits":{"get":{"tags":["Conta"],"operationId":"getCredits","summary":"Saldo e cota do mês","responses":{"200":{"description":"Saldo, custos e cota.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Credits-Used":{"$ref":"#/components/headers/X-Credits-Used"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Credits"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/openapi.json":{"get":{"tags":["Referência"],"operationId":"getOpenApi","summary":"Esta especificação (OpenAPI 3.1)","security":[],"responses":{"200":{"description":"Documento OpenAPI.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ddc_live_…","description":"Chave gerada no painel. Guarde-a como segredo: ela só aparece uma vez."}},"headers":{"X-Request-Id":{"description":"Identificador da requisição (informe ao suporte).","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requisições por minuto permitidas para a chave.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela de 1 minuto.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Requisições por mês do plano (ausente = sem cota mensal).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Requisições restantes no mês.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Início do próximo mês (timestamp Unix, fuso de Brasília).","schema":{"type":"integer"}},"X-Credits-Used":{"description":"Créditos usados nesta requisição.","schema":{"type":"integer"}},"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"schemas":{"Dataset":{"type":["object","null"],"properties":{"version":{"type":"string","examples":["2026_10"]},"competence":{"type":"string","examples":["2026-10"]}}},"Meta":{"type":"object","required":["request_id"],"properties":{"dataset":{"$ref":"#/components/schemas/Dataset"},"request_id":{"type":"string"}},"additionalProperties":true},"Error":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["insufficient_credits"]},"message":{"type":"string"},"details":{"type":"object","description":"Em 422: erros por parâmetro ({\"uf\": [\"Código inválido: XX.\"]})."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CreditsUsed":{"type":"object","properties":{"used":{"type":"integer"},"newly_unlocked":{"type":"boolean"},"balance":{"type":"integer"}}},"Company":{"type":"object","properties":{"cnpj":{"type":"string"},"cnpj_formatted":{"type":"string"},"cnpj_base":{"type":"string"},"url":{"type":"string","format":"uri"},"is_headquarters":{"type":["boolean","null"]},"legal_name":{"type":"string"},"trade_name":{"type":["string","null"]},"status":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"date":{"type":["string","null"]}}},"status_reason":{"type":["object","null"],"properties":{"code":{"type":"string"},"description":{"type":["string","null"]}}},"special_status":{"type":["object","null"]},"opened_at":{"type":["string","null"]},"company_size":{"type":["object","null"],"properties":{"code":{"type":"string"},"label":{"type":"string"}}},"main_activity":{"type":"object","properties":{"code":{"type":"string"},"formatted":{"type":"string"},"description":{"type":["string","null"]}}},"secondary_activities_count":{"type":"integer"},"secondary_activities":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"formatted":{"type":"string"},"description":{"type":["string","null"]}}}},"address":{"type":"object","properties":{"street_type":{"type":["string","null"]},"street":{"type":["string","null"]},"number":{"type":["string","null"]},"complement":{"type":["string","null"]},"district":{"type":["string","null"]},"zip_code":{"type":["string","null"]},"city":{"type":["string","null"]},"city_id":{"type":["string","null"]},"city_slug":{"type":["string","null"]},"uf":{"type":["string","null"]},"foreign_city":{"type":["string","null"]},"country":{"type":["object","null"]}}},"legal_nature":{"type":["object","null"],"properties":{"code":{"type":"string"},"formatted":{"type":"string"},"description":{"type":["string","null"]}}},"responsible_qualification":{"type":["object","null"],"properties":{"code":{"type":"string"},"description":{"type":["string","null"]}}},"share_capital":{"type":["number","null"]},"responsible_federative_entity":{"type":["string","null"]},"simples":{"type":"object","properties":{"opted":{"type":["boolean","null"]},"since":{"type":["string","null"]},"until":{"type":["string","null"]}}},"mei":{"type":"object","properties":{"opted":{"type":["boolean","null"]},"since":{"type":["string","null"]},"until":{"type":["string","null"]}}},"contacts":{"type":"object","description":"Telefones e e-mail só com include=contacts (e se não houver ocultação LGPD).","properties":{"included":{"type":"boolean"},"unlocked":{"type":"boolean"},"suppressed":{"type":"boolean"},"has_phone":{"type":"boolean"},"has_email":{"type":"boolean"},"phones":{"type":["array","null"],"items":{"type":"string"}},"fax":{"type":["string","null"]},"email":{"type":["string","null"]}}},"partners":{"type":"object","description":"Quadro societário: itens só com include=partners.","properties":{"total":{"type":"integer"},"included":{"type":"boolean"},"complete":{"type":"boolean"},"items":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":["integer","null"]},"type_label":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF de pessoa física vem mascarado pela Receita."},"qualification":{"type":["object","null"],"properties":{"code":{"type":"string"},"description":{"type":["string","null"]}}},"entry_date":{"type":["string","null"]},"age_range":{"type":["string","null"]}}}}}},"branches_count":{"type":"integer"}}},"SearchRow":{"type":"object","properties":{"cnpj":{"type":["string","null"]},"legal_name":{"type":["string","null"]},"trade_name":{"type":["string","null"]},"city_name":{"type":["string","null"]},"uf":{"type":["string","null"]},"main_cnae":{"type":["string","null"]},"main_cnae_desc":{"type":["string","null"]},"status":{"type":["string","null"]},"opened_at":{"type":["string","null"]},"company_size":{"type":["string","null"]},"is_headquarters":{"type":["boolean","null"]},"simples":{"type":["boolean","null"]},"mei":{"type":["boolean","null"]},"has_phone":{"type":["boolean","null"]},"has_email":{"type":["boolean","null"]}}},"CountResult":{"type":"object","properties":{"total":{"type":"integer"},"facets":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"integer"}},"examples":[{"uf":{"MG":120,"SP":80}}]}}},"Cnae":{"type":"object","properties":{"code":{"type":"string"},"formatted":{"type":"string"},"description":{"type":"string"},"hierarchy":{"type":"object","properties":{"section":{"type":["object","null"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}},"division":{"type":"string"},"group":{"type":"string"},"class":{"type":"string"},"subclass":{"type":"string"}}}}},"City":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"uf":{"type":["string","null"]},"slug":{"type":"string"}}},"CodeName":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"Credits":{"type":"object","properties":{"balance":{"type":"integer"},"reserved":{"type":"integer"},"costs":{"type":"object","properties":{"cnpj_contacts":{"type":"integer"}}},"quota":{"type":"object","properties":{"period":{"type":"string","examples":["2026-10"]},"limit":{"type":["integer","null"]},"used":{"type":"integer"},"remaining":{"type":["integer","null"]},"resets_at":{"type":"string","format":"date-time"}}},"rate_limit":{"type":"object","properties":{"requests_per_minute":{"type":"integer"}}},"plan":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Sem chave, chave inválida, revogada ou vencida (`missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"Forbidden":{"description":"Conta bloqueada (`account_blocked`), conta no plano Grátis (`plan_required`) ou plano sem API (`api_not_in_plan`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"PaymentRequired":{"description":"Saldo insuficiente (`insufficient_credits`); `details` traz `required` e `balance`. Nada foi cobrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"NotFound":{"description":"Não encontrado (`company_not_found`, `cnae_not_found`, `not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"ValidationFailed":{"description":"Parâmetros inválidos (`validation_failed`, `invalid_cnpj`, `invalid_cursor`); `details` traz os erros por parâmetro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"TooManyRequests":{"description":"Limite por minuto (`rate_limited`) ou cota mensal (`monthly_quota_exceeded`) atingidos. Veja `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"Unavailable":{"description":"Base em publicação (`dataset_unavailable`). Tente de novo em instantes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}}}}}