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

# Cadastrar origem no VIDaaS

> Registra uma origem (domínio) do seu front-end como endereço de retorno válido no VIDaaS.

Cadastra uma origem do seu front-end como endereço de retorno autorizado no VIDaaS. O VIDaaS só redireciona o navegador de volta para endereços previamente cadastrados; este endpoint gerencia esse cadastro.

A operação é **idempotente**: registrar uma origem já cadastrada não dispara uma chamada ao provedor. Use o parâmetro `force` para reenviar ao provedor mesmo que localmente conste como registrada (útil se o cadastro foi perdido do lado do VIDaaS).

**Autenticação**: use uma chave de API (`x-api-key`).

## Parâmetros

<ParamField body="origin" type="string" required>
  Origem do front a cadastrar (esquema + host + porta, sem caminho). Exemplos: `https://assinador.cliente.com.br`, `https://localhost:3000`, `https://app.valid.com:8443`.

  O caminho (tudo após a porta) é ignorado — o VIDaaS sempre usa um caminho fixo de retorno (`/sign/vidaas/callback`).
</ParamField>

<ParamField body="force" type="boolean" optional>
  Se `true`, reenvia o cadastro ao provedor VIDaaS mesmo que a origem conste como já registrada localmente. Use quando o cadastro tiver sido perdido ou sobrescrito do lado do provedor. Padrão: `false`.
</ParamField>

## Respostas

<ResponseField name="uuid" type="string" required>
  Identificador do cadastro.
</ResponseField>

<ResponseField name="origin" type="string" required>
  Origem normalizada (como foi registrada).
</ResponseField>

<ResponseField name="redirectUri" type="string" required>
  URI completa de retorno (origem + caminho fixo). Exemplo: `https://assinador.cliente.com.br/sign/vidaas/callback`.
</ResponseField>

<ResponseField name="projectId" type="string" optional>
  Tenant da Platform (extraído da chave de API).
</ResponseField>

<ResponseField name="status" type="string" required>
  Status do cadastro no provedor:

  * `PENDING`: enviado ao provedor mas ainda aguardando confirmação.
  * `REGISTERED`: aceito e registrado no provedor.
  * `FAILED`: o provedor recusou o cadastro (veja `lastError`).
</ResponseField>

<ResponseField name="registeredAt" type="string" optional>
  Timestamp (ISO-8601) de quando o cadastro foi aceito pelo provedor. Presente apenas quando `status` = `REGISTERED`.
</ResponseField>

<ResponseField name="lastError" type="string" optional>
  Descrição da última falha no cadastro. Presente apenas quando `status` = `FAILED`.
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao).

* **400**: `origin` inválido ou validação falhou (ex: URL malformada, esquema não é `http` ou `https`).
* **401**: Chave de API inválida ou expirada.
* **502**: O VIDaaS não respondeu ou recusou o cadastro.
* **503**: Integração VIDaaS não configurada no ambiente.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "origin": "https://assinador.cliente.com.br",
    "redirectUri": "https://assinador.cliente.com.br/sign/vidaas/callback",
    "projectId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "status": "REGISTERED",
    "registeredAt": "2025-07-27T10:30:00Z",
    "lastError": null
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "uuid": "550e8400-e29b-41d4-a716-446655440001",
    "origin": "https://assinador-dev.cliente.com.br",
    "redirectUri": "https://assinador-dev.cliente.com.br/sign/vidaas/callback",
    "projectId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "status": "PENDING",
    "registeredAt": null,
    "lastError": null
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 401 Unauthorized
  Content-Type: application/json

  {
    "statusCode": 401,
    "message": "Invalid API Key"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/vidaas/redirect-uris" \
  -H "x-api-key: SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://assinador.cliente.com.br",
    "force": false
  }'
```

## Importante

* **Autenticação por API Key**: este é um endpoint administrativo — use sua chave de API.
* **Caminho fixo de retorno**: independente de qual `origin` você registra, o caminho de retorno é sempre `/sign/vidaas/callback`. Se seu front precisa de um caminho diferente, configure um alias/redirecionador.
* **Múltiplas origens**: você pode registrar quantas origens precisar (desenvolvimento, homologação, produção, etc.).
* **Normalização**: a origem é normalizada (trailing slashes e portas implícitas são removidos/padronizados).

## Próximas etapas

1. Após registrar uma origem com sucesso, o VIDaaS começará a aceitar redirecionamentos para `https://origin/sign/vidaas/callback`.
2. Quando o signatário autorizar via QR Code, o VIDaaS o redireciona para este endereço.
3. Seu front extrai o `code` da URL e chama [`POST /signer/v1/sign/:sessionToken/vidaas/authorization/callback`](/plataforma/assinatura-digital/api/post-vidaas-authorization-callback).