{ "openapi": "3.1.0", "info": { "title": "API Kapta360", "version": "1.0.0", "description": "API REST de integração da Kapta360: relatório completo de análise de crédito de pessoa física em JSON e PDF. Servidor a servidor: nunca use o token em navegador ou aplicativo. Documentação completa em https://kapta360.com/docs/api." }, "servers": [ { "url": "https://api.kapta360.com/v1", "description": "Produção" }, { "url": "https://api-homolog.kapta360.com/v1", "description": "Homologação" } ], "security": [ { "bearer": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "k360___", "description": "Token criado na área Integração do painel. O prefixo define o ambiente." } }, "schemas": { "Erro": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "NAO_AUTENTICADO", "TOKEN_REVOGADO", "TOKEN_EXPIRADO", "IP_NAO_PERMITIDO", "CONTA_BLOQUEADA", "API_DESABILITADA", "TERMOS_PENDENTES", "ESCOPO_INSUFICIENTE", "AMBIENTE_INDISPONIVEL", "MUITAS_FALHAS_DE_AUTENTICACAO", "LIMITE_EXCEDIDO", "NAO_ENCONTRADO", "METODO_NAO_PERMITIDO", "CORPO_INVALIDO", "DADOS_INVALIDOS", "CORPO_GRANDE_DEMAIS", "IDEMPOTENCY_KEY_OBRIGATORIA", "IDEMPOTENCY_KEY_REUTILIZADA", "CPF_INVALIDO", "CPF_FORA_DO_AMBIENTE_DE_TESTES", "FINALIDADE_INVALIDA", "AUTORIZACAO_DO_TITULAR_OBRIGATORIA", "REFERENCIA_COM_DADO_PESSOAL", "CONSULTA_EM_ANDAMENTO", "SALDO_INSUFICIENTE", "PDF_EM_GERACAO", "RESULTADO_EXPIRADO", "CAPACIDADE_ESGOTADA", "API_INDISPONIVEL", "SERVICO_INDISPONIVEL", "ERRO_INTERNO" ], "description": "Código estável do erro (use este campo, não a mensagem)." }, "mensagem": { "type": "string", "description": "Mensagem em português, para exibição ou log." }, "requestId": { "type": "string", "description": "Identificador da requisição (informe ao suporte)." }, "detalhes": { "description": "Detalhes de validação, quando houver." } }, "required": [ "codigo", "mensagem", "requestId" ], "additionalProperties": false } }, "required": [ "erro" ], "additionalProperties": false, "description": "Envelope de erro de toda resposta não-2xx da API." }, "Conta": { "type": "object", "properties": { "conta": { "type": "object", "properties": { "nome": { "type": [ "string", "null" ] } }, "required": [ "nome" ], "additionalProperties": false }, "token": { "type": "object", "properties": { "nome": { "type": "string" }, "publico": { "type": "string", "description": "Parte pública do token (identifica o token sem expor o segredo)." }, "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "escopos": { "type": "array", "items": { "type": "string", "enum": [ "consultas:criar", "consultas:ler", "saldo:ler" ] } }, "criadoEm": { "type": "string", "format": "date-time" }, "expiraEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "nome", "publico", "ambiente", "escopos", "criadoEm", "expiraEm" ], "additionalProperties": false }, "limites": { "type": "object", "properties": { "criacoesPorMinuto": { "type": "integer" }, "leiturasPorMinuto": { "type": "integer" }, "consultasEmAndamento": { "type": "integer", "description": "Consultas não concluídas ao mesmo tempo." }, "consultasPorDia": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "null = sem teto diário." } }, "required": [ "criacoesPorMinuto", "leiturasPorMinuto", "consultasEmAndamento", "consultasPorDia" ], "additionalProperties": false }, "termos": { "type": "object", "properties": { "versaoAceita": { "type": [ "string", "null" ] }, "aceitosEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "versaoVigente": { "type": "string" } }, "required": [ "versaoAceita", "aceitosEm", "versaoVigente" ], "additionalProperties": false }, "ambienteDeTestes": { "type": "boolean", "description": "O ambiente de testes (tokens k360_test_) está liberado para a conta." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "eventos": { "type": "array", "items": { "type": "string", "enum": [ "consulta.concluida", "consulta.falhou", "consulta.pdf_disponivel", "saldo.baixo" ] } }, "ativo": { "type": "boolean" }, "desativadoMotivo": { "anyOf": [ { "type": "string", "enum": [ "FALHAS_SEGUIDAS", "CLIENTE" ] }, { "type": "null" } ] } }, "required": [ "url", "eventos", "ativo", "desativadoMotivo" ], "additionalProperties": false }, { "type": "null" } ], "description": "Webhook configurado no ambiente deste token (null = nenhum)." } }, "required": [ "conta", "token", "limites", "termos", "ambienteDeTestes", "webhook" ], "additionalProperties": false }, "Saldo": { "type": "object", "properties": { "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "amostra": { "type": "boolean", "description": "true no ambiente de testes: o saldo é fictício." }, "creditos": { "type": "integer", "description": "Créditos disponíveis (1 crédito = 1 relatório completo)." }, "lotes": { "type": "array", "items": { "type": "object", "properties": { "quantidade": { "type": "integer" }, "expiraEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "quantidade", "expiraEm" ], "additionalProperties": false }, "description": "Créditos por vencimento (os que vencem primeiro são usados primeiro)." } }, "required": [ "ambiente", "amostra", "creditos", "lotes" ], "additionalProperties": false }, "NovaConsulta": { "type": "object", "properties": { "cpf": { "type": "string", "minLength": 11, "maxLength": 14, "description": "CPF do titular (com ou sem pontuação)." }, "finalidade": { "type": "string", "enum": [ "ANALISE_DE_RISCO_DE_CREDITO", "CONCESSAO_OU_EXTENSAO_DE_CREDITO", "VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO" ], "description": "Finalidade da consulta (Lei 12.414/2011), declarada pelo cliente a cada pedido." }, "autorizacaoTitular": { "type": "boolean", "const": true, "description": "Declaração de que o cliente tem a autorização do titular." }, "referenciaExterna": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Identificador do seu sistema (nunca o CPF)." }, "reaproveitarDias": { "type": "integer", "minimum": 1, "maximum": 7, "description": "Se houver relatório completo deste CPF gerado pela API nos últimos N dias, devolve-o sem cobrar." } }, "required": [ "cpf", "finalidade", "autorizacaoTitular" ], "additionalProperties": false }, "Consulta": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "NA_FILA", "PROCESSANDO", "CONCLUIDA", "FALHOU" ] }, "fase": { "anyOf": [ { "type": "string", "enum": [ "COLETANDO", "AGUARDANDO_CAPACIDADE", "RECONSULTANDO", "GERANDO_PDF" ] }, { "type": "null" } ] }, "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "cpfMascarado": { "type": "string" }, "finalidade": { "type": "string", "enum": [ "ANALISE_DE_RISCO_DE_CREDITO", "CONCESSAO_OU_EXTENSAO_DE_CREDITO", "VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO" ], "description": "Finalidade da consulta (Lei 12.414/2011), declarada pelo cliente a cada pedido." }, "referenciaExterna": { "type": [ "string", "null" ] }, "criadoEm": { "type": "string", "format": "date-time" }, "concluidaEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cobranca": { "type": "object", "properties": { "situacao": { "type": "string", "enum": [ "RESERVADO", "COBRADO", "DEVOLVIDO", "SEM_COBRANCA" ] }, "creditos": { "type": "integer", "description": "Créditos consumidos por esta consulta (0 ou 1)." }, "reaproveitada": { "type": "boolean" }, "saldoRestante": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Saldo após esta consulta (só na resposta da criação)." } }, "required": [ "situacao", "creditos", "reaproveitada", "saldoRestante" ], "additionalProperties": false }, "numeroRelatorio": { "type": [ "string", "null" ] }, "validade": { "type": "object", "properties": { "expiraEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expirado": { "type": "boolean" } }, "required": [ "expiraEm", "expirado" ], "additionalProperties": false }, "erro": { "anyOf": [ { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "BASES_INDISPONIVEIS", "PRAZO_ESGOTADO", "FILA_EXPIRADA", "CONTA_BLOQUEADA" ] }, "mensagem": { "type": "string" } }, "required": [ "codigo", "mensagem" ], "additionalProperties": false }, { "type": "null" } ] }, "pdf": { "type": "object", "properties": { "disponivel": { "type": "boolean" }, "url": { "type": [ "string", "null" ] } }, "required": [ "disponivel", "url" ], "additionalProperties": false }, "relatorio": { "anyOf": [ { "type": "object", "properties": { "versao": { "type": "string", "const": "1" }, "metadados": { "type": "object", "properties": { "numero": { "type": "string", "minLength": 1, "description": "Número do relatório (AMOSTRA-… no ambiente de testes)." }, "geradoEm": { "type": "string", "format": "date-time" }, "ambiente": { "type": "string", "enum": [ "live", "test" ] }, "finalidade": { "type": "string", "enum": [ "ANALISE_DE_RISCO_DE_CREDITO", "CONCESSAO_OU_EXTENSAO_DE_CREDITO", "VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO" ] }, "amostra": { "type": "boolean", "description": "true no ambiente de testes: dados fictícios." } }, "required": [ "numero", "geradoEm", "ambiente", "finalidade", "amostra" ], "additionalProperties": false }, "titular": { "type": "object", "properties": { "nome": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cpf": { "type": "string", "pattern": "^\\d{11}$" }, "dataNascimento": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "idade": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "situacaoCadastral": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "nomeMae": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "sexo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "estadoCivil": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "classeSocial": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "obito": { "type": [ "boolean", "null" ] } }, "required": [ "nome", "cpf", "dataNascimento", "idade", "situacaoCadastral", "nomeMae", "sexo", "estadoCivil", "classeSocial", "obito" ], "additionalProperties": false }, "contatos": { "type": "object", "properties": { "telefones": { "type": "array", "items": { "type": "string", "pattern": "^\\d{10,13}$" } }, "emails": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "telefones", "emails" ], "additionalProperties": false }, "enderecos": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Natureza do endereço quando informada (ex.: Residencial, Trabalho)." }, "logradouro": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numero": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "complemento": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bairro": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cidade": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "uf": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "cep": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] } }, "required": [ "tipo", "logradouro", "numero", "complemento", "bairro", "cidade", "uf", "cep" ], "additionalProperties": false } }, "participacoesSocietarias": { "type": "array", "items": { "type": "object", "properties": { "cnpj": { "anyOf": [ { "type": "string", "pattern": "^\\d{14}$" }, { "type": "null" } ] }, "razaoSocial": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "qualificacao": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "participacaoPercentual": { "type": [ "number", "null" ] }, "dataEntrada": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "cnpj", "razaoSocial", "qualificacao", "participacaoPercentual", "dataEntrada" ], "additionalProperties": false } }, "indicadores": { "type": "object", "properties": { "score": { "type": [ "number", "null" ], "description": "Score de crédito (0 a 1000)." }, "probabilidadeInadimplenciaPercentual": { "type": [ "number", "null" ] }, "rendaPresumidaFaixa": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pontualidadePagamentosPercentual": { "type": [ "number", "null" ] } }, "required": [ "score", "probabilidadeInadimplenciaPercentual", "rendaPresumidaFaixa", "pontualidadePagamentosPercentual" ], "additionalProperties": false }, "classificacao": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK", "INDISPONIVEL" ] }, "motivoCodigo": { "anyOf": [ { "type": "string", "enum": [ "SCORE_NAO_CALCULADO", "PD_NAO_CALCULADA", "BASE_NAO_APURADA" ] }, { "type": "null" } ] }, "letra": { "anyOf": [ { "type": "string", "enum": [ "AAA", "AA", "A", "BBB", "BB", "B", "CCC", "CC", "C", "D", "E" ] }, { "type": "null" } ] }, "grupo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "leitura": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "conclusao": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "resumo": { "type": "string", "minLength": 1 }, "letraBase": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ajustes": { "type": "array", "items": { "type": "object", "properties": { "indicador": { "type": "string", "minLength": 1 }, "efeito": { "type": "number", "enum": [ -1, 0, 1 ] }, "motivo": { "type": "string", "minLength": 1 } }, "required": [ "indicador", "efeito", "motivo" ], "additionalProperties": false } }, "somaAjustes": { "type": "integer" }, "versaoMotor": { "type": "string", "minLength": 1 }, "alerta": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "status", "motivoCodigo", "letra", "grupo", "leitura", "conclusao", "resumo", "letraBase", "ajustes", "somaAjustes", "versaoMotor", "alerta" ], "additionalProperties": false }, "restricoes": { "type": "object", "properties": { "semRestricoes": { "type": "boolean" }, "quadro": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string", "minLength": 1 }, "situacao": { "type": "string", "enum": [ "NADA_CONSTA", "CONSTA", "NAO_APURADO" ] }, "descricao": { "type": "string", "minLength": 1 } }, "required": [ "item", "situacao", "descricao" ], "additionalProperties": false } }, "ocorrencias": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "type": "string", "minLength": 1 }, "origem": { "type": "string", "minLength": 1 }, "data": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "valor": { "type": [ "number", "null" ] }, "detalhe": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "tipo", "origem", "data", "valor", "detalhe" ], "additionalProperties": false } } }, "required": [ "semRestricoes", "quadro", "ocorrencias" ], "additionalProperties": false }, "scr": { "type": "object", "properties": { "situacao": { "type": "string", "enum": [ "COM_RELACIONAMENTO", "SEM_RELACIONAMENTO" ] }, "dataBase": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, { "type": "null" } ], "description": "Mês de referência (AAAA-MM)." }, "inicioRelacionamento": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "quantidadeInstituicoes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "quantidadeOperacoes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "carteira": { "type": "object", "properties": { "aVencer": { "type": [ "number", "null" ] }, "vencido": { "type": [ "number", "null" ] }, "prejuizo": { "type": [ "number", "null" ] }, "limite": { "type": [ "number", "null" ] } }, "required": [ "aVencer", "vencido", "prejuizo", "limite" ], "additionalProperties": false }, "modalidades": { "type": "array", "items": { "type": "object", "properties": { "titulo": { "type": "string", "minLength": 1 }, "linhas": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "titulo", "linhas" ], "additionalProperties": false } } }, "required": [ "situacao", "dataBase", "inicioRelacionamento", "quantidadeInstituicoes", "quantidadeOperacoes", "score", "carteira", "modalidades" ], "additionalProperties": false }, "avisos": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string", "minLength": 1 }, "mensagem": { "type": "string", "minLength": 1 } }, "required": [ "codigo", "mensagem" ], "additionalProperties": false } } }, "required": [ "versao", "metadados", "titular", "contatos", "enderecos", "participacoesSocietarias", "indicadores", "classificacao", "restricoes", "scr", "avisos" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "fase", "ambiente", "cpfMascarado", "finalidade", "referenciaExterna", "criadoEm", "concluidaEm", "cobranca", "numeroRelatorio", "validade", "erro", "pdf", "relatorio" ], "additionalProperties": false }, "ListaConsultas": { "type": "object", "properties": { "dados": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "NA_FILA", "PROCESSANDO", "CONCLUIDA", "FALHOU" ] }, "fase": { "anyOf": [ { "type": "string", "enum": [ "COLETANDO", "AGUARDANDO_CAPACIDADE", "RECONSULTANDO", "GERANDO_PDF" ] }, { "type": "null" } ] }, "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "cpfMascarado": { "type": "string" }, "finalidade": { "type": "string", "enum": [ "ANALISE_DE_RISCO_DE_CREDITO", "CONCESSAO_OU_EXTENSAO_DE_CREDITO", "VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO" ], "description": "Finalidade da consulta (Lei 12.414/2011), declarada pelo cliente a cada pedido." }, "referenciaExterna": { "type": [ "string", "null" ] }, "criadoEm": { "type": "string", "format": "date-time" }, "concluidaEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cobranca": { "type": "object", "properties": { "situacao": { "type": "string", "enum": [ "RESERVADO", "COBRADO", "DEVOLVIDO", "SEM_COBRANCA" ] }, "creditos": { "type": "integer", "description": "Créditos consumidos por esta consulta (0 ou 1)." }, "reaproveitada": { "type": "boolean" }, "saldoRestante": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Saldo após esta consulta (só na resposta da criação)." } }, "required": [ "situacao", "creditos", "reaproveitada", "saldoRestante" ], "additionalProperties": false }, "numeroRelatorio": { "type": [ "string", "null" ] }, "validade": { "type": "object", "properties": { "expiraEm": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expirado": { "type": "boolean" } }, "required": [ "expiraEm", "expirado" ], "additionalProperties": false }, "erro": { "anyOf": [ { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "BASES_INDISPONIVEIS", "PRAZO_ESGOTADO", "FILA_EXPIRADA", "CONTA_BLOQUEADA" ] }, "mensagem": { "type": "string" } }, "required": [ "codigo", "mensagem" ], "additionalProperties": false }, { "type": "null" } ] }, "pdf": { "type": "object", "properties": { "disponivel": { "type": "boolean" }, "url": { "type": [ "string", "null" ] } }, "required": [ "disponivel", "url" ], "additionalProperties": false } }, "required": [ "id", "status", "fase", "ambiente", "cpfMascarado", "finalidade", "referenciaExterna", "criadoEm", "concluidaEm", "cobranca", "numeroRelatorio", "validade", "erro", "pdf" ], "additionalProperties": false } }, "proximoCursor": { "type": [ "string", "null" ] } }, "required": [ "dados", "proximoCursor" ], "additionalProperties": false }, "Extrato": { "type": "object", "properties": { "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "amostra": { "type": "boolean" }, "dados": { "type": "array", "items": { "type": "object", "properties": { "data": { "type": "string", "format": "date-time" }, "tipo": { "type": "string", "enum": [ "CONSUMO", "ESTORNO" ] }, "creditos": { "type": "integer" }, "saldoApos": { "type": "integer" }, "consultaId": { "type": "string", "format": "uuid" }, "cpfMascarado": { "type": [ "string", "null" ] } }, "required": [ "data", "tipo", "creditos", "saldoApos", "consultaId", "cpfMascarado" ], "additionalProperties": false } }, "proximoCursor": { "type": [ "string", "null" ] } }, "required": [ "ambiente", "amostra", "dados", "proximoCursor" ], "additionalProperties": false }, "RelatorioV1": { "type": "object", "properties": { "versao": { "type": "string", "const": "1" }, "metadados": { "type": "object", "properties": { "numero": { "type": "string", "minLength": 1, "description": "Número do relatório (AMOSTRA-… no ambiente de testes)." }, "geradoEm": { "type": "string", "format": "date-time" }, "ambiente": { "type": "string", "enum": [ "live", "test" ] }, "finalidade": { "type": "string", "enum": [ "ANALISE_DE_RISCO_DE_CREDITO", "CONCESSAO_OU_EXTENSAO_DE_CREDITO", "VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO" ] }, "amostra": { "type": "boolean", "description": "true no ambiente de testes: dados fictícios." } }, "required": [ "numero", "geradoEm", "ambiente", "finalidade", "amostra" ], "additionalProperties": false }, "titular": { "type": "object", "properties": { "nome": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cpf": { "type": "string", "pattern": "^\\d{11}$" }, "dataNascimento": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "idade": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "situacaoCadastral": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "nomeMae": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "sexo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "estadoCivil": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "classeSocial": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "obito": { "type": [ "boolean", "null" ] } }, "required": [ "nome", "cpf", "dataNascimento", "idade", "situacaoCadastral", "nomeMae", "sexo", "estadoCivil", "classeSocial", "obito" ], "additionalProperties": false }, "contatos": { "type": "object", "properties": { "telefones": { "type": "array", "items": { "type": "string", "pattern": "^\\d{10,13}$" } }, "emails": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "telefones", "emails" ], "additionalProperties": false }, "enderecos": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Natureza do endereço quando informada (ex.: Residencial, Trabalho)." }, "logradouro": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numero": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "complemento": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bairro": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cidade": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "uf": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "cep": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] } }, "required": [ "tipo", "logradouro", "numero", "complemento", "bairro", "cidade", "uf", "cep" ], "additionalProperties": false } }, "participacoesSocietarias": { "type": "array", "items": { "type": "object", "properties": { "cnpj": { "anyOf": [ { "type": "string", "pattern": "^\\d{14}$" }, { "type": "null" } ] }, "razaoSocial": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "qualificacao": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "participacaoPercentual": { "type": [ "number", "null" ] }, "dataEntrada": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "cnpj", "razaoSocial", "qualificacao", "participacaoPercentual", "dataEntrada" ], "additionalProperties": false } }, "indicadores": { "type": "object", "properties": { "score": { "type": [ "number", "null" ], "description": "Score de crédito (0 a 1000)." }, "probabilidadeInadimplenciaPercentual": { "type": [ "number", "null" ] }, "rendaPresumidaFaixa": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pontualidadePagamentosPercentual": { "type": [ "number", "null" ] } }, "required": [ "score", "probabilidadeInadimplenciaPercentual", "rendaPresumidaFaixa", "pontualidadePagamentosPercentual" ], "additionalProperties": false }, "classificacao": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK", "INDISPONIVEL" ] }, "motivoCodigo": { "anyOf": [ { "type": "string", "enum": [ "SCORE_NAO_CALCULADO", "PD_NAO_CALCULADA", "BASE_NAO_APURADA" ] }, { "type": "null" } ] }, "letra": { "anyOf": [ { "type": "string", "enum": [ "AAA", "AA", "A", "BBB", "BB", "B", "CCC", "CC", "C", "D", "E" ] }, { "type": "null" } ] }, "grupo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "leitura": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "conclusao": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "resumo": { "type": "string", "minLength": 1 }, "letraBase": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ajustes": { "type": "array", "items": { "type": "object", "properties": { "indicador": { "type": "string", "minLength": 1 }, "efeito": { "type": "number", "enum": [ -1, 0, 1 ] }, "motivo": { "type": "string", "minLength": 1 } }, "required": [ "indicador", "efeito", "motivo" ], "additionalProperties": false } }, "somaAjustes": { "type": "integer" }, "versaoMotor": { "type": "string", "minLength": 1 }, "alerta": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "status", "motivoCodigo", "letra", "grupo", "leitura", "conclusao", "resumo", "letraBase", "ajustes", "somaAjustes", "versaoMotor", "alerta" ], "additionalProperties": false }, "restricoes": { "type": "object", "properties": { "semRestricoes": { "type": "boolean" }, "quadro": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string", "minLength": 1 }, "situacao": { "type": "string", "enum": [ "NADA_CONSTA", "CONSTA", "NAO_APURADO" ] }, "descricao": { "type": "string", "minLength": 1 } }, "required": [ "item", "situacao", "descricao" ], "additionalProperties": false } }, "ocorrencias": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "type": "string", "minLength": 1 }, "origem": { "type": "string", "minLength": 1 }, "data": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "valor": { "type": [ "number", "null" ] }, "detalhe": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "tipo", "origem", "data", "valor", "detalhe" ], "additionalProperties": false } } }, "required": [ "semRestricoes", "quadro", "ocorrencias" ], "additionalProperties": false }, "scr": { "type": "object", "properties": { "situacao": { "type": "string", "enum": [ "COM_RELACIONAMENTO", "SEM_RELACIONAMENTO" ] }, "dataBase": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, { "type": "null" } ], "description": "Mês de referência (AAAA-MM)." }, "inicioRelacionamento": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "quantidadeInstituicoes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "quantidadeOperacoes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "carteira": { "type": "object", "properties": { "aVencer": { "type": [ "number", "null" ] }, "vencido": { "type": [ "number", "null" ] }, "prejuizo": { "type": [ "number", "null" ] }, "limite": { "type": [ "number", "null" ] } }, "required": [ "aVencer", "vencido", "prejuizo", "limite" ], "additionalProperties": false }, "modalidades": { "type": "array", "items": { "type": "object", "properties": { "titulo": { "type": "string", "minLength": 1 }, "linhas": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "titulo", "linhas" ], "additionalProperties": false } } }, "required": [ "situacao", "dataBase", "inicioRelacionamento", "quantidadeInstituicoes", "quantidadeOperacoes", "score", "carteira", "modalidades" ], "additionalProperties": false }, "avisos": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string", "minLength": 1 }, "mensagem": { "type": "string", "minLength": 1 } }, "required": [ "codigo", "mensagem" ], "additionalProperties": false } } }, "required": [ "versao", "metadados", "titular", "contatos", "enderecos", "participacoesSocietarias", "indicadores", "classificacao", "restricoes", "scr", "avisos" ], "additionalProperties": false }, "EventoWebhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Id do evento: o mesmo em todas as tentativas e reenvios. Use para deduplicar." }, "evento": { "type": "string", "enum": [ "consulta.concluida", "consulta.falhou", "consulta.pdf_disponivel", "saldo.baixo", "webhook.teste" ] }, "criadoEm": { "type": "string", "format": "date-time" }, "ambiente": { "type": "string", "enum": [ "live", "test" ], "description": "live = produção (cobra créditos); test = ambiente de testes (dados fictícios)." }, "dados": { "type": "object", "properties": { "consulta": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "NA_FILA", "PROCESSANDO", "CONCLUIDA", "FALHOU" ] }, "numeroRelatorio": { "type": [ "string", "null" ] }, "cpfMascarado": { "type": "string" }, "referenciaExterna": { "type": [ "string", "null" ] }, "cobranca": { "type": "string", "enum": [ "RESERVADO", "COBRADO", "DEVOLVIDO", "SEM_COBRANCA" ] }, "reaproveitada": { "type": "boolean" }, "erro": { "anyOf": [ { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "BASES_INDISPONIVEIS", "PRAZO_ESGOTADO", "FILA_EXPIRADA", "CONTA_BLOQUEADA" ] }, "mensagem": { "type": "string" } }, "required": [ "codigo", "mensagem" ], "additionalProperties": false }, { "type": "null" } ] }, "pdf": { "type": "object", "properties": { "disponivel": { "type": "boolean" } }, "required": [ "disponivel" ], "additionalProperties": false }, "links": { "type": "object", "properties": { "consulta": { "type": "string" }, "pdf": { "type": [ "string", "null" ] } }, "required": [ "consulta", "pdf" ], "additionalProperties": false } }, "required": [ "id", "status", "numeroRelatorio", "cpfMascarado", "referenciaExterna", "cobranca", "reaproveitada", "erro", "pdf", "links" ], "additionalProperties": false, "description": "Eventos consulta.*" }, "saldo": { "type": "object", "properties": { "creditos": { "type": "integer" }, "limiar": { "type": "integer" } }, "required": [ "creditos", "limiar" ], "additionalProperties": false, "description": "Evento saldo.baixo" }, "mensagem": { "type": "string", "description": "Evento webhook.teste" } }, "additionalProperties": false } }, "required": [ "id", "evento", "criadoEm", "ambiente", "dados" ], "additionalProperties": false } }, "parameters": { "Prefer": { "name": "Prefer", "in": "header", "required": false, "description": "wait=N (0 a 60): espera até N segundos pelo status final antes de responder.", "schema": { "type": "string", "example": "wait=30" } } } }, "paths": { "/conta": { "get": { "operationId": "obterConta", "summary": "Conta, token em uso, limites e termos", "description": "Qualquer escopo. Útil para conferir a configuração da integração.", "responses": { "200": { "description": "Dados da conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conta" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/consultas": { "post": { "operationId": "criarConsulta", "summary": "Cria uma consulta (relatório completo)", "description": "Escopo consultas:criar. Debita 1 crédito na criação (produção); se o relatório não ficar completo, o crédito volta. Repita com a MESMA Idempotency-Key em caso de falha de rede: a resposta é a mesma consulta (Idempotent-Replayed: true).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8 a 64 caracteres [A-Za-z0-9._:-], única por pedido (validade de 7 dias). Nunca o CPF.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Prefer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NovaConsulta" } } } }, "responses": { "200": { "description": "Concluída/falhou dentro da espera, ou reaproveitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consulta" } } } }, "202": { "description": "Aceita e na fila; acompanhe pelo Location (ou pelo webhook).", "headers": { "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consulta" } } } }, "400": { "description": "Pedido malformado. Códigos possíveis: IDEMPOTENCY_KEY_OBRIGATORIA, CORPO_INVALIDO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "402": { "description": "Sem créditos. Códigos possíveis: SALDO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "Já existe consulta em andamento para este CPF (detalhes.consultaId). Códigos possíveis: CONSULTA_EM_ANDAMENTO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "422": { "description": "Dados recusados. Códigos possíveis: DADOS_INVALIDOS, CPF_INVALIDO, CPF_FORA_DO_AMBIENTE_DE_TESTES, FINALIDADE_INVALIDA, AUTORIZACAO_DO_TITULAR_OBRIGATORIA, REFERENCIA_COM_DADO_PESSOAL, IDEMPOTENCY_KEY_REUTILIZADA.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível ou sem capacidade; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL, CAPACIDADE_ESGOTADA.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } }, "get": { "operationId": "listarConsultas", "summary": "Lista as consultas do ambiente do token", "description": "Escopo consultas:ler. Mais recentes primeiro, com cursor. Sem o relatório (use GET /consultas/{id}).", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "NA_FILA", "PROCESSANDO", "CONCLUIDA", "FALHOU" ] } }, { "name": "cobranca", "in": "query", "schema": { "type": "string", "enum": [ "RESERVADO", "COBRADO", "DEVOLVIDO", "SEM_COBRANCA" ] } }, { "name": "token", "in": "query", "description": "Parte pública do token.", "schema": { "type": "string" } }, { "name": "referenciaExterna", "in": "query", "schema": { "type": "string" } }, { "name": "de", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "ate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Página de consultas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListaConsultas" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "422": { "description": "Filtro inválido. Códigos possíveis: DADOS_INVALIDOS, REFERENCIA_COM_DADO_PESSOAL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/consultas/{id}": { "get": { "operationId": "obterConsulta", "summary": "Status e, quando concluída, o relatório v1", "description": "Escopo consultas:ler. Consulta de outro cliente ou de outro ambiente: 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Prefer" } ], "responses": { "200": { "description": "A consulta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consulta" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "Consulta inexistente para este token. Códigos possíveis: NAO_ENCONTRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/consultas/{id}/pdf": { "get": { "operationId": "baixarPdf", "summary": "PDF do relatório (o mesmo da impressão do painel)", "description": "Escopo consultas:ler. Disponível quando pdf.disponivel = true na consulta. A ETag é o SHA-256 do arquivo: envie If-None-Match para receber 304 sem baixar de novo. Consulta que falhou: 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "O PDF (A4).", "headers": { "ETag": { "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=\"kapta360-.pdf\"", "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Não mudou desde a ETag enviada." }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "Consulta inexistente para este token, ou que falhou. Códigos possíveis: NAO_ENCONTRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "Ainda em processamento ou com o PDF sendo gerado. Códigos possíveis: PDF_EM_GERACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até tentar de novo.", "schema": { "type": "integer" } } } }, "410": { "description": "Passou o prazo de retenção do resultado. Códigos possíveis: RESULTADO_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/extrato": { "get": { "operationId": "obterExtrato", "summary": "Consumos e estornos de créditos das consultas da API", "description": "Escopo saldo:ler. No ambiente de testes a lista é vazia (amostra: true).", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lançamentos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Extrato" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/saldo": { "get": { "operationId": "obterSaldo", "summary": "Créditos disponíveis", "description": "Escopo saldo:ler. No ambiente de testes o saldo é fictício (amostra: true).", "responses": { "200": { "description": "Saldo de créditos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saldo" } } } }, "401": { "description": "Token ausente, inválido, revogado ou expirado. Códigos possíveis: NAO_AUTENTICADO, TOKEN_REVOGADO, TOKEN_EXPIRADO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "Token válido sem permissão para esta operação. Códigos possíveis: IP_NAO_PERMITIDO, CONTA_BLOQUEADA, API_DESABILITADA, TERMOS_PENDENTES, AMBIENTE_INDISPONIVEL, ESCOPO_INSUFICIENTE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "Limite excedido. Códigos possíveis: LIMITE_EXCEDIDO, MUITAS_FALHAS_DE_AUTENTICACAO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } }, "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } } }, "503": { "description": "Indisponível no momento; repita após o Retry-After. Códigos possíveis: API_INDISPONIVEL, SERVICO_INDISPONIVEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } } }, "webhooks": { "consulta.concluida": { "post": { "operationId": "webhook_consulta_concluida", "summary": "Consulta concluída: o relatório (e, em geral, o PDF) pode ser buscado em links.consulta.", "description": "POST no endereço configurado. Responda 2xx em até 10 s; qualquer outra resposta conta como falha e é repetida até 10 vezes ao longo de ~23 h (pelo menos uma vez: deduplique pelo id do evento). Confira a assinatura antes de usar o corpo.", "parameters": [ { "name": "Kapta360-Assinatura", "in": "header", "required": true, "description": "t=,v1=.\")>. Recuse t com mais de 300 s de diferença.", "schema": { "type": "string" } }, { "name": "Kapta360-Evento", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kapta360-Entrega", "in": "header", "required": true, "description": "Id desta entrega (muda no reenvio manual; o id do evento não).", "schema": { "type": "string" } }, { "name": "Kapta360-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "responses": { "2XX": { "description": "Recebido." } } } }, "consulta.falhou": { "post": { "operationId": "webhook_consulta_falhou", "summary": "Consulta que não ficou completa: o crédito foi devolvido (dados.consulta.erro diz o motivo).", "description": "POST no endereço configurado. Responda 2xx em até 10 s; qualquer outra resposta conta como falha e é repetida até 10 vezes ao longo de ~23 h (pelo menos uma vez: deduplique pelo id do evento). Confira a assinatura antes de usar o corpo.", "parameters": [ { "name": "Kapta360-Assinatura", "in": "header", "required": true, "description": "t=,v1=.\")>. Recuse t com mais de 300 s de diferença.", "schema": { "type": "string" } }, { "name": "Kapta360-Evento", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kapta360-Entrega", "in": "header", "required": true, "description": "Id desta entrega (muda no reenvio manual; o id do evento não).", "schema": { "type": "string" } }, { "name": "Kapta360-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "responses": { "2XX": { "description": "Recebido." } } } }, "consulta.pdf_disponivel": { "post": { "operationId": "webhook_consulta_pdf_disponivel", "summary": "O PDF ficou pronto depois da conclusão (a consulta já tinha sido avisada com pdf.disponivel = false).", "description": "POST no endereço configurado. Responda 2xx em até 10 s; qualquer outra resposta conta como falha e é repetida até 10 vezes ao longo de ~23 h (pelo menos uma vez: deduplique pelo id do evento). Confira a assinatura antes de usar o corpo.", "parameters": [ { "name": "Kapta360-Assinatura", "in": "header", "required": true, "description": "t=,v1=.\")>. Recuse t com mais de 300 s de diferença.", "schema": { "type": "string" } }, { "name": "Kapta360-Evento", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kapta360-Entrega", "in": "header", "required": true, "description": "Id desta entrega (muda no reenvio manual; o id do evento não).", "schema": { "type": "string" } }, { "name": "Kapta360-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "responses": { "2XX": { "description": "Recebido." } } } }, "saldo.baixo": { "post": { "operationId": "webhook_saldo_baixo", "summary": "Um consumo deixou o saldo abaixo do limiar configurado (só em produção).", "description": "POST no endereço configurado. Responda 2xx em até 10 s; qualquer outra resposta conta como falha e é repetida até 10 vezes ao longo de ~23 h (pelo menos uma vez: deduplique pelo id do evento). Confira a assinatura antes de usar o corpo.", "parameters": [ { "name": "Kapta360-Assinatura", "in": "header", "required": true, "description": "t=,v1=.\")>. Recuse t com mais de 300 s de diferença.", "schema": { "type": "string" } }, { "name": "Kapta360-Evento", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kapta360-Entrega", "in": "header", "required": true, "description": "Id desta entrega (muda no reenvio manual; o id do evento não).", "schema": { "type": "string" } }, { "name": "Kapta360-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "responses": { "2XX": { "description": "Recebido." } } } }, "webhook.teste": { "post": { "operationId": "webhook_webhook_teste", "summary": "Enviado pelo botão de teste da área Integração.", "description": "POST no endereço configurado. Responda 2xx em até 10 s; qualquer outra resposta conta como falha e é repetida até 10 vezes ao longo de ~23 h (pelo menos uma vez: deduplique pelo id do evento). Confira a assinatura antes de usar o corpo.", "parameters": [ { "name": "Kapta360-Assinatura", "in": "header", "required": true, "description": "t=,v1=.\")>. Recuse t com mais de 300 s de diferença.", "schema": { "type": "string" } }, { "name": "Kapta360-Evento", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kapta360-Entrega", "in": "header", "required": true, "description": "Id desta entrega (muda no reenvio manual; o id do evento não).", "schema": { "type": "string" } }, { "name": "Kapta360-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "responses": { "2XX": { "description": "Recebido." } } } } }, "x-cenarios-de-teste": { "00000000191": "Relatório completo, sem restrições.", "00000000272": "Relatório completo, com pendências financeiras e protesto.", "00000000353": "Relatório completo de quem não tem histórico no SCR (vem com aviso).", "00000000434": "Uma base não responde: a consulta falha e o crédito não é cobrado.", "00000000515": "Relatório completo; o PDF fica pronto alguns instantes depois." }, "x-erros": { "NAO_AUTENTICADO": { "status": 401, "mensagem": "Token ausente ou inválido. Envie Authorization: Bearer ." }, "TOKEN_REVOGADO": { "status": 401, "mensagem": "Este token foi revogado. Crie outro na área Integração do painel." }, "TOKEN_EXPIRADO": { "status": 401, "mensagem": "Este token expirou. Crie outro na área Integração do painel." }, "IP_NAO_PERMITIDO": { "status": 403, "mensagem": "O IP de origem não está na lista de IPs permitidos deste token." }, "CONTA_BLOQUEADA": { "status": 403, "mensagem": "A conta está bloqueada. Fale com o suporte." }, "API_DESABILITADA": { "status": 403, "mensagem": "A API não está liberada para esta conta. Fale com o suporte." }, "TERMOS_PENDENTES": { "status": 403, "mensagem": "Aceite os Termos de Uso da API na área Integração do painel." }, "ESCOPO_INSUFICIENTE": { "status": 403, "mensagem": "Este token não tem o escopo necessário para esta operação." }, "AMBIENTE_INDISPONIVEL": { "status": 403, "mensagem": "O ambiente de testes não está liberado para esta conta." }, "MUITAS_FALHAS_DE_AUTENTICACAO": { "status": 429, "mensagem": "Muitas tentativas com credencial inválida. Aguarde e tente de novo." }, "LIMITE_EXCEDIDO": { "status": 429, "mensagem": "Limite de requisições excedido. Aguarde o tempo indicado em Retry-After." }, "NAO_ENCONTRADO": { "status": 404, "mensagem": "Recurso não encontrado." }, "METODO_NAO_PERMITIDO": { "status": 405, "mensagem": "Método não permitido neste endereço." }, "CORPO_INVALIDO": { "status": 400, "mensagem": "Corpo da requisição inválido (JSON esperado)." }, "DADOS_INVALIDOS": { "status": 422, "mensagem": "Dados inválidos." }, "CORPO_GRANDE_DEMAIS": { "status": 413, "mensagem": "Corpo da requisição grande demais." }, "IDEMPOTENCY_KEY_OBRIGATORIA": { "status": 400, "mensagem": "Envie o cabeçalho Idempotency-Key (8 a 64 caracteres)." }, "IDEMPOTENCY_KEY_REUTILIZADA": { "status": 422, "mensagem": "Esta Idempotency-Key já foi usada com outro corpo." }, "CPF_INVALIDO": { "status": 422, "mensagem": "CPF inválido." }, "CPF_FORA_DO_AMBIENTE_DE_TESTES": { "status": 422, "mensagem": "No ambiente de testes, use um dos CPFs de exemplo da documentação." }, "FINALIDADE_INVALIDA": { "status": 422, "mensagem": "Informe uma finalidade permitida (veja a documentação)." }, "AUTORIZACAO_DO_TITULAR_OBRIGATORIA": { "status": 422, "mensagem": "Declare que tem a autorização do titular (autorizacaoTitular: true)." }, "REFERENCIA_COM_DADO_PESSOAL": { "status": 422, "mensagem": "A referência externa e a Idempotency-Key não podem conter CPF." }, "CONSULTA_EM_ANDAMENTO": { "status": 409, "mensagem": "Já existe uma consulta em andamento para este CPF." }, "SALDO_INSUFICIENTE": { "status": 402, "mensagem": "Créditos insuficientes. Compre créditos no painel." }, "PDF_EM_GERACAO": { "status": 409, "mensagem": "O PDF ainda está sendo gerado. Tente de novo em instantes." }, "RESULTADO_EXPIRADO": { "status": 410, "mensagem": "O resultado desta consulta não está mais disponível (prazo de retenção)." }, "CAPACIDADE_ESGOTADA": { "status": 503, "mensagem": "Capacidade de processamento esgotada no momento. Tente de novo após o Retry-After." }, "API_INDISPONIVEL": { "status": 503, "mensagem": "A API está temporariamente indisponível." }, "SERVICO_INDISPONIVEL": { "status": 503, "mensagem": "Serviço temporariamente indisponível. Tente de novo após o Retry-After." }, "ERRO_INTERNO": { "status": 500, "mensagem": "Erro interno. Tente de novo; se persistir, informe o requestId ao suporte." } } }