> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-3ds-3d-secure.md).

# Pedido com 3DS (3D Secure)

Este guia descreve o fluxo completo para criação de pedidos utilizando 3D Secure (3DS), incluindo a criação da sessão, coleta de dados do navegador e, quando necessário, o desafio de autenticação (Ste

***

### 1. Criar Card Token (Tokenização de Cartão)

A tokenização permite armazenar o cartão de forma segura para uso posterior.

#### Endpoint

```
POST /payment/v1/cards
https://api.barte.com/payment/v1/cards
```

#### Body

```json
{
  "holderName": "JOSE DAS NEVES TEST",
  "number": "5383638854440891",
  "cvv": "220",
  "expiration": "12/2025",
  "checkZeroDollar": true,
  "buyerUuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```

#### Response

```json
{
  "uuid": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
  "status": "ACTIVE",
  "cardId": "83d353d2-716f-45cf-837f-50c18f10efa0"
}
```

⚠️ **Importante**

* O **cardToken** utilizado na transação é o campo **uuid**
* O campo **cardId** será utilizado **apenas na criação da sessão 3DS**
* Caso `checkZeroDollar` seja `false`, o token pode iniciar com status `PENDING` e será atualizado para `ACTIVE` após a primeira transação bem-sucedida

***

### 2. Criar sessão 3DS

A sessão 3DS é necessária para iniciar o processo de autenticação.

#### Endpoint

```
POST /v1/3ds/session
https://api.barte.com/v1/3ds/session
```

#### Body

```json
{
  "sourceType": "card",
  "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

#### Response

Status `200`.

```json
{
  "id": "authn_8Kq2Xw7nLp4Rt9Vb3Ycz",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "collectUrl": "https://pay.barte.com/public/3ds/entry/collect/authn_8Kq2Xw7nLp4Rt9Vb3Ycz",
  "providerType": "NETCETERA"
}
```

📌 Guarde:

* **id** → será enviado como `setupId` na criação do pedido
* **token** e **collectUrl** → usados na coleta de dados do navegador

Crie a sessão 3DS só quando o pedido for com 3DS. Depois de criar a sessão, envie o pedido com `threeDSecure.setupId` igual ao `id` dela; um pedido sem o bloco `threeDSecure` não usa a sessão, e ela fica aberta sem efeito.

O `providerType` é um identificador interno de quem conduz a autenticação; não use esse valor na sua integração, porque ele pode mudar sem aviso. O fluxo de integração é o mesmo em todos os casos; o que muda está descrito no passo 5.

***

### 3. Coletar dados do navegador (Browser Data Collection)

Antes de criar o pedido, é obrigatório coletar os dados do navegador do cliente.

#### Objetivo

Enviar informações de background do navegador para o provedor 3DS.

O navegador envia o `token` para a `collectUrl` com um `POST` de formulário, no campo `JWT`, como no script abaixo. A `collectUrl` não aceita `GET`: abrir a URL por link, redirect ou `fetch` sem formulário devolve `405` e a coleta não acontece.

#### Script de coleta

```html
<div style="display: none;">
  <iframe id="cardinal_collection_iframe" name="collectionIframe" height="1" width="1"></iframe>
  <form id="cardinal_collection_form" method="POST" target="collectionIframe">
    <input id="cardinal_collection_form_input" type="text" name="JWT" value="">
  </form>
</div>

<script>
  const collectUrl = '<collectUrl>';
  const token = '<token>';

  const docFormCardinal = document.getElementById('cardinal_collection_form');
  const docInputCardinal = document.getElementById('cardinal_collection_form_input');

  docFormCardinal.action = collectUrl;
  docInputCardinal.value = token;
  docFormCardinal.submit();

  window.addEventListener("message", function (event) {
    const origin = new URL(collectUrl).origin;
    if (event.origin === origin) {
      const data = JSON.parse(event.data);
      console.log('COLETA FINALIZADA:', data);
    }
  });
</script>
```

⚠️ **Importante**

* O seller deve aguardar a finalização da coleta antes de criar o pedido
* A coleta é rápida (≈ 1 segundo)

***

### 4. Criar pedido com 3DS

Após a coleta, o pedido pode ser criado informando os dados de 3DS.

#### Endpoint

```
POST /v2/orders
https://api.barte.com/v2/orders
```

#### Body (exemplo)

```json
{
  "startDate": "2026-01-30",
  "value": 100,
  "installments": 1,
  "urlCallBack": "https://webhook.site/unique-id",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "payment": {
    "method": "CREDIT_CARD_EARLY_SELLER",
    "card": {
      "cardToken": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
      "cvv": "220"
    },
    "fraudData": {
      "document": "48637879012",
      "name": "John Doe",
      "email": "johndoe@barte.com",
      "phone": "34999991111",
      "billingAddress": {
        "country": "BR",
        "state": "Minas Gerais",
        "city": "Uberlândia",
        "district": "Jardim Europa",
        "street": "Rua Orleans",
        "zipCode": "38414552",
        "number": "100",
        "complement": "Bloco A"
      }
    }
  },
  "threeDSecure": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "setupId": "authn_8Kq2Xw7nLp4Rt9Vb3Ycz",
    "redirectURL": "https://meudominio.com/checkout.html",
    "requestorURL": "https://meudominio.com",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "colorDepth": 24,
      "screenHeight": 1080,
      "screenWidth": 1920,
      "timeZoneOffset": "-180",
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "billingAddress": {
      "country": "BR",
      "state": "Minas Gerais",
      "city": "Uberlândia",
      "district": "Jardim Europa",
      "street": "Rua Orleans",
      "zipCode": "38414552",
      "streetNumber": "100"
    },
    "shippingAddress": {
      "city": "Uberlândia",
      "country": "BR",
      "streetNumber": "123",
      "zipCode": "38411999",
      "state": "MG",
      "street": "Rua Exemplo"
    },
    "cardHolder": {
      "email": "johndoe@barte.com",
      "mobilePhone": "34999991111"
    }
  },
  "uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```

📌 Sobre os campos de `threeDSecure`:

* `setupId` → `id` da sessão criada no passo 2
* `redirectURL` → página da sua loja para onde o comprador volta depois do desafio (use `https`)
* `browser` → quando enviado, todos os campos são obrigatórios: `ip`, `userAgent`, `acceptHeader`, `language`, `colorDepth`, `screenHeight`, `screenWidth`, `timeZoneOffset`, `javaEnabled` e `javaScriptEnabled`
* `browser.timeZoneOffset` → diferença do fuso do navegador do comprador para o UTC, em minutos, com o sinal de `-new Date().getTimezoneOffset()`. No horário de Brasília (UTC-3) o valor é `"-180"`, não `"180"`. Com o sinal trocado, o banco emissor recebe o comprador em outro fuso (UTC+3) e isso pesa contra na análise de risco
* `browser.ip` → o IP público do comprador, lido no seu servidor na borda (o primeiro IP confiável do `X-Forwarded-For` ou o cabeçalho do seu CDN, como `CF-Connecting-IP`), em IPv4 (`0.0.0.0`) ou IPv6 no formato padrão. Não envie o IP interno do seu servidor, proxy ou container (faixas privadas como `10.x`, `172.16.x` a `172.31.x` e `192.168.x`) nem o IPv6 mapeado (`::ffff:...`) em outra notação: um IP fora desses formatos é descartado e a autenticação segue sem ele
* `browser.acceptHeader` → o cabeçalho `Accept` da página de checkout carregada pelo comprador (por exemplo `text/html,application/xhtml+xml,...`), lido no seu servidor. Não use o `Accept` de uma chamada de API (`application/json, text/plain, */*`)
* Os campos lidos no navegador podem ser coletados assim:

```javascript
const browser = {
  userAgent: navigator.userAgent,
  language: navigator.language,
  colorDepth: screen.colorDepth,
  screenHeight: screen.height,
  screenWidth: screen.width,
  timeZoneOffset: String(-new Date().getTimezoneOffset()),
  javaEnabled: false,
  javaScriptEnabled: true
};
```

* Os demais campos não são exigidos pela validação da API, mas o banco emissor pode recusar a autenticação por falta de dados (veja o `BAR-1808` em "Erros na autenticação 3DS", abaixo)

#### Response (resumo)

```json
{
  "uuid": "4668ab70-39c3-4ab3-8770-995f6333e200",
  "status": "SENT",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "value": 100,
  "installments": 1,
  "startDate": "2026-01-30",
  "payment": "CREDIT_CARD_EARLY_SELLER",
  "customer": {
    "document": "48637879012",
    "type": "CPF",
    "documentCountry": "BR",
    "name": "John Doe",
    "email": "johndoe@barte.com",
    "phone": "34999991111",
    "alternativeEmail": "johndoealt@barte.copm",
    "integrationCustomerId": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
  },
  "idempotencyKey": "5e643a79-3b3f-4db9-95a3-a998caf914ff",
  "subSellerPaymentResponse": [
    {}
  ],
  "charges": [
    {
      "uuid": "27dccdbb-73a9-4799-93c9-e30e2c71cc75",
      "title": "Compra Exemplo",
      "expirationDate": "2026-01-30",
      "value": 100,
      "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
      "status": "SCHEDULED",
      "customer": {
        "document": "48637879012",
        "type": "CPF",
        "name": "John Doe",
        "email": "johndoe@barte.com",
        "phone": "34999991111",
        "alternativeEmail": "johndoealt@barte.com"
      }
    }
  ],
  "three3DSSecure": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "redirectURL": "https://meudominio.com/checkout.html",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "screenHeight": 1080,
      "screenWidth": 1920,
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "auth": {
      "action": "REDIRECT",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "stepUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp"
    },
    "challenged": true,
    "authenticated": false,
    "offeredType": "Challenge",
    "liabilityShift": false
  }
}
```

⚠️ **Nome do objeto de 3DS na resposta**

* Na resposta da criação do pedido (`POST /v2/orders`), o objeto se chama `three3DSSecure`
* Na consulta do pedido (`GET /v2/orders/{uuid}`), o mesmo objeto vem como `threeDSSecure`
* Quando o pedido não tem 3DS, o objeto não vem na resposta

***

### 5. Desafio 3DS (Step Up Challenge)

O desafio só é necessário quando a resposta da criação do pedido traz:

```
three3DSSecure.challenged = true
three3DSSecure.auth.action = REDIRECT
```

Nesse caso, o pedido fica `SENT` e a cobrança fica `SCHEDULED` até o comprador concluir o desafio. Não existe endpoint da API para o desafio: você envia o navegador do comprador para o `auth.stepUrl`, com um `POST` de formulário que leva o `auth.token` no campo `JWT`.

#### Passo a passo

1. Crie a sessão 3DS (passo 2) e guarde o `id`.
2. Crie o pedido com `threeDSecure.setupId` igual ao `id` da sessão e com o `threeDSecure.redirectURL` da sua loja (passo 4).
3. Leia `three3DSSecure.auth` na resposta: `action`, `token` e `stepUrl`.
4. Envie o comprador para o `stepUrl` com o script abaixo.
5. O comprador faz o desafio no banco emissor (senha, app, biometria).
6. Ao final, o comprador volta para o `redirectURL` do pedido. O retorno não traz o resultado da autenticação nem do pagamento.
7. Consulte o resultado pelo webhook do pedido ou pelo `GET /v2/orders/{uuid}`.

#### Script de Step Up

```html
<form id="step_up_form" method="POST" style="display: none;">
  <input id="step_up_form_jwt_input" type="hidden" name="JWT">
</form>

<script>
  const stepUrl = '<stepUrl>';
  const token = '<token>';

  const docFormStep = document.getElementById('step_up_form');
  const docInputStepJwt = document.getElementById('step_up_form_jwt_input');

  docFormStep.action = stepUrl;
  docInputStepJwt.value = token;
  docFormStep.submit();
</script>
```

O script leva a página inteira ao desafio. Se preferir manter o comprador na sua página, aponte o formulário para um iframe com o atributo `target`; nesse caso o `redirectURL` também abre dentro do iframe.

⚠️ Observações importantes:

* O redirecionamento não confirma o pagamento. O **status final da transação** é enviado via **webhook** e também pode ser consultado no `GET /v2/orders/{uuid}`
* Envie o comprador ao `stepUrl` assim que receber a resposta do pedido, na mesma aba e em primeiro plano. O banco emissor espera cerca de 30 segundos pela abertura da página do desafio; se ela não abrir nesse tempo (por exemplo, com a aba em segundo plano ou o redirecionamento atrasado), a autenticação expira e volta recusada
* Um desafio não concluído em 12 minutos é cancelado: o pedido e a cobrança passam a `CANCELED` e o webhook `order.canceled` é enviado. O cancelamento roda a cada 5 minutos, então pode acontecer alguns minutos depois desse prazo. No `GET /v2/orders/{uuid}`, a cobrança cancelada por prazo traz o `failureReason` com o código `BAR-7994`
* Quando o `stepUrl` é uma página da Barte (`https://pay.barte.com`; no sandbox, `https://sandbox-pay.barte.com`):
  * reabrir o `stepUrl` depois de concluir o desafio leva o comprador de volta ao `redirectURL`, sem refazer o desafio e sem nova cobrança
  * se o comprador concluir o desafio depois do cancelamento por prazo, nada é cobrado
  * sem `redirectURL`, ou com um `redirectURL` que não use `https`, o comprador não volta para a sua loja: ele vê uma página da Barte pedindo para voltar à loja

***

### Resumo de decisão

* `challenged = false` → pagamento segue normalmente (PAID / FAILED)
* `challenged = true` → exige Step Up Challenge
* Resultado final sempre confirmado via webhook ou pela consulta do pedido

#### Erros na autenticação 3DS

Quando a autenticação não é concluída, o pedido é recusado com HTTP `400`. O código diz quem recusou:

| Código   | O que aconteceu                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | O que fazer                                                                                                                                                                                                                                                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BAR-7068 | O cartão não foi autenticado. A `description` traz entre parênteses o `transStatus` da autenticação e, quando houver, o motivo (`reason`), por exemplo `Não foi possível validar a autenticação do cartão (transStatus: N)`: `N` autenticação negada, `R` recusa do emissor, `U` autenticação indisponível. Sem `transStatus`, o motivo diz o que aconteceu: `AUTHENTICATION_TECHNICAL_FAILURE` (falha técnica ao autenticar), `SESSION_ALREADY_USED` (sessão 3DS já usada em outro pedido), `SESSION_CARD` (sessão aberta para outro cartão) ou outro `SESSION_*` (sessão que não pertence a este pedido) | Peça ao comprador para refazer a autenticação com o banco ou usar outro cartão. Com `U` ou `AUTHENTICATION_TECHNICAL_FAILURE`, tente novamente mais tarde. Com `SESSION_*`, abra uma nova sessão 3DS para o pedido                                                                                                                          |
| BAR-1808 | Os dados da autenticação 3DS foram recusados antes de avaliar o cartão (campo ausente ou formato inválido). Quando o provedor informa os campos com problema, eles vêm entre parênteses no fim da `description`, por exemplo `O banco emissor recusou os dados de autenticação 3DS enviados (formato inválido) (threeDSecure2.cardHolder.email is required)`. A descrição também pode trazer o `transStatus` da autenticação, por exemplo `(transStatus: N)`                                                                                                                                               | Corrija os campos indicados na descrição. Sem campos indicados, confira os dados do navegador em `threeDSecure.browser`: valores reais do navegador do comprador, `screenHeight` e `screenWidth` maiores que zero, `timeZoneOffset`, `language`, `userAgent` e `acceptHeader` preenchidos. Tentar de novo com os mesmos dados repete o erro |
| BAR-7951 | O banco emissor não conseguiu autenticar o cartão no momento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Tente novamente mais tarde ou use outro cartão                                                                                                                                                                                                                                                                                              |
| BAR-7994 | O comprador não concluiu o desafio. Quando o desafio expira ou é cancelado no banco, a cobrança fica `FAILED` e a `description` traz o motivo, por exemplo `A autenticação 3DS não foi concluída a tempo (transStatus: N, reason: EXPIRED_TIMEOUT)` ou `(transStatus: N, reason: CHALLENGE_CANCELED)`. Quando a Barte cancela o pedido depois de 12 minutos sem resposta, a cobrança fica `CANCELED` e o código vem no `failureReason`                                                                                                                                                                     | Crie um novo pedido e peça ao comprador para concluir a autenticação no app ou site do banco                                                                                                                                                                                                                                                |

Os demais códigos estão em [Códigos de Erro](https://docs.barte.com/guias/inicio/codigos-de-erro.md).

### 🔔 Confirmação do pagamento

Após o cliente realizar o pagamento:

1. O status da transação é atualizado na Barte
2. Um webhook é disparado para o seu sistema
3. Seu sistema deve validar o evento recebido
4. A confirmação do pagamento deve ser feita **exclusivamente via webhook**

📌 Isso se aplica a **cartão, PIX e boleto**, inclusive quando o cartão retorna `PAID` de forma síncrona.

***

### <i class="fa-rotate">:rotate:</i> Fluxo resumido

```
Criar pedido
     ↓
Cliente realiza pagamento
     ↓
Status atualizado na Barte
     ↓
Webhook enviado
     ↓
Seu sistema confirma o pagamento
```

***

#### Campos importantes no 3DS

**`threeDSecure.setupId`**

ID da sessão 3DS criada previamente.

**`three3DSSecure.challenged`** (`threeDSSecure.challenged` na consulta do pedido)

* `true` → exige desafio (Step Up)
* `false` → fluxo segue normalmente

**`three3DSSecure.auth.action`**

* `REDIRECT` → enviar o comprador para o `auth.stepUrl`, com o `auth.token` no campo `JWT`

**`three3DSSecure.liabilityShift`** (`threeDSSecure.liabilityShift` na consulta do pedido)

* `true` → a compra tem garantia contra chargeback de fraude (liability shift)
* `false` ou ausente → a compra não tem essa garantia

Use esse campo para saber se a compra está protegida. Não use o `authenticated` para isso.

📌 **O resultado final do 3DS nunca deve ser inferido no frontend.**

***

### Pedido com autenticação externa (MPI)

Se você faz a autenticação 3DS com o seu próprio 3DS Server, envie o resultado no pedido em `threeDSecure.mpi`, sem `setupId`. Nesse caso a Barte não faz a autenticação: o resultado enviado é repassado na autorização como veio.

```json
"threeDSecure": {
  "mpi": {
    "transStatus": "Y",
    "eci": "05",
    "cavv": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "xid": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "version": "2.2.0",
    "challenged": true,
    "threeDSServerTransactionId": "9b2c6f2e-1d6e-4c1f-9a1f-2b7f1a9d3c10",
    "directoryServerTransactionId": "3f8a1c2d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "acsTransactionId": "7c6b5a4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d"
  }
}
```

O que acontece em cada resultado da autenticação (`transStatus`):

| `transStatus` | Significado                               | O que acontece na autorização                                                                                                  |
| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Y`           | Autenticado                               | A autorização segue com o CAVV e o ECI da autenticação, com garantia contra chargeback de fraude                               |
| `A`           | Tentativa de autenticação                 | A autorização segue com o CAVV e o ECI de tentativa; a garantia depende da regra de cada bandeira                              |
| `N`           | Autenticação negada pelo banco emissor    | A autorização segue como compra online sem 3DS, **sem garantia contra chargeback de fraude**. O banco emissor decide se aprova |
| `R`           | Autenticação rejeitada pelo banco emissor | Igual ao `N`: segue sem garantia                                                                                               |
| `U`           | Autenticação indisponível                 | Igual ao `N`: segue sem garantia                                                                                               |

⚠️ A Barte não recusa o pedido pelo resultado do MPI externo. Se você não quer seguir sem garantia, não envie o pedido quando o `transStatus` for `N`, `R` ou `U`. Para conferir a garantia de um pedido, use o `liabilityShift` da resposta.

***

### <i class="fa-thumbtack-angle">:thumbtack-angle:</i> Importante sobre 3DS

* O cliente pode ser autenticado com sucesso **e ainda assim** o pagamento falhar
* O redirecionamento não confirma o pagamento
* **Somente o webhook indica o estado final da transação**

***

### <i class="fa-lightbulb">:lightbulb:</i> Boas práticas

* Sempre utilize webhooks para confirmar pagamento
* Armazene:
  * `uuid` do pedido
  * `uuid` da charge
* Trate webhooks de forma idempotente
* Use `metadata` para rastreabilidade interna
* Aguarde a finalização da coleta de navegador no 3DS

***

### <i class="fa-hexagon-xmark">:hexagon-xmark:</i> O que não fazer

* Confirmar pagamento sem webhook
* Reutilizar pedidos para novas cobranças
* Reutilizar a mesma `idempotencyKey` em uma nova tentativa de pagamento: com a mesma chave e os mesmos dados, a API devolve o pedido da tentativa anterior, sem autenticar o cartão de novo. Use uma chave nova a cada tentativa
* Criar a sessão 3DS e enviar o pedido sem `threeDSecure.setupId`
* Assumir sucesso após retorno síncrono do cartão
* Criar pedido 3DS antes da coleta de navegador
* Expor sua chave de API no frontend


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-3ds-3d-secure.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
