QSA

Este endpoint devolve o QSA (quadro societário e de administradores) de um CNPJ, como registrado na Receita Federal: quem são os sócios e os administradores da empresa, com nome, qualificação e, no caso de sócio estrangeiro, país de origem.

🚧 O corpo é repassado do provedor, sem transformação

O conteúdo de data é o que o provedor devolve, entregue como está dentro do envelope padrão. Três consequências práticas:

• Os nomes dos campos estão em português, no vocabulário do provedor (nome, qualificacao, paisOrigem), e não no camelCase em inglês do resto da API.
• Todo bloco é opcional. Um bloco só aparece quando o provedor tem dado para ele. Nunca assuma que uma chave existe: teste antes de acessar.
• Não há garantia de tipo. Como não há conversão no caminho, o mesmo campo pode chegar como número ou como texto conforme a origem do dado.

Request

GET /receita-federal-cnpj-qsa/v1

Parâmetros

Parâmetro	Descrição	Obrigatório
taxId	CNPJ	Sim

TIP

O CNPJ pode ser passado com ou sem máscara (12.345.678/0001-95 ou 12345678000195) e devem ser passados todos os chars, incluindo os zeros à esquerda.

Um CNPJ que não passa na validação do dígito verificador devolve 422 antes de qualquer consulta — e é isso que acontece também quando o taxId não é informado.

CNPJ alfanumérico

O endpoint aceita o CNPJ alfanumérico definido pela IN RFB 2.229/2024, em que as oito primeiras posições da raiz e as quatro da ordem podem conter letras, e os dois dígitos verificadores continuam numéricos.

GET /receita-federal-cnpj-qsa/v1?taxId=12ABC34501DE35

As letras podem ser enviadas em minúsculas: a API normaliza para maiúsculas antes de consultar o provedor. A máscara também é aceita: 12.ABC.345/01DE-35.

Headers

Authorization: ApiKey <sua-chave-de-api>

Parâmetro de query desconhecido é ignorado

Um parâmetro diferente de taxId não gera erro: ele é simplesmente ignorado, e a resposta vem 200 normalmente.

Exemplo Request

GET /receita-federal-cnpj-qsa/v1?taxId=12.345.678/0001-95

curl -i -G 'https://api.nxcd.app/receita-federal-cnpj-qsa/v1' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --data-urlencode 'taxId=12345678000195'

Response

Campo	Descrição	Tipo
id	ID único da requisição	String
version	Versão da API	String
data	Objeto com o resultado da busca	Object
data.cnpj	CNPJ consultado	String
data.receitaFederalQsa	Objeto com o resultado da busca	Object
data.receitaFederalQsa.qsa	Lista com os dados encontrados por pessoa	Object[]
data.receitaFederalQsa.urlComprovante	URL com o comprovante da busca efetuada	String
metadata	Objeto com os metadados da requisição	Object
metadata.timeSpent	Tempo da requisição, em milissegundos	Number

data.receitaFederalQsa.qsa[]

Cada item é uma pessoa do quadro societário e de administradores.

Campo	Descrição	Tipo
nome	Nome do sócio ou administrador	String
qualificacao	Código e descrição da qualificação na Receita Federal	String
nomeRepresentanteLegal	Nome do representante legal, quando houver	String
qualificacaoRepresentanteLegal	Qualificação do representante legal, quando houver	String
paisOrigem	País de origem, quando o sócio for estrangeiro	String

Campo sem valor vem como texto vazio.

🚧 A consulta traz junto o cadastro na Receita Federal, sem o comprovante

Além do QSA, o provedor é consultado pelo cadastro do CNPJ, e o bloco receitaFederal pode vir na resposta. A API remove o urlComprovante desse bloco antes de responder — o comprovante do QSA, em receitaFederalQsa, não é removido.

Exemplos JSON

Veja alguns exemplos em JSON da resposta.

1. Exemplo quando dados encontrados

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": {
    "cnpj": "12345678000195",
    "receitaFederalQsa": {
      "qsa": [
        {
          "nome": "FULANO",
          "qualificacao": "49-Sócio-Administrador",
          "nomeRepresentanteLegal": "",
          "qualificacaoRepresentanteLegal": "",
          "paisOrigem": ""
        },
        {
          "nome": "FULANO",
          "qualificacao": "49-Sócio-Administrador",
          "nomeRepresentanteLegal": "",
          "qualificacaoRepresentanteLegal": "",
          "paisOrigem": ""
        }
      ],
      "urlComprovante": "https://..."
    }
  },
  "metadata": {
    "timeSpent": 10000
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ausente, inválida, ou sem a permissão nextid.bureaus.qsa.
404 Not Found	A versão informada na URL não existe. Só v1 é aceita.
422 Unprocessable Entity	taxId ausente, ou CNPJ que não passa na validação do dígito verificador.
500 Internal Server Error	Falha inesperada durante o processamento.

Exemplo de resposta com CNPJ inválido ou ausente:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid taxId (CNPJ)"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

A única versão é a v1, e ela é a que atende quando a versão é omitida na URL. /receita-federal-cnpj-qsa e /receita-federal-cnpj-qsa/v1 são equivalentes.

Versão	Situação	O que muda
v1	Recomendada	Única versão. É o que responde quando a versão é omitida na URL.

Qualquer outro valor no lugar de v1 devolve 404 com a mensagem API version not found.

Endpoints relacionados

Para a inscrição estadual do mesmo CNPJ, veja o Sintegra. Para o dossiê completo da empresa, com o quadro societário entre muitos outros blocos, veja o Background Check PJ.