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

# Migrar uma integração existente

> Troque duas constantes. Depois leia os pontos em que o comportamento é diferente.

Esta API implementa o contrato padrão de tarefas assíncronas. Nos endpoints que ela suporta, os esquemas de
requisição e resposta não mudam, então um cliente que funciona normalmente não precisa de alterações de código.

## A migração

```diff theme={null}
- const BASE = "https://api.your-current-provider.example"
+ const BASE = "https://api.querying.ai"
```

Aponte sua constante de chave de API para uma chave da querying.ai. URL de webhook, chaves de idempotência, tipos de
tarefa e o parsing das respostas continuam como estão.

## O que está implementado

<CardGroup cols={2}>
  <Card title="Suportado" icon="check">
    `POST /v1/async/task`

    `POST /v1/async/task/batch`

    `GET /v1/async/task/{id}`

    Callbacks de webhook
  </Card>

  <Card title="Não implementado" icon="x">
    Endpoints síncronos `/v1/monitor/*`

    `/v1/async/status`
  </Card>
</CardGroup>

A família síncrona `/v1/monitor/*` está ausente de propósito. Todos os mecanismos aqui funcionam de forma assíncrona;
uma requisição que fica bloqueada durante o tempo de uma consulta não é algo que este serviço oferece.

## Onde o comportamento é diferente

<AccordionGroup>
  <Accordion title="1. Sem limitador de taxa: use lotes" icon="gauge">
    Não há limite de taxa por chave. Para grandes volumes, use o envio em lote para reduzir as idas e voltas.

    Veja [Regiões e boas práticas](/pt/engines/capacity).
  </Accordion>

  <Accordion title="2. Os créditos são por mecanismo" icon="coins">
    `credits` aparece em toda resposta como parte do envelope. As respostas de envio e polling informam
    `{ "creditsToCharge": 0, "creditsCharged": 0 }`; os webhooks informam o custo em créditos do mecanismo (1–3 créditos
    conforme o mecanismo).

    Tarefas com falha não são cobradas. Os saldos de créditos ficam visíveis no painel.
  </Accordion>

  <Accordion title="3. Alguns pares mecanismo × região são recusados de cara" icon="ban">
    Uma combinação não pode ser atendida de jeito nenhum: `CHATGPT`/`PERPLEXITY`/`GEMINI` para `CN`, onde não há oferta de
    saída e a requisição nunca chega ao destino. Ela falha imediatamente com `422 REGION_UNSUPPORTED` em vez de ser
    aceita. `422 REGION_UNAVAILABLE` cobre a versão transitória da mesma situação.

    Um cliente que supõe que todo envio bem formado é aceito precisa de uma ramificação aqui. Veja [Regiões](/pt/engines/capacity).
  </Accordion>

  <Accordion title="4. As flags include quase não têm efeito" icon="toggle-left">
    As flags `payload.include` são aceitas, mas a maioria dos mecanismos retorna uma resposta de formato fixo e as ignora.
    Só o ChatGPT respeita o conjunto completo; `GEMINI` respeita apenas `markdown` e `rawResponse`.

    Pedir `html` ao Gemini, por exemplo, é ignorado em silêncio: sem erro e sem campo. Veja a
    [tabela de flags suportadas](/pt/engines/overview).
  </Accordion>

  <Accordion title="5. Um código de status a mais: 422" icon="hash">
    Fora isso, o tratamento de erros é convencional: falhas de validação retornam `400`, `401` informa `MISSING_API_KEY`,
    `404` informa `RESOURCE_NOT_FOUND` e `details` aponta o campo com problema.

    A única novidade é o par `422` (`REGION_UNSUPPORTED`, `REGION_UNAVAILABLE`) descrito acima. Avisamos de antemão quando
    uma região não pode ser atendida, então um cliente que nunca precisou tratar um `422` vai começar a vê-los.
  </Accordion>

  <Accordion title="6. Uma tarefa com falha ganha uma string `error` de nível superior" icon="triangle-alert">
    `GET /v1/async/task/{id}` em uma tarefa `FAILED` retorna um campo `error` de nível superior que o esquema de status da
    tarefa não define, e ele é uma **string simples**, não o objeto `{code, message, timestamp}` dos erros de requisição.

    ```json theme={null}
    { "success": true, "task": { "status": "FAILED", "...": "..." }, "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline." }
    ```

    Um cliente que trata um `body.error` verdadeiro como *requisição* com falha vai interpretar errado uma *tarefa* com
    falha que foi obtida com sucesso. Ramifique por `task.status`.
  </Accordion>
</AccordionGroup>

<Note>
  Esses comportamentos foram verificados chamando esta API, não lendo um esquema. Se uma especificação publicada e uma
  resposta real divergirem, estas páginas documentam a resposta real.
</Note>

## Escolhendo o `taskType` certo

Se sua integração atual chama um endpoint por mecanismo, o nome do mecanismo corresponde a um `taskType`:

| Você chamava | `taskType` |
| - | - |
| ChatGPT | `CHATGPT` |
| Perplexity | `PERPLEXITY` |
| Gemini | `GEMINI` |
| Google AI Mode | `AIMODE` |
| Google AI Overview | `GOOGLE` |
| Naver | `NAVER_AI_BRIEF` / `NAVER_AI_TAB` |

<Note>
  `GOOGLE` significar "AI Overview" é uma convenção de nomes, não um nome de produto do Google. A resposta é um
  envelope de SERP com `aioverview` como membro anulável; veja [o formato do GOOGLE](/pt/engines/overview).
</Note>

## Validando a virada

Rode sua integração atual e esta em paralelo por um tempo e compare os campos que você realmente consome, na prática
`response.text`, `response.sources[]` e `response.markdown`. Uma comparação em sombra pega diferenças de formato que
uma checagem de esquema não pega, como uma lista de fontes preenchida mas em outra ordem.