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

# Consulta Bureau Async por pacote

> Consulte PF ou PJ com retorno assincrono via webhook, reutilizando um pacote de datasets previamente criado.

Use a mesma URI de consulta assincrona (`POST /bureau/api/v1/bureau/person/async`) quando quiser **reutilizar um pacote de datasets** criado previamente, informando o ID do pacote no campo `datasetPackageId`, com resultado entregue via webhook.

<Card title="Async por datasets" icon="list" href="/plataforma/background-check/bureau-person/api/post-person-async">
  Escolha quais datasets consultar
</Card>

## Request Body

<ParamField body="key" type="string" required>
  CPF ou CNPJ da pessoa

  **Exemplo**: `12345678901`
</ParamField>

<ParamField body="datasetPackageId" type="string" required>
  ID do pacote de datasets

  **Formato**: UUID

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

<ParamField body="webhookUrl" type="string" required>
  URL de callback para receber o resultado

  **Formato**: URI

  **Exemplo**: `https://seusistema.com/webhook`
</ParamField>

<ParamField body="webhookBasicAuth" type="string">
  Autenticacao basica para o webhook (username:password)

  **Exemplo**: `usuario:senha`
</ParamField>

<ParamField body="refreshData" type="boolean">
  Forca a busca de dados atualizados

  **Exemplo**: `true`
</ParamField>

Consulte [Pacote de Datasets](/plataforma/background-check/dataset-package/o-que-sao) para criar e gerenciar pacotes.

## Response

Retorna confirmacao de recebimento/processamento da consulta. O resultado final e entregue no webhook informado.

<ResponseField name="requestId" type="string">
  ID da requisicao

  **Formato**: UUID
</ResponseField>

<ResponseField name="createdAt" type="string">
  Data de criacao da requisicao

  **Exemplo**: `2026-03-12T10:30:00Z`
</ResponseField>

<ResponseField name="status" type="string">
  Status inicial da requisicao

  **Valor**: `PROCESSING`
</ResponseField>

<ResponseField name="datasetPackage" type="object">
  Metadados do pacote utilizado (`id`, `name`), quando informado no request.
</ResponseField>

### Exemplo de sucesso (`200 OK`)

```json theme={"theme":"catppuccin-latte"}
{
  "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
  "createdAt": "2026-03-12T10:30:00Z",
  "status": "PROCESSING",
  "datasetPackage": {
    "id": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
    "name": "Pacote antifraude PF"
  }
}
```

## Webhook Content

O payload enviado para o webhook contem o resultado da consulta solicitada, no mesmo formato da resposta sincrona (`PersonResultResponseDto`).

<ResponseField name="requestId" type="string">
  ID da requisicao
</ResponseField>

<ResponseField name="createdAt" type="string">
  Data de criacao da requisicao
</ResponseField>

<ResponseField name="key" type="string">
  CPF ou CNPJ consultado
</ResponseField>

<ResponseField name="status" type="string">
  Status final da consulta

  **Valores possiveis**: `FINISHED`, `FAILED`
</ResponseField>

<ResponseField name="datasets" type="object[]">
  Datasets processados com sucesso
</ResponseField>

<ResponseField name="failedDatasets" type="object[]">
  Datasets que falharam no processamento. Cada item contem `dataset` e `reason`.
</ResponseField>

<ResponseField name="datasetPackage" type="object">
  Metadados do pacote utilizado (`id`, `name`).
</ResponseField>

### Exemplo de payload do webhook

```json theme={"theme":"catppuccin-latte"}
{
  "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
  "createdAt": "2026-03-12T10:30:00.000Z",
  "key": "12345678900",
  "status": "FINISHED",
  "datasetPackage": {
    "id": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
    "name": "Pacote antifraude PF"
  },
  "datasets": [
    {
      "dataset": "basic",
      "data": {
        "document": "12345678900",
        "name": "Joao da Silva",
        "motherName": "Maria da Silva",
        "birthDate": "1990-05-21",
        "status": "REGULAR"
      }
    },
    {
      "dataset": "addresses",
      "data": {
        "addresses": [
          {
            "street": "Rua das Flores",
            "number": "123",
            "complement": "Apto 45",
            "district": "Centro",
            "city": "Sao Paulo",
            "state": "SP",
            "zipCode": "01001-000",
            "country": "BR"
          }
        ]
      }
    }
  ],
  "failedDatasets": []
}
```

### Exemplo com falha parcial no webhook

```json theme={"theme":"catppuccin-latte"}
{
  "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
  "createdAt": "2026-03-12T10:30:00.000Z",
  "key": "12345678900",
  "status": "FAILED",
  "datasetPackage": {
    "id": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
    "name": "Pacote antifraude PF"
  },
  "datasets": [
    {
      "dataset": "basic",
      "data": {
        "document": "12345678900",
        "name": "Joao da Silva",
        "status": "REGULAR"
      }
    }
  ],
  "failedDatasets": [
    {
      "dataset": "pgfn_certificate_person",
      "reason": "[ondemand_pgfn_person] DATASET IS TOO SLOW. PLEASE TRY AGAIN IN A FEW MINUTES"
    }
  ]
}
```

## Respostas de Erro

<ResponseField name="code" type="string">
  Codigo do erro que categoriza o tipo de erro

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

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

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