> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Registro de Alterações

> Últimas atualizações e melhorias na documentação da gu1 — cobrindo novos endpoints, recursos do painel e correções, com exemplos para changelog.

***

***

***

***

<Update label="2026-07-31" description="Filtrar transações pela data da última avaliação de regras" tags={["Transações", "Regras"]}>
  ## Filtro pela última avaliação de regras

  **`GET /transactions`** agora aceita os filtros ISO inclusivos opcionais
  `lastRiskEvaluationFrom` e `lastRiskEvaluationTo`. Eles podem ser combinados para selecionar
  transações cuja última avaliação de regras concluída com sucesso esteja dentro de um intervalo.
  Transações avaliadas antes da existência desse campo são resolvidas a partir do seu histórico
  de análise de risco, e a lista agora retorna `lastRiskEvaluationAt`.

  Veja [Listar transações](/pt/api-reference/transactions/list).
</Update>

<Update label="2026-07-31" description="Webhooks legacy de entidades agora incluem score e documento" tags={["Webhooks", "Entidades"]}>
  ## Campos adicionais nos webhooks legacy planos de entidades

  Os payloads legacy planos de webhooks de entidades agora incluem os campos aditivos
  `riskScore` e `documentNumber`. Os valores e mapeamentos de status existentes permanecem
  inalterados.

  Veja [Eventos de webhook de entidades](/pt/webhooks/events/entity-events).
</Update>

<Update label="2026-07-31" description="Baixar quais transações foram ignoradas por duplicidade" tags={["Transações", "Batch"]}>
  ## Relatório de linhas ignoradas em batch de transações

  Novo endpoint **`GET /batch-import/transaction-jobs/{jobId}/skips.csv`**: lista as transações que o batch não inseriu porque o `externalId` já existia (colunas `external_id,reason`). Até agora `skipped` era apenas um contador, e um reenvio de duplicatas parecia uma falha silenciosa.

  * Disponível para jobs executados com o default `skipDuplicates=true`; com `skipDuplicates=false` as duplicatas são resolvidas pelo banco e apenas contadas, então o endpoint retorna `SKIPS_NOT_AVAILABLE`.
  * Jobs finalizados antes deste release não têm relatório salvo (`SKIPS_NOT_AVAILABLE`).
  * Também disponível como botão de download no histórico de importações.

  Ver [Falhas batch de transações](/pt/api-reference/bulk-imports/get-transaction-batch-failures).
</Update>

<Update label="2026-07-24" description="Bulk: aplicar relações declarativas quando a entidade já existe" tags={["Entidades", "Batch"]}>
  ## Relações declarativas com `tax_id` duplicado (bulk)

  Na importação em massa **manual**, se o `tax_id` da linha já existir e a criação for omitida, a Gu1 **ainda aplica** as `relationships` / colunas CSV `related_*` dessa linha (igual ao create **automático**). Se o vínculo (mesmo source → target + tipo) já existir, é omitido de forma idempotente.

  Ver [Importar entidades (bulk)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-07-23" description="Relações declarativas em create + bulk de entidades" tags={["Entidades", "API", "Batch"]}>
  ## Vínculos a entidades existentes no create e na importação em massa

  Você pode declarar relações a entidades **já existentes** (`relatedEntityId` / `relatedTaxId` / `relatedExternalId` + `relationshipType` + `role`) sem depender do `depth` de enrichment:

  * **`POST /entities`** e **`POST /entities/automatic`**: body opcional `relationships[]` (máx. 10).
  * **Bulk CSV plataforma**: colunas `related_tax_id` / `related_external_id` / `related_entity_id`, `relationship_type`, `relationship_role`, `relationship_as_source` (uma relação por linha).
  * Se a contraparte não existir → **`RELATED_ENTITY_NOT_FOUND`** e a entidade **não** é criada.

  Ver [Criar entidade](/pt/api-reference/entities/create), [Criar automaticamente](/pt/api-reference/entities/create-automatic) e [Importar entidades (bulk)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-07-23" description="Webhook de segurança: alteração de acesso ao ambiente" tags={["Webhooks", "Segurança", "IAM"]}>
  ## `security.member.environment_changed`

  Quando um admin atualiza o acesso prod/sandbox de um membro em Equipes (roster) em **uma** atribuição, a Gu1 emite um único webhook em vez de vários grant/revoke:

  * **Evento:** `security.member.environment_changed`
  * **`context.fromAccess` / `context.toAccess`:** `"both"` | `"production"` | `"sandbox"` | `"none"`
  * **`changes.environmentAccess`:** `{ previous, current }` com os mesmos valores

  Os eventos `security.member.environment_granted` / `.environment_revoked` continuam existindo para fluxos de grant/revoke de um único ambiente.

  Ver [Eventos de webhook de segurança](/pt/webhooks/events/security-events).
</Update>

<Update label="2026-07-22" description="linkEntityStrict + soft-link sem quebrar defaults do lote" tags={["Transações", "API", "Batch"]}>
  ## Vínculo de entidades: soft-link sempre, default estrito do lote inalterado

  Criar TX / lote **sempre tenta auto-vincular** quando há match (entityId → externalId → taxId).

  * **Default do lote (BC):** omitir flags continua **estrito** — `validateExistingEntity` padrão **`true`**. Refs não resolvidas → **400** (igual a antes).
  * **`linkEntityStrict=true`**: força hard-fail (body ou query).
  * **`linkEntityStrict=false`**: força soft-link (não falha se faltar), mesmo se `validateExistingEntity` diga o contrário.
  * **`validateExistingEntity=false`**: soft-link (e agora vincula se encontrar — antes o soft do lote pulava o link).

  `POST /transactions` (uma TX) mantém `validateExistingEntity` padrão **`false`**.

  Ver [Criar lote](/pt/api-reference/transactions/create-batch).
</Update>

<Update label="2026-07-13" description="Rename do código de cota contratual de criação" tags={["API", "Billing"]}>
  ## Código de erro: `CREATION_CONTRACT_QUOTA_EXCEEDED`

  Quando a **cota contratual de criação** da organização se esgota (entidades, transações, eventos de usuário), as APIs Gu1 passam a responder **`429`** com o código **`CREATION_CONTRACT_QUOTA_EXCEEDED`** (substitui `CREATION_QUOTA_EXCEEDED`).

  * Mesmo status HTTP e shape do payload (`module`, `remainingTotal`, `periodKey`, `requested`).
  * Falhas de linha no bulk import emitem **`CREATION_CONTRACT_QUOTA_EXCEEDED`**; o código antigo permanece como alias depreciado para `failures.csv` históricos.

  Ver [Códigos de falha de bulk import](/pt/api-reference/bulk-imports/batch-import-failure-codes).
</Update>

<Update label="2026-07-10" description="Unicidade de taxId entre person e company" tags={["API", "Entities"]}>
  ## Unicidade de tax ID (por organização)

  Um **`taxId`** ativo (normalizado alfanumérico) pode pertencer a **apenas uma** entidade por organização, seja `person` ou `company`.

  * **Mesmo tipo** já existe → a criação automática **reutiliza** essa entidade (`alreadyExisted`).
  * **Outro tipo** já possui o tax ID → **`409`** com código **`DUPLICATE_TAX_ID`** (sem nova linha).
  * Aplica-se a create manual, create automatic, PATCH de tax ID e restore de soft-delete.
  * Duplicados históricos não são apagados; writes conflitantes novos são bloqueados na app e via trigger no banco.

  Ver [Criar entidade automaticamente](/pt/api-reference/entities/create-automatic) e [Criar entidade](/pt/api-reference/entities/create).
</Update>

<Update label="2026-07-08" description="Ação addFieldToCustomList em regras" tags={["API", "Rules"]}>
  ## Nova ação de regra: `addFieldToCustomList`

  Regras de **transação**, **pessoa** e **empresa** podem incluir `addFieldToCustomList`. Ao corresponder, o motor extrai um ou mais campos do contexto avaliado e os adiciona a **listas customizadas** do tenant (`type: custom`, ativas, não globais).

  ```json theme={null}
  {
    "type": "addFieldToCustomList",
    "addFieldToCustomList": {
      "mappings": [
        { "fieldPath": "originTaxId", "listId": "uuid-lista-123" },
        { "fieldPath": "metadata.phone", "listId": "uuid-lista-456" }
      ],
      "reason": "Motivo opcional no item"
    }
  }
  ```

  Valores vazios são ignorados; duplicados por `primaryValue` são omitidos. Disponível em `POST`/`PUT` de regras universais e no Rule Builder.
</Update>

<Update label="2026-07-08" description="Bloqueio na criação por listas" tags={["API", "Entities"]}>
  ## Bloqueio na criação (configuração de análise de risco)

  As organizações podem configurar **regras de bloqueio na criação** em **Configurações da organização → Análise de risco**: campo da entidade (ex. `taxId`) contra uma lista custom. Se o valor estiver na lista, **a criação é bloqueada**: a requisição falha com **`422`** e código **`ENTITY_CREATION_LIST_BLOCK`** (`details`: `ruleId`, `listId`, `fieldPath`, `scope`, `matchedValue`). A tentativa bloqueada é registrada no log de auditoria como evidência.

  Aplica-se a **`POST /entities`**, **`POST /entities/automatic`**, importação em massa, upsert (somente criação) e criação automática via eventos SDK. Acionistas/UBO na criação automática quando o escopo da regra incluir; se um acionista for bloqueado, as entidades criadas nessa execução automática são revertidas.
</Update>

<Update label="2026-07-03" description="PATCH /entities/{id}/attributes" tags={["API", "Entities"]}>
  ## Endpoint dedicado para atributos

  **`PATCH /entities/{id}/attributes`** — atualiza apenas atributos personalizados sem alterar outros campos.

  * **`mode: merge`** (padrão) — chaves enviadas sobrescrevem ou criam; omitidas **são mantidas**
  * **`mode: replace`** — `attributes` do body substitui o mapa completo (`{}` limpa tudo)
  * Buckets aninhados por categoria na escrita
  * Dispara webhook **`entity.updated`** e matrizes com trigger **`entity_updated`** quando configurado

  Ver [Atualizar atributos](/pt/api-reference/entities/attributes-update).
</Update>

<Update label="2026-07-03" description="Atributos de entidade: armazenamento literal + categorias" tags={["API", "Entities"]}>
  ## Atributos personalizados armazenados como enviados (API)

  **Aditivo.** Os `attributes` são armazenados **exatamente como enviados** em create/update/upsert/importação automática — o input aninhado não é mais achatado.

  * **Sem categoria:** valores escalares/array na raiz (ex.: `{ "phone": "..." }`) — inalterado.
  * **Categorizado:** um objeto de primeiro nível agrupa suas chaves internas sob essa categoria (ex.: `{ "contact": { "phone": "..." } }`). A chave do objeto *é* a categoria; no dashboard aparece como card de categoria.
  * **Leitura:** `GET` retorna a mesma forma que foi escrita (sem achatar).
  * **Regras / webhooks:** leem a forma armazenada — `attributes.phone` para plano, `attributes.contact.phone` para aninhado. Use chaves de categoria seguras como identificador.

  Ver [Obter entidade](/pt/api-reference/entities/get) e [Atualizar entidade](/pt/api-reference/entities/update).
</Update>

<Update label="2026-07-03" description="API ativação de país por entidade + webhook" tags={["API", "Webhooks", "Entities"]}>
  ## Ativação operacional por país (merchant)

  **Aditivo.** Ativar ou desativar países suportados por entidade sem alterar o perfil da entidade:

  * **`GET /entities/{id}/country-activations`** — lista AR, BR, CL, CO, MX, US; linhas ausentes = `deactivated` (opt-in).
  * **`PATCH /entities/{id}/country-activations/{countryCode}`** — body `{ "status": "deactivated" | "activation_requested" | "activation_in_progress" | "activated" }`; requer `entities:edit`. Transições livres. Idempotente se o status não mudar (sem webhook).
  * **Webhook `entity.country_activation_changed`** — emitido em cada mudança real; inclui `activeCountryCodes`, snapshot `countries` e `timeline` por país; inscrever-se na config de webhooks existente.

  Ver [Listar ativações](/pt/api-reference/entities/country-activations-list), [Atualizar ativação](/pt/api-reference/entities/country-activations-update) e [Eventos webhook de entidade](/pt/webhooks/events/entity-events).
</Update>

<Update label="2026-07-01" description="Bulk import: paridade de política de erros em eventos" tags={["API", "Bulk imports"]}>
  ## Import batch de eventos de usuário — política de erros por linha

  **Aditivo.** Imports CSV de eventos alinham com entidades e transações:

  * **`POST /batch-import/import/user-events`** aceita **`batchErrorHandling`**: `continue_collect_errors` (padrão), `rollback_all` ou `stop_keep_success`.
  * Respostas **`202`** incluem **`preflightFailures`** quando linhas inválidas são ignoradas com política continue.
  * **`POST /batch-import/validate-csv`** valida **cada linha** quando o target é **`user_event`** (`rowErrors`, `validRowCount`, `invalidRowCount`).

  Ver [Importar eventos](/pt/api-reference/bulk-imports/import-user-events) e [Validar CSV](/pt/api-reference/bulk-imports/validate-csv).
</Update>

<Update label="2026-07-01" description="Create regras: revisão IA obrigatória + provenance" tags={["Rules", "API"]}>
  ## `POST /rules` — revisão IA síncrona em toda criação

  * Regras novas ficam sempre em **`in_progress`** com **`enabled: false`**; `status` / `enabled` do body são ignorados no create.
  * A resposta inclui **`aiReview`** e pode levar vários segundos.
  * Body opcional **`creationProvenance`**: origem (`user`, `agent`, `import_json`, `template`, `bundle`, `api`) e ids de chat do agente.
  * A revisão é auditada mas **não debita** tokens de IA.

  Ver [Criar regra](/pt/api-reference/rules/create).
</Update>

<Update label="2026-06-26" description="Webhooks de segurança: campos de contexto de convite" tags={["Webhooks", "Security", "IAM"]}>
  ## `security.member.invited` / `security.member.created` — `payload.context` ampliado

  **Aditivo.** Webhooks do ciclo de convite incluem metadados de correlação e acesso em `payload.context`:

  * `invitationId` — correlacionar `invited` → `created`
  * `granularRoleIds`, `granularRoleIdsSandbox`
  * `includeProduction`, `includeSandbox`
  * `teamId`, `teamIdSandbox`
  * `hasEnvironmentAccess` — flag de acesso para a org do envelope
  * `environment` — `"production"` ou `"sandbox"` conforme a org do envelope
  * `invitedByUserId`, `acceptedVia` (em `created`)
  * `syncPartialFailure`, `syncErrorMessage` (em `created` quando a configuração secundária não concluiu)

  Campos existentes inalterados. Ver [Eventos de webhooks de segurança](/pt/webhooks/events/security-events).
</Update>

<Update label="2026-06-26" description="Batch import: polling de job por jobId" tags={["API", "Bulk imports"]}>
  ## Polling de jobs batch import

  **Aditivo.** Novo endpoint canônico para consultar um job de importação batch sem percorrer o histórico paginado.

  ### Endpoints HTTP

  * `GET /batch-import/jobs/{jobId}` — lookup direto por job id (entidades, transações e user events). Retorna `status`, contadores (`totalItems`, `succeeded`, `failed`, `skipped`), timestamps e `jobFailure` opcional se o job inteiro abortou. Query opcional `include=failures` retorna o mesmo JSON dos endpoints de failures por tipo.
  * `GET /batch-import/unified-history` — novo query param **`jobId`** (correspondência exata; 0 ou 1 linha). O histórico unificado continua para listagens; use `GET /batch-import/jobs/{jobId}` para polling pós-upload.

  ### Fluxo recomendado para integradores

  Upload (`202` + `jobId`) → poll `GET /batch-import/jobs/{jobId}` a cada 2–5 s até status terminal → buscar falhas se necessário.

  Ver [Consultar status do job batch](/pt/api-reference/bulk-imports/get-batch-job-status) e [Histórico unificado](/pt/api-reference/bulk-imports/list-unified-history).
</Update>

<Update label="2026-06-25" description="Inteligência de titulares: exists + accounts-count + metrics" tags={["Marketplace", "API", "Rules"]}>
  ## Inteligência de Titulares CBU/CVU (`ar_gueno_holder_intelligence_service`)

  **Aditivo.** Endpoint de totais renomeado para `accounts-count` (substitui `cbu-count` em desenvolvimento). Retorna `snapshotDate`, `isNew`, `cbuCount`, `cvuCount` e `totalAccounts`.

  ### Endpoints HTTP

  * `GET /api/integration-services/ar_gueno_holder_intelligence_service/health` — disponibilidade e frescor do corpus (`status`, `corpusFreshnessDate`). **Sem cobrança.**
  * `GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/exists` — verificação no corpus. Retorna `found` e `snapshotDate` (`null` se não encontrado). Sempre HTTP `200` em sucesso (incluindo `found: false`). **Sem cobrança.**
  * `GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/accounts-count` — totais CBU/CVU + `isNew` e `snapshotDate`. **Cobrável por request** quando o produto tem preço.
  * `GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/metrics` — lookback densificado (`lookback` 1–180 **ou** preset `window` `w_1d`…`w_180d`). Query opcional `date` (`YYYY-MM-DD`, fim inclusive). Retorna aliases de estoque, deltas, `%`, variância e aceleração. **Cobrável por request** quando o produto tem preço. Erros: `400` `LOOKBACK_REQUIRED` / `INVALID_LOOKBACK` / `INVALID_WINDOW` / `INVALID_DATE`, `404` `CUIT_NOT_FOUND`, `422` `INCOMPLETE_WINDOW` / `NO_INCREMENTAL_STATE`.

  ### Motor de regras

  Novos campos em `services.holder_intelligence.*`: `found`, `snapshot_date`, `cbu_quantity`, `cvu_quantity`, `total_accounts` e `metrics.*` com `holderIntelligenceLookbackDays` (1–180) por condição. Em regras de transação a janela termina em `transactedAt` por padrão. Métricas disparam fetch upstream cobrável separado.

  Ver [Códigos de provedor](/pt/api-reference/integrations/provider-codes) e [Serviços marketplace](/pt/api-reference/services/overview).
</Update>

<Update label="2026-06-26" description="Documentação seção Serviços marketplace" tags={["Docs", "Marketplace", "API"]}>
  ## Documentação Serviços (en / es / pt)

  Nova seção **Serviços** no Mintlify: overview, guia por serviço e uma página por endpoint HTTP para `ar_gueno_holder_intelligence_service`. [Overview](/pt/api-reference/services/overview).
</Update>

<Update label="2026-06-24" description="KYC e biométrico: entityTaxId / entityExternalId" tags={["KYC", "Biometric", "API", "Entities"]}>
  ## Identificadores de entidade além de `entityId`

  **Aditivo — retrocompatível.** Clientes que enviam apenas `entityId` não mudam.

  ### Criação (POST)

  * `POST /api/kyc/validations` — body aceita **`entityId`**, **`entityExternalId`** ou **`entityTaxId`** (exatamente um).
  * `POST /api/kyc/biometric/sessions` — mesmas opções.

  A Gu1 resolve para UUID interno. **`404 NOT_FOUND`** se não houver entidade persistida.

  ### Leitura (GET)

  * `GET /api/kyc/validations?entityTaxId=...` ou `?entityExternalId=...`
  * `GET /api/kyc/biometric/sessions?entityTaxId=...` ou `?entityExternalId=...`
  * KYC: `GET /api/kyc/entities/by-tax-id/:taxId/current|validations|status` e rotas `by-external-id`
  * Biométrico: `GET /api/kyc/biometric/entities/by-tax-id/:taxId/current` e `by-external-id`

  ### Prévia sandbox (somente GET)

  * `GET /api/entities/by-tax-id/{taxId}` e `GET /api/entities?taxId=...` podem retornar dados sintéticos **`sandboxMock: true`** (`id: null`) para números do catálogo sem linha real. **Não** habilita POST sem criar entidade real.

  Ver [Criar validação KYC](/pt/use-cases/kyc/create-validation), [Sessão biométrica incorporada](/pt/use-cases/kyc/embedded-biometric) e [Dados mock sandbox](/pt/use-cases/kyc/sandbox-mock-data).
</Update>

<Update label="2026-06-23" description="KYC e biométrico: IDs bloqueantes no 409" tags={["KYC", "Biometric", "API"]}>
  ## Respostas 409 aditivas para sessões / validações abertas

  **Sem breaking change** para clientes que leem apenas `error` e `message`. Campos opcionais novos em códigos `409` existentes:

  ### Biometria incorporada — `POST /api/kyc/biometric/sessions`

  * Com a última sessão em `pending` ou `in_progress`, o create **sempre** retorna **`409 ACTIVE_SESSION_EXISTS`** (nunca `201` com a mesma sessão pending).
  * O body inclui **`activeSessionId`** para cancelar: `POST .../sessions/{activeSessionId}/cancel`.

  ### Validação KYC — `POST /api/kyc/validations`

  * Com validação aberta (`pending`, `in_progress`, `in_review`), o create retorna **`409 VALIDATION_IN_PROGRESS`**.
  * O body agora também inclui **`activeValidationId`** para cancelar: `DELETE .../validations/{activeValidationId}/cancel`.

  Ver [Criar validação KYC](/pt/use-cases/kyc/create-validation) e [Sessão biométrica incorporada](/pt/use-cases/kyc/embedded-biometric).
</Update>

<Update label="2026-06-20" description="GET transação: rulesExecutionSummary opcional em persisted" tags={["API", "Transactions", "Rules"]}>
  ## `includeRulesSummary` no GET de uma transação

  `GET /transactions/{id}` e `GET /transactions/external/{externalId}` aceitam um query param opcional:

  * **`includeRulesSummary=full`** — Adiciona **`persisted.rulesExecutionSummary`** da linha **mais recente** de `risk_analysis_audits` dessa transação. Regras **não** são reexecutadas na leitura.

  **Padrão (sem param):** resposta inalterada — sem `rulesExecutionSummary` na leitura. Use `full` apenas em telas de detalhe ou debugging, não em polling em volume de listagens.

  Ver [Obter transação](/pt/api-reference/transactions/get) e [Resumo de execução de regras](/pt/api-reference/rules-execution-summary).
</Update>

<Update label="2026-06-19" description="Resumo de regras: status entidade origem/destino" tags={["API", "Rules", "Transactions"]}>
  ## Campos opcionais em `rulesExecutionSummary`

  Quando regras transacionais usam `updateEntityStatus` com status de entidade origem ou destino, a API pode incluir estes campos **opcionais** (aditivos; clientes existentes sem alteração):

  * **`rulesHit[].actions.originEntityStatus`** / **`destinationEntityStatus`** — configurados na regra que deu match.
  * **`actionsExecuted.originEntityStatus`** / **`destinationEntityStatus`** — status finais de entidade aplicados na execução (junto com **`actionsExecuted.status`** para a transação).

  Snapshots de regras na auditoria passam a reter a lista completa de ações configuradas (inclui mudança de status diferida) para UI e integradores.

  Ver [Resumo de execução de regras](/pt/api-reference/rules-execution-summary).
</Update>

<Update label="2026-06-19" description="Webhooks security: membro unificado + ambientes" tags={["Webhooks", "Security", "IAM"]}>
  ## Eventos `security.member.*` (nomenclatura unificada)

  Todos os eventos de IAM sobre pessoas usam o prefixo **`security.member.*`** (não mais `security.user.*`, `security.team.*` nem `security.channel.*`):

  * **Perfil / senha:** `security.member.profile_updated`, `.password_reset`, `.password_generated`
  * **Equipes:** `security.member.team_added`, `.team_removed`, `.team_role_changed`
  * **Canais (org filha):** `security.member.channel_granted`, `.channel_revoked`
  * **Acesso a ambientes (production / sandbox):** `security.member.environment_granted`, `.environment_revoked` — distinguidos por `context.environment` (`"production"` | `"sandbox"`)

  Mudanças de membership em equipes não emitem mais `security.role.assigned` / `security.role.updated` ambíguos.

  **Breaking:** se você assinou `security.user.password_*` ou outros keys antigos, migre para os equivalentes `security.member.*`.

  Ver [Eventos webhook de segurança](/pt/webhooks/events/security-events).
</Update>

<Update label="2026-06-19" description="Endpoint sessão biométrica atual" tags={["KYC", "Biometric", "API"]}>
  ## `GET /api/kyc/biometric/entities/:entityId/current`

  Alinhado ao KYC `GET /api/kyc/entities/:entityId/current`:

  * Retorna a **última sessão biométrica** da entidade (por `createdAt`), **qualquer status** (`pending`, `in_progress`, `approved`, `rejected`, …).
  * **`200` com `null`** quando a entidade não tem sessões biométricas (não mais `404`).
  * Na listagem, `currentSessionId` continua sendo apenas a última sessão **`approved`**.

  O **`409 ACTIVE_SESSION_EXISTS`** ao criar inclui **`activeSessionId`** para cancelar a sessão bloqueante sem consulta extra.

  Ver [Sessão biométrica atual](/pt/use-cases/kyc/current-biometric-session).
</Update>

<Update label="2026-06-18" description="Eventos webhook de Segurança e IAM" tags={["Webhooks", "Security", "IAM"]}>
  ## Eventos webhook de segurança (`security.*`)

  Nova categoria outbound para monitoramento **Segurança / IAM** (integrações SIEM). Inscreva-se em **Webhooks → Configuração** em eventos como:

  * **Auth:** `security.auth.login_succeeded`, `security.auth.logout`, `security.auth.login_failed`
  * **Membros:** `security.member.invited`, `.created`, `.removed`, `.activated`, `.deactivated`
  * **Perfis:** `security.role.created`, `.updated`, `.deleted`, `.assigned`, `.revoked`
  * **RBAC:** `security.rbac.granular_toggled`
  * **Senha (admin):** `security.member.password_reset`, `security.member.password_generated` (antes `security.user.password_*`)
  * **Settings:** `security.settings.updated` (sandbox, configurações de segurança auditadas)

  O payload inclui `actionAt`, `actor`, `affectedUser`, `description`, `changes` (anterior/atual) e `context` (IP, user agent, scope).

  **Não coberto:** alteração de senha self-service no Clerk, MFA/SSO no Clerk, auth por API key.

  Ver [Eventos webhook de segurança](/pt/webhooks/events/security-events).
</Update>

<Update label="2026-06-18" description="watchFields em matrizes + entity_updated no runtime" tags={["Risk matrices", "Entities", "Transactions", "API"]}>
  ## Triggers granulares de matriz (`watchFields`)

  Triggers **`entity_updated`** (entidades e transação atualizada em KYT) aceitam **`watchFields`** opcional: paths do motor (ex. `email`, `phone`, `attributes.clientTypes`, `metadata.email`). Vazio ou ausente = qualquer mudança dispara a matriz (retrocompatível). Com valores, a matriz roda só se pelo menos um path listado mudou.

  Configure no editor de matrizes (aba Triggers) ou em `risk_matrices.triggers[]` via API.

  ## Atualização de entidade — `entity_updated` ativo

  `PATCH /entities/{id}` (e por external ID / tax ID) executa matrizes atribuídas com trigger **`entity_updated`**, salvo `skipRulesExecution: true`. O webhook `entity.updated` inclui `rulesExecutionSummary`. Ver [Atualizar entidade](/pt/api-reference/entities/update).

  `PATCH` de transação com `executeRules=true` repassa paths alterados ao mesmo filtro.
</Update>

<Update label="2026-06-17" description="Import bulk entidades — política de enrichments nos filhos" tags={["Entities", "Bulk import", "API"]}>
  ## Import bulk automático — enrichments nos filhos e escopo de monitoramento

  **`POST /batch-import/import/entities`** e bulk JSON aceitam (modo automático, `depth` > 0):

  * **`childEnrichmentPolicy`**: `all_active` (padrão), `by_root_type` ou `basic_only`.
    * **`by_root_type`**: linhas empresa → acionistas com todos os enrichments ativos **exceto** `global_gueno_sanctions_enrichment`; linhas pessoa → relacionadas só com **dados básicos** do provedor da raiz.
  * **`monitoringApplyToRelationships`**: com `false`, `monitoring` só nas entidades principais. Padrão `true` com `depth` > 0 se omitido.

  A UI de importação em massa expõe os mesmos controles. Ver [Importar entidades (bulk)](/pt/api-reference/bulk-imports/import-entities#enrichments-nos-filhos-e-monitoramento).
</Update>

<Update label="2026-06-16" description="Eventos pré-login do SDK e remote config" tags={["Events", "SDK", "API"]}>
  ## Eventos — campos de sessão do SDK e pré-login

  `POST /events/user` agora aceita dois campos opcionais: **`sessionId`** (id de sessão do SDK, `sess_...`) e **`sdkSignals`** (sinais estruturados do SDK — flags de integridade e comportamento, separados do `metadata`). Ambos são persistidos no evento. **Omiti-los mantém o comportamento anterior byte a byte.**

  Para organizações com o SDK habilitado, um evento que traz **apenas um `sessionId`** (sem `entityId`/`entityExternalId`/`taxId`) agora é aceito e armazenado como **evento anônimo pré-login** em vez de retornar erro; é vinculado à entidade depois, no primeiro evento que trouxer `sessionId` e um identificador de entidade juntos. Sem o SDK habilitado, um identificador de entidade continua obrigatório (mesma resposta de antes).

  ## Eventos — novos tipos

  Foram adicionados três tipos de evento do SDK: **`SESSION_STARTED`**, **`SESSION_IDENTIFIED`**, **`SCREEN_VIEW`**. Clientes existentes não são afetados.

  ## Novo endpoint — `GET /sdk/config`

  Retorna o remote config do SDK (toggles de sinais + defaults de transporte) mais a flag `sdkEnabled` da organização.

  Veja [Criar Evento de Usuário](/pt/api-reference/events/create).
</Update>

<Update label="2026-06-15" description="Erros de enrichment e validação de tax ID" tags={["Enrichment", "Entities", "API"]}>
  ## Enrichment marketplace — erros estruturados

  `POST /integration-execution/marketplace/enrichment` retorna objetos `error` mais ricos: `category`, `retryable` e `statusCode` opcionais.

  ## Criação automática / bulk — tax ID estrito

  `taxId` deve ser apenas o identificador fiscal; valores fusionados com colunas extras são rejeitados com `INVALID_TAX_ID`.

  ## Transações — `exchangeRate` opcional (fallback)

  `POST /transactions` e batch aceitam **`exchangeRate` opcional** por transação. **Sem este campo, o comportamento permanece o mesmo** (conversão automática).

  Usado **somente** quando a conversão automática falha. Semântica: unidades da moeda base por 1 unidade de `currency`; valor normalizado na base = `amount × exchangeRate`. `rateSource: client-provided`.

  **Não conversíveis hoje (sem taxa automática):** `WLD` (Worldcoin), `ETH` (Ethereum). Envie `exchangeRate` para valor normalizado na moeda base e regras que dependem de conversão.

  Ver [Criar transação — Conversão de moeda](/pt/api-reference/transactions/create#conversão-de-moeda).
</Update>

<Update label="2026-06-11" description="Entidades — refresh scope e preserve" tags={["Entities", "Enrichment", "API", "Docs"]}>
  ## `POST /entities/{entityId}/refresh` — escopo unificado e sync seguro

  Novos campos opcionais (retrocompatíveis quando omitidos):

  * **`refreshScope`**: `basic_data` | `all_active` | `selected` (+ `providerCodes` se `selected`).
  * **`preserveName`**: `true` mantém o nome; omitido = sync legacy de `fullName` normalizado.
  * **`preserveEntityData`**: apenas com `refreshScope: "basic_data"` — `true` preenche vazios em `entityData`, `false` substitui; omitido = não alterar ficha.

  `basic_data` sempre só na entidade raiz (sem sócios), independente de `depth`.

  Ver [Atualizar entidade](/pt/api-reference/entities/refresh). Payloads existentes sem esses campos mantêm o comportamento anterior.
</Update>

<Update label="2026-06-11" description="KYC — aviso duplicado cross-entity" tags={["KYC", "API", "Docs"]}>
  ## Aviso `GUENO_CROSS_ENTITY_DUPLICATED`

  Quando Gu1 resolve referências duplicadas do provedor em **outra entidade** da mesma organização (`metadata.kycCrossEntityDuplicates.matches`):

  * Adiciona **`GUENO_CROSS_ENTITY_DUPLICATED`** a `warnings` da validação por sessão.
  * Se o provedor mapeou **`approved`**, Gu1 define o status como **`in_review`** (`metadata.guenoCrossEntityDuplicateEscalation`).
  * **Não omitível:** não pode constar em `omitWarnings` (400) e bloqueia autoaprovação por omit.

  Ver [Códigos de aviso KYC](/pt/use-cases/kyc/warning-risk-codes) e [`omitWarnings`](/pt/use-cases/kyc/create-validation).
</Update>

<Update label="2026-06-11" description="KYC — Gu1 Biometria" tags={["KYC", "API", "Webhooks", "Docs"]}>
  ## Gu1 Biometria (`POST /api/kyc/biometric` e `/api/kyc/biometric/sessions`)

  Reautenticação após KYC aprovado: verificação por imagem ou sessão com **UI hospedada** (`sessionUrl`, `iframeAllow`, `hostedSessionId`, `webhookUrl` opcional, webhooks `biometric.session_*`, veredito **Gu1** com `rejectionCode`). Produto `global_gueno_biometric_kyc`. Ver [Verificação biométrica](/pt/use-cases/kyc/biometric) e [Sessão biométrica](/pt/use-cases/kyc/embedded-biometric).
</Update>

<Update label="2026-06-10" description="KYC — decision com forma dual array/objeto" tags={["KYC", "API", "Webhooks", "Docs"]}>
  ## `decision` sempre inclui pares array + objeto por feature

  Ao persistir (sync, webhook, ingest manual), o Gu1 **normaliza** `decision` para integradores lerem chaves singulares legacy ou arrays de forma intercambiável:

  * `id_verification` ↔ `id_verifications[0]`
  * `liveness` ↔ `liveness_checks[0]`
  * `face_match` ↔ `face_matches[0]`
  * `aml_screening` ↔ `aml_screenings[0]`
  * `ip_analysis` ↔ `ip_analyses[0]`

  Quando ambas as formas existiam, **`array[0]` prevalece** e o objeto singular é sincronizado. Vale para GET de validação e webhooks KYC (`payload.decision`).

  Exemplos Mintlify atualizados com `decision` **completo** (sem branding de vendor; mídia como chaves `kyc/...`). Ver [Eventos webhook KYC](/pt/webhooks/events/kyc-events#objeto-decision-payloaddecision).
</Update>

<Update label="2026-06-10" description="Matriz de risco — rulesEngineConfig no analyze" tags={["Entities", "Risk Matrix", "API", "Docs"]}>
  ## Config do motor em `POST /entities/{entityId}/analyze`

  Novo objeto opcional **`rulesEngineConfig`**: **`partialCoverage`** e **`omitCoverage`** (defaults `false`).

  Ver [Analisar entidade](/pt/api-reference/entities/analyze).
</Update>

<Update label="2026-06-09" description="KYC — extractedData.ejemplar (DNI argentino)" tags={["KYC", "API", "Docs"]}>
  ## `ejemplar` em extractedData

  Verificações de DNI argentino podem incluir **`extractedData.ejemplar`** (`A`–`D`) em validações KYC e registos de ID Verification (GET, sync, webhooks).

  Com **`doubleCheckRenaper: true`**, **`comparisonResults.ejemplar`** compara OCR vs RENAPER; mismatch adiciona **`RENAPER_EJEMPLAR_NOT_MATCH`** a **`warnings`**.

  Ver [campos de extractedData](/pt/use-cases/kyc/id-verification#campos-de-extracteddata) e [dupla verificação RENAPER](/pt/use-cases/kyc/create-validation#dupla-verificação-renaper-argentina).
</Update>

<Update label="2026-06-05" description="KYC — fluxo RENAPER e revisão manual" tags={["KYC", "API", "Docs"]}>
  ## Dupla verificação RENAPER em validações KYC

  Com `doubleCheckRenaper: true`, `metadata.responseDoubleChecks.renaper` inclui **`comparisonResults`**, **`renaperBiometric`** (quando aplicável) e códigos RENAPER em **`warnings`** (ex.: `RENAPER_TRAMITE_ID_NOT_MATCH`, `RENAPER_EXPIRY_NOT_MATCH`) **sem substituir** avisos da verificação OCR KYC.

  **Enforce (rejeição automática):** somente se a verificação OCR KYC retornar o estado **`approved`**. Em **`in_review`** e **`rejected`** o chequeo é informativo e grava dados em metadata. **`POST /api/kyc/validations/{id}/approve`** a partir de `in_review` **não** reexecuta RENAPER.

  Ver [Criar validação KYC](/pt/use-cases/kyc/create-validation#quando-o-renaper-aplica-enforce-rejeição-automática) e [Aprovar validação](/pt/use-cases/kyc/approve-validation).
</Update>

<Update label="2026-06-04" description="Marketplace — checks removidos, só enrichments" tags={["Entities", "Enrichment", "API", "Docs"]}>
  ## Produto marketplace `*_check` removido

  * **Removido:** códigos `*_check`, `POST /integration-execution/marketplace/check`, triggers/ações de regras `check_completed` / `execute_check`, e permissões RBAC `checks:read` / `checks:execute`.
  * **Use em vez disso:** o `*_enrichment` correspondente com [Executar enrichment](/pt/api-reference/enrichment/execute-by-id).
  * **Compat legacy:** payloads de create/import com `checks`, `executeAllActiveChecks` ou `*_check` em `autoExecuteIntegrations.enrichments` são **ignorados no parse**.

  Ver [Códigos de provedores](/pt/api-reference/integrations/provider-codes), [Criar entidade](/pt/api-reference/entities/create) e [Criar automaticamente](/pt/api-reference/entities/create-automatic).
</Update>

<Update label="2026-06-04" description="Bulk imports — códigos de falha + JSON" tags={["Bulk imports", "API", "Docs"]}>
  ## Códigos estáveis e endpoints JSON de falhas batch

  * Falhas por linha com **`code`** + **`message`** — [Catálogo](/pt/api-reference/bulk-imports/batch-import-failure-codes). CSV inclui coluna `code`.
  * **JSON:** `GET /batch-import/transaction-jobs/{jobId}/failures`, `GET /batch-import/user-event-jobs/{jobId}/failures`, `GET /batch-import/entity-jobs/{jobId}/failures` — incluem `failures[]`, `jobFailure` opcional, `skips[]` em entidades, `truncated` / `failuresTotal` (máx. 500).
  * **CSV:** mesmas rotas com sufixo `.csv` para download direto.
</Update>

<Update label="2026-06-04" description="Entidades — PATCH riskMatrixIds" tags={["Entities", "API", "Docs"]}>
  ## Atribuir matrizes de risco na atualização de entidade

  * **`PATCH /entities/{id}`** (e **`PATCH /entities/by-external-id/{externalId}`**, **`PATCH /entities/by-tax-id/{taxId}`**): documentados **`riskMatrixIds`** (`string[]`) e **`riskMatrixId`** (`string | string[] | null`) — mesma normalização do create. Apenas atribui matrizes; **não** executa o motor de regras (usar [Analisar entidade](/en/api-reference/entities/analyze) ou triggers de ciclo de vida).
  * Mintlify atualizado em `/en/`, `/es/`, `/pt/` em [Atualizar entidade](/pt/api-reference/entities/update) e [Atualizar por ID externo](/pt/api-reference/entities/update-by-external-id).
</Update>

<Update label="2026-06-03" description="Transações — configRulesExecution.notifications" tags={["Transactions", "Rules", "API", "Docs"]}>
  ## `configRulesExecution` na criação de transação

  * **`POST /transactions`**: objeto opcional no body **`configRulesExecution`** com **`notifications`** (`boolean`). Com `false`, a gu1 não envia **notificações in-app** da avaliação de regras (matriz / status). Ações **`createAlert`** e investigações permanecem iguais.
  * **Padrão:** omitir o objeto mantém o comportamento anterior na maioria das orgs (`notifications` efetivamente `true`). **Paytime prod** (`3bc1f621-27d4-423e-9d64-86680bec2388`) usa **`notifications: false`** por padrão.
  * **Legacy KYT** `POST /legacy/kyt/verifyTransaction`: mesmo campo no body Gu2; Paytime prod **`notifications: false`** por padrão se omitido.
  * Vale para regras **sync e async** (`asyncRules`).

  Ver [Criar transação](/pt/api-reference/transactions/create). Paridade em `/en/` e `/es/`.
</Update>

<Update label="2026-06-02" description="Transações — denormalização canônica ao vincular entidade" tags={["Transactions", "API", "Docs"]}>
  ## `POST /transactions` e lote — campos de contraparte vinculados

  Quando origem ou destino fica **vinculado** a pessoa/empresa (`originEntityId` / auto-link por external ou tax id), a gu1 **sempre sobrescreve** as colunas denormalizadas a partir da entidade antes do insert:

  * `originTaxId` / `destinationTaxId` ← `entities.tax_id`
  * `originExternalId` / `destinationExternalId` ← `entities.external_id`

  Valores enviados pelo cliente nesses campos **não são mantidos** se diferirem da entidade vinculada. Alinha regras transacionais com eventos de usuário nos mesmos identificadores.

  Documentado em [Criar transação](/pt/api-reference/transactions/create#origem-entidade) e [Criar lote](/pt/api-reference/transactions/create-batch).
</Update>

<Update label="2026-06-02" description="Eventos de usuário — prioridade isNewDevice do cliente" tags={["Events", "API", "Docs"]}>
  ## `POST /events/user` — `isNewDevice` respeita o valor do integrador

  * Se você enviar **`isNewDevice: true` ou `false`**, a gu1 **persiste exatamente esse valor** (sem sobrescrita no servidor).
  * Se **omitir** o campo, a gu1 infere quando há **`deviceId` + `deviceDetails`** (registro de dispositivos; `true` se o device for novo ou `firstSeenAt` estiver nos últimos **5 minutos**); caso contrário **`false`**.

  Documentado em [Criar evento de usuário](/pt/api-reference/events/create#como-funciona-o-isnewdevice) e [Overview de eventos](/pt/api-reference/events/overview).
</Update>

<Update label="2026-06-01" description="Import entidades — dot notation attributes / entityData" tags={["Entities", "Bulk import", "API"]}>
  ## CSV plataforma: `attributes.*` e `entityData.*`

  * Cabeçalhos com ponto (como transações nativas): `attributes.segment_tag`, `entityData.income`, `entityData.tradeName`.
  * **`entityData.<campo>`** sem `person`/`company` → bucket conforme **`type`** da linha.
  * Colunas sem prefixo permanecem em `attributes` (retrocompat).
  * Ver [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-06-01" description="Importações em lote — limites e manual vs automático" tags={["Bulk import", "API", "Docs"]}>
  ## Limites documentados (en / es / pt)

  * [Importações em lote — overview](/pt/api-reference/bulk-imports/overview): matriz de **arquivos por request**, **linhas por plano** e **manual vs automático** em entidades.
  * Páginas por endpoint com limites (entidades CSV, transações, eventos).
  * Consulta limites em runtime: `GET /individual-organization/batch-upload-enabled`.
</Update>

<Update label="2026-06-01" description="Import entidades — países por modo" tags={["Entities", "Bulk import", "API"]}>
  ## Países na importação bulk (manual vs automático)

  * **Manual** (`manual`): qualquer **ISO2 válido** da plataforma (lote ou `country_code` / `country` por linha). Sem pipeline Nosis/CPF.
  * **Automático** (`automatic`): **AR**, **BR** e **CL** (dados básicos por tax ID, incl. enrichments Chile: ruts.info / BaseAPI).
  * Vale para **`POST /batch-import/import/entities`** (CSV plataforma e CSV custom com `mappingId`).

  Ver [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-06-01" description="Import entidades — manual multipart alinhado" tags={["Entities", "Bulk import", "API"]}>
  ## `POST /batch-import/import/entities` — enrichments no manual

  * Modo **manual** multipart alinhado ao hub **Manual**: **`autoExecuteIntegrations`**, **`monitoring`** e matrizes opcionais — **sem** pipeline Nosis/CPF.
  * Só CSV (sem enrichments explícitos) → entidade mínima, sem enrichments.
  * Colunas CSV de enrichment por linha aplicam no manual; **`depth`** só no automático.

  Ver [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-06-01" description="Import entidades — padrão manual na API" tags={["Entities", "Bulk import", "API"]}>
  ## `POST /batch-import/import/entities` — padrão manual

  * Sem **`entityImportMode`** → **`manual`** (entidade mínima; enrichments só se pedidos).
  * **Automático** com **`entityImportMode=automatic`**. Resposta **`202`** inclui **`importMode`**.

  Ver [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-06-01" description="Import entidades — CSV plataforma sem mappingId" tags={["Entities", "Bulk import", "API"]}>
  ## `POST /batch-import/import/entities` — formato plataforma

  * **`mappingId` passa a ser opcional** quando o CSV usa cabeçalhos canônicos do hub (`tax_id`, `type`, `country_code`, … — template automático/manual).
  * **Sem mudança** para layouts custom: colunas arbitrárias ainda exigem **`mappingId`** (mapeamento salvo).
  * CSV **simples** (`tax_id` + `type` apenas): envie **`country`** (ISO2, ex. `AR`) no form multipart como padrão do lote.
  * Paridade com transações: formato nativo → sem mapeamento; colunas custom → com mapeamento.

  Ver [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities).
</Update>

<Update label="2026-06-01" description="Avaliação assíncrona de regras no create" tags={["Transactions", "Rules", "API"]}>
  ## `asyncRules` ao criar transação

  * **`POST /transactions`**: flag opcional **`asyncRules`** em query ou body (padrão **`false`**). Com `true` e `executeRules` diferente de `false`, a transação é criada na mesma request mas as regras rodam **em background** via fila de jobs. A resposta HTTP retorna na hora com `rulesHit` / `rulesNoHit` vazios, mais **`asyncRules: true`** e **`rulesEvaluationStatus: "queued"`**.
  * **Padrão inalterado:** omitir `asyncRules` mantém execução **síncrona** e `rulesExecutionSummary` completo — clientes existentes continuam iguais.
  * **Legacy KYT** `POST /legacy/kyt/verifyTransaction`: mesmo flag via query ou campo no body Gu2. **Paytime prod** (`3bc1f621-27d4-423e-9d64-86680bec2388`) usa async por padrão se omitirem o flag; `asyncRules=false` força sync numa request.
  * **Não vale para batch.** Se Redis/fila indisponível, pode retornar **503** `ASYNC_RULES_QUEUE_UNAVAILABLE` (a transação pode já existir — conferir o body antes de reenviar).

  Ver [Criar transação](/pt/api-reference/transactions/create).
</Update>

<Update label="2026-05-29" description="Face Match e ID Verification — dupla verificação RENAPER" tags={["KYC", "API"]}>
  ## Dupla verificação RENAPER em endpoints KYC standalone

  * **`POST /api/kyc/face-match`**: `doubleCheckRenaper` opcional (body ou query). Após face match aprovado: RENAPER **biométrico** + **dados**. Requer `documentNumber`, `gender`, `personalNumber` (fallback de entidade para DNI/gênero). Resposta com `responseDoubleChecks`.
  * **`POST /api/kyc/id-verification`**: mesmo flag; após OCR approved apenas chequeo **dados** RENAPER. Falha → `declined` + códigos em `warnings`.
  * Credenciais RENAPER da org (igual ao KYC por sessão). Timeout HTTP ≥ 60 s no face-match com double-check.

  Ver [Face Match](/pt/use-cases/kyc/face-match) e [ID Verification](/pt/use-cases/kyc/id-verification).
</Update>

<Update label="2026-05-29" description="Trigger status-change em regras KYT" tags={["Transactions", "Rules", "API"]}>
  ## KYT — triggers separados: mudança de status vs atualização de campos

  * **`PATCH …/changeStatus`** executa regras/matrizes com trigger **`status_changed`** (`trigger_transaction_status_changed`), não `updated`.
  * **`PATCH /transactions/{id}`** com `executeRules=true` continua usando **`updated`** (`trigger_transaction_updated`) para alterações de **metadata**, **deviceDetails**, **channel** ou **reason**.
  * **Migração:** reconfigurar regras que rodavam na mudança de status para o novo trigger (Rule Builder: *Mudança de status*; matrizes: `transaction_status_changed`).

  Ver [Alterar status](/pt/use-cases/transaction-monitoring/change-status-api) e [Atualizar transação](/pt/api-reference/transactions/update).
</Update>

<Update label="2026-05-29" description="PATCH transação — metadata, deviceDetails, channel, reason" tags={["Transactions", "API"]}>
  ## Atualização parcial de transação

  * **`PATCH /transactions/{id}`** e **`PATCH /transactions/external/{externalId}`**: atualizar **`metadata`** (merge superficial), **`deviceDetails`** (merge superficial em `device_details`), **`channel`** (nullable) e/ou **`reason`** (enum). Requer `transactions:edit`.
  * Query **`executeRules=true`** reexecuta regras KYT com trigger **`updated`** — não regras de mudança de status.
  * Auditoria `transaction_updated` e webhook `transaction.updated` com mapa `changes` (inclui `deviceDetails` quando aplicável).

  Ver [Atualizar transação](/pt/api-reference/transactions/update).
</Update>

<Update label="2026-05-29" description="Tem eventos? — identificadores por query" tags={["Events", "API"]}>
  ## Eventos de usuário — has-events por external ID ou tax ID

  * **`GET /events/user/entity/has-events`** (novo): verificação sim/não sem UUID interno. Query params: `entity_id`, `entity_external_id` ou `tax_id` (pelo menos um obrigatório). Prioridade: `entity_id` → `entity_external_id` → `tax_id`; tax ID com normalização (caracteres não alfanuméricos removidos).
  * A resposta inclui **`entityId`** resolvido para chamar [Listar por entidade](/pt/api-reference/events/list-by-entity) quando `hasEvents` for true.
  * **`GET /events/user/entity/{entityId}/has-events`** continua suportado (contrato inalterado).

  Ver [Tem eventos? (por entidade)](/pt/api-reference/events/has-events-by-entity).
</Update>

<Update label="2026-05-28" description="Códigos de aviso IP analysis KYC" tags={["KYC", "API"]}>
  ## KYC por sessão — avisos de análise de dispositivo e IP

  * **`GET /api/kyc/validations/:id`** (e rotas de sync/webhook): o array **`warnings`** agora funde códigos **`risk`** de **`decision.ip_analyses[].warnings[]`** (e legacy `decision.ip_analysis.warnings`), além de verificação de documento, liveness, face match e AML.
  * Oito códigos do provedor (ex.: `PRIVATE_NETWORK_DETECTED`, `DUPLICATED_DEVICE_FINGERPRINT`, `IP_ADDRESS_IN_BLOCKLIST`). Ver [Códigos de aviso KYC — Análise de dispositivo e IP](/pt/use-cases/kyc/warning-risk-codes#análise-de-dispositivo-e-ip-kyc-por-sessão).
  * Os mesmos códigos são válidos em **`omitWarnings`** em [`POST /api/kyc/validations`](/pt/use-cases/kyc/create-validation) ao autoaprovar sessões em `in_review`.

  **Nota para integradores:** validações existentes mantêm o `warnings` armazenado até o próximo sync; consulte novamente ou sincronize para preencher códigos de IP analysis em linhas antigas.
</Update>

<Update label="2026-05-26" description="ID Verification — extractedData ampliado" tags={["KYC", "API"]}>
  ## ID Verification — `extractedData` mais completo

  * **`POST /api/kyc/id-verification`** e auditoria list/get passam a persistir e devolver um `extractedData` mais amplo: identidade (`personalNumber`, `taxNumber`, `placeOfBirth`, …), `providerStatus`, `warningMeta` (ex.: sessão duplicada), pontuações de qualidade, `extraFields`, `mrz`, `parsedAddress`, `barcodes` quando o serviço ID Verification da Gu1 os devolve.
  * **`warnings`** continua como array de códigos de risco para i18n; metadados estruturados de duplicado ficam em `warningMeta` dentro de `extractedData`.
  * URLs externas de imagem e base64 **não** são devolvidas; imagens enviadas estão em [imagens ID Verification](/pt/use-cases/kyc/id-verification-images).
  * **`debugProviderResponse`** apenas em ambientes não produtivos da API Gu1 (payload de verificação sanitizado, sem imagens).

  Ver [ID Verification](/pt/use-cases/kyc/id-verification#campos-de-extracteddata).
</Update>

<Update label="2026-05-26" description="operationalHours em entidades + regras KYT" tags={["Entidades", "Transações", "Regras", "API"]}>
  ## Horário operativo por entidade (global)

  * **Entidades:** campo opcional na raiz `operationalHours` (`timezone` enum + `weekly`). Coluna `entities.operational_hours`. Ver [Criar entidade](/pt/api-reference/entities/create).
  * **Transações:** enum `transaction_time_zone` ampliado (fusos do Brasil). `timeZone` independente de `operationalHours`. **`transactedAt`:** gravado em UTC; ISO com `Z` inalterado para clientes atuais; datetime local + `timeZone` opcional converte para UTC.
  * **Regras:** operadores `outside_entity_operational_hours` e `inside_entity_operational_hours` em `transactedAt` (`value`: `origin` | `destination`).

  Ver [Criar transação](/pt/api-reference/transactions/create).
</Update>

<Update label="2026-05-22" description="timeZone opcional em transações" tags={["Transações", "API", "Banco de dados"]}>
  ## `timeZone` em transações

  * **Banco de dados:** Nova coluna nullable `time_zone` em `transactions` com enum `transaction_time_zone` (valores IANA como `America/Argentina/Buenos_Aires`, `UTC`, etc.). Registros existentes permanecem `null`.
  * **API:** `timeZone` opcional em `POST /transactions` e criação em lote; retornado em `GET /transactions/{id}` e `GET /transactions/external/{externalId}` como `string | null`.

  Ver [Enum fuso horário](/pt/api-reference/transactions/time-zone-enum) e [Criar transação](/pt/api-reference/transactions/create).
</Update>

<Update label="2026-05-21" description="validateExistingEntity em transações" tags={["Transações", "API", "Legacy"]}>
  ## `validateExistingEntity` (criação de transações)

  * **`POST /transactions`**: campo opcional `validateExistingEntity` (padrão **`false`**). Com `true`, cada identificador de origem/destino enviado deve existir na org; senão **400** `INVALID_ENTITY_REFERENCES` e a linha não é criada.
  * **Lote** (`POST /transactions/batch`, upload, JSON): padrão continua **`true`**. Import permissivo: `validateExistingEntity: false`.
  * **Legacy KYT** `POST /legacy/kyt/verifyTransaction`: mesmo campo no body Gu2.

  Ver [Criar transação](/pt/api-reference/transactions/create) e [Criar transações em lote](/pt/api-reference/transactions/create-batch).
</Update>

<Update label="2026-05-21" description="Auto-execução na criação de entidades" tags={["Entidades", "API", "Enriquecimento"]}>
  ## `excludeEnrichments` na criação de entidades

  `autoExecuteIntegrations` e `autoExecuteIntegrationsShareholders` aceitam **`excludeEnrichments`**: códigos de provedor excluídos do conjunto final de enriquecimentos (inclusive com `executeAllActiveEnrichments: true`).

  **`executeAllActiveChecks` e `checks` não fazem mais parte do contrato público** desses objetos; payloads legados que os enviem são ignorados no parse.

  Ver [Criar entidade (automática)](/pt/api-reference/entities/create-automatic).
</Update>

<Update label="2025-01-27" description="v1.3.0 - Documentação Página de Onboarding Hospedada" tags={["KYC", "Página Hospedada", "Documentação"]}>
  ## Novo: Documentação da Página de Onboarding Hospedada

  Documentação completa para a Página de Onboarding Hospedada - a maneira mais rápida de implementar verificação KYC sem código.

  ### Novidades

  **Documentação da Página Hospedada:**

  * ✅ Guia completo de parâmetros de personalização (branding, cores, layout)
  * ✅ Configuração de regras de validação (verificação de idade, métodos de captura, detecção de duplicados)
  * ✅ Regras de validação de documentos (QR/código de barras, MRZ, datas de validade, vivacidade)
  * ✅ Guia de integração passo a passo com exemplos de código
  * ✅ Diagrama de fluxo visual mostrando o processo completo
  * ✅ Melhores práticas de segurança para gerenciamento de sessões
  * ✅ Confirmação de design mobile-responsive

  **Recursos Principais:**

  * 📱 Design mobile-responsive para todos os dispositivos
  * 🎨 Personalização completa de cores, branding e layout
  * 🔒 Diretrizes de segurança abrangentes
  * 📊 Diagramas de sequência visuais para clareza
  * 🌐 Informações de canal de suporte para alterações de configuração

  ### Idiomas

  Toda a documentação disponível em:

  * 🇺🇸 English
  * 🇪🇸 Español
  * 🇧🇷 Português

  ### Impacto

  * Implementação mais rápida para soluções sem código
  * Orientação clara sobre opções de personalização
  * Maior conscientização sobre segurança
  * Melhor compreensão do fluxo da página hospedada

  [Ver Documentação da Página Hospedada](/pt/use-cases/kyc/hosted-page)
</Update>

<Update label="2025-01-09" description="v1.2.0 - Melhoria Documentação KYC" tags={["KYC", "Documentação", "Multi-idioma"]}>
  ## Refinamento de Páginas KYC Baseado em Feedback do Cliente

  Grande melhoria na documentação de KYC baseada em 14 perguntas do feedback de clientes.

  ### Novidades

  **Documentação de Fluxo Completo:**

  * ✅ Tabela comparativa completa: Criação Automática vs Manual
  * ✅ Guia completo de configuração de Matriz de Risco com instruções do dashboard
  * ✅ Esclarecimento sobre recurso de acionistas (apenas KYB, não KYC)
  * ✅ Referência de códigos de provedores com exemplos de uso
  * ✅ Seção detalhada de gestão de créditos com custos e fluxos de trabalho

  **Página Overview:**

  * ✅ Explicação Webhooks vs polling manual
  * ✅ Tabela comparativa KYC Completo vs Verificações Individuais
  * ✅ Aviso completo sobre segurança de comparação facial para bancos/fintech
  * ✅ Tabela melhorada de endpoints API com casos de uso

  **Página Criar Validação:**

  * ✅ Diagrama de sequência completo mostrando o fluxo completo
  * ✅ Esclarecimento Sandbox vs Produção
  * ✅ Tratamento de entidades duplicadas com exemplos de código
  * ✅ Documentação expandida de integrationCode

  **API de Entidades:**

  * ✅ Campos opcionais marcados com exemplos (attributes, entityData)
  * ✅ Exemplos de criação de entidade mínima vs completa

  ### Idiomas

  Todas as melhorias disponíveis em:

  * 🇺🇸 English
  * 🇪🇸 Español
  * 🇧🇷 Português

  ### Impacto

  * 14 perguntas de cliente respondidas inline
  * 12 arquivos de documentação atualizados
  * 0 links quebrados
  * Experiência de onboarding de desenvolvedores melhorada

  [Ver Documentação KYC](/pt/use-cases/kyc/overview)
</Update>

<Update label="2025-01-08" description="v1.1.0 - Suporte Multi-idioma" tags={["Infraestrutura", "i18n"]}>
  ## Documentação Multi-idioma Aprimorada

  Estrutura de documentação melhorada com traduções completas em espanhol e português.

  ### Mudanças

  * Cobertura completa de tradução para KYC, KYB e Monitoramento de Transações
  * Terminologia consistente em todos os idiomas
  * Exemplos específicos do idioma (CPF para Brasil, DNI para Espanha, etc.)

  ### Idiomas Disponíveis

  * Inglês (EN) - Principal
  * Espanhol (ES) - Completo
  * Português (PT) - Completo
</Update>

<Update label="2024-12-20" description="v1.0.0 - Lançamento Inicial" tags={["Lançamento"]}>
  ## Lançamento da Documentação gu1

  Lançamento inicial da documentação API completa.

  ### Funcionalidades Principais

  * Referência API completa para todos os endpoints
  * Guias de casos de uso (KYC, KYB, Monitoramento de Transações)
  * Guias de integração de webhooks
  * Tutoriais interativos
  * Suporte multi-idioma

  ### Componentes

  * API de entidades pessoa
  * API de entidades empresa
  * Fluxos de validação KYC
  * Monitoramento de transações
  * Motor de regras
  * Matrizes de risco
  * Alertas e investigações

  [Começar](/pt/quickstart)
</Update>