> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # BRA Unico IDCloud API: CPF- und Selfie-Verifizierung > BRA - Unico IDCloud (CPF + Selfie): Brasilien-Datenbankabfrage über Didit. Pay-per-Call ab $0.20, ohne Verträge, ohne Mindestabnahme. Biometrische Validierung mit Unico IDCloud: Gleicht das Selfie des Benutzers mit dem Gesicht ab, das für seine CPF hinterlegt ist, und gibt zurück, ob es sich um dieselbe Person handelt, nicht um dieselbe Person oder ob das Ergebnis nicht eindeutig ist. Didit stellt diesen Dienst über `POST /v3/database-validation/` bereit, damit Sie die übermittelten Daten mit der maßgeblichen Quelle abgleichen und normalisierte Übereinstimmungsergebnisse erhalten. Eingabeformat: `tax_number` erwartet die brasilianische CPF (genau 11 Ziffern). ## Abdeckung * **Abdeckung:** 96% * **Land:** Brasilien * **Service-ID:** `bra_unico_idcloud` * **Datenbereich:** Identität * **Kategorie:** BiometricRiskScore Etwa 96% der CPF-Inhaber sind im Register von Unico mit einem biometrischen Datensatz vertreten. Das ist etwa doppelt so viel wie bei der staatlichen Quelle für den Gesichtsabgleich [Datavalid](https://docs.didit.me/de/api-reference/database-validation/brazil/cpf-facial.md), die rund 50% abdeckt. ## Eingaben | Feld | Pflichtfeld | Beispiel | | - | -: | - | | `tax_number` | Ja | `11111111111` | | `selfie` | Ja | `@./selfie.jpg` | | `first_name` | Nein | `John` | | `last_name` | Nein | `Doe` | | `full_name` | Nein | `John Doe` | | `date_of_birth` | Nein | `1990-01-01` | | `vendor_data` | Nein | `user-1234` | * **Pflichteingaben:** `tax_number`, `selfie` * **Optionale Eingaben:** `first_name`, `last_name`, `full_name`, `date_of_birth`, `vendor_data` * **Einwilligung:** erforderlich * **Verfügbarkeit im Workflow:** im Workflow verfügbar * **Abdeckung:** 96% * **Preis:** \$0.20 pro erfolgreicher Abfrage ## Body-Parameter **issuing\_state** `string` *required* (default: BRA) ISO-3166-1-Alpha-3-Ländercode für diesen Datenbankdienst. Beispiel: `BRA` **services** `string` *required* (default: bra\_unico\_idcloud) Array mit dieser Service-ID. Durch das Festlegen des Dienstes bleibt die Anfrage auf genau diese Datenbank beschränkt. Beispiel: `bra_unico_idcloud` **consent** `boolean` *required* (default: true) Ausdrückliche Einwilligung des Endbenutzers für diesen Dienst. Beispiel: `true` **tax\_number** `string` *required* (default: 11111111111) Steuer- oder Fiskalidentifikationsnummer. Beispiel: `11111111111` **selfie** `file` *required* Selfie-Bilddatei für die biometrische Datenbankvalidierung. Akzeptierte Formate: JPEG, PNG oder WebP. Beispiel: `@./selfie.jpg` **first\_name** `string` Zu validierender Vorname. Beispiel: `John` **last\_name** `string` Zu validierender Nachname. Beispiel: `Doe` **full\_name** `string` Zu validierender vollständiger amtlicher Name. Beispiel: `John Doe` **date\_of\_birth** `string` Geburtsdatum im Format `YYYY-MM-DD`. Beispiel: `1990-01-01` **vendor\_data** `string` (default: user-1234) Ihre stabile Benutzerreferenz für diese Person, etwa Ihre interne Benutzer-ID. Didit verwendet sie, um eigenständige Prüfungen demselben Endbenutzer zuzuordnen und die Zahl fälschlicher Duplikatmeldungen zu verringern. Beispiel: `user-1234` ## Eingaberegeln und Hinweise zur Validierung * Brasilianische CPF (genau 11 Ziffern) * `tax_number` darf nur Ziffern enthalten. Entfernen Sie vor dem Senden der Anfrage Leerzeichen, Bindestriche und Satzzeichen. * `tax_number` muss genau 11 Zeichen lang sein. ## So rufen Sie den Dienst auf ```bash cURL theme={null} curl -X POST "https://verification.didit.me/v3/database-validation/" \ -H "x-api-key: YOUR_API_KEY" \ -F "issuing_state=BRA" \ -F "services=bra_unico_idcloud" \ -F "vendor_data=user-1234" \ -F "consent=true" \ -F "tax_number=11111111111" \ -F "selfie=@./selfie.jpg" ``` ```python Python theme={null} from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_unico_idcloud"], consent=True, tax_number="11111111111", vendor_data="user-1234", selfie=open("selfie.jpg", "rb"), ) print(result) ``` ```javascript Node.js theme={null} import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_unico_idcloud"], consent: true, tax_number: "11111111111", vendor_data: "user-1234", selfie: await fileFromPath("selfie.jpg"), }); console.log(result); ``` ```go Go theme={null} ctx := context.Background() // Reads DIDIT_API_KEY. client := didit.NewClient() result, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{ IssuingState: "BRA", Services: didit.Some([]string{"bra_unico_idcloud"}), Consent: didit.Bool(true), TaxNumber: didit.String("11111111111"), VendorData: didit.String("user-1234"), Selfie: didit.Some(didit.FileFromPath("selfie.jpg")), }) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", result) ``` ```java Java theme={null} import java.nio.file.Path; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_unico_idcloud")) .consent(true) .taxNumber("11111111111") .vendorData("user-1234") .selfie(Path.of("selfie.jpg")) .build()); System.out.println(result); ``` ```php PHP theme={null} databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_unico_idcloud'], 'consent' => true, 'tax_number' => '11111111111', 'vendor_data' => 'user-1234', 'selfie' => File::fromPath('selfie.jpg'), ]); print_r($result->toArray()); ``` ```ruby Ruby theme={null} require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_unico_idcloud"], consent: true, tax_number: "11111111111", vendor_data: "user-1234", selfie: Pathname("selfie.jpg") ) puts result.to_h ``` ```csharp .NET theme={null} using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_unico_idcloud" }, Consent = true, TaxNumber = "11111111111", VendorData = "user-1234", Selfie = FileUpload.FromPath("selfie.jpg"), }); Console.WriteLine(JsonSerializer.Serialize(result)); ``` Jeder erfolgreiche Aufruf gibt HTTP `200` zurück. Das Feld **`outcome_code`** zeigt Ihnen, was tatsächlich passiert ist. So lässt sich beispielsweise eine echte biometrische Nichtübereinstimmung (`BIOMETRIC_NO_MATCH`) von einem Selfie unterscheiden, das nicht gelesen werden konnte (`BIOMETRIC_IMAGE_UNUSABLE`). Der angezeigte `status` ist der Standardstatus der Funktion. Ihre konfigurierten [Aktionen bei Teilübereinstimmung/keiner Übereinstimmung](https://docs.didit.me/de/core-technology/database-validation/database-validation-warnings.md) können ihn überschreiben. **`MATCH`**: Das Register hat die Identität bestätigt, und jedes geprüfte Feld stimmt überein. ```json 200 OK — MATCH theme={null} { "request_id": "req_01H…", "status": "Approved", "issuing_state": "BRA", "match_type": "full_match", "validations": [ { "outcome_code": "MATCH", "service_id": "bra_unico_idcloud", "service_name": "BRA - Unico IDCloud (CPF + selfie)", "source_data": { "unico_face_match": "yes" }, "validation": { "identification_number": "full_match" } } ] } ``` **`BIOMETRIC_NO_MATCH`**: Der Übereinstimmungswert des Gesichtsabgleichs lag unter dem Akzeptanz-Schwellenwert. Das Selfie zeigt nicht dieselbe Person wie das Registerfoto. ```json 200 OK — BIOMETRIC_NO_MATCH theme={null} { "request_id": "req_01H…", "status": "Declined", "issuing_state": "BRA", "match_type": "no_match", "validations": [ { "outcome_code": "BIOMETRIC_NO_MATCH", "service_id": "bra_unico_idcloud", "service_name": "BRA - Unico IDCloud (CPF + selfie)", "source_data": { "identification_number": "NO_MATCH" }, "validation": { "identification_number": "no_match" } } ] } ``` **`INCONCLUSIVE`**: Das Register konnte nicht feststellen, ob die Person übereinstimmt. Das Ergebnis ist tatsächlich unsicher, denn die Person ist möglicherweise im Register enthalten oder auch nicht. Es handelt sich weder um eine Nichtübereinstimmung noch um ein technisches Bildproblem. Kein Feld wird bestätigt, daher ist match\_type null, und die Prüfung wird zur Überprüfung weitergeleitet. ```json 200 OK — INCONCLUSIVE theme={null} { "request_id": "req_01H…", "status": "In Review", "issuing_state": "BRA", "match_type": null, "validations": [ { "outcome_code": "INCONCLUSIVE", "service_id": "bra_unico_idcloud", "service_name": "BRA - Unico IDCloud (CPF + selfie)", "source_data": {}, "validation": {} } ] } ``` ## Rückgabedaten Welche Felder genau in `source_data` erscheinen, hängt von den Daten ab, die das Register zurückgibt. Das generierte Beispiel für `bra_unico_idcloud` dokumentiert derzeit diese normalisierte Struktur: * `unico_face_match` ## Preise und SLAs Anfragen für BRA – Unico IDCloud (CPF + Selfie) werden nur berechnet, wenn Didit von der Validierungsquelle ein eindeutiges Ergebnis erhält. * **Preis pro Aufruf:** \$0.20 USD. * **Abrechnung:** pro erfolgreicher Abfrage. Sie zahlen nichts, wenn das Register nicht erreichbar ist, wenn Pflichtfelder fehlen oder wenn die Anfrage abgelehnt wird, bevor sie die Quelle erreicht. * **Latenz:** typischerweise p95 \< 2 s. * **Verfügbarkeit:** 99.9% pro Quartal auf Seiten von Didit. Die Verfügbarkeit der nachgelagerten Quelle variiert je nach Land und Datensatz. ## Über diese Quelle [Unico](https://unico.io) ist ein brasilianisches IDTech-Unternehmen, das das größte private Gesichtsbiometrie-Register des Landes betreibt. Seine Plattform IDCloud enthält mehr als eine Milliarde Gesichts-Embeddings und kommt monatlich um rund 35 Millionen neue Gesichter hinzu. Diese stammen aus den Onboarding- und Re-Authentifizierungsprozessen von über 800 brasilianischen Unternehmen, darunter vier der fünf größten Banken. Diese Größe erklärt die oben genannte Abdeckung: Eine CPF-Abfrage führt bei etwa 96 % der erwachsenen Brasilianer zu einem biometrischen Datensatz. Didit unterhält eine direkte Partnerschaft mit Unico. Sie können IDCloud daher über die standardmäßige Database Validation API abfragen: Abrechnung pro Abfrage, ohne separaten Vertrag mit Unico, ohne Mindestabnahme und ohne Onboarding-Prozess. **Unterschied zum staatlichen Register.** Didit bietet außerdem [Brazil - CPF + face match (Datavalid)](https://docs.didit.me/de/api-reference/database-validation/brazil/cpf-facial.md) an. Diese Quelle ist das offizielle SERPRO-Register und die richtige Wahl, wenn Sie das staatliche Register ausdrücklich als maßgebliche Quelle benötigen. In allen anderen Fällen ist IDCloud die stärkere Wahl, und das lässt sich an zwei Punkten überprüfen: Die Quelle erreicht etwa 96 % der Erwachsenen, Datavalid dagegen rund 50 %. Außerdem gleicht IDCloud gegen einen biometrischen Datensatz ab, den das Register selbst pflegt, und nicht gegen ein Porträt aus einem Dokument, das der Benutzer vorlegt. Dadurch ist die Quelle sowohl gegen Dokumentenfälschung als auch gegen Betrug mit gestohlenen CPF-Nummern widerstandsfähiger. Außerdem kostet eine Abfrage weniger als die Hälfte. ## Empfohlener Ablauf für Brasilien Für die meisten Anwendungsfälle in Brasilien benötigen Sie keine Dokumentenaufnahme. Der Benutzer gibt Ihnen eine CPF, und ein durch eine Liveness-Erkennung abgesichertes Selfie bestätigt, dass der Benutzer die Person hinter dieser CPF ist. **1. CPF erfassen** Ihre einzige Texteingabe ist die elfstellige CPF. Ein Ausweisfoto sowie ein manuell eingegebener Name oder ein Geburtsdatum sind nicht erforderlich. Da in diesem Ablauf kein Dokument ausgelesen wird, kann Didit die CPF nicht anderweitig beziehen. Sie müssen daher angeben, woher sie stammt. Übergeben Sie sie beim Erstellen der Sitzung in den `metadata` der Sitzung und ordnen Sie sie dem Eingabefeld `tax_number` des Datenbankvalidierungsschritts zu. In der Business Console erfolgt dies über die Eingabezuordnung des Schritts, über die Workflows-API über `database_validation_field_sources` des Knotens: ```json theme={null} { "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}}, "database_validation_field_sources": { "tax_number": {"source": "expected_data", "key": "metadata.cpf"} } } ``` Erstellen Sie anschließend jede Sitzung mit dem Wert unter diesem Schlüssel: ```json theme={null} {"workflow_id": "", "metadata": {"cpf": "12345678909"}} ``` Ohne diese Zuordnung wird der Schritt trotzdem ausgeführt, meldet `tax_number` jedoch als fehlend und fragt das Register nie ab. Es fallen keine Kosten an, und der Eintrag `database_validations` der Sitzung enthält den Grund. **2. Selfie mit Liveness-Erkennung aufnehmen** Fügen Sie dem gleichen Workflow einen [Schritt für Liveness-Erkennung](https://docs.didit.me/de/core-technology/liveness/overview.md) hinzu und wählen Sie die Methode, die zu Ihrer Risikobereitschaft passt: **Passive Liveness-Erkennung** (keine Aktion des Benutzers), **3D-Flash** oder **3D-Aktion & Flash** (aktive Methoden, die Lichtmuster projizieren; die letzte Methode fügt zusätzlich eine zufällige Aktion hinzu). Legen Sie die Methode mit `face_liveness_method` fest (`PASSIVE`, `FLASHING` oder `ACTIVE_3D`), entweder in der Business Console oder über die Workflows-API. Unabhängig von der Wahl rendert Didit den Aufnahmeschritt und bestätigt, dass eine echte, anwesende Person vor der Kamera steht. Dadurch wird verhindert, dass ein gespeichertes Foto oder eine Bildschirmwiedergabe eingereicht wird. **3. CPF und Selfie mit Unico IDCloud validieren** Innerhalb eines Sitzungsablaufs verwendet Didit das Selfie der Liveness-Erkennung automatisch erneut. Sie verarbeiten das Bild also nie selbst. Didit liest die CPF aus der oben beschriebenen Zuordnung. IDCloud prüft anschließend, ob dieses Gesicht zu der Person gehört, der die CPF zugeordnet ist. Der Schritt benötigt nur diese beiden Eingaben. Wenn Sie zusätzlich `full_name` oder `date_of_birth` in `metadata` übergeben und zuordnen, werden diese an Unico als Gegenprüfungen weitergeleitet. Sie sind jedoch nicht erforderlich. > [!NOTE] > > Dieser Ablauf mit alleiniger CPF gilt für **Sitzungs- und Workflow-Integrationen**, bei denen Didit die Aufnahme übernimmt und die Liveness-Selfie für Sie an diesen Dienst übergibt. Wenn Sie `POST /v3/database-validation/` **direkt** aufrufen, ist `selfie` eine verpflichtende Dateieingabe, und Sie stellen das Bild selbst bereit. Beide Modi werden in der [Übersicht zur Datenbankvalidierung](https://docs.didit.me/de/core-technology/database-validation/overview.md) beschrieben. **Kosten:** etwa \$0.30 pro verifiziertem Benutzer mit Passiver Liveness-Erkennung (\$0.20 für die IDCloud-Abfrage plus \$0.10 für die Liveness-Erkennung) oder etwa \$0.35 mit einer aktiven Methode, bei der die Liveness-Erkennung \$0.15 kostet. Dies sind Listenpreise. Ihr Tarifrabatt gilt für jeden dieser Posten. Details finden Sie unter [Preise](https://docs.didit.me/de/getting-started/pricing.md). **Ausweichlösung für die etwa 4%, für die keine Abdeckung besteht.** Gibt IDCloud `INCONCLUSIVE` zurück, konnte das Register diese CPF nicht in einen verwertbaren biometrischen Datensatz auflösen. Das liegt meist daran, dass die Person nicht im Register geführt wird. Behandeln Sie dies als „keine Antwort“ und nicht als fehlgeschlagene Prüfung. Greifen Sie in diesem Fall auf die vollständige [Ausweisverifizierung](https://docs.didit.me/de/core-technology/id-verification/overview.md) zurück: Dokumentenaufnahme plus Gesichtsabgleich mit dem Dokumentenporträt. So bleibt jeder Benutzer verifizierbar, und Sie zahlen die Dokumentenverifizierung nur für den kleinen Rest. **Ablehnungen behandeln.** `BIOMETRIC_NO_MATCH` bedeutet, dass das Register aktiv widersprochen hat: Das Gesicht gehört nicht zu dieser CPF. Behandeln Sie dies als starkes negatives Signal und nicht als Aufforderung zum erneuten Versuch. Den Benutzer direkt zur Dokumentenaufnahme zu schicken, wäre genau der Weg, den ein Betrüger sucht, denn das Dokument ist das Artefakt, das er kontrolliert. Falsch negative Ergebnisse kommen dennoch vor, etwa bei verändertem Aussehen, einem alten Registerfoto oder einer schlechten Aufnahme. Leiten Sie solche Fälle deshalb an die manuelle Prüfung weiter, statt sie automatisch zu genehmigen oder den Benutzer in einer Sackgasse enden zu lassen. `BIOMETRIC_IMAGE_UNUSABLE` ist anders: Das Selfie konnte schlicht nicht gelesen werden, daher fordern Sie ein neues an. Legen Sie mit den [Aktionen für Partial Match / No Match](https://docs.didit.me/de/core-technology/database-validation/database-validation-warnings.md) fest, wie sich jedes Ergebnis auf die Sitzung auswirkt. Die vollständige Liste finden Sie unter [Ergebniscodes](https://docs.didit.me/de/core-technology/database-validation/database-validation-outcome-codes.md). **Wiederkehrende Benutzer.** Eine Registerabfrage müssen Sie nur einmal bezahlen. Nachdem ein Benutzer diesen Ablauf erfolgreich durchlaufen hat, wird das Liveness-Selfie bei dessen `vendor_data` gespeichert. Sie können ihn später mit der [Biometrischen Authentifizierung](https://docs.didit.me/de/core-technology/biometric-auth/overview.md) erneut verifizieren. Dabei werden eine Liveness-Erkennung und ein Gesichtsabgleich mit diesem gespeicherten Gesicht durchgeführt. Die Kosten betragen \$0.10, und es stehen dieselben Liveness-Methoden zur Auswahl. Beachten Sie, dass dies speziell für **wiederkehrende** Benutzer gilt: Eine Sitzung zur biometrischen Authentifizierung benötigt ein gespeichertes Gesicht (oder ein von Ihnen bereitgestelltes `portrait_image`) und schlägt bei der Erstellung fehl, wenn der Benutzer keines von beiden hat. Erstnutzer durchlaufen daher zuerst den oben beschriebenen Ablauf. ## Weiterlesen * [Übersicht zur Brasilien-Datenbankvalidierung](https://docs.didit.me/api-reference/database-validation/brazil.md) * [Übersicht zur Datenbankvalidierung](https://docs.didit.me/de/core-technology/database-validation/overview.md) * [Ergebniscodes](https://docs.didit.me/de/core-technology/database-validation/database-validation-outcome-codes.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.