# Atualizar uma identidade Identity Management v3 Este tópico descreve o modelo de identidade v3. O **Identity Management v3** é recomendado para todas as novas integrações. Para conhecer os corredores de pagamento compatíveis, consulte [Payout network](/pt-br/products/payments-direct-2/introduction/payout-network). Este tutorial mostra como usar `PUT /v3/identities/{identity-id}` para atualizar uma identidade existente no **Identity Management v3**. Ele cobre a atualização de metadados, campos de PII e validação de payment rail, e explica como funciona o versionamento de identidades e o que isso significa para a sua integração. ## Antes de começar Para seguir estes exemplos, você precisa de: - URL base do Identity Management (por exemplo, `https://{base-url}`) - Um token de acesso com o escopo `participants:update` - Um `identityId` de uma identidade criada anteriormente Em todos os exemplos abaixo, substitua: - `{base-url}` pela sua URL base de PII real - `` por um token de acesso OAuth2 válido - `{identity-id}` por um `identityId` real retornado pela API ## Como funcionam as atualizações de identidade ### Versionamento imutável Toda chamada bem-sucedida a `PUT /v3/identities/{identity-id}` cria uma **nova versão** da identidade. A versão anterior é preservada e continua disponível para consulta e auditoria. O `identityId` nunca muda. Por exemplo, se uma identidade está em `version: 2`, uma atualização bem-sucedida produz `version: 3`. O registro da versão 2 continua acessível por `GET /v3/identities/{identity-id}?version=2`. ### Atualizações parciais O corpo da requisição PUT aceita atualizações parciais. Você só precisa incluir os campos que quer alterar. Os campos que você omite mantêm os valores atuais. Por exemplo, para atualizar apenas o `nickName`, basta enviar `nickName` no corpo da requisição. Todos os demais dados de PII e metadados são preservados sem alteração. ### Efeito sobre os pagamentos Os pagamentos ficam vinculados a um `identityId` e a uma `version` específicos no momento da criação. Atualizar uma identidade cria uma nova versão, mas **não afeta os pagamentos que já foram criados** com uma versão anterior. Esses pagamentos continuam referenciando a versão da identidade com que foram criados. ### O que você pode e o que não pode alterar | Campo(s) | Pode atualizar? | Observações | | --- | --- | --- | | `nickName` | Sim | — | | `tags` | Sim | Substitui integralmente o array de tags existente | | `internalId` | Sim | Precisa continuar único entre todas as identidades ACTIVE da sua organização | | `validatePayoutRails` | Sim | Revalida o PII da identidade contra os rails especificados | | Campos de `individual` | Sim | Qualquer campo dentro do objeto `individual` (endereço, contato, documentos etc.) | | Campos de `business` | Sim | Qualquer campo dentro do objeto `business` (nome, endereço, contato, registro etc.) | | `identityType` | **Não** | Definido na criação (INDIVIDUAL ou BUSINESS). Não pode ser alterado. | | `paymentRole` | **Não** | Definido na criação (ORIGINATOR ou BENEFICIARY). Não pode ser alterado. | Identidades DEACTIVATED Não é possível atualizar uma identidade DEACTIVATED. A desativação é permanente. Se você precisar retomar a atividade de uma parte desativada, crie uma nova identidade. ## Atualizar os metadados da identidade Os campos de metadados (`nickName`, `tags`) são a atualização mais simples. Nenhuma validação de PII é disparada. **Exemplo: atualizar o apelido e as tags** ```bash curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "nickName": "Alice Chen - Primary USD", "tags": ["usd", "high-value", "verified"] }' ``` **Resposta (200 OK)** ```json { "identityId": "99254c4f-f207-4792-a846-06928825018c", "identityState": "ACTIVE", "version": "2", "schemaVersion": "1.0.0", "identityType": "INDIVIDUAL", "paymentRole": "ORIGINATOR", "internalId": "customer-12345", "nickName": "Alice Chen - Primary USD", "tags": ["usd", "high-value", "verified"], "createdAt": "2025-10-01T18:46:41.833Z", "updatedAt": "2026-03-10T09:15:10.000Z", "individual": { "firstName": "Alice", "lastName": "Chen", "dateOfBirth": "1990-05-14", "citizenship": "US", "address": { "streetAddress": ["123 Main Street"], "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" } } } ``` Observe que `version` passou de `1` para `2` e que `updatedAt` reflete o momento da atualização. Todos os demais campos permanecem inalterados. As tags são substituídas, não mescladas O campo `tags` é substituído integralmente a cada atualização. Se você enviar `"tags": ["usd"]`, todas as tags anteriores são removidas e substituídas pelo novo valor. Busque a identidade atual antes, se precisar preservar as tags existentes. ## Atualizar campos de PII ### Atualizar uma identidade INDIVIDUAL Use isto para corrigir ou atualizar dados pessoais, como endereço, informações de contato ou documentos de identidade. **Exemplo: atualizar o endereço** ```bash curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "individual": { "address": { "streetAddress": ["500 Market Street", "Suite 200"], "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94103", "country": "US" } } }' ``` **Resposta (200 OK)** ```json { "identityId": "99254c4f-f207-4792-a846-06928825018c", "identityState": "ACTIVE", "version": "3", "schemaVersion": "1.0.0", "identityType": "INDIVIDUAL", "paymentRole": "ORIGINATOR", "internalId": "customer-12345", "nickName": "Alice Chen - Primary USD", "tags": ["usd", "high-value", "verified"], "createdAt": "2025-10-01T18:46:41.833Z", "updatedAt": "2026-03-10T10:22:05.000Z", "individual": { "firstName": "Alice", "lastName": "Chen", "dateOfBirth": "1990-05-14", "citizenship": "US", "address": { "streetAddress": ["500 Market Street", "Suite 200"], "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94103", "country": "US" } } } ``` ### Atualizar uma identidade BUSINESS **Exemplo: atualizar e-mail e telefone** ```bash curl -X PUT "https://{base-url}/v3/identities/0116bacc-ffbf-4fa2-a29c-ecd9ea346806" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "business": { "email": "ops@widgetsorg.com", "phone": "+14155550199" } }' ``` **Resposta (200 OK)** ```json { "identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806", "identityState": "ACTIVE", "version": "2", "schemaVersion": "1.0.0", "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "internalId": "counterparty-7890", "nickName": "Widgets Org MX", "tags": ["beneficiary", "mx"], "createdAt": "2025-10-01T16:14:13.200Z", "updatedAt": "2026-03-10T11:05:30.000Z", "business": { "businessName": "Widgets Org", "incorporationCountry": "US", "email": "ops@widgetsorg.com", "phone": "+14155550199", "registration": [ { "number": "123ABC", "type": "INCORPORATION_CERTIFICATE" } ], "address": { "streetAddress": ["123 Example MA"], "city": "Boston", "stateOrProvince": "MS", "postalCode": "12345", "country": "US" } } } ``` ## Adicionar ou alterar a validação de payment rail Use `validatePayoutRails` para validar o PII de uma identidade contra payment rails adicionais. Isso é útil quando você está cadastrando um beneficiário em um novo corredor que exige campos de PII específicos. **Exemplo: adicionar validação de EU SEPA e GB FPS** ```bash curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "validatePayoutRails": ["US_ACH", "EU_SEPA", "GB_FPS"] }' ``` Se o PII atual da identidade atender a todos os requisitos dos rails especificados, a atualização é bem-sucedida e retorna a nova versão. Se faltar algum campo obrigatório para qualquer um dos rails especificados, a requisição retorna **400 Bad Request** com detalhes por campo: ```json { "code": "VALIDATION_ERROR", "title": "Identity validation failed", "description": "The identity is missing required fields for the specified payment rails.", "details": [ { "field": "individual.dateOfBirth", "message": "Date of birth is required for EU_SEPA beneficiary identities" } ] } ``` Para resolver isso, adicione os campos de PII ausentes à mesma requisição de atualização: ```bash curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "validatePayoutRails": ["US_ACH", "EU_SEPA", "GB_FPS"], "individual": { "dateOfBirth": "1990-05-14" } }' ``` validatePayoutRails é orientativo Incluir um rail em `validatePayoutRails` não impede que você adicione instrumentos financeiros para outros rails, e omitir um rail não impede que você o use depois. De qualquer forma, a validação é feita no momento da criação do instrumento financeiro e da iniciação do pagamento. ## Atualizar o internalId Você pode alterar o `internalId` de uma identidade com uma requisição PUT. O novo valor não pode já estar em uso por outra identidade ACTIVE da sua organização. **Exemplo: renomear um internalId** ```bash curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "internalId": "customer-12345-v2" }' ``` Se o `internalId` solicitado já estiver em uso por outra identidade ACTIVE, a requisição retorna **409 Conflict**: ```json { "code": "CONFLICT", "title": "Identity conflict", "description": "The provided internalId already exists on a different identity.", "details": [ { "field": "internalId", "message": "An ACTIVE identity with internalId 'customer-12345-v2' already exists (identityId: 7ea3399c-1234-5678-8d8f-d320ea406630)" } ] } ``` Para orientações sobre o tratamento de conflitos 409, consulte [Criar e gerenciar identidades](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities#tratamento-de-conflitos-de-internalid-409-conflict). ## Atualizar uma identidade BLOCKED Uma identidade pode estar no estado `BLOCKED` se foi sinalizada para análise de compliance ou se foi importada de uma versão anterior da API. Identidades BLOCKED não podem ser usadas para criar novos pagamentos. Chamar `PUT /v3/identities/{identity-id}` em uma identidade BLOCKED atualiza os dados da identidade **e** transiciona o estado dela de `BLOCKED` de volta para `ACTIVE`. Estado BLOCKED e reativação Um PUT bem-sucedido em uma identidade BLOCKED define `identityState` como `ACTIVE`. Confirme com a sua equipe de compliance que a reativação é adequada antes de enviar uma atualização para uma identidade BLOCKED. **Exemplo: atualizar uma identidade BLOCKED** ```bash curl -X PUT "https://{base-url}/v3/identities/{identity-id}" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "nickName": "Reviewed and cleared" }' ``` **Resposta (200 OK)** ```json { "identityId": "{identity-id}", "identityState": "ACTIVE", "version": "3", ... } ``` O `identityState` na resposta é `ACTIVE`, confirmando que a identidade foi reativada como parte da atualização. ## Referência de erros | Status HTTP | Quando ocorre | O que fazer | | --- | --- | --- | | `400 Bad Request` | Campos ausentes ou inválidos, ou PII reprovado na validação dos `validatePayoutRails` especificados | Verifique o array `details[]` para ver as mensagens por campo. Corrija a requisição e tente novamente. | | `404 Not Found` | O `identity-id` não existe | Confira o `identityId` e tente novamente. | | `409 Conflict` | O `internalId` da requisição já está em uso por outra identidade ACTIVE | Use a identidade existente ou escolha outro `internalId`. | | `500 Internal Server Error` | Erro de processamento no lado da Ripple | Tente novamente após um breve intervalo. Entre em contato com o suporte se o erro persistir. | ## Próximos passos - Para entender o modelo de dados completo da identidade e o comportamento de versionamento, consulte [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities). - Para criar identidades e gerenciar o ciclo de vida completo, incluindo a desativação, consulte [Criar e gerenciar identidades](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities). - Para adicionar ou atualizar dados de conta bancária e de payout de uma identidade, consulte [Criar e gerenciar instrumentos financeiros](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments).