Documentação

Uma chave e três formas de identificar a empresa: domínio, CNPJ ou ticker da B3. O logoapi devolve a imagem pronta.

Início rápido

Você precisa de uma chave pk_live_…. Nesta fase o cadastro está fechado: use o playground com os endpoints de demonstração ou a conta demo no painel.

<img
  src="https://logoapi.nohumans.com.br/v1/logo/nubank.com.br?size=128&format=png&key=pk_live_SUA_CHAVE"
  alt="Nubank"
  width="128"
  height="128"
/>

Pronto. A resposta é uma imagem em JPG (padrão), PNG ou WebP, com cache de um dia no navegador e 30 dias no servidor.

Sem img, direto no servidor

curl "https://logoapi.nohumans.com.br/v1/logo/nubank.com.br?format=png" \
  -H "Authorization: Bearer pk_live_SUA_CHAVE" \
  --output nubank.png

Autenticação

Toda requisição precisa de uma chave. Há duas formas, e as duas usam a mesma chave:

Authorization: Bearer pk_live_SUA_CHAVE

GET /v1/logo/nubank.com.br?key=pk_live_SUA_CHAVE

A chave do logoapi só funciona nos nossos domínios. Ela não dá acesso ao logo.dev: o proxy guarda a credencial do provedor no servidor.

Referência

Por domínio

O jeito mais direto. Use só o host, sem protocolo e sem caminho:

GET /v1/logo/nubank.com.br?size=64&format=webp&retina=true

www. e subdomínios são reduzidos ao domínio registrável. Maiúsculas não importam.

Por CNPJ

O logoapi valida os dígitos, consulta a base pública (BrasilAPI), encontra a razão social e procura o domínio da empresa. Se achar, serve o logo; se não, gera o monograma.

GET /v1/logo/cnpj/00.000.000/0001-91?format=png&size=128

Aceita CNPJ com ou sem pontuação. O CNPJ também vai nos headers da resposta:

x-logoapi-cnpj: 00000000000191
x-logoapi-razao-social: BANCO%20DO%20BRASIL%20SA

Por ticker da B3

Tickers da B3 são resolvidos por um mapa local antes de chegar ao provedor:

GET /v1/logo/ticker/PETR4?format=png

A amostra cobre as ações mais negociadas. Tickers fora da amostra seguem para o provedor, que pode ou não reconhecer a bolsa brasileira.

Parâmetros de imagem

theme=dark exige transparência: se você pedir JPG, o proxy troca para PNG automaticamente. fallback=404 devolve 404 quando não há logo, para você usar sua própria imagem.

Fallback monograma

Sem logo, a resposta é um SVG determinístico com as iniciais da marca — mesma entrada, mesmo desenho, status 200. O header x-logoapi-source diz de onde veio a imagem:

x-logoapi-source: cache | upstream | monogram | budget | quota

Busca por nome

Converte nome em candidatos de domínio, do mais provável ao menos provável.

GET /v1/search?q=quinto%20andar&limit=5&method=typeahead

{
  "data": [
    {
      "name": "QuintoAndar",
      "domain": "quintoandar.com.br",
      "logo_url": "/v1/logo/quintoandar.com.br",
      "segment": null
    }
  ],
  "meta": { "source": "logodev", "cached": false, "count": 1 }
}

method=match (padrão) busca nome completo e apelidos. method=typeahead casa só prefixos, para autocomplete. Sem chave de provedor configurada, a busca usa o catálogo local de marcas brasileiras.

Dados da empresa

O mesmo pipeline do logo, mas em JSON:

GET /v1/cnpj/00.000.000/0001-91

{
  "data": {
    "cnpj": "00.000.000/0001-91",
    "razaoSocial": "BANCO DO BRASIL SA",
    "nomeFantasia": "DIRECAO GERAL",
    "situacao": "ATIVA",
    "cnae": "Bancos múltiplos, com carteira comercial",
    "email": null,
    "endereco": { "cidade": "BRASILIA", "uf": "DF" },
    "dominio": "bb.com.br",
    "logo_url": "/v1/logo/bb.com.br",
    "candidatos": []
  }
}

Erros

{
  "error": {
    "code": "quota_exceeded",
    "message": "Créditos de API esgotados neste mês.",
    "limit": 100,
    "used": 100
  }
}

Limites e cotas

Duas coisas diferentes, com headers diferentes:

• Por minuto — x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset.
• Por mês — x-quota-kind, x-quota-limit, x-quota-used, x-quota-remaining e x-quota-reset.

Imagens consomem a cota de cdn_requests. Busca e dados de CNPJ consomem api_credits. O ciclo vira no primeiro dia do mês, no fuso de São Paulo.

Estourou a cota? Imagens recebem monograma com status 429; JSON recebe o erro acima. Nada é cobrado automaticamente.

Cache

O logoapi guarda cada resposta em disco por 30 dias (imagens) ou 24 horas (JSON). O navegador recebe Cache-Control: public, max-age=86400 nas imagens, então repetir a mesma URL nem chega ao servidor.

O header x-logoapi-cache mostra hit ou miss para o cache do servidor. A taxa de acerto aparece no painel.

Atribuição e marcas

Os logos pertencem aos seus titulares. Use o logo para identificar a marca, nunca para sugerir endosso. Não registre marca a partir de um logo obtido aqui.

No plano Grátis, projetos comerciais precisam de um link visível:

<a href="https://logoapi.nohumans.com.br">Logos via logoapi</a>

Projetos pessoais e planos pagos não precisam. O logoapi, por sua vez, mantém o crédito ao logo.dev onde a licença exige — veja o rodapé deste site.

Produção

• Guarde a chave em variável de ambiente; não versione.
• Crie uma chave por ambiente e revogue as antigas.
• Use size igual ao tamanho exibido e retina=true em telas densas.
• Prefira format=webp em listas grandes.
• Monitore x-quota-remaining antes de campanhas.
• Configure fallback=404 se quiser controlar a imagem padrão.