Skip to main content




TransaçõesRegras
Filtrar transações pela data da última avaliação de 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.
WebhooksEntidades
Webhooks legacy de entidades agora incluem score e documento

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.
TransaçõesBatch
Baixar quais transações foram ignoradas por duplicidade

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.
EntidadesBatch
Bulk: aplicar relações declarativas quando a entidade já existe

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).
EntidadesAPIBatch
Relações declarativas em create + bulk de entidades

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, Criar automaticamente e Importar entidades (bulk).
WebhooksSegurançaIAM
Webhook de segurança: alteração de acesso ao ambiente

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.
TransaçõesAPIBatch
linkEntityStrict + soft-link sem quebrar defaults do lote
Criar TX / lote sempre tenta auto-vincular quando há match (entityId → externalId → taxId).
  • Default do lote (BC): omitir flags continua estritovalidateExistingEntity 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.
APIBilling
Rename do código de cota contratual de criação

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.
APIEntities
Unicidade de taxId entre person e company

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 e Criar entidade.
APIRules
Ação addFieldToCustomList em regras

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).
Valores vazios são ignorados; duplicados por primaryValue são omitidos. Disponível em POST/PUT de regras universais e no Rule Builder.
APIEntities
Bloqueio na criação por listas

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.
APIEntities
PATCH /entities/{id}/attributes

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: replaceattributes 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.
APIEntities
Atributos de entidade: armazenamento literal + categorias

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 e Atualizar entidade.
APIWebhooksEntities
API ativação de país por entidade + webhook

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, Atualizar ativação e Eventos webhook de entidade.
APIBulk imports
Bulk import: paridade de política de erros em eventos

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 e Validar CSV.
RulesAPI
Create regras: revisão IA obrigatória + provenance

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.
WebhooksSecurityIAM
Webhooks de segurança: campos de contexto de convite

security.member.invited / security.member.createdpayload.context ampliado

Aditivo. Webhooks do ciclo de convite incluem metadados de correlação e acesso em payload.context:
  • invitationId — correlacionar invitedcreated
  • 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.
APIBulk imports
Batch import: polling de job por jobId

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 e Histórico unificado.
MarketplaceAPIRules
Inteligência de titulares: exists + accounts-count + metrics

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_1dw_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 e Serviços marketplace.
DocsMarketplaceAPI
Documentação seção Serviços marketplace

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.
KYCBiometricAPIEntities
KYC e biométrico: entityTaxId / entityExternalId

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, Sessão biométrica incorporada e Dados mock sandbox.
KYCBiometricAPI
KYC e biométrico: IDs bloqueantes no 409

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 e Sessão biométrica incorporada.
APITransactionsRules
GET transação: rulesExecutionSummary opcional em persisted

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 e Resumo de execução de regras.
APIRulesTransactions
Resumo de regras: status entidade origem/destino

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.
WebhooksSecurityIAM
Webhooks security: membro unificado + ambientes

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.
KYCBiometricAPI
Endpoint sessão biométrica atual

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.
WebhooksSecurityIAM
Eventos webhook de Segurança e 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.
Risk matricesEntitiesTransactionsAPI
watchFields em matrizes + entity_updated no runtime

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.PATCH de transação com executeRules=true repassa paths alterados ao mesmo filtro.
EntitiesBulk importAPI
Import bulk entidades — política de enrichments nos filhos

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).
EventsSDKAPI
Eventos pré-login do SDK e remote config

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.
EnrichmentEntitiesAPI
Erros de enrichment e validação de tax ID

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.
EntitiesEnrichmentAPIDocs
Entidades — refresh scope e preserve

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. Payloads existentes sem esses campos mantêm o comportamento anterior.
KYCAPIDocs
KYC — aviso duplicado cross-entity

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 e omitWarnings.
KYCAPIWebhooksDocs
KYC — Gu1 Biometria

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 e Sessão biométrica.
KYCAPIWebhooksDocs
KYC — decision com forma dual array/objeto

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_verificationid_verifications[0]
  • livenessliveness_checks[0]
  • face_matchface_matches[0]
  • aml_screeningaml_screenings[0]
  • ip_analysisip_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.
EntitiesRisk MatrixAPIDocs
Matriz de risco — rulesEngineConfig no analyze

Config do motor em POST /entities/{entityId}/analyze

Novo objeto opcional rulesEngineConfig: partialCoverage e omitCoverage (defaults false).Ver Analisar entidade.
KYCAPIDocs
KYC — extractedData.ejemplar (DNI argentino)

ejemplar em extractedData

Verificações de DNI argentino podem incluir extractedData.ejemplar (AD) 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 e dupla verificação RENAPER.
KYCAPIDocs
KYC — fluxo RENAPER e revisão manual

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 e Aprovar validação.
EntitiesEnrichmentAPIDocs
Marketplace — checks removidos, só enrichments

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.
  • Compat legacy: payloads de create/import com checks, executeAllActiveChecks ou *_check em autoExecuteIntegrations.enrichments são ignorados no parse.
Ver Códigos de provedores, Criar entidade e Criar automaticamente.
Bulk importsAPIDocs
Bulk imports — códigos de falha + JSON

Códigos estáveis e endpoints JSON de falhas batch

  • Falhas por linha com code + messageCatálogo. 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.
EntitiesAPIDocs
Entidades — PATCH riskMatrixIds

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 ou triggers de ciclo de vida).
  • Mintlify atualizado em /en/, /es/, /pt/ em Atualizar entidade e Atualizar por ID externo.
TransactionsRulesAPIDocs
Transações — configRulesExecution.notifications

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. Paridade em /en/ e /es/.
TransactionsAPIDocs
Transações — denormalização canônica ao vincular entidade

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 / destinationTaxIdentities.tax_id
  • originExternalId / destinationExternalIdentities.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 e Criar lote.
EventsAPIDocs
Eventos de usuário — prioridade isNewDevice do cliente

POST /events/userisNewDevice 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 e Overview de eventos.
EntitiesBulk importAPI
Import entidades — dot notation attributes / entityData

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).
Bulk importAPIDocs
Importações em lote — limites e manual vs automático

Limites documentados (en / es / pt)

  • Importações em lote — 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.
EntitiesBulk importAPI
Import entidades — países por modo

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).
EntitiesBulk importAPI
Import entidades — manual multipart alinhado

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).
EntitiesBulk importAPI
Import entidades — padrão manual na API

POST /batch-import/import/entities — padrão manual

  • Sem entityImportModemanual (entidade mínima; enrichments só se pedidos).
  • Automático com entityImportMode=automatic. Resposta 202 inclui importMode.
Ver Importar entidades (CSV).
EntitiesBulk importAPI
Import entidades — CSV plataforma sem mappingId

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).
TransactionsRulesAPI
Avaliação assíncrona de regras no create

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.
KYCAPI
Face Match e ID Verification — dupla verificação RENAPER

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 e ID Verification.
TransactionsRulesAPI
Trigger status-change em regras KYT

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 e Atualizar transação.
TransactionsAPI
PATCH transação — metadata, deviceDetails, channel, reason

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.
EventsAPI
Tem eventos? — identificadores por query

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_identity_external_idtax_id; tax ID com normalização (caracteres não alfanuméricos removidos).
  • A resposta inclui entityId resolvido para chamar Listar por entidade quando hasEvents for true.
  • GET /events/user/entity/{entityId}/has-events continua suportado (contrato inalterado).
Ver Tem eventos? (por entidade).
KYCAPI
Códigos de aviso IP analysis KYC

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.
  • Os mesmos códigos são válidos em omitWarnings em POST /api/kyc/validations 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.
KYCAPI
ID Verification — extractedData ampliado

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.
  • debugProviderResponse apenas em ambientes não produtivos da API Gu1 (payload de verificação sanitizado, sem imagens).
Ver ID Verification.
EntidadesTransaçõesRegrasAPI
operationalHours em entidades + regras KYT

Horário operativo por entidade (global)

  • Entidades: campo opcional na raiz operationalHours (timezone enum + weekly). Coluna entities.operational_hours. Ver Criar entidade.
  • 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.
TransaçõesAPIBanco de dados
timeZone opcional em transações

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 e Criar transação.
TransaçõesAPILegacy
validateExistingEntity em transações

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 e Criar transações em lote.
EntidadesAPIEnriquecimento
Auto-execução na criação de entidades

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).
KYCPágina HospedadaDocumentação
v1.3.0 - Documentação Página de Onboarding Hospedada

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
KYCDocumentaçãoMulti-idioma
v1.2.0 - Melhoria Documentação KYC

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
Infraestruturai18n
v1.1.0 - Suporte Multi-idioma

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
Lançamento
v1.0.0 - Lançamento Inicial

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