> ## 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.

# Planificar una comprovació de frau

> Valida les dades d'entrada i estima els càrrecs de les comprovacions de frau seleccionades amb Didit abans d'executar la sol·licitud.

Envia el mateix cos que penses utilitzar per a [Fraud Check](https://docs.didit.me/ca/standalone-apis/fraud-check.md).
La planificació no crea cap comprovació ni sessió, no crida cap proveïdor d'enriquiment, no llegeix l'historial de xarxa i no cobra res.

Cada mòdul distingeix entre `available` i `will_run`.
`availability_reason` explica si les dades proporcionades permeten executar-lo, mentre que `selection_reason` explica per què se selecciona o no.
Mantén visibles els interruptors no disponibles i mostra'n els requisits d'entrada.

`networks_cross_org` requereix el pla Enterprise i que el mode de compartició de la teva organització estigui definit com a `global`.
Si no es compleix alguna d'aquestes condicions, o si Networks no està habilitat per a la teva organització, la planificació ho informa amb `available: false` i `availability_reason: "entitlement_required"`.
Una comprovació que el selecciona l'omet amb el mateix motiu.
Les aplicacions de sandbox no estan restringides pel pla ni pel mode de compartició: amb un identificador compatible, el mòdul s'executa i retorna un resultat de mostra buit.

`estimated_price` és una cadena decimal en la `currency` retornada.
Un preu null significa no disponible o sense preu, no gratuït.
L'estimació de nivell superior suma els mòduls executables seleccionats; `can_afford` també comprova l'acord de facturació aplicable.
Torna a planificar després de canviar els identificadors, el context o les seleccions.
L'execució torna a comprovar l'elegibilitat i el preu, de manera que un pla no és una reserva ni una garantia que una font externa respondrà.


## OpenAPI

````yaml ca/openapi-25.json POST /v3/fraud/checks/plan/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/fraud/checks/plan/:
    post:
      tags:
        - Fraud Check
      summary: Planificar un control de frau
      description: >-
        Valida les comprovacions seleccionades i n'estima el preu sense
        executar-les, crear cap sessió ni facturar.
      operationId: plan_create
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/FraudCheckRequestRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/FraudCheckRequestRequest'
            example:
              client_reference: review-attempt-001
              subject:
                identifiers:
                  - type: email
                    value: applicant@example.com
                attributes:
                  first_name: Alex
                  last_name: Example
              checks:
                include:
                  - networks_same_org
                  - networks_cross_org
                  - email_risk
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FraudCheckRequestRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FraudCheckPlan'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FraudBadRequestErrorMessage'
          description: ''
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.fraud_checks.plan(
                client_reference="review-attempt-001",
                subject={
                    "identifiers": [{
                        "type": "email",
                        "value": "applicant@example.com",
                    }],
                    "attributes": {
                        "first_name": "Alex",
                        "last_name": "Example",
                    },
                },
                checks={
                    "include": ["networks_same_org", "networks_cross_org", "email_risk"],
                },
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.fraudChecks.plan({
              client_reference: "review-attempt-001",
              subject: {
                identifiers: [{
                  type: "email",
                  value: "applicant@example.com",
                }],
                attributes: {
                  first_name: "Alex",
                  last_name: "Example",
                },
              },
              checks: {
                include: ["networks_same_org", "networks_cross_org", "email_risk"],
              },
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Plan(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType:  didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName:  didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.FraudCheckAttributesRequest;

            import me.didit.types.FraudCheckIdentifierRequest;

            import me.didit.types.FraudCheckModuleSelectionRequest;

            import me.didit.types.FraudCheckRequestRequest;

            import me.didit.types.FraudCheckSubjectRequest;

            import me.didit.types.FraudExcludeEnum;

            import me.didit.types.FraudTypeEnum;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.fraudChecks().plan(FraudCheckRequestRequest.builder()
                    .clientReference("review-attempt-001")
                    .subject(FraudCheckSubjectRequest.builder()
                            .identifiers(List.of(FraudCheckIdentifierRequest.builder()
                                    .type(FraudTypeEnum.of("email"))
                                    .value("applicant@example.com")
                                    .build()))
                            .attributes(FraudCheckAttributesRequest.builder()
                                    .firstName("Alex")
                                    .lastName("Example")
                                    .build())
                            .build())
                    .checks(FraudCheckModuleSelectionRequest.builder()
                            .include(List.of(FraudExcludeEnum.of("networks_same_org"), FraudExcludeEnum.of("networks_cross_org"), FraudExcludeEnum.of("email_risk")))
                            .build())
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->fraudChecks->plan([
                'client_reference' => 'review-attempt-001',
                'subject' => [
                    'identifiers' => [[
                        'type' => 'email',
                        'value' => 'applicant@example.com',
                    ]],
                    'attributes' => [
                        'first_name' => 'Alex',
                        'last_name' => 'Example',
                    ],
                ],
                'checks' => [
                    'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],
                ],
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.fraud_checks.plan(
              client_reference: "review-attempt-001",
              subject: {
                identifiers: [{
                  type: "email",
                  value: "applicant@example.com",
                }],
                attributes: {
                  first_name: "Alex",
                  last_name: "Example",
                },
              },
              checks: {
                include: ["networks_same_org", "networks_cross_org", "email_risk"],
              }
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.FraudChecks.PlanAsync(new
            FraudCheckRequestRequest

            {
                ClientReference = "review-attempt-001",
                Subject = new()
                {
                    Identifiers = new FraudCheckIdentifierRequest[]
                    {
                        new()
                        {
                            Type = "email",
                            Value = "applicant@example.com",
                        },
                    },
                    Attributes = new FraudCheckAttributesRequest
                    {
                        FirstName = "Alex",
                        LastName = "Example",
                    },
                },
                Checks = new FraudCheckModuleSelectionRequest
                {
                    Include = new FraudExcludeEnum[] { "networks_same_org", "networks_cross_org", "email_risk" },
                },
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    FraudCheckRequestRequest:
      type: object
      properties:
        client_reference:
          type: string
          minLength: 1
          description: >-
            La teva pròpia referència per a aquesta comprovació. Actua també com
            a clau d'idempotència: reutilitzar-la amb el mateix cos retorna la
            comprovació original sense tornar a executar ni facturar els mòduls;
            reutilitzar-la amb un cos diferent retorna un 409.
          maxLength: 255
        profile:
          type: string
          minLength: 1
          default: standard
          description: >-
            ID del perfil d'orquestració. Per defecte és el perfil `standard` de
            Didit.
          maxLength: 64
        profile_version:
          type: string
          minLength: 1
          description: >-
            Fixa una versió de perfil congelada. Per defecte s'utilitza la
            versió actual del perfil.
          maxLength: 32
        subject:
          $ref: '#/components/schemas/FraudCheckSubjectRequest'
        context:
          $ref: '#/components/schemas/FraudCheckContextRequest'
        checks:
          $ref: '#/components/schemas/FraudCheckModuleSelectionRequest'
        vendor_data:
          type: string
          maxLength: 1000
        metadata: {}
      required:
        - subject
    FraudCheckPlan:
      type: object
      properties:
        profile_id:
          type: string
        profile_version:
          type: string
        modules:
          type: array
          items:
            $ref: '#/components/schemas/FraudCheckPlannedModule'
        estimated_price:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        is_sandbox:
          type: boolean
        can_afford:
          type: boolean
      required:
        - can_afford
        - currency
        - estimated_price
        - is_sandbox
        - modules
        - profile_id
        - profile_version
    FraudBadRequestErrorMessage:
      type: object
      properties:
        detail:
          type: string
          default: Bad Request - Invalid request data
    FraudCheckSubjectRequest:
      type: object
      properties:
        selfie:
          type: string
          minLength: 1
          description: >-
            Selfie JPEG, PNG o WebP codificat en Base64, de fins a 6 MB. Sense
            imatge de referència ni URL.
          maxLength: 8388672
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/FraudCheckIdentifierRequest'
          description: Un o més identificadors tipats. Amb un és suficient.
          maxItems: 10
          minItems: 1
        attributes:
          $ref: '#/components/schemas/FraudCheckAttributesRequest'
      required:
        - identifiers
    FraudCheckContextRequest:
      type: object
      properties:
        ip_address:
          type: string
          minLength: 1
        user_agent:
          type: string
          maxLength: 512
        country:
          type: string
          description: >-
            País on el subjecte afirma trobar-se. Només contextual - mai una
            prova de titularitat de la identitat.
          maxLength: 3
        purpose:
          type: string
          maxLength: 128
        consent_obtained:
          type: boolean
    FraudCheckModuleSelectionRequest:
      type: object
      properties:
        include:
          type: array
          items:
            $ref: '#/components/schemas/FraudExcludeEnum'
        exclude:
          type: array
          items:
            $ref: '#/components/schemas/FraudExcludeEnum'
    FraudCheckPlannedModule:
      type: object
      properties:
        module:
          $ref: '#/components/schemas/FraudExcludeEnum'
        available:
          type: boolean
        availability_reason:
          type: string
          nullable: true
        will_run:
          type: boolean
        selection_reason:
          type: string
          nullable: true
        estimated_price:
          type: string
          nullable: true
      required:
        - availability_reason
        - available
        - estimated_price
        - module
        - selection_reason
        - will_run
    FraudCheckIdentifierRequest:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/FraudTypeEnum'
          description: >-
            Tipus d'identificador. Determina quins camps de l'espai de noms són
            obligatoris.


            * `email` - Correu electrònic

            * `phone` - Telèfon

            * `national_id` - Document d'identitat nacional

            * `tax_number` - Número d'identificació fiscal

            * `passport_number` - Número de passaport

            * `driving_licence_number` - Número de permís de conduir

            * `residence_permit_number` - Número de permís de residència

            * `voter_id` - ID electoral

            * `external_id` - ID extern
        value:
          type: string
          minLength: 1
          description: El valor de l'identificador, en qualsevol format habitual.
          maxLength: 255
        country:
          type: string
          description: >-
            País emissor ISO-3166 alpha-2 o alpha-3. Obligatori per a tipus
            d'identificador governamental: els mateixos dígits representen
            persones diferents en països diferents.
          maxLength: 3
        issuer:
          type: string
          description: >-
            Autoritat emissora opcional o emissor subnacional, quan el país per
            si sol no permet identificar-lo unívocament.
          maxLength: 128
      required:
        - type
        - value
    FraudCheckAttributesRequest:
      type: object
      description: >-
        Atributs de corroboració. Tots opcionals; amplien la cobertura del
        mòdul.
      properties:
        first_name:
          type: string
          maxLength: 128
        last_name:
          type: string
          maxLength: 128
        full_name:
          type: string
          maxLength: 256
        date_of_birth:
          type: string
          format: date
        nationality:
          type: string
          maxLength: 3
        gender:
          type: string
          maxLength: 16
        address:
          type: string
          maxLength: 512
        city:
          type: string
          maxLength: 128
        state:
          type: string
          maxLength: 128
        postal_code:
          type: string
          maxLength: 32
    FraudExcludeEnum:
      enum:
        - normalization
        - email_risk
        - email_social
        - phone_social
        - phone_risk
        - ip_risk
        - database_validation
        - networks_same_org
        - networks_cross_org
        - biometric_identity
      type: string
      description: |-
        * `normalization` - Normalització
        * `email_risk` - Risc de correu electrònic
        * `email_social` - Aspectes socials del correu electrònic
        * `phone_social` - Aspectes socials del telèfon
        * `phone_risk` - Risc de telèfon
        * `ip_risk` - Risc d'IP
        * `database_validation` - Validació en bases de dades
        * `networks_same_org` - Xarxes de la mateixa organització
        * `networks_cross_org` - Xarxes entre organitzacions
        * `biometric_identity` - Identitat biomètrica
    FraudTypeEnum:
      enum:
        - email
        - phone
        - national_id
        - tax_number
        - passport_number
        - driving_licence_number
        - residence_permit_number
        - voter_id
        - external_id
      type: string
      description: |-
        * `email` - Correu electrònic
        * `phone` - Telèfon
        * `national_id` - Document d'identitat nacional
        * `tax_number` - Identificador fiscal
        * `passport_number` - Número de passaport
        * `driving_licence_number` - Número de permís de conduir
        * `residence_permit_number` - Número de permís de residència
        * `voter_id` - Identificador de votant
        * `external_id` - ID extern
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.
    BearerAuth:
      type: http
      scheme: bearer
      description: El token d'accés de credencials de client de l'aplicació.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.