As listas de sanções e de PPE, prontas a integrar por API

Como funciona

O que obtém

A Authenica fornece dados de conformidade prontos a usar : a triagem dos seus clientes face a listas públicas e oficiais de sanções e de pessoas politicamente expostas (PPE), consolidadas, recarregadas regularmente e servidas por uma API segura, para que as suas equipas não tenham de recolher nem normalizar essas listas.

As listas consultadas

A triagem incide sobre listas públicas e oficiais, publicadas pelos respetivos emissores e recarregadas regularmente. Novas fontes são acrescentadas ao longo do tempo; a lista atualizada está sempre disponível pela API (ver «Listar as fontes»).

Situação segundo o registo de fontes da API. O estado em tempo real de cada lista e a data do seu último carregamento constam dos campos status e lastLoadedAt de GET /api/v1/lists/sources ; esta página não apresenta nenhuma data que aí não figure.

Cobertura das listas nacionais de congelamento

Cada Estado da União mantém, através da sua CENTIF, a sua própria lista nacional de congelamento de bens. A Authenica integra-as uma a uma; uma lista só é indicada como «servida» quando é efetivamente consultada pela API.

Começar em dois minutos

1. Obtenha uma chaveFaça o pedido online: criamos o seu acesso e entregamos-lhe a chave.
2. Chame a APIUma chamada POST com o nome pesquisado e a sua chave.
3. Leia o resultadoUma lista de registos, cada um com a sua lista e a sua versão.

curl -X POST https://api.authenica.tech/api/v1/screenings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Zorbek Nandrawell","scoreThreshold":0.85}'

Obter a sua chave

1. Preencha o formulário de pedido de chave de avaliação com o nome da sua organização e a utilização prevista. Respondemos em um dia útil.
2. Criamos o seu acesso e entregamos-lhe a chave uma única vez. Não é conservada em claro: não lha podemos voltar a dar, apenas criar uma nova.
3. Acordamos consigo uma quota por minuto.

Para alterar ou revogar uma chave, escreva para it@authenica.tech. A revogação é imediata.

Autenticação

Cada chamada leva a sua chave no cabeçalho X-Api-Key. O endereço de base é https://api.authenica.tech, apenas em HTTPS: uma chamada em HTTP é redirecionada.

Sem chave, com uma chave desconhecida, revogada ou expirada: resposta 401. Conhecer o endereço não dá qualquer acesso.

Consultar as listas

POST /api/v1/screenings

O que envia

Ler a resposta

Resposta 200 :

{
  "requestId": "63f766c4-9c1c-4adb-ac8e-4e66674b4be0",
  "matches": [
    {
      "listType": "SANCTIONS",
      "listName": "AUTHENICA_TEST_SANCTIONS",
      "listVersion": "a0a0a0a0-0000-4000-8000-000000000001",
      "targetLabel": "Zorbek NANDRAWELL",
      "score": 1.0,
      "confidence": "UNCORROBORATED",
      "evidence": [
        {
          "field": "DOCUMENT_NUMBER",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": null
        },
        {
          "field": "DATE_OF_BIRTH",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": "15 Jun 1975"
        },
        {
          "field": "NATIONALITY",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": "Mali"
        },
        {
          "field": "PLACE_OF_BIRTH",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": "Bamako"
        }
      ],
      "details": {
        "entityType": "NATURAL_PERSON",
        "list": {
          "label": "Liste d'essai fictive : sanctions",
          "publisher": "Authenica"
        },
        "sanctionPrograms": [
          "TEST-FICTIF"
        ],
        "title": "Personne fictive de la liste d'essai",
        "description": "Fiche fictive pour tester l'intégration. Aucune personne réelle.",
        "nationalities": [
          "Mali"
        ],
        "datesOfBirth": [
          "15 Jun 1975"
        ],
        "placesOfBirth": [
          "Bamako"
        ]
      }
    }
  ],
  "ignoredFields": []
}

A confiança, em termos simples

Ela nunca afasta um registo: um provável homónimo continua a ser um alerta a examinar por uma pessoa.

O detalhe do registo

O bloco details retoma o que o emissor da lista publica sobre o registo. Ajuda a distinguir dois homónimos, por exemplo duas pessoas com o mesmo nome mas funções diferentes.

O detalhe da comparação

Cada linha de evidence tem field (DATE_OF_BIRTH, NATIONALITY, PLACE_OF_BIRTH ou DOCUMENT_NUMBER), customerValue (o que enviou), listValue (o que diz o registo) e status :

• MATCH : os dois coincidem.
• CONFLICT : os dois contradizem-se.
• UNKNOWN : um dos dois lados não indica o elemento, logo nem confirmação nem contradição.

Experimente com casos de teste

A Authenica mantém uma lista de ensaio fictícia para testar a sua integração de ponta a ponta, com resultados reproduzíveis. Não contém nenhuma pessoa nem empresa real : os nomes abaixo não existem. Pode repetir cada pedido com a sua chave e obter a mesma resposta.

curl -X POST https://api.authenica.tech/api/v1/screenings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Zorbek Nandrawell","dateOfBirth":"1975-06-15","nationality":"ML","scoreThreshold":0.85}'

{
  "requestId": "b0fa0a4d-8236-44bc-9979-2a0a41fc95f2",
  "matches": [
    {
      "listType": "SANCTIONS",
      "listName": "AUTHENICA_TEST_SANCTIONS",
      "listVersion": "a0a0a0a0-0000-4000-8000-000000000001",
      "targetLabel": "Zorbek NANDRAWELL",
      "score": 1.0,
      "confidence": "CORROBORATED",
      "evidence": [
        {
          "field": "DOCUMENT_NUMBER",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": null
        },
        {
          "field": "DATE_OF_BIRTH",
          "status": "MATCH",
          "customerValue": "1975-06-15",
          "listValue": "15 Jun 1975"
        },
        {
          "field": "NATIONALITY",
          "status": "MATCH",
          "customerValue": "ML",
          "listValue": "Mali"
        },
        {
          "field": "PLACE_OF_BIRTH",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": "Bamako"
        }
      ],
      "details": {
        "entityType": "NATURAL_PERSON",
        "list": {
          "label": "Liste d'essai fictive : sanctions",
          "publisher": "Authenica"
        },
        "sanctionPrograms": [
          "TEST-FICTIF"
        ],
        "title": "Personne fictive de la liste d'essai",
        "description": "Fiche fictive pour tester l'intégration. Aucune personne réelle.",
        "nationalities": [
          "Mali"
        ],
        "datesOfBirth": [
          "15 Jun 1975"
        ],
        "placesOfBirth": [
          "Bamako"
        ]
      }
    }
  ],
  "ignoredFields": []
}

curl -X POST https://api.authenica.tech/api/v1/screenings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Kassim Dromvale","dateOfBirth":"1968-03-02","nationality":"CI","scoreThreshold":0.85}'

{
  "requestId": "5ce9f675-92cf-4f19-9bd3-3098496f12e9",
  "matches": [
    {
      "listType": "PPE",
      "listName": "AUTHENICA_TEST_PPE",
      "listVersion": "a0a0a0a0-0000-4000-8000-000000000002",
      "targetLabel": "Kassim DROMVALE",
      "score": 1.0,
      "confidence": "CORROBORATED",
      "evidence": [
        {
          "field": "DOCUMENT_NUMBER",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": null
        },
        {
          "field": "DATE_OF_BIRTH",
          "status": "MATCH",
          "customerValue": "1968-03-02",
          "listValue": "02 Mar 1968"
        },
        {
          "field": "NATIONALITY",
          "status": "MATCH",
          "customerValue": "CI",
          "listValue": "Côte d'Ivoire"
        },
        {
          "field": "PLACE_OF_BIRTH",
          "status": "UNKNOWN",
          "customerValue": null,
          "listValue": "Abidjan"
        }
      ],
      "details": {
        "entityType": "NATURAL_PERSON",
        "list": {
          "label": "Liste d'essai fictive : personnes politiquement exposées",
          "publisher": "Authenica"
        },
        "sanctionPrograms": [],
        "title": "Ministre (fonction fictive)",
        "description": "Fiche fictive pour tester l'intégration. Aucune personne réelle.",
        "nationalities": [
          "Côte d'Ivoire"
        ],
        "datesOfBirth": [
          "02 Mar 1968"
        ],
        "placesOfBirth": [
          "Abidjan"
        ]
      }
    }
  ],
  "ignoredFields": []
}

curl -X POST https://api.authenica.tech/api/v1/screenings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Aminata Kone Diabate","dateOfBirth":"1990-04-12","nationality":"CI","scoreThreshold":0.85}'

{
  "requestId": "3b3a92ce-018f-452e-a63b-24d9129179a6",
  "matches": [],
  "ignoredFields": []
}

curl -X POST https://api.authenica.tech/api/v1/screenings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Nandrawell Holding SARL","entityType":"LEGAL_ENTITY","scoreThreshold":0.85}'

{
  "requestId": "bf7e6348-5909-49a4-a997-ed600d1e7494",
  "matches": [
    {
      "listType": "SANCTIONS",
      "listName": "AUTHENICA_TEST_SANCTIONS",
      "listVersion": "a0a0a0a0-0000-4000-8000-000000000001",
      "targetLabel": "NANDRAWELL HOLDING SARL",
      "score": 1.0,
      "confidence": "UNCORROBORATED",
      "evidence": [],
      "details": {
        "entityType": "LEGAL_ENTITY",
        "list": {
          "label": "Liste d'essai fictive : sanctions",
          "publisher": "Authenica"
        },
        "sanctionPrograms": [
          "TEST-FICTIF"
        ],
        "title": "Société fictive de la liste d'essai",
        "description": "Fiche fictive pour tester l'intégration. Aucune société réelle.",
        "nationalities": [],
        "datesOfBirth": [],
        "placesOfBirth": []
      }
    }
  ],
  "ignoredFields": []
}

Filtrar a pesquisa

Dois filtros, que se combinam. Um filtro ausente não filtra nada.

# Seulement les personnes politiquement exposées
-d '{"fullName":"Kassim Dromvale","scoreThreshold":0.85,"listTypes":["PPE"]}'

# Seulement les sociétés, dans les listes de sanctions
-d '{"fullName":"Société Exemple SARL","scoreThreshold":0.85,"entityType":"LEGAL_ENTITY","listTypes":["SANCTIONS"]}'

# Avec la date de naissance et la nationalité, pour corroborer
-d '{"fullName":"Zorbek Nandrawell","scoreThreshold":0.85,"corroboratedThreshold":0.70,"dateOfBirth":"1975-06-15","nationality":"ML"}'

Um tipo desconhecido (por exemplo "entityType":"NAVIRE") é recusado com um erro 400.

Listar as fontes

GET /api/v1/lists/sources

Uma entrada por lista: code (o que encontra em listName), label (o seu nome legível), publisher (o emissor), listType, lastBatchId (o último lote carregado, o que encontra em listVersion), lastLoadedAt (a data do carregamento), status e entityCount (o número de registos). Nenhum dado pessoal.

curl https://api.authenica.tech/api/v1/lists/sources -H "X-Api-Key: $AUTHENICA_CLE_API"

Ler e controlar um documento de identidade

Para além das listas, a Authenica lê um documento de identidade a partir da sua fotografia: bilhete de identidade, passaporte, carta de condução, autorização de residência. O serviço devolve os campos lidos, o modelo de documento reconhecido e os controlos efetuados (validade, autenticidade, qualidade da imagem, coerência da zona de leitura ótica). Pode assim preencher previamente o seu formulário de entrada em relação e saber se o documento merece confiança.

O que envia

POST /api/v1/document-readings, em multipart/form-data, com a sua chave em X-Api-Key como para as listas.

Imagens JPEG ou PNG, no máximo 5 MB cada. O conteúdo é verificado: um ficheiro renomeado em .jpg que não seja uma imagem é recusado.

curl -X POST https://api.authenica.tech/api/v1/document-readings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -F "front=@recto.jpg;type=image/jpeg" \
  -F "back=@verso.jpg;type=image/jpeg"

O que recebe

Os alertas

Um ensaio real com um documento fictício

Eis a resposta real da API para uma imagem de passaporte gerada para o ensaio : não é autêntica e contém apenas dados inventados. O serviço lê os campos, mas assinala que o modelo não é reconhecido e que os controlos de autenticidade não puderam ser efetuados, exatamente o que deve fazer. Para um documento autêntico de um modelo conhecido, o modelo é identificado e os controlos de segurança são efetuados e contabilizados em securityChecks.

curl -X POST https://api.authenica.tech/api/v1/document-readings \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -F "singlePage=@passeport-fictif.png;type=image/png"

{
  "requestId": "c6f82bd1-898a-45de-bcbf-95925b156d48",
  "documentName": null,
  "fields": {
    "LAST_NAME": {
      "value": "KONE",
      "confidence": 78,
      "source": "MRZ",
      "validity": "NOT_PERFORMED",
      "consistent": true
    },
    "GIVEN_NAMES": {
      "value": "AMINATA",
      "confidence": 82,
      "source": "MRZ",
      "validity": "NOT_PERFORMED",
      "consistent": true
    },
    "DATE_OF_BIRTH": {
      "value": "1990-04-12",
      "confidence": 34,
      "source": "MRZ",
      "validity": "ERROR",
      "consistent": true
    },
    "NATIONALITY": {
      "value": "CIV",
      "confidence": 97,
      "source": "MRZ",
      "validity": "OK",
      "consistent": true
    },
    "DOCUMENT_NUMBER": {
      "value": "XXI2345G7",
      "confidence": 34,
      "source": "MRZ",
      "validity": "ERROR",
      "consistent": true
    },
    "EXPIRY_DATE": {
      "value": "2031-01-01",
      "confidence": 29,
      "source": "MRZ",
      "validity": "OK",
      "consistent": true
    }
  },
  "otherFields": {
    "MRZ Type": {
      "value": "ID-3",
      "confidence": 100,
      "source": "MRZ",
      "validity": "NOT_PERFORMED",
      "consistent": true
    },
    "Issuing State Name": {
      "value": "Cote d'Ivoire",
      "confidence": 0,
      "source": "MRZ",
      "validity": "OK",
      "consistent": true
    }
  },
  "authenticity": {
    "overall": "ERROR",
    "documentType": "ERROR",
    "security": "NOT_PERFORMED",
    "expiry": "OK",
    "imageQuality": "ERROR",
    "mrz": "ERROR",
    "securityChecks": null
  },
  "expired": false,
  "warnings": [
    "DOCUMENT_TYPE_NOT_RECOGNISED",
    "AUTHENTICITY_NOT_PERFORMED",
    "LOW_IMAGE_QUALITY",
    "MRZ_CHECK_FAILED"
  ]
}

Os erros

Os erros

Todos os erros têm a mesma forma: {"code": "...", "message": "...", "requestId": "..."}. A mensagem nunca reproduz o que enviou.

Exemplos de código

Em cada exemplo, a chave vem de uma variável de ambiente e a falha suspende a operação.

import os, requests

reponse = requests.post(
    "https://api.authenica.tech/api/v1/screenings",
    headers={"X-Api-Key": os.environ["AUTHENICA_CLE_API"]},
    json={"fullName": "Zorbek Nandrawell", "scoreThreshold": 0.85, "listTypes": ["SANCTIONS"]},
    timeout=10,
)
if reponse.status_code != 200:
    raise RuntimeError(f"Criblage impossible ({reponse.status_code}) : suspendre l'opération")
for fiche in reponse.json()["matches"]:
    print(fiche["listName"], fiche["listVersion"], fiche["score"], fiche["confidence"])

// Node.js 18 ou plus
const reponse = await fetch("https://api.authenica.tech/api/v1/screenings", {
  method: "POST",
  headers: { "X-Api-Key": process.env.AUTHENICA_CLE_API, "Content-Type": "application/json" },
  body: JSON.stringify({ fullName: "Zorbek Nandrawell", scoreThreshold: 0.85 }),
  signal: AbortSignal.timeout(10_000),
});
if (!reponse.ok) throw new Error(`Criblage impossible (${reponse.status}) : suspendre l'opération`);
const { matches, requestId } = await reponse.json();

// Java 11 ou plus
HttpRequest requete = HttpRequest.newBuilder(URI.create("https://api.authenica.tech/api/v1/screenings"))
    .timeout(Duration.ofSeconds(10))
    .header("X-Api-Key", System.getenv("AUTHENICA_CLE_API"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"fullName\":\"Zorbek Nandrawell\",\"scoreThreshold\":0.85}"))
    .build();
HttpResponse<String> reponse = HttpClient.newHttpClient().send(requete, HttpResponse.BodyHandlers.ofString());
if (reponse.statusCode() != 200) throw new IllegalStateException("Criblage impossible : suspendre l'opération");

curl -X POST https://api.authenica.tech/api/v1/screenings \
  --max-time 10 --fail-with-body \
  -H "X-Api-Key: $AUTHENICA_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Zorbek Nandrawell","scoreThreshold":0.85}'

Contrato OpenAPI

O contrato da API está publicado em https://api.authenica.tech/v3/api-docs. Pode importá-lo para o Postman ou o Insomnia, ou gerar um cliente com uma ferramenta como o OpenAPI Generator.

Boas práticas

• Conserve o requestId e a listVersion com a sua decisão: é a sua prova em caso de inspeção.
• Não registe os nomes pesquisados nem a chave. A Authenica também não os guarda: pesquisa, não armazena.
• Um resultado não é uma decisão: uma pessoa examina cada correspondência.
• As listas são recarregadas automaticamente. A data do último carregamento de cada lista está na lista das fontes.
• Defina um prazo de espera para cada chamada e decida antecipadamente o que o seu processo faz se o serviço não responder: suspende.

Planos

Contacte-nos

Uma demonstração, um acesso de avaliação, uma questão comercial: o formulário de contacto.

Uma chave a alterar ou revogar, uma questão de integração, um incidente: it@authenica.tech. Indique o requestId da chamada em causa quando o tiver.