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

# Gerenciar aliases de Virtual Accounts

A Localpayment permite criar e gerenciar aliases para contas virtuais na Argentina, oferecendo referências fáceis de memorizar que podem ser usadas no lugar dos números de CVU para pagamentos.

Os aliases simplificam o processo de pagamento ao substituir um CVU de 22 dígitos por uma cadeia de texto curta e legível, mais fácil de compartilhar e lembrar.

## Disponibilidade

O gerenciamento de aliases de contas virtuais está disponível nos seguintes países:

| País | Operações apoiadas | Tipos de alias suportados |
| - | - | :- |
| [Argentina](https://docs.localpayment.com/pt-br/docs/argentina.md) | Definir alias | Personalizável (`C`): texto definido pelo usuário |
| [Brasil](https://docs.localpayment.com/pt-br/docs/brazil.md) | N / D | |
| [Colômbia](https://docs.localpayment.com/pt-br/docs/colombia.md) | N / D | |
| [México](https://docs.localpayment.com/pt-br/docs/mexico.md) | N / D | |
| [Peru](https://docs.localpayment.com/pt-br/docs/peru.md) | N / D | |

***

## Antes de começar

Certifique-se de ter:

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).
* O `externalId` de uma conta virtual ativa com status `COMPLETED`.

> [!WARNING]
>
> Uma conta virtual deve estar com status `COMPLETED` antes que você possa atribuir um alias a ela. Essa transição de status é automática.

***

## Como os aliases funcionam na Argentina

A Argentina oferece suporte a **aliases de CVU** para contas virtuais. Principais características:

* **Formato**: Apenas letras (a–z, A–Z), números (0–9) e pontos (`.`). Sem espaços, hifens, sublinhados ou caracteres especiais.
* **Comprimento**: Entre **5 e 20 caracteres**.
* **Unicidade**: O alias deve ser único em nível de país. Isso não é uma restrição da plataforma, mas um requisito do sistema bancário argentino. Se outra CVU já usar o mesmo alias, a solicitação será rejeitada.
* **Atualização de um alias**: Para atualizar um alias, chame o mesmo endpoint com o novo valor depois que o período de espera necessário tiver decorrido.
* **Limite de alterações**: Depois de definido ou atualizado, um alias não pode ser alterado novamente por **24 horas**. O alias pode ser atualizado no máximo **10 vezes** no total.
* **Ativação assíncrona**: O alias é ativado em segundo plano. Uma resposta `INPROGRESS` não significa que o alias já esteja ativo. Verifique a ativação usando [Obtenha o status da sua Virtual Account](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md).

**Exemplos de alias válidos:** `alias.example` · `alias.example2026` · `alias.example.test`

**Exemplos de alias inválidos:** `alias example` (espaço) · `alias-example` (hífen) · `alias_example` (sublinhado) · `alias@example` (arroba)

***

## Definir alias da Virtual Account

Defina um alias personalizado para uma conta virtual ativa existente. Esta operação atribui um novo alias e também atualiza um alias existente. O mesmo endpoint trata ambos os casos.

### Parâmetros-chave da solicitação

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| externalId | O ID externo da conta virtual (parâmetro de caminho). | ✅ |
| type | Tipo de alias. Para a Argentina, o único valor válido é `C` (Personalizável). | ✅ |
| value | O texto do alias desejado. Apenas letras, números e pontos (`.`) são permitidos. Entre 5 e 20 caracteres. | ✅ |

### Exemplo de solicitação

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "type": "C",
  "value": "alias.example"
}'
```

Consulte todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/create-an-alias-to-a-virtual-account.md) na referência da API.

### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
```

> [!NOTE]
>
> O status `INPROGRESS` significa que a solicitação foi recebida e está sendo processada de forma assíncrona. O alias **ainda não está ativo**. Use o endpoint [Obtenha o status da sua Virtual Account](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) para confirmar a ativação antes de notificar seus usuários finais.

### Verificar a ativação do alias

Depois de receber uma resposta `INPROGRESS`, consulte a conta virtual para confirmar que o alias está ativo. Envie uma solicitação `GET` ao endpoint de status individual:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId} \
     --header 'Authorization: Bearer <your_access_token>'
```

Quando o alias estiver ativo, ele aparecerá em `beneficiary.bank.account.alias`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "currency": "ARS",
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "accountNumber": "0000003100099999999015",
    "beneficiary": {
        "type": "COMPANY",
        "name": "Example Company S.A.",
        "fullName": "Example Company S.A.",
        "document": {
            "type": "CUIT",
            "id": "30-71234567-9"
        },
        "bank": {
            "account": {
                "number": "0000003100099999999015",
                "alias": [
                    {
                        "type": "C",
                        "value": "alias.example"
                    }
                ]
            }
        }
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "Virtual account has been created"
    },
    "errors": [],
    "disabled": false
}
```

Se a configuração do alias falhar de forma assíncrona após uma resposta `INPROGRESS`, o erro aparecerá no array `errors` desta mesma resposta. Consulte o endpoint de status repetidamente até que `errors` esteja vazio e o alias esteja visível em `beneficiary.bank.account.alias`.

### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `externalId` | O ID externo da conta virtual para a qual o alias foi solicitado. |
| `alias.type` | O tipo de alias informado na solicitação (`C`). |
| `alias.value` | O valor do alias informado na solicitação. |
| `status.code` | `100`: operação em andamento. |
| `status.description` | `INPROGRESS`: a ativação do alias está sendo processada de forma assíncrona. |

### Respostas de erro

Os códigos de erro a seguir se aplicam à resposta **síncrona**. Se a resposta inicial for `INPROGRESS`, a operação foi aceita, mas ainda podem ocorrer erros durante o processamento assíncrono. Para detectá-los, consulte [Obtenha o status da sua Virtual Account](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) e verifique o array `errors`.

| Código | Descrição | Detalhe |
| :-: | - | - |
| `776` | `REJECTED` | O apelido já está em uso; selecione um apelido diferente. |
| `777` | `REJECTED` | O apelido é inválido; por favor, insira um apelido válido. |
| `778` | `REJECTED` | O apelido não pode ser alterado agora; você precisa aguardar 24 horas após a última atualização. |
| `779` | `REJECTED` | Erro de sistema ao gerar o alias. |
| `896` | `REJECTED` | Alias já atribuído a esta conta virtual. |

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "776",
        "description": "REJECTED",
        "detail": "The alias is already in use; please select a different alias."
    }
}
```

### Cenários de erro comuns

| Código | Causa | Correção recomendada |
| :-: | - | - |
| `776` | Alias já em uso por outra CVU. | Escolha um valor de alias diferente e único. |
| `777` | O alias contém caracteres inválidos, formato incorreto ou comprimento fora do intervalo de 5 a 20 caracteres. | Verifique o campo `value`: apenas letras, números e pontos (`.`) são permitidos, entre 5 e 20 caracteres. |
| `778` | O período de 24 horas para alteração não decorreu desde a última atualização do alias. | Aguarde pelo menos 24 horas antes de tentar novamente. |
| `779` | Erro interno do sistema durante a geração do alias. | Tente a solicitação novamente. Se o problema persistir, entre em contato com o [suporte](mailto:support@localpayment.com). |
| `896` | Alias já atribuído a esta conta virtual. | Use [Obtenha o status da sua Virtual Account](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) para verificar o alias já associado à conta. |

***

## Demonstração

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/7d467db90140ec74c2c8a18e6b4f82d35cebfd2a0e54808f985ea2f228593b48-Demo-Alias-Arg.gif?s=c4dadb3971e23eda32c49653dd86840e)

***

## Próximos passos

> [card] [Criar contas virtuais](https://docs.localpayment.com/pt-br/docs/create-a-virtual-account.md)
>
> Gere novas contas virtuais que podem ser aprimoradas com pseudônimos.

> [card] [Gerenciar o status da conta virtual](https://docs.localpayment.com/pt-br/docs/get-virtual-account-status.md)
>
> Verifique o status das contas virtuais e seus respectivos aliases.

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/create-an-alias-to-a-virtual-account.md)
>
> Referência completa de parâmetros do endpoint Definir alias.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.