Linvix Consulta API
Uma API para consultar CPF e CNPJ, com chave segura, origem identificada e validade explícita.
Consultar um documento
POST /v1/consultas
Authorization: Bearer SUA_CHAVE_DE_API
Content-Type: application/json
{
"tipo": "cnpj",
"documento": "37335118000180",
"fresh": false
}Envie um documento por requisição. Para CPF, use "tipo": "cpf". CPF e CNPJ são validados antes da consulta. CNPJ numérico e alfanumérico são aceitos. Não coloque documentos nem chaves na URL.
Resposta
{
"request_id": "uuid-da-requisicao",
"tipo": "cnpj",
"origem": "cache",
"provedor": "cnpjws",
"consultado_em": "2026-10-19T16:00:00Z",
"valido_ate": "2026-11-18T16:00:00Z",
"desatualizado": false,
"status": "found",
"dados": {
"documento": "37335118000180",
"razao_social": "EMPRESA DE EXEMPLO",
"endereco": { "cidade": "Exemplo", "uf": "SP" }
}
}origem é cache quando a resposta veio da base local e provider quando exigiu consulta externa. consultado_em é a data da coleta pela Linvix; atualizado_na_fonte, quando disponível, indica a atualização declarada pelo fornecedor. Isso não constitui consulta oficial em tempo real.
A resposta CPF contém documento, nome e nascimento no formato ISO. A resposta CNPJ contém razão social, nome fantasia, situação, abertura, natureza jurídica, porte, CNAE principal e endereço, conforme a disponibilidade do fornecedor. Campos ausentes são null. Não são armazenados o payload bruto nem o quadro societário nesta versão.
Validade e atualização
O parâmetro fresh: true exige a permissão cache:refresh e pode consumir uma nova consulta do fornecedor. Consultas simultâneas do mesmo documento são agrupadas para evitar chamadas pagas repetidas.
Por padrão, dados vencidos não são devolvidos quando o fornecedor falha. A administração pode autorizar contingência de CNPJ com sinalização desatualizado: true. CPF vencido nunca é devolvido nessa situação.
Limites
As cotas de segundo, dia e mês são compartilhadas entre todos os sistemas que usam a mesma chave. Dia e mês seguem UTC. Tanto respostas da base quanto consultas externas válidas consomem a cota da chave. Uma cobrança do fornecedor é independente dessa cota. Não há consulta em lote na primeira versão.
Erros
| HTTP | Significado |
|---|---|
| 401 | Chave ausente, inválida, expirada, revogada ou IP não autorizado. |
| 403 | Permissão insuficiente para CPF, CNPJ ou atualização forçada. |
| 404 | Documento não encontrado. A resposta usa o mesmo formato, com status not_found e dados null. |
| 422 | Documento ou corpo inválido. Não é feita consulta ao fornecedor. |
| 429 | Cota atingida. Respeite Retry-After. |
| 503 | Fornecedor indisponível, limitado ou consulta em andamento. Respeite Retry-After. |
Erros de autenticação e validação usam {"error":{"code":"...","message":"..."},"request_id":"..."}. Não repita automaticamente respostas 401, 403 ou 422. Para 429/503, respeite o prazo informado e aplique espera progressiva.
Segurança
Guarde a chave no servidor, fora de repositórios e páginas públicas. Use uma chave por sistema, o menor conjunto de permissões possível e rotação periódica. As respostas não devem ser registradas indiscriminadamente em logs. A finalidade e o acesso aos dados devem ser compatíveis com os contratos e a operação da sua empresa.