{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities","default":true,"active":true,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-identities","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/api-docs/developer-guides/create-and-manage-identities","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Criar e gerenciar identidades","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"criar-e-gerenciar-identidades","__idx":0},"children":["Criar e gerenciar identidades"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Corredores compatíveis"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para conhecer os corredores de pagamento compatíveis, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/payout-network"},"children":["Payout network"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este tutorial mostra como usar os endpoints de identidade do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," para:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Criar uma nova identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Recuperar uma identidade por ID (e por versão)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Listar identidades com filtros e paginação"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Atualizar os dados de uma identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Desativar uma identidade"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ele parte do modelo descrito em ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities"},"children":["Identidades do pagamento"]}," e foca no schema de identidade v3."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um comportamento central da v3 é que ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no máximo uma identidade ACTIVE"]}," no seu ambiente pode usar um determinado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},". Tentativas de criar ou atualizar uma identidade de modo que o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," dela colida com o de outra identidade ACTIVE resultam em ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"antes-de-começar","__idx":1},"children":["Antes de começar"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para seguir estes exemplos, você precisa de:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["URL base do Identity Management (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{base-url}"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Um token de acesso com os seguintes escopos (ou equivalentes):",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:create "]},"para criar identidades"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:read"]}," para ler e listar identidades"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:update"]}," para atualizar e desativar identidades"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O modelo de identidade v3 de ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identidades do pagamento"]}," (INDIVIDUAL vs BUSINESS e ORIGINATOR vs BENEFICIARY)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Em todos os exemplos abaixo, substitua:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{base-url}"]}," pela sua URL base de PII real"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<access_token>"]}," por um token de acesso OAuth2 válido"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{identity-id} "]},"por um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," real retornado pela API"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"criar-uma-identidade","__idx":2},"children":["Criar uma identidade"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities"]}," para criar uma nova identidade."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No mínimo, você precisa informar:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," – INDIVIDUAL ou BUSINESS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRole"]}," – ORIGINATOR ou BENEFICIARY"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os dados de pessoa física ou de empresa, conforme o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," para identidades ORIGINATOR"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para identidades ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BENEFICIARY"]},", o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," é opcional, mas recomendado se você quiser vincular beneficiários aos seus próprios registros de clientes."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Deduplicação via internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O Identity Management v3 garante que no máximo uma identidade ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," por organização possa usar um determinado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se você tentar criar uma identidade e o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," informado já estiver em uso por outra identidade ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]},", a requisição falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Você pode tratar esse erro na sua integração para sinalizar situações de “cliente duplicado” ou orientar os usuários a reutilizar a identidade existente."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Número da conta do ordenante para pagamentos em USD à China"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alguns corredores exigem o número da conta do próprio ordenante. Envie-o em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]},", e não em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},". Em uma identidade de ordenante validada em relação a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN_CFXPS"]}," (pagamentos em USD à China), omitir ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_111"]},"), e um UUID gerado aleatoriamente ou outra referência arbitrária faz o payout ser rejeitado."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#o-n%C3%BAmero-de-conta-do-ordenante"},"children":["O número da conta do ordenante"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Documentos de identidade na jurisdição do Brasil (BR)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a sua organização estiver configurada para a jurisdição do Brasil (BR), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}," é obrigatório em toda identidade ORIGINATOR, em todos os corredores, inclusive naqueles que de outra forma não o exigiriam. Omiti-lo falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_111"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Isso vale tanto para atualizações quanto para criações. Uma atualização valida o corpo que você envia, não o registro já armazenado, portanto uma atualização que omita ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}," falha mesmo quando você está alterando algo não relacionado."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#requisitos-por-jurisdi%C3%A7%C3%A3o"},"children":["Requisitos por jurisdição"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Opcionalmente, você também pode:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Definir um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickName"]}," amigável e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adicionar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," para validar a identidade contra payment rails específicos (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},")"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: criar um INDIVIDUAL ORIGINATOR"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"INDIVIDUAL\",\n    \"paymentRole\": \"ORIGINATOR\",\n    \"internalId\": \"customer-12345-uuid\",\n    \"nickName\": \"Alice Sender USD\",\n    \"tags\": [\"sender\", \"priority\"],\n    \"validatePayoutRails\": [\"US_ACH\"],\n    \"individual\": {\n      \"firstName\": \"Alice\",\n      \"lastName\": \"Chen\",\n      \"dateOfBirth\": \"1990-05-14\",\n      \"citizenship\": \"US\",\n      \"address\": {\n        \"streetAddress\": [\"123 Main Street\"],\n        \"city\": \"San Francisco\",\n        \"stateOrProvince\": \"CA\",\n        \"postalCode\": \"94105\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (201 Created)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"99254c4f-f207-4792-a846-06928825018c\",\n  \"version\": \"1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Deduplicação via internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se você enviar outro ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities"]}," com o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," enquanto esta identidade ainda estiver ACTIVE, o serviço retorna:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," – indicando que outra identidade ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," já usa esse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trate o 409 como um sinal de que você deve localizar e reutilizar a identidade existente em vez de criar uma duplicada."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: criar um BUSINESS BENEFICIARY"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"BUSINESS\",\n    \"paymentRole\": \"BENEFICIARY\",\n    \"internalId\": \"counterparty-7890\",\n    \"nickName\": \"Widgets Org MX\",\n    \"tags\": [\"beneficiary\", \"mx\"],\n    \"validatePayoutRails\": [\"MX_SPEI\"],\n    \"business\": {\n      \"businessName\": \"Widgets Org\",\n      \"incorporationCountry\": \"US\",\n      \"registration\": [\n        {\n          \"number\": \"123ABC\",\n          \"type\": \"INCORPORATION_CERTIFICATE\"\n        }\n      ],\n      \"email\": \"fake@example.com\",\n      \"phone\": \"+1234567890\",\n      \"address\": {\n        \"streetAddress\": [\"123 Example MA\"],\n        \"city\": \"Boston\",\n        \"stateOrProvince\": \"MS\",\n        \"postalCode\": \"12345\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (201 Created)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"0116bacc-ffbf-4fa2-a29c-ecd9ea346806\",\n  \"version\": \"1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"PII ausente ou inválido"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se algum dado de PII obrigatório estiver ausente ou inválido para os rails em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},", a API retorna um erro 400 descrevendo quais campos falharam na validação."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: falha de validação por campos obrigatórios ausentes"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se você tentar criar uma identidade com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails: [\"US_ACH\"]"]}," mas omitir campos obrigatórios como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]},", receberá:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (400 Bad Request)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"VALIDATION_ERROR\",\n  \"title\": \"Identity validation failed\",\n  \"description\": \"The identity is missing required fields for the specified payment rails.\",\n  \"details\": [\n    {\n      \"field\": \"individual.identityDocuments\",\n      \"message\": \"At least one identity document (SSN or Tax ID) is required for US_ACH beneficiary identities\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para corrigir isso, adicione os campos ausentes e envie a requisição novamente."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: falha de validação por tipo de documento não compatível"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alguns corredores aceitam apenas um subconjunto do enum ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idType"]}," (pessoa física) ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registration.type"]}," (empresa), e a API rejeita os tipos não compatíveis com um erro 400. Por exemplo, ordenantes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]}," aceitam apenas ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSPORT"]},", portanto enviar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NATIONAL_ID_NUMBER"]}," falha:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (400 Bad Request)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"VALIDATION_ERROR\",\n  \"title\": \"Identity validation failed\",\n  \"description\": \"The identity uses a document type that is not supported for the specified payment rails.\",\n  \"details\": [\n    {\n      \"field\": \"individual.identityDocuments.idType\",\n      \"message\": \"Document type NATIONAL_ID_NUMBER is not accepted for KR_KFTC originator identities. Accepted values: PASSPORT.\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para ver os tipos de documento aceitos por corredor e papel, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#tipos-de-documento-aceitos-por-corredor"},"children":["Tipos de documento aceitos por corredor"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratamento-de-conflitos-de-internalid-409-conflict","__idx":3},"children":["Tratamento de conflitos de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," (409 Conflict)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando você cria ou atualiza uma identidade com um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," que já está em uso por outra identidade ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]},", a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este é um ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["recurso de deduplicação"]}," que evita que você crie acidentalmente várias identidades para o mesmo cliente."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-internalid-duplicado-na-criação","__idx":4},"children":["Exemplo: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," duplicado na criação"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Requisição:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"INDIVIDUAL\",\n    \"paymentRole\": \"BENEFICIARY\",\n    \"internalId\": \"customer-12345-uuid\",\n    \"individual\": {\n      \"firstName\": \"Bob\",\n      \"lastName\": \"Smith\",\n      \"address\": {\n        \"streetAddress\": [\"456 Oak Ave\"],\n        \"city\": \"Austin\",\n        \"stateOrProvince\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (409 Conflict)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"CONFLICT\",\n  \"title\": \"Identity conflict\",\n  \"description\": \"An identity with the provided internalId already exists.\",\n  \"details\": [\n    {\n      \"field\": \"internalId\",\n      \"message\": \"An ACTIVE identity with internalId 'customer-12345-uuid' already exists (identityId: 99254c4f-f207-4792-a846-06928825018c)\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"como-tratar-o-409-conflict","__idx":5},"children":["Como tratar o 409 Conflict"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando você receber um 409 Conflict:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Localize a identidade existente"]}," usando o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," da mensagem de erro"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reutilize a identidade existente"]}," em vez de criar uma nova"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Atualize a identidade existente"]}," se necessário (por exemplo, para adicionar novos dados de PII ou alterar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Investigue os seus sistemas upstream"]}," se estiver recebendo conflitos inesperados (isso pode indicar registros de clientes duplicados no seu CRM ou banco de dados)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: localizar a identidade existente"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a identidade existente estiver correta, use-a na criação do seu pagamento ou instrumento financeiro. Se ela precisar de atualizações, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]}," para modificá-la."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-internalid-duplicado-na-atualização","__idx":6},"children":["Exemplo: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," duplicado na atualização"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Requisição:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://{base-url}/v3/identities/1d927c62-45fa-4f42-b9f8-8210e1a111bb\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"internalId\": \"customer-99999\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer-99999"]}," já estiver em uso por uma identidade ACTIVE diferente:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (409 Conflict)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"CONFLICT\",\n  \"title\": \"Identity conflict\",\n  \"description\": \"The provided internalId already exists on a different identity.\",\n  \"details\": [\n    {\n      \"field\": \"internalId\",\n      \"message\": \"An ACTIVE identity with internalId 'customer-99999' already exists (identityId: 7ea3399c-1234-5678-8d8f-d320ea406630)\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"boas-práticas-para-conflitos-de-internalid","__idx":7},"children":["Boas práticas para conflitos de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use chaves upstream estáveis"]}," – use o ID de cliente do seu CRM, o ID de cliente do core bancário ou o ID do registro mestre de KYC como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mantenha-o como a sua própria chave"]}," – você não precisa adaptar o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," para nenhum corredor. Os corredores que precisam do número da conta do ordenante leem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]},". Consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#o-n%C3%BAmero-de-conta-do-ordenante"},"children":["O número da conta do ordenante"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implemente uma lógica de criação idempotente"]}," – ao criar identidades, capture os erros 409 e localize a identidade existente em vez de falhar"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Evite PII no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]}," – não use e-mails, telefones ou documentos nacionais diretamente; use identificadores opacos"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitore os conflitos"]}," – acompanhe os erros 409 nos seus logs para identificar problemas de qualidade de dados nos sistemas upstream"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obter-uma-identidade-por-id-e-versão","__idx":8},"children":["Obter uma identidade por ID (e versão)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}"]}," para recuperar uma identidade específica."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se você omitir o parâmetro de consulta version, a versão mais recente é retornada."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para recuperar uma versão específica, inclua ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?version={version-number}"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: obter a versão mais recente"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"9d839f58-7fd3-4913-a27e-48d31973d3f9\",\n  \"identityState\": \"ACTIVE\",\n  \"nickName\": \"nickName\",\n  \"tags\": [\"tag1\"],\n  \"version\": \"2\",\n  \"schemaVersion\": \"1.0.0\",\n  \"createdAt\": \"2025-10-01T18:46:41.833Z\",\n  \"updatedAt\": \"2025-10-01T18:46:47.430Z\",\n  \"identityType\": \"BUSINESS\",\n  \"paymentRole\": \"BENEFICIARY\",\n  \"internalId\": \"counterparty-7890\",\n  \"business\": {\n    \"businessName\": \"Widgets Org\",\n    \"address\": {\n      \"streetAddress\": [\"123 Example MA\"],\n      \"country\": \"US\",\n      \"city\": \"Boston\",\n      \"stateOrProvince\": \"MS\",\n      \"postalCode\": \"12345\"\n    },\n    \"email\": \"fake@example.com\",\n    \"phone\": \"+1234567890\",\n    \"registration\": [\n      {\n        \"number\": \"123ABC\",\n        \"type\": \"INCORPORATION_CERTIFICATE\"\n      }\n    ],\n    \"incorporationCountry\": \"US\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: obter uma versão específica"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9?version=1\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Consultas versionadas"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use consultas versionadas quando precisar:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Comparar mudanças ao longo do tempo para auditoria"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Conciliar pagamentos que usaram uma versão anterior de uma identidade"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a identidade ou a versão não existir, o serviço retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obter-uma-identidade-pelo-id-interno","__idx":9},"children":["Obter uma identidade pelo ID interno"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/by-internal-id/{internal-id}"]}," para localizar uma identidade diretamente pelo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," fornecido por você, sem precisar saber antes o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," gerado pelo servidor."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este endpoint é especialmente útil para:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolver o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," de uma identidade de cliente existente quando você tem apenas a sua própria referência (por exemplo, um ID de cliente do CRM)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implementar fluxos idempotentes de criar-ou-buscar sem armazenar o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," separadamente."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tratar respostas 409 Conflict localizando imediatamente a identidade conflitante."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: localizar uma identidade pelo ID interno"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/by-internal-id/customer-12345-uuid\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"99254c4f-f207-4792-a846-06928825018c\",\n  \"identityState\": \"ACTIVE\",\n  \"identityType\": \"INDIVIDUAL\",\n  \"paymentRole\": \"ORIGINATOR\",\n  \"internalId\": \"customer-12345-uuid\",\n  \"nickName\": \"Alice Sender USD\",\n  \"tags\": [\"sender\", \"priority\"],\n  \"version\": \"1\",\n  \"schemaVersion\": \"1.0.0\",\n  \"createdAt\": \"2025-10-01T18:46:41.833Z\",\n  \"updatedAt\": \"2025-10-01T18:46:47.430Z\",\n  \"individual\": {\n    \"firstName\": \"Alice\",\n    \"lastName\": \"Chen\",\n    \"dateOfBirth\": \"1990-05-14\",\n    \"citizenship\": \"US\",\n    \"address\": {\n      \"streetAddress\": [\"123 Main Street\"],\n      \"city\": \"San Francisco\",\n      \"stateOrProvince\": \"CA\",\n      \"postalCode\": \"94105\",\n      \"country\": \"US\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Apenas identidades ACTIVE"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este endpoint retorna a identidade apenas se ela estiver ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," no momento. Se a identidade existir mas tiver sido desativada ou bloqueada, o serviço retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A consulta é restrita à sua organização. Valores de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," de outras organizações não geram conflito."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Respostas de erro:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – não existe nenhuma identidade ACTIVE com o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," especificado na sua organização"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listar-identidades","__idx":10},"children":["Listar identidades"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities"]}," para recuperar as identidades da sua organização com filtros e paginação opcionais."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parâmetros de consulta compatíveis:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment-role"]}," – filtra por papel de pagamento (ORIGINATOR ou BENEFICIARY)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nick-name"]}," – filtra por apelido (correspondência exata)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," – número máximo de identidades a retornar (de 1 a 100, padrão 10)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," – token opaco retornado em uma resposta anterior, usado para buscar a próxima página"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: listar identidades por papel"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"identityId\": \"0116bacc-ffbf-4fa2-a29c-ecd9ea346806\",\n      \"identityType\": \"BUSINESS\",\n      \"paymentRole\": \"BENEFICIARY\",\n      \"createdAt\": \"2025-10-01T16:14:13.200Z\",\n      \"updatedAt\": \"2025-10-01T16:14:15.763Z\",\n      \"identityState\": \"ACTIVE\",\n      \"nickName\": \"testNickName\",\n      \"tags\": [\"tag1\"],\n      \"version\": 2,\n      \"schemaVersion\": \"1.0.0\",\n      \"internalId\": \"counterparty-7890\"\n    },\n    {\n      \"identityId\": \"1d927c62-45fa-4f42-b9f8-8210e1a111bb\",\n      \"identityType\": \"INDIVIDUAL\",\n      \"paymentRole\": \"ORIGINATOR\",\n      \"createdAt\": \"2025-10-01T17:20:05.111Z\",\n      \"updatedAt\": \"2025-10-01T17:20:06.500Z\",\n      \"identityState\": \"ACTIVE\",\n      \"nickName\": \"Alice Originator\",\n      \"tags\": [\"sender\", \"priority\"],\n      \"version\": 1,\n      \"schemaVersion\": \"1.0.0\",\n      \"internalId\": \"customer-12345-uuid\"\n    }\n  ],\n  \"nextToken\": \"eyJrZXkxIjoidmFsdWUifQ==\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se você receber um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]},", devolva-o como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," para buscar a próxima página:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2&next-token=eyJrZXkxIjoidmFsdWUifQ==\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Nenhuma identidade encontrada"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se nenhuma identidade corresponder aos seus filtros, o serviço retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"atualizar-uma-identidade","__idx":11},"children":["Atualizar uma identidade"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]}," para atualizar uma identidade existente."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cada atualização bem-sucedida cria uma ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nova versão da identidade"]},". O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," nunca muda, e as versões anteriores continuam disponíveis para consulta e auditoria. O corpo da requisição aceita ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["atualizações parciais"]},". Inclua apenas os campos que você quer alterar."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Você pode atualizar:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Metadados: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PII: qualquer campo dentro de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," (precisa continuar único entre todas as identidades ACTIVE)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," (revalida o PII contra os rails especificados)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," e o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRole"]}," não podem ser alterados após a criação."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para ver exemplos completos, tratamento de erros e orientações sobre a atualização de identidades BLOCKED, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/developer-guides/update-an-identity"},"children":["Atualizar uma identidade"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"desativar-uma-identidade","__idx":12},"children":["Desativar uma identidade"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v3/identities/{identity-id}"]}," para desativar uma identidade."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A desativação:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define o estado da identidade como ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DEACTIVATED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Desativa os ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["instrumentos financeiros"]}," associados à identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Impede que ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["novos pagamentos"]}," usem esta identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mantém as versões históricas disponíveis para auditoria"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Permanente"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A desativação é ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["permanente"]},"; não é possível reativar uma identidade desativada."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: desativar uma identidade"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE \"https://{base-url}/v3/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta (204 No Content) – a identidade foi desativada com sucesso."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Respostas de erro:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," – requisição malformada ou formato inválido de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – a identidade não existe"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["422 Unprocessable Entity"]}," – a identidade já está desativada ou não pode ser desativada (por exemplo, por restrições internas)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratamento-de-erros-e-validação","__idx":13},"children":["Tratamento de erros e validação"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os endpoints de identidade usam um schema padrão de resposta de erro com:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["code"]}," – código de erro legível por máquina"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["title"]}," – resumo curto legível por humanos"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["description"]}," – explicação detalhada e sugestões de correção"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Casos comuns:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," – campos ausentes ou inválidos na requisição, ou identidade reprovada nas regras de validação específicas do corredor"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]}," – identidade não encontrada (para um ID, versão ou consulta específicos)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409"]}," – conflito de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," (outra identidade ACTIVE já usa o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["422"]}," – transição de ciclo de vida inválida (por exemplo, tentar desativar uma identidade já desativada)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," – erro interno de processamento; tente novamente ou entre em contato com o suporte se persistir"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consulte a seção geral de ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors"},"children":["Tratamento de erros"]}," da documentação da API para ver a lista completa de códigos de erro."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":14},"children":["Próximos passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para uma explicação mais aprofundada do modelo de identidade, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities"},"children":["Identidades do pagamento"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para ver exemplos completos de atualização e orientações sobre versionamento imutável, validação de payment rail e reativação de identidades BLOCKED, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/developer-guides/update-an-identity"},"children":["Atualizar uma identidade"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para saber como vincular dados de conta de payout às identidades (contas bancárias, carteiras, payment rails locais), continue com ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments"},"children":["Criar e gerenciar instrumentos financeiros"]},"."]}]}]},"headings":[{"value":"Criar e gerenciar identidades","id":"criar-e-gerenciar-identidades","depth":1},{"value":"Antes de começar","id":"antes-de-começar","depth":2},{"value":"Criar uma identidade","id":"criar-uma-identidade","depth":2},{"value":"Tratamento de conflitos de internalId (409 Conflict)","id":"tratamento-de-conflitos-de-internalid-409-conflict","depth":2},{"value":"Exemplo: internalId duplicado na criação","id":"exemplo-internalid-duplicado-na-criação","depth":3},{"value":"Como tratar o 409 Conflict","id":"como-tratar-o-409-conflict","depth":3},{"value":"Exemplo: internalId duplicado na atualização","id":"exemplo-internalid-duplicado-na-atualização","depth":3},{"value":"Boas práticas para conflitos de internalId","id":"boas-práticas-para-conflitos-de-internalid","depth":3},{"value":"Obter uma identidade por ID (e versão)","id":"obter-uma-identidade-por-id-e-versão","depth":2},{"value":"Obter uma identidade pelo ID interno","id":"obter-uma-identidade-pelo-id-interno","depth":2},{"value":"Listar identidades","id":"listar-identidades","depth":2},{"value":"Atualizar uma identidade","id":"atualizar-uma-identidade","depth":2},{"value":"Desativar uma identidade","id":"desativar-uma-identidade","depth":2},{"value":"Tratamento de erros e validação","id":"tratamento-de-erros-e-validação","depth":2},{"value":"Próximos passos","id":"próximos-passos","depth":2}],"frontmatter":{"title":"Criar e gerenciar identidades","toc":{"enable":true,"maxDepth":2},"seo":{"title":"Criar e gerenciar identidades"}},"lastModified":"2026-10-21T04:11:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}