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.Campos adicionais nos webhooks legacy planos de entidades
Os payloads legacy planos de webhooks de entidades agora incluem os campos aditivosriskScore e documentNumber. Os valores e mapeamentos de status existentes permanecem
inalterados.Veja Eventos de webhook de entidades.Relatório de linhas ignoradas em batch de transações
Novo endpointGET /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; comskipDuplicates=falseas duplicatas são resolvidas pelo banco e apenas contadas, então o endpoint retornaSKIPS_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.
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).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 /entitiesePOST /entities/automatic: body opcionalrelationships[](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_FOUNDe a entidade não é criada.
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
security.member.environment_granted / .environment_revoked continuam existindo para fluxos de grant/revoke de um único ambiente.Ver Eventos de webhook de segurança.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 —
validateExistingEntitypadrãotrue. 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 sevalidateExistingEntitydiga 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.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 parafailures.csvhistóricos.
Unicidade de tax ID (por organização)
UmtaxId 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 →
409com códigoDUPLICATE_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.
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).primaryValue são omitidos. Disponível em POST/PUT de regras universais e no Rule Builder.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.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 mantidasmode: replace—attributesdo body substitui o mapa completo ({}limpa tudo)- Buckets aninhados por categoria na escrita
- Dispara webhook
entity.updatede matrizes com triggerentity_updatedquando configurado
Atributos personalizados armazenados como enviados (API)
Aditivo. Osattributes 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:
GETretorna a mesma forma que foi escrita (sem achatar). - Regras / webhooks: leem a forma armazenada —
attributes.phonepara plano,attributes.contact.phonepara aninhado. Use chaves de categoria seguras como identificador.
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" }; requerentities:edit. Transições livres. Idempotente se o status não mudar (sem webhook).- Webhook
entity.country_activation_changed— emitido em cada mudança real; incluiactiveCountryCodes, snapshotcountriesetimelinepor país; inscrever-se na config de webhooks existente.
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-eventsaceitabatchErrorHandling:continue_collect_errors(padrão),rollback_alloustop_keep_success.- Respostas
202incluempreflightFailuresquando linhas inválidas são ignoradas com política continue. POST /batch-import/validate-csvvalida cada linha quando o target éuser_event(rowErrors,validRowCount,invalidRowCount).
POST /rules — revisão IA síncrona em toda criação
- Regras novas ficam sempre em
in_progresscomenabled: false;status/enableddo body são ignorados no create. - A resposta inclui
aiReviewe 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.
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— correlacionarinvited→createdgranularRoleIds,granularRoleIdsSandboxincludeProduction,includeSandboxteamId,teamIdSandboxhasEnvironmentAccess— flag de acesso para a org do envelopeenvironment—"production"ou"sandbox"conforme a org do envelopeinvitedByUserId,acceptedVia(emcreated)syncPartialFailure,syncErrorMessage(emcreatedquando a configuração secundária não concluiu)
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). Retornastatus, contadores (totalItems,succeeded,failed,skipped), timestamps ejobFailureopcional se o job inteiro abortou. Query opcionalinclude=failuresretorna o mesmo JSON dos endpoints de failures por tipo.GET /batch-import/unified-history— novo query paramjobId(correspondência exata; 0 ou 1 linha). O histórico unificado continua para listagens; useGET /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.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. RetornafoundesnapshotDate(nullse não encontrado). Sempre HTTP200em sucesso (incluindofound: false). Sem cobrança.GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/accounts-count— totais CBU/CVU +isNewesnapshotDate. Cobrável por request quando o produto tem preço.GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/metrics— lookback densificado (lookback1–180 ou presetwindoww_1d…w_180d). Query opcionaldate(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:400LOOKBACK_REQUIRED/INVALID_LOOKBACK/INVALID_WINDOW/INVALID_DATE,404CUIT_NOT_FOUND,422INCOMPLETE_WINDOW/NO_INCREMENTAL_STATE.
Motor de regras
Novos campos emservices.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.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 aceitaentityId,entityExternalIdouentityTaxId(exatamente um).POST /api/kyc/biometric/sessions— mesmas opções.
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|statuse rotasby-external-id - Biométrico:
GET /api/kyc/biometric/entities/by-tax-id/:taxId/currenteby-external-id
Prévia sandbox (somente GET)
GET /api/entities/by-tax-id/{taxId}eGET /api/entities?taxId=...podem retornar dados sintéticossandboxMock: true(id: null) para números do catálogo sem linha real. Não habilita POST sem criar entidade real.
Respostas 409 aditivas para sessões / validações abertas
Sem breaking change para clientes que leem apenaserror e message. Campos opcionais novos em códigos 409 existentes:Biometria incorporada — POST /api/kyc/biometric/sessions
- Com a última sessão em
pendingouin_progress, o create sempre retorna409 ACTIVE_SESSION_EXISTS(nunca201com a mesma sessão pending). - O body inclui
activeSessionIdpara cancelar:POST .../sessions/{activeSessionId}/cancel.
Validação KYC — POST /api/kyc/validations
- Com validação aberta (
pending,in_progress,in_review), o create retorna409 VALIDATION_IN_PROGRESS. - O body agora também inclui
activeValidationIdpara cancelar:DELETE .../validations/{activeValidationId}/cancel.
includeRulesSummary no GET de uma transação
GET /transactions/{id} e GET /transactions/external/{externalId} aceitam um query param opcional:includeRulesSummary=full— Adicionapersisted.rulesExecutionSummaryda linha mais recente derisk_analysis_auditsdessa transação. Regras não são reexecutadas na leitura.
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.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 comactionsExecuted.statuspara a transação).
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 porcontext.environment("production"|"sandbox")
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.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, …). 200comnullquando a entidade não tem sessões biométricas (não mais404).- Na listagem,
currentSessionIdcontinua sendo apenas a última sessãoapproved.
409 ACTIVE_SESSION_EXISTS ao criar inclui activeSessionId para cancelar a sessão bloqueante sem consulta extra.Ver Sessão biométrica atual.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(antessecurity.user.password_*) - Settings:
security.settings.updated(sandbox, configurações de segurança auditadas)
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.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.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_typeoubasic_only.by_root_type: linhas empresa → acionistas com todos os enrichments ativos excetoglobal_gueno_sanctions_enrichment; linhas pessoa → relacionadas só com dados básicos do provedor da raiz.
monitoringApplyToRelationships: comfalse,monitoringsó nas entidades principais. Padrãotruecomdepth> 0 se omitido.
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.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.POST /entities/{entityId}/refresh — escopo unificado e sync seguro
Novos campos opcionais (retrocompatíveis quando omitidos):refreshScope:basic_data|all_active|selected(+providerCodesseselected).preserveName:truemantém o nome; omitido = sync legacy defullNamenormalizado.preserveEntityData: apenas comrefreshScope: "basic_data"—truepreenche vazios ementityData,falsesubstitui; 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.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_DUPLICATEDawarningsda validação por sessão. - Se o provedor mapeou
approved, Gu1 define o status comoin_review(metadata.guenoCrossEntityDuplicateEscalation). - Não omitível: não pode constar em
omitWarnings(400) e bloqueia autoaprovação por omit.
omitWarnings.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.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]
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.Config do motor em POST /entities/{entityId}/analyze
Novo objeto opcional rulesEngineConfig: partialCoverage e omitCoverage (defaults false).Ver Analisar entidade.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 e dupla verificação RENAPER.Dupla verificação RENAPER em validações KYC
ComdoubleCheckRenaper: 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.Produto marketplace *_check removido
- Removido: códigos
*_check,POST /integration-execution/marketplace/check, triggers/ações de regrascheck_completed/execute_check, e permissões RBACchecks:read/checks:execute. - Use em vez disso: o
*_enrichmentcorrespondente com Executar enrichment. - Compat legacy: payloads de create/import com
checks,executeAllActiveChecksou*_checkemautoExecuteIntegrations.enrichmentssão ignorados no parse.
Códigos estáveis e endpoints JSON de falhas batch
- Falhas por linha com
code+message— Catálogo. CSV inclui colunacode. - JSON:
GET /batch-import/transaction-jobs/{jobId}/failures,GET /batch-import/user-event-jobs/{jobId}/failures,GET /batch-import/entity-jobs/{jobId}/failures— incluemfailures[],jobFailureopcional,skips[]em entidades,truncated/failuresTotal(máx. 500). - CSV: mesmas rotas com sufixo
.csvpara download direto.
Atribuir matrizes de risco na atualização de entidade
PATCH /entities/{id}(ePATCH /entities/by-external-id/{externalId},PATCH /entities/by-tax-id/{taxId}): documentadosriskMatrixIds(string[]) eriskMatrixId(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.
configRulesExecution na criação de transação
POST /transactions: objeto opcional no bodyconfigRulesExecutioncomnotifications(boolean). Comfalse, a gu1 não envia notificações in-app da avaliação de regras (matriz / status). AçõescreateAlerte investigações permanecem iguais.- Padrão: omitir o objeto mantém o comportamento anterior na maioria das orgs (
notificationsefetivamentetrue). Paytime prod (3bc1f621-27d4-423e-9d64-86680bec2388) usanotifications: falsepor padrão. - Legacy KYT
POST /legacy/kyt/verifyTransaction: mesmo campo no body Gu2; Paytime prodnotifications: falsepor padrão se omitido. - Vale para regras sync e async (
asyncRules).
/en/ e /es/.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_idoriginExternalId/destinationExternalId←entities.external_id
POST /events/user — isNewDevice respeita o valor do integrador
- Se você enviar
isNewDevice: trueoufalse, a gu1 persiste exatamente esse valor (sem sobrescrita no servidor). - Se omitir o campo, a gu1 infere quando há
deviceId+deviceDetails(registro de dispositivos;truese o device for novo oufirstSeenAtestiver nos últimos 5 minutos); caso contráriofalse.
CSV plataforma: attributes.* e entityData.*
- Cabeçalhos com ponto (como transações nativas):
attributes.segment_tag,entityData.income,entityData.tradeName. entityData.<campo>semperson/company→ bucket conformetypeda linha.- Colunas sem prefixo permanecem em
attributes(retrocompat). - Ver Importar entidades (CSV).
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.
Países na importação bulk (manual vs automático)
- Manual (
manual): qualquer ISO2 válido da plataforma (lote oucountry_code/countrypor 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 commappingId).
POST /batch-import/import/entities — enrichments no manual
- Modo manual multipart alinhado ao hub Manual:
autoExecuteIntegrations,monitoringe 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;
depthsó no automático.
POST /batch-import/import/entities — padrão manual
- Sem
entityImportMode→manual(entidade mínima; enrichments só se pedidos). - Automático com
entityImportMode=automatic. Resposta202incluiimportMode.
POST /batch-import/import/entities — formato plataforma
mappingIdpassa 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+typeapenas): enviecountry(ISO2, ex.AR) no form multipart como padrão do lote. - Paridade com transações: formato nativo → sem mapeamento; colunas custom → com mapeamento.
asyncRules ao criar transação
POST /transactions: flag opcionalasyncRulesem query ou body (padrãofalse). ComtrueeexecuteRulesdiferente defalse, a transação é criada na mesma request mas as regras rodam em background via fila de jobs. A resposta HTTP retorna na hora comrulesHit/rulesNoHitvazios, maisasyncRules: trueerulesEvaluationStatus: "queued".- Padrão inalterado: omitir
asyncRulesmantém execução síncrona erulesExecutionSummarycompleto — 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=falseforç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).
Dupla verificação RENAPER em endpoints KYC standalone
POST /api/kyc/face-match:doubleCheckRenaperopcional (body ou query). Após face match aprovado: RENAPER biométrico + dados. RequerdocumentNumber,gender,personalNumber(fallback de entidade para DNI/gênero). Resposta comresponseDoubleChecks.POST /api/kyc/id-verification: mesmo flag; após OCR approved apenas chequeo dados RENAPER. Falha →declined+ códigos emwarnings.- Credenciais RENAPER da org (igual ao KYC por sessão). Timeout HTTP ≥ 60 s no face-match com double-check.
KYT — triggers separados: mudança de status vs atualização de campos
PATCH …/changeStatusexecuta regras/matrizes com triggerstatus_changed(trigger_transaction_status_changed), nãoupdated.PATCH /transactions/{id}comexecuteRules=truecontinua usandoupdated(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).
Atualização parcial de transação
PATCH /transactions/{id}ePATCH /transactions/external/{externalId}: atualizarmetadata(merge superficial),deviceDetails(merge superficial emdevice_details),channel(nullable) e/oureason(enum). Requertransactions:edit.- Query
executeRules=truereexecuta regras KYT com triggerupdated— não regras de mudança de status. - Auditoria
transaction_updatede webhooktransaction.updatedcom mapachanges(incluideviceDetailsquando aplicável).
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_idoutax_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
entityIdresolvido para chamar Listar por entidade quandohasEventsfor true. GET /events/user/entity/{entityId}/has-eventscontinua suportado (contrato inalterado).
KYC por sessão — avisos de análise de dispositivo e IP
GET /api/kyc/validations/:id(e rotas de sync/webhook): o arraywarningsagora funde códigosriskdedecision.ip_analyses[].warnings[](e legacydecision.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
omitWarningsemPOST /api/kyc/validationsao autoaprovar sessões emin_review.
warnings armazenado até o próximo sync; consulte novamente ou sincronize para preencher códigos de IP analysis em linhas antigas.ID Verification — extractedData mais completo
POST /api/kyc/id-verificatione auditoria list/get passam a persistir e devolver umextractedDatamais amplo: identidade (personalNumber,taxNumber,placeOfBirth, …),providerStatus,warningMeta(ex.: sessão duplicada), pontuações de qualidade,extraFields,mrz,parsedAddress,barcodesquando o serviço ID Verification da Gu1 os devolve.warningscontinua como array de códigos de risco para i18n; metadados estruturados de duplicado ficam emwarningMetadentro deextractedData.- URLs externas de imagem e base64 não são devolvidas; imagens enviadas estão em imagens ID Verification.
debugProviderResponseapenas em ambientes não produtivos da API Gu1 (payload de verificação sanitizado, sem imagens).
Horário operativo por entidade (global)
- Entidades: campo opcional na raiz
operationalHours(timezoneenum +weekly). Colunaentities.operational_hours. Ver Criar entidade. - Transações: enum
transaction_time_zoneampliado (fusos do Brasil).timeZoneindependente deoperationalHours.transactedAt: gravado em UTC; ISO comZinalterado para clientes atuais; datetime local +timeZoneopcional converte para UTC. - Regras: operadores
outside_entity_operational_hourseinside_entity_operational_hoursemtransactedAt(value:origin|destination).
timeZone em transações
- Banco de dados: Nova coluna nullable
time_zoneemtransactionscom enumtransaction_time_zone(valores IANA comoAmerica/Argentina/Buenos_Aires,UTC, etc.). Registros existentes permanecemnull. - API:
timeZoneopcional emPOST /transactionse criação em lote; retornado emGET /transactions/{id}eGET /transactions/external/{externalId}comostring | null.
validateExistingEntity (criação de transações)
POST /transactions: campo opcionalvalidateExistingEntity(padrãofalse). Comtrue, cada identificador de origem/destino enviado deve existir na org; senão 400INVALID_ENTITY_REFERENCESe a linha não é criada.- Lote (
POST /transactions/batch, upload, JSON): padrão continuatrue. Import permissivo:validateExistingEntity: false. - Legacy KYT
POST /legacy/kyt/verifyTransaction: mesmo campo no body Gu2.
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).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
- 📱 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
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
- ✅ 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
- ✅ 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
- ✅ 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
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 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