Consultas Externas (queries)

Rota base v5/queries.

Registro único das consultas a provedores externos usadas na análise de uma operação. Cada execução vira uma consulta persistida com o que foi pedido (params), a resposta original do provedor (data), os principais resultados já normalizados em chave/valor (values) e os registros a que a consulta foi vinculada (associations), como uma proposta ou um empréstimo.

Tipos disponíveis:

type	Provedor	Para que serve
semear_srcc	Banco Semear	Autorregulação do crédito do trabalhador (CLT): verificação SRCC, pela matrícula.
semear_nmp	Banco Semear	Autorregulação CLT: verificação NMP, pelo telefone do trabalhador.
semear_mcb	Banco Semear	Autorregulação CLT: verificação MCB, pelo CPF do agente de crédito.
nova_vida_next_clt	Nova Vida	Perfil do trabalhador CLT: dados cadastrais, renda estimada, scores, telefones e dados do empregador.
alertaki_receita_federal_pf	Alertaki	Situação cadastral do CPF na Receita Federal, com nome, data de nascimento e comprovante de emissão.

Execução síncrona

Ao contrário das consultas da Dataprev, o POST aguarda o provedor e responde com o resultado final. A consulta é gravada antes da chamada ao provedor, então até uma falha fica no histórico com status = failed.

Autenticação

Todos os endpoints exigem API Key (X-Api-Key) (ver Autenticação). Permissões do recurso "Consulta Externa":

Permissão	Endpoints
Acessar	GET /{id}, POST /search
Executar consulta externa	POST /, POST /{id}/repetitions

GET /v5/query-supports e GET /v5/queries/filter-fields exigem apenas autenticação. Ver Autenticação.

Rotas implementadas

Rota	Verbo	Resumo
/v5/queries	POST	Executa uma consulta (ou reaproveita uma ainda válida) e devolve o resultado.
/v5/queries/{id}	GET	Busca uma consulta com valores e vínculos.
/v5/queries/{id}/repetitions	POST	Executa de novo uma consulta, com os mesmos parâmetros, sempre no provedor.
/v5/queries/search	POST	Busca paginada com filtros, inclusive por valor do resultado.
/v5/queries/filter-fields	GET	Campos disponíveis para filtro.
/v5/query-supports	GET	Listas de domínio do módulo (tipos, status, provedores, estruturas vinculáveis).

Convenções reutilizadas nesta página: Tratamento de erros, Objeto de domínio, Campo de status, Referências organizacionais. Valores fixos em Domínios › Consultas Externas.

Reaproveitamento (validade)

Cada empresa pode configurar uma validade por tipo de consulta (horas para as consultas do Banco Semear, dias para a Nova Vida e para a Alertaki). Com validade configurada:

• Uma consulta concluída com sucesso recebe expiresAt.
• Um novo POST com o mesmo tipo, o mesmo CPF e os mesmos parâmetros, antes de expiresAt, não chama o provedor: devolve a consulta já existente. Se o POST pedir vínculo a um registro, o vínculo é acrescentado com reused = true.
• Sem validade configurada, toda chamada vai ao provedor e expiresAt fica null.

POST /{id}/repetitions ignora a validade e sempre consulta o provedor.

Campos da entidade

Campo	Tipo	Descrição
id	string (uuid)	Identificador da consulta.
nid	integer	Número sequencial da consulta.
type	object (code/key/name)	Tipo. Ver QueryType.
provider	object (code/key/name)	Provedor: semear, nova_vida ou alertaki. Ver QueryProvider.
personType	object (code/key/name)	Sempre natural_person nos tipos atuais. Ver PersonType.
documentType	object (code/key/name)	Sempre cpf nos tipos atuais.
documentNumber	string	CPF consultado, 11 dígitos.
name	string | null	Nome informado em params.name ou devolvido pelo provedor.
params	object	Parâmetros efetivamente enviados ao provedor, no formato dele.
data	object | null	Resposta original do provedor. O formato é definido pelo provedor e pode mudar: para regras de negócio, use values.
httpStatus	integer | null	Status HTTP devolvido pelo provedor.
errorMessage	string | null	Motivo da falha, quando status = failed.
status	object (Status)	pending, completed ou failed. Ver QueryStatus.
requestedAt / completedAt	string (date-time)	Início e fim da execução.
expiresAt	string (date-time) | null	Até quando a consulta é reaproveitada. Ver Reaproveitamento.
durationMs	integer | null	Tempo de resposta do provedor, em milissegundos.
values[]	array	Resultado normalizado. Ver Valores do resultado.
associations[]	array	Registros a que a consulta está vinculada. Ver Vínculos.

Valores do resultado

Cada item de values[]:

Campo	Tipo	Descrição
key	string	Chave estável do valor (snake_case). Use-a nas regras de negócio.
label	string	Rótulo em português para exibição.
value	string | null	Valor como texto. Booleanos chegam como "true"/"false"; datas como YYYY-MM-DD.
valueNumber	decimal | null	Preenchido quando o valor é numérico.
valueDate	string (date-time) | null	Preenchido quando o valor é data.
groupKey	string | null	Grupo de uma lista repetida (ex.: phones). null para valores simples.
itemIndex	integer | null	Posição do item dentro do grupo, começando em 0.

Em falha, values vem vazio.

Banco Semear (semear_srcc, semear_nmp, semear_mcb)

key	Rótulo	Tipo
eligible	Elegível	booleano
message	Mensagem	texto
agent_monthly_score	Pontuação do Agente no Mês	número (quando devolvido)
agent_accumulated_score	Pontuação Acumulada do Agente	número (quando devolvido)

Nova Vida (nova_vida_next_clt)

Quando o CPF não tem perfil CLT no provedor, a consulta termina com sucesso e traz apenas profiled = "false" e message. Com perfil, profiled = "true" e os valores abaixo, omitidos quando o provedor não os devolve:

Grupo	key
Trabalhador	profiled, name, gender, birth_date, generation, estimated_income_amount, economic_class, probable_occupation, city, state, best_time_to_call, email
Indicadores	credit_score, credit_persona, digital_score, payment_propensity_score, clt_score, turnover, average_employment_time, occupational_risk
Empregador	employer_document_number, employer_name, employer_trade_name, employer_is_head_office, employer_branch_count, employer_opening_date, employer_legal_nature, employer_cnae_description, employer_size, employer_estimated_revenue_amount, employer_employee_count, employer_share_capital_amount, employer_partner_count, employer_has_federal_debt, employer_debt_count, employer_has_fgts_debt, employer_registration_status, employer_special_status, employer_sector_risk, employer_turnover
Telefones (groupKey = phones)	phone_number, has_whatsapp, priority, repetidos por itemIndex
Marcadores (groupKey = flags)	Um item por marcador devolvido pelo provedor, com a key do marcador

Alertaki (alertaki_receita_federal_pf)

Quando a data de nascimento informada não confere com a da Receita Federal, a consulta termina com sucesso e traz apenas found = "false", birth_date_matches = "false" e message com o texto da Receita. Outras recusas do provedor terminam em failed. Com o CPF encontrado, found = "true" e os valores abaixo, omitidos quando o provedor não os devolve:

key	Rótulo	Tipo
found	Encontrado na Receita Federal	booleano
name	Nome	texto
birth_date	Data de Nascimento	data
birth_date_matches	Data de Nascimento Confere	booleano (só quando a data foi informada)
situation	Situação Cadastral	texto, como devolvido pela Receita (ex.: REGULAR)
regular	Situação Regular	booleano
registration_date	Data de Inscrição	data
check_digit	Dígito Verificador	texto
issued_at	Emissão do Comprovante	data e hora
receipt_code	Código do Comprovante	texto
other_information	Outras Informações	texto
message	Mensagem	texto

Vínculos

Uma consulta pode ser vinculada a uma proposta (loan_proposal) ou a um empréstimo (loan), informando feature e entityId no POST. A mesma consulta pode ter vários vínculos. Cada item de associations[]:

Campo	Tipo	Descrição
id	string (uuid)	Identificador do vínculo.
feature	object (code/key/name)	Estrutura vinculada. Ver QueryAssociationFeature.
entityId / entityCode	string (uuid) / integer	id e code do registro vinculado.
reused	boolean	true quando o vínculo foi feito reaproveitando uma consulta válida, ou copiado de outro registro (ex.: da proposta para o empréstimo emitido).
associatedAt	string (date-time)	Momento do vínculo.
user	object (Referência)	Usuário que fez o vínculo.

O GET /{id} e o POST não trazem os campos organizacionais. A busca traz também createdAt, createdBy, company, unit, partner, branch, agent e user.

---

POST /v5/queries

Executa uma consulta no provedor do tipo informado e devolve o resultado.

Autenticação: API Key (X-Api-Key). Exige a permissão "Executar consulta externa".

Comportamento

1. Valida o type (1171004) e, se informado, o vínculo: feature e entityId juntos (1171006), feature aceita (1171007) e registro existente na empresa (1171008).
2. Valida os parâmetros exigidos pelo tipo (ver tabela abaixo).
3. Se houver consulta válida com os mesmos dados, devolve essa consulta (ver Reaproveitamento).
4. Senão, grava a consulta como pending, chama o provedor e atualiza o registro para completed ou failed.
5. Em completed, responde 201 com a consulta. Em failed, responde 400 com o erro do provedor; a consulta com status = failed continua disponível na busca e pode ser repetida.

Payload de entrada

Visualizar parâmetros

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	key do tipo. Ausente ou inválido → 1171004.
documentNumber	string	Sim	CPF do trabalhador. Pontuação é removida.
params	object (string → string)	Depende do tipo	Parâmetros adicionais, ver tabela abaixo. Os nomes não diferenciam maiúsculas de minúsculas.
feature	string	Não	Estrutura a vincular: loan_proposal ou loan. Exige entityId.
entityId	string (uuid)	Não	id da proposta ou do empréstimo. Exige feature.

Parâmetros por tipo

type	params obrigatórios	params opcionais	Erros de validação
semear_srcc	registrationNumber (matrícula do trabalhador)	name	CPF inválido → 9507013; sem matrícula → 9507007
semear_nmp	phoneNumber (DDD + número, 10 ou 11 dígitos)	name	CPF inválido → 9507013; telefone ausente ou inválido → 9507008
semear_mcb	agentDocumentNumber (CPF do agente de crédito)	name	CPF inválido → 9507013; CPF do agente ausente ou inválido → 9507009
nova_vida_next_clt	—	employerDocumentNumber (raiz de 8 dígitos ou CNPJ de 14 dígitos do empregador)	CPF ausente → 9508004; CPF inválido → 9508005; CNPJ do empregador inválido → 9508006
alertaki_receita_federal_pf	—	birthDate (data de nascimento no formato aaaa-mm-dd, conferida pela Receita)	CPF ausente → 9509004; CPF inválido → 9509005; data de nascimento inválida → 9509006

Exemplo de Requisição e Resposta

Body

Visualizar Body

{
  "type": "semear_srcc",
  "documentNumber": "00000000000",
  "params": {
    "registrationNumber": "000123",
    "name": "NOME DO TRABALHADOR"
  },
  "feature": "loan_proposal",
  "entityId": "00000000-0000-7000-8000-000000000451"
}

cURL

curl --request POST \
  --url 'https://{base-url}/v5/queries' \
  --header 'X-Api-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "semear_srcc",
    "documentNumber": "00000000000",
    "params": {
      "registrationNumber": "000123",
      "name": "NOME DO TRABALHADOR"
    },
    "feature": "loan_proposal",
    "entityId": "00000000-0000-7000-8000-000000000451"
  }'

201 - Created

Visualizar Response

{
  "id": "00000000-0000-7000-8000-000000000a01",
  "nid": 1024,
  "type": { "code": 1, "key": "semear_srcc", "name": "Autorregulação Semear - SRCC" },
  "provider": { "code": 9507, "key": "semear", "name": "Banco Semear" },
  "personType": { "code": 1, "key": "natural_person", "name": "Pessoa Física" },
  "documentType": { "code": 100, "key": "cpf", "name": "CPF" },
  "documentNumber": "00000000000",
  "name": "NOME DO TRABALHADOR",
  "params": { "cpf": "00000000000", "matricula": "000123", "srcc": true, "nmp": false, "mcb": false },
  "data": { "elegivel": true, "mensagem": "Elegível" },
  "httpStatus": 200,
  "errorMessage": null,
  "status": { "code": 2, "key": "completed", "name": "Concluída", "date": "2026-10-17T16:05Z", "color": "#4CAF50", "note": null },
  "requestedAt": "2026-10-17T16:05Z",
  "completedAt": "2026-10-17T16:05Z",
  "expiresAt": "2026-10-18T16:05Z",
  "durationMs": 842,
  "values": [
    { "key": "eligible", "label": "Elegível", "value": "true", "valueNumber": null, "valueDate": null, "groupKey": null, "itemIndex": null },
    { "key": "message", "label": "Mensagem", "value": "Elegível", "valueNumber": null, "valueDate": null, "groupKey": null, "itemIndex": null }
  ],
  "associations": [
    {
      "id": "00000000-0000-7000-8000-000000000b01",
      "feature": { "code": 101035, "key": "loan_proposal", "name": "Proposta de Empréstimo" },
      "entityId": "00000000-0000-7000-8000-000000000451",
      "entityCode": 77,
      "reused": false,
      "associatedAt": "2026-10-17T16:05Z",
      "user": { "code": 18, "key": null, "name": "Usuário Exemplo" }
    }
  ]
}

201 - Nova Vida

Trecho de uma consulta nova_vida_next_clt com perfil encontrado, mostrando valores simples, numéricos e o grupo de telefones.

Visualizar trecho da Response

{
  "type": { "code": 4, "key": "nova_vida_next_clt", "name": "Nova Vida - Perfil do Trabalhador CLT" },
  "provider": { "code": 9508, "key": "nova_vida", "name": "Nova Vida" },
  "documentNumber": "00000000000",
  "name": "NOME DO TRABALHADOR",
  "status": { "code": 2, "key": "completed", "name": "Concluída", "date": "2026-10-17T16:10Z", "color": "#4CAF50", "note": null },
  "values": [
    { "key": "profiled", "label": "Possui Perfil CLT", "value": "true", "valueNumber": null, "valueDate": null, "groupKey": null, "itemIndex": null },
    { "key": "estimated_income_amount", "label": "Renda Estimada", "value": "3500", "valueNumber": 3500.000000, "valueDate": null, "groupKey": null, "itemIndex": null },
    { "key": "birth_date", "label": "Data de Nascimento", "value": "1990-01-01", "valueNumber": null, "valueDate": "1990-01-01T00:00Z", "groupKey": null, "itemIndex": null },
    { "key": "employer_name", "label": "Razão Social do Empregador", "value": "EMPRESA EXEMPLO LTDA", "valueNumber": null, "valueDate": null, "groupKey": null, "itemIndex": null },
    { "key": "phone_number", "label": "Telefone", "value": "11999990000", "valueNumber": null, "valueDate": null, "groupKey": "phones", "itemIndex": 0 },
    { "key": "has_whatsapp", "label": "WhatsApp", "value": "true", "valueNumber": null, "valueDate": null, "groupKey": "phones", "itemIndex": 0 },
    { "key": "priority", "label": "Prioridade", "value": "1", "valueNumber": 1.000000, "valueDate": null, "groupKey": "phones", "itemIndex": 0 }
  ]
}

400 - Erro

Erros de validação do módulo (1171004, 1171006–1171008) e do tipo (tabela acima); configuração do provedor ausente ou incompleta para a empresa (9507001, 9508001–9508003, 9509001–9509003); falha do provedor (9508007 para a Nova Vida; 9509007 para a Alertaki; para o Banco Semear, 1171002 com o motivo em text); exceção não tratada (9999999).

Visualizar Response

{ "messages": [ { "code": "9507007", "text": "A autorregulação do Banco Semear exige a matrícula do trabalhador para consultar o SRCC" } ] }

401 - Não autorizado

Token ausente, inválido ou expirado.

403 - Proibido

Usuário sem a permissão "Executar consulta externa". Corpo vazio.

---

GET /v5/queries/{id}

Busca uma consulta, com values e associations.

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Consulta Externa.

Parâmetro	Tipo	Descrição
id	string (uuid)	id da consulta. Não encontrada → 1171003.

curl --request GET \
  --url 'https://{base-url}/v5/queries/00000000-0000-7000-8000-000000000a01' \
  --header 'X-Api-Key: {api_key}'

Resposta 200 no mesmo formato do POST.

---

POST /v5/queries/{id}/repetitions

Executa a consulta de novo no provedor, com o mesmo tipo, CPF e parâmetros da consulta original, e grava uma nova consulta. Os vínculos da original são copiados para a nova. A original não muda.

Use para atualizar um resultado vencido ou repetir uma consulta que falhou por indisponibilidade do provedor.

Autenticação: API Key (X-Api-Key). Exige a permissão "Executar consulta externa".

Parâmetro	Tipo	Descrição
id	string (uuid)	id da consulta a repetir. Não encontrada → 1171003.

Sem corpo.

curl --request POST \
  --url 'https://{base-url}/v5/queries/00000000-0000-7000-8000-000000000a01/repetitions' \
  --header 'X-Api-Key: {api_key}'

Resposta 201 com a nova consulta, no formato do POST. Falha do provedor → 400, como no POST.

---

POST /v5/queries/search

Busca paginada de consultas.

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Consulta Externa.

Payload de entrada

Campo	Tipo	Descrição
offset / limit	integer	Paginação.
sort	array de string	Ordenação.
searchText	string	Texto livre (número, CPF, nome, tipo e termos do resultado, como nome e CNPJ do empregador).
id	object	{ "eq": "<uuid>" }.
nid	object	{ "eq": 1024 }.
type / provider	object	{ "code": { "in": [1, 2, 3] } } ou { "key": { "eq": "nova_vida_next_clt" } }.
status	object	{ "code": { "in": [3] } } para as falhas.
personType / documentType	object	Como type.
documentNumber	object	{ "eq": "00000000000" }.
name	object	{ "regex": "maria" }.
requestedAt / expiresAt	object	{ "gte": "2026-10-01T00:00Z", "lt": "2026-11-01T00:00Z" }.
associationFeature	object	{ "key": { "eq": "loan" } }.
associationEntityId	object	{ "eq": "<uuid do empréstimo ou proposta>" }: todas as consultas vinculadas a um registro.
dataKey / dataValue	object	Filtra por um valor do resultado, ex.: dataKey = { "eq": "eligible" } e dataValue = { "regex": "false" }.
unit, partner, branch, agent, user	object	Filtro organizacional.
filters	array	Filtros dinâmicos no formato devolvido por GET /filter-fields.

Resposta (200)

{ count, offset, limit, items[] }. Cada item traz id, nid, type, provider, personType, documentType, documentNumber, name, errorMessage, status, requestedAt, completedAt, expiresAt, durationMs, associationCount, values[], createdAt, createdBy e os campos organizacionais. params, data e associations vêm só no GET /{id}.

curl --request POST \
  --url 'https://{base-url}/v5/queries/search' \
  --header 'X-Api-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{ "limit": 20, "associationEntityId": { "eq": "00000000-0000-7000-8000-000000000501" } }'

---

GET /v5/queries/filter-fields

Lista os campos aceitos em filters da busca. Cada item traz key, name, label, type (guid, int, string, datetime, select_list), operator (eq, in, regex, btw), sourceType, source e active.

Autenticação: API Key (X-Api-Key).

---

GET /v5/query-supports

Devolve as listas de domínio do módulo, para montar formulários e filtros.

Autenticação: API Key (X-Api-Key).

Campo	Conteúdo
status	QueryStatus, com color.
types	Todos os QueryType.
manualTypes	Tipos que podem ser executados por POST /v5/queries. Hoje, todos.
providers	QueryProvider.
associationFeatures	QueryAssociationFeature.

Visualizar Response

{
  "status": [
    { "code": 1, "key": "pending", "name": "Pendente", "color": "#FFEB3B", "note": null },
    { "code": 2, "key": "completed", "name": "Concluída", "color": "#4CAF50", "note": null },
    { "code": 3, "key": "failed", "name": "Falha", "color": "#F44336", "note": null }
  ],
  "types": [
    { "code": 1, "key": "semear_srcc", "name": "Autorregulação Semear - SRCC" },
    { "code": 2, "key": "semear_nmp", "name": "Autorregulação Semear - NMP" },
    { "code": 3, "key": "semear_mcb", "name": "Autorregulação Semear - MCB" },
    { "code": 4, "key": "nova_vida_next_clt", "name": "Nova Vida - Perfil do Trabalhador CLT" },
    { "code": 5, "key": "alertaki_receita_federal_pf", "name": "Alertaki - Receita Federal PF" }
  ],
  "manualTypes": [
    { "code": 4, "key": "nova_vida_next_clt", "name": "Nova Vida - Perfil do Trabalhador CLT" },
    { "code": 5, "key": "alertaki_receita_federal_pf", "name": "Alertaki - Receita Federal PF" },
    { "code": 1, "key": "semear_srcc", "name": "Autorregulação Semear - SRCC" },
    { "code": 2, "key": "semear_nmp", "name": "Autorregulação Semear - NMP" },
    { "code": 3, "key": "semear_mcb", "name": "Autorregulação Semear - MCB" }
  ],
  "providers": [
    { "code": 9507, "key": "semear", "name": "Banco Semear" },
    { "code": 9508, "key": "nova_vida", "name": "Nova Vida" },
    { "code": 9509, "key": "alertaki", "name": "Alertaki" }
  ],
  "associationFeatures": [
    { "code": 101035, "key": "loan_proposal", "name": "Proposta de Empréstimo" },
    { "code": 1010, "key": "loan", "name": "Empréstimo" }
  ]
}

Erros do módulo

code	text	Onde
1171001	Nenhum provedor registrado para o tipo de consulta	POST /
1171002	O provedor não retornou o resultado da consulta	POST /, POST /{id}/repetitions (o text pode trazer o motivo devolvido pelo provedor)
1171003	Consulta não encontrada	GET /{id}, POST /{id}/repetitions
1171004	Tipo de consulta inválido	POST /, POST /{id}/repetitions
1171005	Este tipo de consulta não pode ser executado manualmente	POST /
1171006	Para vincular a consulta informe a estrutura e o id do registro	POST /
1171007	A consulta só pode ser vinculada a proposta ou empréstimo	POST /
1171008	Registro a vincular não encontrado	POST /
9507001	Configuração não encontrada para o Banco Semear	Tipos semear_*
9507007	A autorregulação do Banco Semear exige a matrícula do trabalhador para consultar o SRCC	semear_srcc
9507008	A autorregulação do Banco Semear exige o telefone do trabalhador com DDD para consultar o NMP	semear_nmp
9507009	A autorregulação do Banco Semear exige um agente com CPF no empréstimo para consultar o MCB	semear_mcb
9507013	Informe um CPF válido para a autorregulação do Banco Semear	Tipos semear_*
9508001	Configuração não encontrada para Nova Vida	nova_vida_next_clt
9508002	Configuração da Nova Vida incompleta: informe URL, usuário, senha e cliente	nova_vida_next_clt
9508003	Falha ao obter token de acesso da Nova Vida	nova_vida_next_clt
9508004	Informe o CPF do trabalhador	nova_vida_next_clt
9508005	CPF do trabalhador inválido	nova_vida_next_clt
9508006	Informe a raiz (8 dígitos) ou o CNPJ completo (14 dígitos) do empregador	nova_vida_next_clt
9508007	Erro ao consultar o perfil do trabalhador na Nova Vida	nova_vida_next_clt (o text traz a mensagem do provedor)
9509001	Configuração não encontrada para Alertaki	alertaki_receita_federal_pf
9509002	Configuração da Alertaki incompleta: informe URL, e-mail e senha	alertaki_receita_federal_pf
9509003	Falha ao obter token de acesso da Alertaki	alertaki_receita_federal_pf
9509004	Informe o CPF	alertaki_receita_federal_pf
9509005	CPF inválido	alertaki_receita_federal_pf
9509006	Data de nascimento inválida: use o formato aaaa-mm-dd	alertaki_receita_federal_pf
9509007	Erro ao consultar o CPF na Receita Federal pela Alertaki	alertaki_receita_federal_pf (o text traz a mensagem do provedor)

Este módulo não publica eventos de webhook: o resultado vem na própria resposta.