Catta API v1

Base URL

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

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.

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

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

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

Consumo de créditos

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.

Parâmetros comuns

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

Para limitar os resultados a um bairro, combine neighborhood, city e state. O filtro está disponível em Nome, CPF/CNPJ, Telefone, Endereço, Atividade e Nome da mãe. Sem neighborhood, o comportamento da consulta permanece igual.

A busca ignora acentos e diferenças entre maiúsculas e minúsculas. Todas as palavras informadas precisam aparecer no bairro, sem exigir a mesma ordem: sao jose encontra São José, mas Jose não encontra Josefina. Cidade e bairro precisam pertencer ao mesmo endereço cadastrado. Em Endereço, a rua, o CEP e os demais termos também precisam corresponder a esse mesmo endereço.

O filtro é aplicado antes da contagem e da paginação. A lista addresses contém somente os endereços que correspondem ao recorte; company_address continua sendo o endereço cadastral da empresa. O bairro não representa a localização atual da pessoa nem a origem do DDD do telefone.

Exemplo: empresas de uma atividade no bairro Ponta Verde, em Maceió:

curl --get "https://api.catta.com.br/v1/search/activity" \
  -H "Token: <api_key>" \
  --data-urlencode "state=AL" \
  --data-urlencode "query=6201501" \
  --data-urlencode "city=2704302" \
  --data-urlencode "neighborhood=Ponta Verde"

Informar neighborhood sem cidade, com state=BR, vazio ou acima de 160 caracteres retorna 422 com os campos inválidos em params. O formato da resposta, a paginação e o consumo de créditos não mudam.

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 completo é direta: retorna um registro ou {} quando nada é encontrado. No mesmo endpoint, uma raiz de CNPJ com oito caracteres retorna o objeto paginado, mesmo com apenas um estabelecimento. Sem resultados, a raiz retorna total: 0 e results: [].

Nas buscas por nome, nome da mãe e telefone com state=BR, cada resultado reúne a mesma identidade por CPF/CNPJ, com telefones e endereços separados por UF. total conta identidades, não ocorrências estaduais. São aceitas páginas de 1 a 10, com até 100 resultados navegáveis. Nome da mãe retorna cada pessoa encontrada pelo CPF dela. Registros sem documento utilizável permanecem separados.

A busca nacional usa os mesmos endpoints da v1. Consultas com uma UF específica continuam retornando o formato estadual existente.

Nome e nome da mãe com state=BR são ordenados por relevância: nome completo, sequência de palavras e demais correspondências. A melhor correspondência entre nome civil, social, razão social e fantasia determina a posição; atualização e identidade desempatam. Ocorrências em mais UFs não aumentam a relevância. Essa ordenação não acrescenta busca aproximada. Consultas por UF mantêm a ordenação estadual existente.

Buscas nacionais muito amplas ou que excedam o tempo disponível retornam 422 com code: "search_national_limit"; refine a consulta ou selecione uma UF. Não há resultado parcial nem cobrança de crédito nessa falha. Mudanças concorrentes nos resultados podem retornar 409 com code: "search_results_changed"; repita a busca. A seleção e o total podem ser reutilizados por até cinco minutos; os dados das identidades da página são relidos a cada requisição.

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

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.