> ## 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.

# Callback unificado do step de assinatura

> Envie os values do template ou as URLs dos documentos em tempo de execução do step de assinatura, informando o requestId como parâmetro de caminho.

Use `POST /onboarding/api/v1/steps/signer/{requestId}/values` para informar ao onboarding, em tempo de execução do step de assinatura, qual documento deve ser apresentado ao usuário. A requisição requer o `requestId` como parâmetro de caminho e espera receber os valores que preenchem um template previamente configurado ou as URLs públicas dos documentos a serem assinados.

Esse endpoint é o retorno do callback unificado: quando o usuário atinge a etapa de assinatura, o onboarding aciona a API externa configurada no projeto e aguarda essa chamada para carregar o documento. Os modelos de integração da etapa de assinatura estão descritos em [Fluxo de assinatura no onboarding](/plataforma/onboarding/assinatura-digital).

Requisito: é necessário enviar o header de autenticação, mais informações [aqui](/plataforma/autenticacao-api)

## Path Parameters

<ParamField path="requestId" type="string" required>
  O ID único da requisição de processo em execução, no formato UUID. Corresponde ao `id` recebido na chamada que o onboarding faz para a API externa.

  **Exemplo**: `05be75cc-8f8a-414a-891f-434aa9b4e7a5`
</ParamField>

## Request Body

Envie `templateId` e `values` para preencher dinamicamente um template configurado, **ou** `urls` para apontar documentos já gerados por um sistema externo. As duas formas são mutuamente exclusivas e não devem ser combinadas na mesma chamada.

<ParamField body="templateId" type="string">
  Identificador do template de documento configurado para o projeto, no formato UUID.

  **Exemplo**: `05be75cc-8f8a-414a-891f-434aa9b4e7a5`
</ParamField>

<ParamField body="values" type="object">
  Pares de chave e valor que preenchem os campos (placeholders) do template informado em `templateId`. Os campos aceitos são definidos junto ao time de Suporte na configuração do template.

  **Exemplo**: `{ "nome": "João Silva", "cpf": "12345678900" }`
</ParamField>

<ParamField body="urls" type="string[]">
  Lista de URLs públicas dos documentos a serem apresentados e assinados pelo usuário.

  **Exemplo**: `["https://cliente.example.com/doc1.pdf"]`
</ParamField>

<ParamField body="externalId" type="string">
  Identificador externo do processo, definido pelo integrador.

  **Exemplo**: `cliente-123`
</ParamField>

### Exemplo de requisição

```bash theme={"theme":"catppuccin-latte"}
curl --location 'https://api.valid.com/onboarding/api/v1/steps/signer/05be75cc-8f8a-414a-891f-434aa9b4e7a5/values' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: <API KEY>' \
--data '{
  "urls": [
    "https://cliente.example.com/doc1.pdf"
  ],
  "externalId": "cliente-123"
}'
```

## Response

Em caso de sucesso, a API retorna o status `200 OK` sem corpo de resposta.

## Respostas de Erro

A API pode retornar os status `400` (Bad request), `422` (Validation or semantic error) e `500` (Internal server error), seguindo o modelo padrão de erro da aplicação.

<ResponseField name="code" type="string" required>
  Código do erro que categoriza o tipo de erro.

  **Exemplo**: `VALIDATION_ERROR`
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem de erro.

  **Exemplo**: `The request is invalid`
</ResponseField>

<ResponseField name="details" type="object[]">
  Lista contendo ou não um erro detalhado.

  * `field` (`string`): caminho do campo incorreto ou inválido. **Exemplo**: `name`
  * `message` (`string`): mensagem de erro do campo. **Exemplo**: `The field cannot be blank`
</ResponseField>