API - Validações de Documentos ( CPF )
Introdução
A validação de documentos é uma etapa essencial para garantir a integridade e confiabilidade das informações fornecidas por indivíduos em diversas transações. No Brasil, o CPF (Cadastro de Pessoa Física) é amplamente utilizado como identificador único para pessoas físicas.
O CPF é composto por 11 dígitos e pode ser enviado no formato numérico puro ou com pontuação (pontos e traços). A API suporta ambas as formas de envio e oferece endpoints que permitem verificar a existência e a validade das informações associadas a esse documento
Exemplos de CPFs válidos:
-
12345678901 -
123.456.789-01
Regras de Validação
-
Formato:
-
O CPF pode ser enviado com ou sem formatação.
-
Se o CPF for inválido (exemplo:
12345678900), a API retornará um erro 422 - Unprocessable Entity.
-
A API oferece os seguintes endpoints para validação de CPFs:
-
Validação de Dados Cadastrais Básicos: Retorna informações essenciais associadas ao CPF.
-
Validação de KYC e Compliance: Fornece informações detalhadas relacionadas a requisitos regulatórios.
-
Validação de Compliance para Apostas Online: Retorna informações sobre restrições legais ou regulatórias associadas ao CPF, especialmente relacionadas ao segmento de apostas online.
Endpoints
1. Validação de Dados Cadastrais Básicos
Endpoint: POST /api/validations_documents/basic_data/{cpf}
Descrição
Este endpoint retorna informações cadastrais básicas associadas ao CPF consultado. Ele é usado para validações iniciais e identificação de informações fundamentais.
Requisição
-
Parâmetro de Caminho:
cpf(string): CPF no formato válido, com ou sem pontos e traços.Exemplo:
123.456.789-01ou12345678901. -
Headers:
Authorization(string, obrigatório): Token de autenticação no formato Bearer. -
Corpo da Requisição:
Não aplicável.
Exemplo de Requisição
Basic Data
Comportamento em Caso de Erros
-
CPF inválido: Retorna 422 - Unprocessable Entity.
-
CPF inexistente na Receita Federal: Retorna 200 OK com uma mensagem indicando que o CPF não está registrado.
Respostas
200 - Exemplo: CPF Inexistente na base da Receita Federal
{
"Result": [
{
"MatchKeys": "doc{02106092888}",
"BasicData": {
"TaxIdStatusDate": "0001-01-01T00:00:00"
}
}
],
"QueryId": "0c8814c9-977b-43bf-8bb8-bcdfea940ce7",
"ElapsedMilliseconds": 86,
"QueryDate": "2024-12-11T20:23:16.6152517Z",
"Status": {
"basic_data": [
{
"Code": -114,
"Message": "INVALID DOC PARAMETER"
}
]
},
"Evidences": {}
}
200 - Exemplo: CPF Válido com Dados
{
"Result": [
{
"MatchKeys": "doc**********84}",
"BasicData": {
"TaxIdNumber": "140*****254",
"TaxIdCountry": "BRAZIL",
"AlternativeIdNumbers": {},
"ExtendedDocumentInformation": {
"RG": {
"DocumentLast4Digits": "1225",
"CreationDate": "2020-11-28T23:03:40.212Z",
"LastUpdateDate": "2020-11-28T23:03:40.212Z",
"Sources": [
"ENADE"
]
}
},
"Name": "JOS************MAR",
"Aliases": {
"CommonName": "JOSE******MAR",
"StandardizedName": "JOS************MAR"
},
"Gender": "M",
"NameWordCount": 3,
"NumberOfFullNameNamesakes": 1,
"NameUniquenessScore": 1,
"FirstNameUniquenessScore": 0.001,
"FirstAndLastNameUniquenessScore": 0.001,
"BirthDate": "1986-08-05T00:00:00Z",
"Age": 28,
"ZodiacSign": "LEAO",
"ChineseSign": "Rat",
"BirthCountry": "BRASILEIRA",
"MotherName": "LED****************IRA",
"FatherName": "",
"MaritalStatusData": {},
"TaxIdStatus": "REGULAR",
"TaxIdOrigin": "RECEITA FEDERAL",
"TaxIdFiscalRegion": "ES-RJ",
"HasObitIndication": false,
"TaxIdStatusDate": "2024-08-11T00:00:00",
"TaxIdStatusRegistrationDate": "2009-12-14T00:00:00Z",
"CreationDate": "2016-08-23T00:00:00Z",
"LastUpdateDate": "2024-09-10T00:00:00Z"
}
}
],
"QueryId": "9b57e2c0-9324-43cb-a200-c986eb841912",
"ElapsedMilliseconds": 70,
"QueryDate": "2024-09-24T18:47:32.3585033Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Exemplo: CPF Válido sem Dados
{
"Result": [
{
"MatchKeys": "doc**********87}",
"BasicData": {
"TaxIdStatusDate": "0001-01-01T00:00:00"
}
}
],
"QueryId": "84c33c28-2865-41fe-a520-90dbc1d047f4",
"ElapsedMilliseconds": 13458,
"QueryDate": "2024-01-05T10:58:59.5867667Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
2. Validação de KYC e Compliance
Endpoint: POST /api/validations_documents/kyc/{cpf}
Descrição
Este endpoint realiza uma validação avançada de KYC (Know Your Customer), retornando informações detalhadas, como histórico de PEPs (Pessoas Politicamente Expostas) e sanções.
Requisição
-
Parâmetro de Caminho:
cpf(string): CPF no formato válido, com ou sem pontos e traços.Exemplo:
123.456.789-01ou12345678901. -
Headers:
Authorization(string, obrigatório): Token de autenticação no formato Bearer. -
Corpo da Requisição:
query_parameters(objeto, opcional): Configurações adicionais para a análise.minmatch(integer, opcional): Nível mínimo de correspondência esperado.Valor padrão: `95`
Exemplo de Requisição
KYC e Compliance - minmatch = 95
Exemplo de Requisição
KYC e Compliance - minmatch = 100
- O minmatch é um parâmetro que define o nível mínimo de correspondência esperado para a validação, valores válidos de 0 a 100.
Comportamento em Caso de Erros
-
CPF inválido: Retorna 422 - Unprocessable Entity.
-
CPF inexistente na Receita Federal: Retorna 200 OK, mas com informações vazias no retorno.
Respostas
200 - Exemplo: CPF Inexistente
200 - Exemplo: CPF Válido com Dados
{
"Result": [
{
"MatchKeys": "doc**********11}",
"KycData": {
"PEPHistory": [
{
"Level": "1",
"JobTitle": "PRESIDENTE",
"Department": "COMPANHIA DE TESTE (2011)",
"Motive": "STATE EMPLOYEE",
"Source": "QSA",
"TaxId": "122*****301",
"StartDate": "2023-08-16T00:00:00Z",
"EndDate": "2029-10-11T00:00:00Z"
}
],
"IsCurrentlyPEP": true,
"SanctionsHistory": [
{
"Source": "ofac",
"Type": "Money Laundering",
"StandardizedSanctionType": "FINANCIAL CRIMES",
"MatchRate": 51,
"NameUniquenessScore": "0,125",
"Details": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*************NES",
"BirthDate": "15 Dec 1975",
"StandardizedBirthDate": "1975-12-15T00:00:00",
"SourcePossibleDateOfBirthScore": "0",
"SanctionAliases|MatchRate": "El Borrego|5",
"remarks": "(linked to: LA TEST)"
},
"NormalizedDetails": {
"OriginalName": "LUC**************MAR",
"SanctionName": "LUC*************MAR",
"SanctionAliasesAndMatchRate": "El Borrego|5",
"BirthDate": "12 Dec 1978",
"StandardizedBirthDate": "1975-12-15T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"CreationDate": "2024-11-01T03:04:52.705",
"LastUpdateDate": "2024-11-01T03:04:52.705",
"IsCurrentlyPresentOnSource": true,
"WasRecentlyPresentOnSource": true
},
{
"Source": "ofac",
"Type": "Money Laundering",
"StandardizedSanctionType": "FINANCIAL CRIMES",
"MatchRate": 50,
"NameUniquenessScore": "0,125",
"Details": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*****************ANO",
"BirthDate": "13 Dec 1946",
"StandardizedBirthDate": "1946-12-13T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"NormalizedDetails": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*****************ANO",
"BirthDate": "13 Dec 1946",
"StandardizedBirthDate": "1946-12-13T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"CreationDate": "2024-11-01T03:03:46.034",
"LastUpdateDate": "2024-11-01T03:03:46.034",
"IsCurrentlyPresentOnSource": true,
"WasRecentlyPresentOnSource": true
}
],
"IsCurrentlySanctioned": false,
"WasPreviouslySanctioned": false,
"Last30DaysSanctions": 0,
"Last90DaysSanctions": 0,
"Last180DaysSanctions": 0,
"Last365DaysSanctions": 0,
"LastYearPEPOccurence": 1,
"Last3YearsPEPOccurence": 0,
"Last5YearsPEPOccurence": 0,
"Last5PlusYearsPEPOccurence": 0,
"FirstPEPOccurenceDate": "2023-08-16T00:00:00Z",
"LastPEPOccurenceDate": "2023-08-16T00:00:00Z",
"FirstSanctionDate": "0001-01-01T00:00:00",
"LastSanctionDate": "0001-01-01T00:00:00",
"IsCurrentlyElectoralDonor": false,
"IsHistoricalElectoralDonor": true,
"TotalElectoralDonations": 2,
"TotalElectoralDonationAmount": 30000,
"ElectoralDonations": {
"2016": {
"DonationsCount": 2,
"AmountDonated": 30000
}
}
}
}
],
"QueryId": "1f88c0fb-c648-4a92-88ac-c5769e9f28e2",
"ElapsedMilliseconds": 147,
"QueryDate": "2023-10-01T17:19:13.7795502Z",
"Status": {
"kyc": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Exemplo: CPF Válido sem Dados
{
"Result": [
{
"MatchKeys": "doc**********64}",
"KycData": {
"PEPHistory": [],
"IsCurrentlyPEP": false,
"SanctionsHistory": [],
"IsCurrentlySanctioned": false,
"WasPreviouslySanctioned": false,
"Last30DaysSanctions": 0,
"Last90DaysSanctions": 0,
"Last180DaysSanctions": 0,
"Last365DaysSanctions": 0,
"LastYearPEPOccurence": 0,
"Last3YearsPEPOccurence": 0,
"Last5YearsPEPOccurence": 0,
"Last5PlusYearsPEPOccurence": 0,
"IsCurrentlyElectoralDonor": false,
"IsHistoricalElectoralDonor": false,
"TotalElectoralDonations": 0,
"TotalElectoralDonationAmount": 0,
"ElectoralDonations": {}
}
}
],
"QueryId": "f6ccee7f-da9b-4282-b588-15e6cc917777",
"ElapsedMilliseconds": 150,
"QueryDate": "2024-11-01T17:19:16.2869226Z",
"Status": {
"kyc": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
3. Validação de Compliance para Apostas Online
Endpoint: POST /api/validations_documents/check_aptitude/{cpf}
Descrição
Este endpoint verifica se o CPF informado está associado a restrições legais ou regulatórias específicas para o segmento de apostas online. Ele é usado para determinar a aptidão de um indivíduo para participar de atividades de apostas, com base em listas de autoexclusão e outras restrições relevantes.
Requisição
-
Parâmetro de Caminho:
cpf(string): CPF no formato válido, com ou sem pontos e traços.Exemplo:
123.456.789-01ou12345678901. -
Headers:
Authorization(string, obrigatório): Token de autenticação no formato Bearer. -
Corpo da Requisição:
Não aplicável.
Exemplo de Requisição
Compliance para Apostas Online
Comportamento em Caso de Erros
-
CPF inválido: Retorna 422 - Unprocessable Entity.
-
CPF inexistente na Receita Federal: Retorna 200 OK, mas com informações indicando que o CPF não possui restrições associadas.
Respostas
200 - Exemplo: CPF Inexistente
{
"Result": [
{
"MatchKeys": "doc{01406092888}",
"OnlineBettingCompliance": {}
}
],
"QueryId": "3fca8f74-bd1e-467f-b777-6cf6f6115e94",
"ElapsedMilliseconds": 95,
"QueryDate": "2024-12-11T22:35:45.680699Z",
"Status": {
"online_betting_compliance": [
{
"Code": -114,
"Message": "INVALID DOC PARAMETER"
}
]
},
"Evidences": {}
}
200 - Exemplo: CPF com Restrições
{
"Result": [
{
"MatchKeys": "doc**********77}",
"OnlineBettingCompliance": {
"SportsExposure": {
"Sports": [
{
"SportName": "SO**QR",
"Region": "BRAZIL",
"TotalRelatedEntities": 1,
"RelatedEntities": [
{
"DocNumber": "808*****850",
"DocType": "CPF",
"RelationshipLevel": "BUSINESS PARTNER",
"InstitutionName": "FLA**NGO",
"InstitutionActivity": "CLUBES SOCIAIS, ESPORTIVOS E SIMILARES",
"Role": "MANAGER",
"IsActive": true,
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"Source": "FLAMENGOCOUNCIL"
}
]
}
]
},
"ForbiddenBet": {
"Name": "PED*************************AES",
"Age": "53",
"TaxIdStatus": "REGULAR",
"IsFromMinisterioDaFazenda": false,
"IsBookmakerOwner": true,
"BookmakerOwnerMotives": [
{
"Source": "SIGAP",
"CNPJ": "46786961000174",
"CompanyName": "KAI********************DA.",
"EconomicActivityCodes": "6463800;7319004;9200399",
"AdditionalDetails": {
"SIGAPApplicationNumber": "000**024",
"SIGAPRegistrationDate": "2024-05-26 22:35:16"
}
}
],
"MinisterioDaFazendaMotives": {}
}
}
}
],
"QueryId": "fb90339c-787a-4001-a30f-dfecc5a21a4b",
"ElapsedMilliseconds": 854,
"QueryDate": "2024-12-10T17:41:30.6211076Z",
"Status": {
"online_betting_compliance": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Exemplo: CPF Sem Restrições
{
"Result": [
{
"MatchKeys": "doc**********88}",
"OnlineBettingCompliance": {
"SportsExposure": {
"Sports": []
},
"ForbiddenBet": {
"Name": "JOA*****************************MAR",
"Age": "1",
"TaxIdStatus": "REGULAR",
"IsFromMinisterioDaFazenda": false,
"IsBookmakerOwner": false,
"BookmakerOwnerMotives": [],
"MinisterioDaFazendaMotives": {}
}
}
}
],
"QueryId": "708fa54e-488e-4778-a090-297a82f2f959",
"ElapsedMilliseconds": 136,
"QueryDate": "2024-12-10T17:41:31.507089Z",
"Status": {
"online_betting_compliance": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}