didit-sdk 1.0.0

data/lib/didit/resources/businesses.rb

@@ -0,0 +1,471 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +businesses+ resource.
+    class Businesses < Didit::Resource
+      # Batch delete businesses
+      #
+      # **Permanently delete** businesses - this cannot be undone. For blocking prefer [Update Business
+      # Status](#patch-/v3/businesses/-vendor_data-/update-status/) with `BLOCKED`.
+      #
+      # **Filed regulatory reports:** if the selected data is in a finalized regulatory report, the whole request is
+      # refused with `409` and nothing is deleted. The body uses `code: in_filed_report` and names each report with
+      # `uuid`, `report_number`, `report_type` and `case_uuid`. Delete the reports, then repeat the request.
+      #
+      # +POST /v3/businesses/delete/+
+      #
+      # @param vendor_data_list [Array<String>] Your own identifiers to delete, matched exactly as sent.
+      # @param didit_internal_id_list [Array<String>] Didit's internal UUIDs (`didit_internal_id`) to delete.
+      # @param delete_all [Boolean] If `true`, deletes every business in the application. Cannot be combined with the
+      #   list selectors.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BusinessesBatchDeleteResponse]
+      def batch_delete(vendor_data_list: OMIT, didit_internal_id_list: OMIT, delete_all: OMIT, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/businesses/delete/",
+          body: {
+            "vendor_data_list" => vendor_data_list,
+            "didit_internal_id_list" => didit_internal_id_list,
+            "delete_all" => delete_all
+          },
+          response: Types::BusinessesBatchDeleteResponse,
+          request_options: request_options
+        )
+      end
+
+      # Create business
+      #
+      # Pre-create a [business](/entities/businesses) *without* a KYB session. All fields are optional, but you should
+      # always send `vendor_data` - without it the record cannot be linked to sessions or transactions. When provided,
+      # `vendor_data` must be unique among non-deleted businesses (exact match; conflicts return 400). Not idempotent.
+      #
+      # +POST /v3/businesses/create/+
+      #
+      # @param vendor_data [String, nil] Your unique identifier for this business (free-form string, NOT a UUID).
+      #   Optional but strongly recommended. When provided, must be unique among non-deleted businesses for the
+      #   application; matched exactly as sent.
+      # @param display_name [String, nil] Friendly display name shown in the console (takes precedence over
+      #   `legal_name` for UI display).
+      # @param legal_name [String, nil] Official legal name of the company.
+      # @param registration_number [String, nil] Company registration or incorporation number.
+      # @param country_code [String, nil] Country of incorporation (ISO 3166-1 alpha-2, e.g. `GB`, `US`).
+      # @param status [String] Initial lifecycle status. Defaults to `ACTIVE`.
+      # @param metadata [Hash, nil] Arbitrary JSON object you attach to the business. Defaults to `{}`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BusinessDetailItem]
+      def create(
+        vendor_data: OMIT,
+        display_name: OMIT,
+        legal_name: OMIT,
+        registration_number: OMIT,
+        country_code: OMIT,
+        status: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/businesses/create/",
+          body: {
+            "vendor_data" => vendor_data,
+            "display_name" => display_name,
+            "legal_name" => legal_name,
+            "registration_number" => registration_number,
+            "country_code" => country_code,
+            "status" => status,
+            "metadata" => metadata
+          },
+          response: Types::BusinessDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Download a business session PDF report
+      #
+      # Render the PDF report of one Business Verification (KYB) session: company registry data, key people and
+      # beneficial owners, documents, AML results and the other workflow features, plus the session's tags and review
+      # activity. With white-label customization on, the report carries your logo and privacy policy URL. The body is
+      # the PDF itself (`application/pdf`), not JSON.
+      #
+      # The session must be `Approved`, `Declined` or `In Review`; any other status returns `403`, so wait for the
+      # `status.updated` [webhook](https://docs.didit.me/integration/webhooks) first. The report is rendered on every
+      # call and nothing is billed, so store the file instead of fetching it repeatedly. `GET
+      # /v3/session/{sessionId}/generate-pdf/` renders the same kind of report by session ID alone.
+      #
+      # A PDF report counts as media: a scoped API key needs `businesses: read` and `media: read`, and a key limited
+      # to some workflows or to approved sessions cannot call it.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/businesses/{business_session_id}/pdf/+
+      #
+      # @param business_session_id [String] `session_id` of the Business Verification (KYB) session, as returned when
+      #   the session was created. A session of another application returns `404`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [String, nil] the body bytes, or nil when a block receives the chunks
+      def generate_session_pdf(business_session_id, request_options: nil, &block)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/businesses/{business_session_id}/pdf/",
+          path_params: { "business_session_id" => business_session_id },
+          scope: :application,
+          response: :binary,
+          accept: "application/pdf, application/json",
+          request_options: request_options, &block
+        )
+      end
+
+      # List businesses
+      #
+      # List [businesses](/entities/businesses) Didit assembles from KYB sessions sharing the same `vendor_data`
+      # (free-form string, NOT a UUID), plus businesses created via the API. Paginated, ordered by `last_session_at`
+      # desc. This endpoint does not support filtering or search parameters - fetch pages and filter client-side.
+      #
+      # +GET /v3/businesses/+
+      #
+      # @param limit [Integer] Page size. Defaults to 50 when omitted. There is no enforced maximum, but keep pages
+      #   small for latency.
+      # @param offset [Integer] Zero-based offset of the first record to return. Prefer following the `next` URL from
+      #   the previous page over computing this by hand.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::BusinessListItem>]
+      def list(limit: OMIT, offset: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/businesses/",
+          query: {
+            "limit" => limit,
+            "offset" => offset
+          },
+          page: Types::BusinessListItem,
+          request_options: request_options
+        )
+      end
+
+      # List networks for a business
+      #
+      # List the networks a vendor business belongs to.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/businesses/{vendor_business_uuid}/networks/+
+      #
+      # @param vendor_business_uuid [String] Vendor business UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::EntityNetworkMembershipList]
+      def list_networks(vendor_business_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/businesses/{vendor_business_uuid}/networks/",
+          path_params: { "vendor_business_uuid" => vendor_business_uuid },
+          scope: :application,
+          response: Types::EntityNetworkMembershipList,
+          request_options: request_options
+        )
+      end
+
+      # Get business
+      #
+      # Fetch one [business](/entities/businesses) by `vendor_data` (exact match). Adds `metadata` and `updated_at` to
+      # the list view. Deleted businesses return 404.
+      #
+      # +GET /v3/businesses/{vendor_data}/+
+      #
+      # @param vendor_data [String] Your unique identifier for the business - a free-form string (NOT a UUID), matched
+      #   exactly as sent.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BusinessDetailItem]
+      def retrieve(vendor_data, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/businesses/{vendor_data}/",
+          path_params: { "vendor_data" => vendor_data },
+          response: Types::BusinessDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Get AML ongoing monitoring job
+      #
+      # Progress and per-outcome counters of a monitoring toggle job. Poll every couple of seconds while status is
+      # PENDING or PROCESSING.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/{job_id}/+
+      #
+      # @param job_id [String] Monitoring job UUID returned by the toggle endpoint.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringJob]
+      def retrieve_ongoing_monitoring_job(job_id, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/{job_id}/",
+          path_params: { "job_id" => job_id },
+          scope: :application,
+          response: Types::OngoingMonitoringJob,
+          request_options: request_options
+        )
+      end
+
+      # Get AML ongoing monitoring job
+      #
+      # Progress and per-outcome counters of a monitoring toggle job. Poll every couple of seconds while status is
+      # PENDING or PROCESSING.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/{job_id}/+
+      #
+      # @param job_id [String] Monitoring job UUID returned by the toggle endpoint.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringJob]
+      def retrieve_session_ongoing_monitoring_job(job_id, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/{job_id}/",
+          path_params: { "job_id" => job_id },
+          scope: :application,
+          response: Types::OngoingMonitoringJob,
+          request_options: request_options
+        )
+      end
+
+      # Enable or disable AML ongoing monitoring for businesses
+      #
+      # Turns AML ongoing monitoring on or off for the selected businesses, with the same semantics as the Business
+      # Console. Exactly one monitored AML screening is kept per business, so a profile that verified several times is
+      # monitored and billed once; disabling turns monitoring off across all of the profile's screenings. Businesses
+      # without any AML screening are screened first (billed as a regular AML screening) when they have the legal or
+      # display name needed; otherwise they are reported as `skipped_no_identity_data`.
+      #
+      # Set `estimate_only: true` to preview counts and costs without writing anything. Selections of 20 profiles or
+      # fewer resolve inline and return `200` with the completed job; larger selections return `202` and run in the
+      # background - poll [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/) with the returned `job_id`.
+      # Enabling is refused with `403` when the organization balance does not cover the estimate. Identifiers that
+      # match nothing are listed in `unmatched` and never fail the request: a selection that matches nothing completes
+      # as an empty job (`total` 0), the same convention as the batch delete endpoints.
+      #
+      # +POST /v3/businesses/aml-monitoring/+
+      #
+      # @param is_enabled [Boolean] true to enable monitoring, false to disable it.
+      # @param estimate_only [Boolean] When true, returns the cost estimate and performs no writes - no screening, no
+      #   billing, no job.
+      # @param vendor_data_list [Array<String>] Your own identifiers of the businesses to toggle, matched exactly as
+      #   sent.
+      # @param didit_internal_id_list [Array<String>] Didit internal ids of the businesses to toggle - the
+      #   `didit_internal_id` returned by the create, get and list endpoints.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AMLMonitoringToggleResult, Didit::Types::AMLMonitoringJob]
+      def set_aml_monitoring(
+        is_enabled:,
+        estimate_only: OMIT,
+        vendor_data_list: OMIT,
+        didit_internal_id_list: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/businesses/aml-monitoring/",
+          body: {
+            "is_enabled" => is_enabled,
+            "estimate_only" => estimate_only,
+            "vendor_data_list" => vendor_data_list,
+            "didit_internal_id_list" => didit_internal_id_list
+          },
+          response: { 200 => Types::AMLMonitoringToggleResult, 202 => Types::AMLMonitoringJob },
+          request_options: request_options
+        )
+      end
+
+      # Toggle AML ongoing monitoring for businesses
+      #
+      # Business-level equivalent of the user toggle: one monitored AML screening per business, with businesses
+      # lacking any AML screening screened first (company entity). Same estimate_only, inline fast-path and async job
+      # contract.
+      #
+      # +PATCH /v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/+
+      #
+      # @param is_enabled [Boolean] true to enable monitoring, false to disable it.
+      # @param estimate_only [Boolean] When true, returns the cost estimate and performs no writes.
+      # @param update_all [Boolean] Apply to every entity of the application (scoped by the filter_* params when
+      #   present).
+      # @param filter_search [String]
+      # @param filter_status [Array<String>]
+      # @param filter_country [String]
+      # @param filter_date_from [Date, String]
+      # @param filter_date_to [Date, String]
+      # @param didit_internal_id_list [Array<String>] Entities to toggle. Required unless update_all is true.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringToggleResult, Didit::Types::OngoingMonitoringJob]
+      def set_ongoing_monitoring(
+        is_enabled:,
+        estimate_only: OMIT,
+        update_all: OMIT,
+        filter_search: OMIT,
+        filter_status: OMIT,
+        filter_country: OMIT,
+        filter_date_from: OMIT,
+        filter_date_to: OMIT,
+        didit_internal_id_list: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/",
+          body: {
+            "is_enabled" => is_enabled,
+            "estimate_only" => estimate_only,
+            "update_all" => update_all,
+            "filter_search" => filter_search,
+            "filter_status" => filter_status,
+            "filter_country" => filter_country,
+            "filter_date_from" => filter_date_from,
+            "filter_date_to" => filter_date_to,
+            "didit_internal_id_list" => didit_internal_id_list
+          },
+          scope: :application,
+          response: { 200 => Types::OngoingMonitoringToggleResult, 202 => Types::OngoingMonitoringJob },
+          request_options: request_options
+        )
+      end
+
+      # Toggle AML ongoing monitoring for business sessions
+      #
+      # Session-level toggle for KYB verifications, addressed by session number. Sessions without an AML screening get
+      # one created and attached to the session itself. Same estimate_only, inline fast-path and async job contract as
+      # the user-level endpoints. Replaces the legacy synchronous behavior that skipped sessions without an AML
+      # screening.
+      #
+      # +PATCH /v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/+
+      #
+      # @param is_enabled [Boolean] true to enable monitoring, false to disable it.
+      # @param estimate_only [Boolean] When true, returns the cost estimate and performs no writes.
+      # @param update_all [Boolean] Apply to every entity of the application (scoped by the filter_* params when
+      #   present).
+      # @param filter_search [String]
+      # @param filter_status [Array<String>]
+      # @param filter_country [String]
+      # @param filter_date_from [Date, String]
+      # @param filter_date_to [Date, String]
+      # @param session_numbers [Array<String>] Business session numbers to toggle. Required unless update_all (or the
+      #   legacy toggle_all alias) is true.
+      # @param toggle_all [Boolean] Legacy alias of update_all.
+      # @param filter_workflow_id [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringToggleResult, Didit::Types::OngoingMonitoringJob]
+      def set_session_ongoing_monitoring(
+        is_enabled:,
+        estimate_only: OMIT,
+        update_all: OMIT,
+        filter_search: OMIT,
+        filter_status: OMIT,
+        filter_country: OMIT,
+        filter_date_from: OMIT,
+        filter_date_to: OMIT,
+        session_numbers: OMIT,
+        toggle_all: OMIT,
+        filter_workflow_id: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/",
+          body: {
+            "is_enabled" => is_enabled,
+            "estimate_only" => estimate_only,
+            "update_all" => update_all,
+            "filter_search" => filter_search,
+            "filter_status" => filter_status,
+            "filter_country" => filter_country,
+            "filter_date_from" => filter_date_from,
+            "filter_date_to" => filter_date_to,
+            "session_numbers" => session_numbers,
+            "toggle_all" => toggle_all,
+            "filter_workflow_id" => filter_workflow_id
+          },
+          scope: :application,
+          response: { 200 => Types::OngoingMonitoringToggleResult, 202 => Types::OngoingMonitoringJob },
+          request_options: request_options
+        )
+      end
+
+      # Update business
+      #
+      # Partial update of a business: `display_name`, `legal_name`, `registration_number`, `country_code`, `status`,
+      # `metadata`. `metadata` fully replaces. Setting `status` to `BLOCKED` adds the `vendor_data` to the system
+      # blocklist; moving away from `BLOCKED` removes that entry. Every edit is recorded in the company's activity: a
+      # status change with the optional `reason`, and a change to `display_name`, `legal_name`, `registration_number`,
+      # `country_code` or `metadata` as a profile update.
+      #
+      # +PATCH /v3/businesses/{vendor_data}/+
+      #
+      # @param vendor_data [String] Your unique identifier for the business (free-form string, NOT a UUID).
+      # @param display_name [String, nil] Friendly display name shown in the console (takes precedence over
+      #   `legal_name` for UI display).
+      # @param legal_name [String, nil] Official legal name from registry or manual entry.
+      # @param registration_number [String, nil] Company registration or incorporation number.
+      # @param country_code [String, nil] Country of incorporation (ISO 3166-1 alpha-2, e.g. `GB`, `US`).
+      # @param status [String] Business lifecycle status. Setting `BLOCKED` automatically adds the `vendor_data` to
+      #   the system blocklist; flipping away from `BLOCKED` removes that blocklist entry.
+      # @param metadata [Hash, nil] Arbitrary JSON object you attach to the business. **Fully replaces** the existing
+      #   metadata on update - merge client-side if you only want to add keys.
+      # @param reason [String, nil] Why the status changed. Recorded on the status-change entry of the company's
+      #   **Activity** in the Business Console, only when the status actually changes. Webhooks do not carry it.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BusinessDetailItem]
+      def update(
+        vendor_data,
+        display_name: OMIT,
+        legal_name: OMIT,
+        registration_number: OMIT,
+        country_code: OMIT,
+        status: OMIT,
+        metadata: OMIT,
+        reason: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/businesses/{vendor_data}/",
+          path_params: { "vendor_data" => vendor_data },
+          body: {
+            "display_name" => display_name,
+            "legal_name" => legal_name,
+            "registration_number" => registration_number,
+            "country_code" => country_code,
+            "status" => status,
+            "metadata" => metadata,
+            "reason" => reason
+          },
+          response: Types::BusinessDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Update business status
+      #
+      # Flip only the lifecycle `status` of a business: `ACTIVE`, `FLAGGED` or `BLOCKED` (not session statuses).
+      # `BLOCKED` adds the `vendor_data` to the system blocklist; moving away from `BLOCKED` removes that entry. Each
+      # change is recorded in the company's activity, with the optional `reason`. Sending the current status changes
+      # nothing and records no `reason`. The `business.status.updated` webhook does not carry `reason`.
+      #
+      # +PATCH /v3/businesses/{vendor_data}/update-status/+
+      #
+      # @param vendor_data [String] Your unique identifier for the business (free-form string, NOT a UUID).
+      # @param status [String] New lifecycle status. `BLOCKED` also adds the `vendor_data` to the system blocklist.
+      # @param reason [String, nil] Why the status changed. Recorded on the status-change entry of the company's
+      #   **Activity** in the Business Console, only when the status actually changes. Webhooks do not carry it.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BusinessDetailItem]
+      def update_status(vendor_data, status:, reason: OMIT, request_options: nil)
+        @client.request(
+          :patch,
+          "/v3/businesses/{vendor_data}/update-status/",
+          path_params: { "vendor_data" => vendor_data },
+          body: {
+            "status" => status,
+            "reason" => reason
+          },
+          response: Types::BusinessDetailItem,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end