Catta API v1

Guia de integração da Catta API: autenticação, créditos, endpoints, respostas e erros.

Primeiros passos

Use a base da versão v1 e valide a chave com o status do workspace antes de executar uma busca.

Base URL

Todas as rotas desta documentação usam HTTPS, retornam JSON e começam pela mesma base.

https://api.catta.com.br/v1

A versão faz parte da URL. Monte os caminhos de busca a partir dessa base, por exemplo https://api.catta.com.br/v1/search/name.

Primeira requisição

Consulte GET /workspace para validar a autenticação e conferir créditos e disponibilidade. Esse endpoint não consome créditos.

RequisiçãoGET /workspace

curl "https://api.catta.com.br/v1/workspace" \
  -H "Token: <api_key>"

Resposta200 OK

{
  "handle": "empresa-exemplo",
  "api_credits": 1200,
  "can_search": true,
  "search_status": "available",
  "has_debt": false,
  "is_banned": false
}

Autenticação

Cada workspace possui uma chave própria, enviada no header Token em todas as requisições.

Chave de API

A chave fica disponível em Configurações → API no workspace. Envie seu valor no header Token. A ausência do header ou uma chave bem-formada que não pertença a um workspace retorna 401; uma chave fora do formato esperado retorna 422 com o campo apiKey em params.

Segurança da credencial

Trate a chave como um segredo

Qualquer pessoa com acesso à chave pode fazer buscas e consumir créditos em nome do workspace. Use variáveis de ambiente e nunca exponha a credencial no navegador, em código-fonte, logs ou interfaces públicas.

Créditos e disponibilidade

Cada busca válida reserva um crédito antes de consultar os dados e só o consome quando encontra resultado.

Consumo de créditos

Resultado da busca	Efeito sobre os créditos
Um ou mais registros	Consome 1 crédito, independentemente da quantidade retornada na página.
Nenhum registro	Não consome crédito; a reserva é devolvida ao workspace.

Estado do workspace

Consulte GET /workspace sempre que precisar sincronizar a disponibilidade. Os campos api_credits, can_search e search_status formam o estado operacional da integração.

`search_status`	Significado
`available`	O workspace tem créditos e pode executar buscas.
`out_of_credits`	Não existem créditos disponíveis.
`has_debt`	As buscas estão temporariamente indisponíveis por pendência na conta.
`banned`	O workspace foi desativado permanentemente.

O status do workspace não consome créditos

Você pode consultar GET /workspace mesmo quando can_search for false. Apenas os endpoints em /search/* exigem disponibilidade e reservam crédito.

Endpoints

A v1 expõe o status do workspace e seis formas de busca. Todas as operações usam GET.

Método	Caminho	Uso
`GET`	`/workspace`	Consulta créditos e disponibilidade.
`GET`	`/search/name`	Busca pessoas ou empresas por nome.
`GET`	`/search/cpf-cnpj`	Consulta direta por CPF ou CNPJ.
`GET`	`/search/phone`	Busca registros por telefone.
`GET`	`/search/address`	Busca por endereço, número ou CEP.
`GET`	`/search/activity`	Busca empresas por CNAE ou atividade.
`GET`	`/search/mother-name`	Busca pessoas físicas pelo nome da mãe.

Parâmetros comuns

Os parâmetros são enviados na query string. Cada endpoint detalha abaixo quais deles aceita.

Parâmetro	Formato e comportamento
`state`	Obrigatório nas buscas. Use uma UF brasileira; apenas CPF/CNPJ aceita `BR` para busca nacional.
`query`	Obrigatório nas buscas. O formato depende do endpoint.
`city`	Opcional. Código IBGE da cidade com 7 dígitos. Não pode ser usado com `state=BR`.
`phone_type`	Opcional nos endpoints compatíveis: `landlines` para fixos ou `mobiles` para celulares.
`person_type`	Opcional nos endpoints compatíveis: `individuals` para pessoas físicas ou `companies` para pessoas jurídicas.
`page`	Opcional nos endpoints paginados. A primeira página é usada quando o parâmetro é omitido.

Formatos de resposta

Nome, telefone, endereço, atividade e nome da mãe retornam um objeto paginado com start, limit, length, total e results. Cada página contém até 10 resultados. A busca por CPF/CNPJ é direta: retorna um registro ou um objeto vazio quando nada é encontrado.

Privacidade na resposta

Um registro removido por solicitação de privacidade pode ser representado apenas pelos campos id e lgpd_removed: true. Trate esse estado sem tentar reutilizar dados armazenados anteriormente.

GET/workspace

Status do workspace

Retorna o estado operacional do workspace vinculado à chave. A requisição exige autenticação, mas não exige disponibilidade para busca e não consome créditos.

curl "https://api.catta.com.br/v1/workspace" \
  -H "Token: <api_key>"

Campo	Descrição
`handle`	Identificador do workspace no Catta.
`api_credits`	Créditos disponíveis para buscas com resultado.
`can_search`	Indica se a chave pode executar buscas neste momento.
`search_status`	Estado operacional: `available`, `out_of_credits`, `has_debt` ou `banned`.
`has_debt`	Indica bloqueio temporário por pendência na conta.
`is_banned`	Indica desativação permanente do workspace.

GET/search/name

Busca por nome

Busca pessoas físicas ou jurídicas por nome, nome civil ou razão social. Os resultados são paginados.

curl "https://api.catta.com.br/v1/search/name?state=AL&query=Empresa%20Exemplo&page=1" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira. Busca nacional não está disponível.
`query`	Sim	Nome, nome civil ou razão social.
`person_type`	Não	`individuals` ou `companies`.
`phone_type`	Não	`landlines` ou `mobiles`.
`city`	Não	Código IBGE da cidade.
`page`	Não	Página buscada.

GET/search/cpf-cnpj

Busca por CPF ou CNPJ

Faz uma consulta direta por CPF ou CNPJ, com ou sem pontuação. Este é o único endpoint que aceita state=BR para procurar em todos os estados.

curl "https://api.catta.com.br/v1/search/cpf-cnpj?state=BR&query=00000000000000" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira ou `BR` para busca nacional.
`query`	Sim	CPF ou CNPJ, com ou sem pontuação.
`phone_type`	Não	`landlines` ou `mobiles`.
`city`	Não	Código IBGE; não pode ser combinado com `state=BR`.

A resposta não usa paginação. Quando a consulta nacional encontra um registro, os telefones e endereços são agrupados por UF.

GET/search/phone

Busca por telefone

Busca registros por telefone, com ou sem DDD. Os resultados são paginados.

curl "https://api.catta.com.br/v1/search/phone?state=AL&query=0000000000&page=1" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira. Busca nacional não está disponível.
`query`	Sim	Telefone com ou sem formatação.
`person_type`	Não	`individuals` ou `companies`.
`city`	Não	Código IBGE da cidade.
`page`	Não	Página buscada.

GET/search/address

Busca por endereço

Busca por endereço acompanhado do número ou por CEP acompanhado do número. Os resultados são paginados.

curl "https://api.catta.com.br/v1/search/address?state=AL&query=Avenida%20Exemplo%20100&page=1" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira. Busca nacional não está disponível.
`query`	Sim	Endereço e número, ou CEP e número.
`person_type`	Não	`individuals` ou `companies`.
`phone_type`	Não	`landlines` ou `mobiles`.
`city`	Não	Código IBGE da cidade.
`page`	Não	Página buscada.

GET/search/activity

Busca por atividade

Busca empresas pelo código CNAE ou pelo nome da atividade econômica. Códigos podem ser enviados com 6 ou 7 dígitos. Os resultados são paginados.

curl "https://api.catta.com.br/v1/search/activity?state=AL&query=6201501&page=1" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira. Busca nacional não está disponível.
`query`	Sim	Código CNAE com 6 ou 7 dígitos, ou nome da atividade.
`phone_type`	Não	`landlines` ou `mobiles`.
`city`	Não	Código IBGE da cidade.
`page`	Não	Página buscada.

GET/search/mother-name

Busca por nome da mãe

Busca pessoas físicas pelo nome da mãe. Os resultados são paginados.

curl "https://api.catta.com.br/v1/search/mother-name?state=AL&query=Maria%20Exemplo&page=1" \
  -H "Token: <api_key>"

Parâmetro	Obrigatório	Observação
`state`	Sim	Use uma UF brasileira. Busca nacional não está disponível.
`query`	Sim	Nome da mãe.
`phone_type`	Não	`landlines` ou `mobiles`.
`city`	Não	Código IBGE da cidade.
`page`	Não	Página buscada.

Erros

Falhas usam status HTTP e um corpo JSON com message. Erros de validação também incluem params.

Formato da resposta

{
  "message": "Algumas informações enviadas não puderam ser processadas. Revise os campos e tente novamente.",
  "params": [
    {
      "param": "state",
      "message": "O estado a ser buscado não é válido."
    }
  ]
}

Status HTTP

Status	Significado
`401`	O header `Token` não foi enviado ou a chave bem-formada não pertence a um workspace.
`403`	Um endpoint em `/search/*` foi chamado por um workspace sem créditos, inadimplente ou permanentemente desativado. `GET /workspace` continua disponível para consultar esse estado.
`404`	O caminho solicitado não existe na API.
`405`	O endpoint existe, mas não aceita o método HTTP usado.
`422`	A chave está malformada ou um ou mais parâmetros não passaram pela validação.
`500`	Uma falha interna impediu o processamento da requisição.

Retentativas e observabilidade

Não registre o header Token nem respostas com dados pessoais em ferramentas de observabilidade. Defina timeout no cliente e, antes de repetir uma busca após uma falha de rede, considere que a primeira requisição pode ter sido processada e consumido crédito.

Suporte

Suporte de integração

Quer desenhar o melhor fluxo para o seu produto?

Fale com a equipe sobre integração, volume de buscas ou uso responsável da API.

Falar no WhatsApp Enviar email