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

# Primeiro pré-teste

> Do zero ao PDF: crie a chave, envie um criativo e leia o resultado.

Neste guia você cria um pré-teste de mídia exterior (OOH) e baixa o PDF. Os valores dos exemplos são fictícios.

> [!WARNING]
>
> A chave de API é um segredo de servidor. Guarde-a em uma variável de ambiente do seu back-end. Nunca a coloque em código de navegador, em app de celular ou em repositório.

## 1. Crie a chave no painel

1. Entre no painel da Unite com uma conta de **administrador** do workspace.
2. Abra a área de administração do workspace e vá em **Chaves de API**.
3. Clique em **Criar chave**.
4. Dê um nome (por exemplo, "Integração do CRM"), escolha as permissões **Ler pré-testes** e **Criar pré-testes** e defina a validade.
5. Clique em **Criar chave** e copie o valor. Ele aparece uma única vez.

Se a tela avisar que a API ainda não está liberada para o workspace, fale com o time da Unite.

Nos exemplos abaixo, a chave fica na variável `UNITE_API_KEY`. O valor tem o formato `unite_live_SUA_CHAVE_AQUI`.

```bash theme={null}
export UNITE_API_KEY="unite_live_SUA_CHAVE_AQUI"
```

Os blocos de cada linguagem formam um só roteiro: você pode colar os passos 2 a 7 em um único arquivo, na ordem. No curl, cada passo guarda em variáveis do shell os valores que o próximo usa (precisa do `jq`). Os exemplos de JavaScript usam `node` 18 ou mais novo, em módulo ES (`.mjs`).

## 2. Consulte o catálogo

O catálogo lista os formatos OOH, as plataformas digitais e as marcas do workspace. Guarde o `key` do formato que você vai usar.

```bash curl theme={null}
curl -s https://myunite.ai/api/v1/catalog \
  -H "Authorization: Bearer $UNITE_API_KEY" -o catalog.json

export FORMAT_KEY=$(jq -r '.ooh.formats[0].key' catalog.json)
echo "$FORMAT_KEY"
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const catalogRes = await fetch("https://myunite.ai/api/v1/catalog", {
  headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
});
const catalog = await catalogRes.json();
const formatKey = catalog.ooh.formats[0].key;
console.log(formatKey);
```

```python Python theme={null}
import os
import time
import requests

API = "https://myunite.ai/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"}

catalog = requests.get(f"{API}/catalog", headers=AUTH).json()
format_key = catalog["ooh"]["formats"][0]["key"]
print(format_key)
```

## 3. Peça o endereço de envio

Informe o tipo e o tamanho do arquivo. A resposta traz o `uploadId` e uma URL de envio válida por 15 minutos.

```bash curl theme={null}
SIZE=$(wc -c < verao-relogio-urbano.png | tr -d ' ')

curl -s -X POST https://myunite.ai/api/v1/uploads \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\":\"image/png\",\"sizeBytes\":$SIZE,\"filename\":\"verao-relogio-urbano.png\"}" \
  -o upload.json

export UPLOAD_ID=$(jq -r '.uploadId' upload.json)
export UPLOAD_URL=$(jq -r '.uploadUrl' upload.json)
export CACHE_CONTROL=$(jq -r '.headers["Cache-Control"]' upload.json)
```

```javascript JavaScript theme={null}
const file = await readFile("verao-relogio-urbano.png");

const uploadRes = await fetch("https://myunite.ai/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contentType: "image/png",
    sizeBytes: file.length,
    filename: "verao-relogio-urbano.png",
  }),
});
const target = await uploadRes.json();
```

```python Python theme={null}
with open("verao-relogio-urbano.png", "rb") as f:
    file_bytes = f.read()

target = requests.post(
    f"{API}/uploads",
    headers=AUTH,
    json={
        "contentType": "image/png",
        "sizeBytes": len(file_bytes),
        "filename": "verao-relogio-urbano.png",
    },
).json()
```

Resposta (valores fictícios; o `uploadUrl` real é longo e muda a cada pedido):

```json theme={null}
{
  "uploadId": "upl_0123456789abcdef0123456789abcdef.png",
  "uploadUrl": "https://armazenamento.exemplo/...",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/png",
    "Cache-Control": "public, max-age=31536000, immutable"
  },
  "expiresAt": "2026-11-16T14:15:00.000Z"
}
```

## 4. Envie o arquivo

Faça um `PUT` do arquivo na `uploadUrl`, com **todos** os cabeçalhos devolvidos, exatamente com os mesmos valores. Esta chamada não leva a chave de API. Veja os detalhes em [Envio de arquivos](https://docs.myunite.ai/uploads.md).

```bash curl theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  -H "Cache-Control: $CACHE_CONTROL" \
  --data-binary @verao-relogio-urbano.png
```

```javascript JavaScript theme={null}
const putRes = await fetch(target.uploadUrl, {
  method: target.method,
  headers: target.headers, // todos, sem alterar
  body: file,
});
if (!putRes.ok) throw new Error(`Envio falhou: ${putRes.status}`);
```

```python Python theme={null}
put_res = requests.put(target["uploadUrl"], headers=target["headers"], data=file_bytes)
put_res.raise_for_status()
```

## 5. Crie o pré-teste

Envie o `uploadId` e o canal. O cabeçalho `Idempotency-Key` é obrigatório: use um valor novo por pré-teste e reutilize-o só para repetir a mesma chamada. Veja [Idempotência](https://docs.myunite.ai/idempotency.md).

```bash curl theme={null}
curl -s -X POST https://myunite.ai/api/v1/pretests \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Idempotency-Key: verao-relogio-urbano-001" \
  -H "Content-Type: application/json" \
  -d "{
    \"uploadId\": \"$UPLOAD_ID\",
    \"title\": \"Verão · relógio urbano\",
    \"channel\": \"ooh\",
    \"ooh\": { \"format\": \"$FORMAT_KEY\" }
  }" -o pretest.json

export PRETEST_ID=$(jq -r '.id' pretest.json)
jq -r '.status' pretest.json   # queued
```

```javascript JavaScript theme={null}
const createRes = await fetch("https://myunite.ai/api/v1/pretests", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
    "Idempotency-Key": "verao-relogio-urbano-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    uploadId: target.uploadId,
    title: "Verão · relógio urbano",
    channel: "ooh",
    ooh: { format: formatKey },
  }),
});
const pretest = await createRes.json(); // status 202, pretest.status === "queued"
```

```python Python theme={null}
create_res = requests.post(
    f"{API}/pretests",
    headers={**AUTH, "Idempotency-Key": "verao-relogio-urbano-001"},
    json={
        "uploadId": target["uploadId"],
        "title": "Verão · relógio urbano",
        "channel": "ooh",
        "ooh": {"format": format_key},
    },
)
pretest = create_res.json()  # status 202, pretest["status"] == "queued"
```

A resposta é `202` e traz o cabeçalho `Location` com o endereço do pré-teste.

## 6. Consulte até `completed`

```bash curl theme={null}
while true; do
  STATUS=$(curl -s "https://myunite.ai/api/v1/pretests/$PRETEST_ID" \
    -H "Authorization: Bearer $UNITE_API_KEY" | jq -r '.status')
  echo "$STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 10
done
```

```javascript JavaScript theme={null}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

let current = pretest;
while (current.status === "queued" || current.status === "processing") {
  await sleep(10_000);
  const statusRes = await fetch(`https://myunite.ai/api/v1/pretests/${pretest.id}`, {
    headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
  });
  current = await statusRes.json();
}
console.log(current.status, current.result?.score);
```

```python Python theme={null}
current = pretest
while current["status"] in ("queued", "processing"):
    time.sleep(10)
    current = requests.get(f"{API}/pretests/{pretest['id']}", headers=AUTH).json()
print(current["status"], (current.get("result") or {}).get("score"))
```

Consulte a cada 10 segundos ou mais. Com `completed`, o campo `result` traz nota, pilares e achados (veja [Resultados](https://docs.myunite.ai/results.md)). Com `failed`, o campo `error.code` diz o motivo. Se terminar em `failed`, pare aqui: não há PDF para baixar.

## 7. Baixe o PDF

O PDF é gerado sob demanda. Se ainda estiver sendo gerado, a resposta é `202` com `Retry-After`: espere esse número de segundos e tente de novo. Com `200` e `status: "ready"`, baixe o arquivo em `url`. Essa segunda chamada é um `GET` simples na `url`, sem a chave de API.

```bash curl theme={null}
while true; do
  CODE=$(curl -s -o report.json -D report-headers.txt -w "%{http_code}" \
    "https://myunite.ai/api/v1/pretests/$PRETEST_ID/report" \
    -H "Authorization: Bearer $UNITE_API_KEY")
  if [ "$CODE" = "200" ]; then break; fi
  if [ "$CODE" != "202" ]; then break; fi
  WAIT=$(grep -i '^retry-after:' report-headers.txt | tr -dc '0-9')
  sleep "${WAIT:-15}"
done

if [ "$CODE" = "200" ]; then
  curl -s -o analise.pdf "$(jq -r '.url' report.json)"
else
  echo "Falha ao gerar o PDF: HTTP $CODE"; cat report.json
fi
```

```javascript JavaScript theme={null}
import { writeFile } from "node:fs/promises";

let report;
while (true) {
  const reportRes = await fetch(`https://myunite.ai/api/v1/pretests/${pretest.id}/report`, {
    headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
  });
  if (reportRes.status === 200) {
    report = await reportRes.json();
    break;
  }
  if (reportRes.status !== 202) throw new Error(`Falha ao gerar o PDF: ${reportRes.status}`);
  await sleep(Number(reportRes.headers.get("Retry-After") ?? "15") * 1000);
}

const pdfRes = await fetch(report.url); // sem Authorization
await writeFile("analise.pdf", Buffer.from(await pdfRes.arrayBuffer()));
```

```python Python theme={null}
while True:
    report_res = requests.get(f"{API}/pretests/{pretest['id']}/report", headers=AUTH)
    if report_res.status_code == 200:
        report = report_res.json()
        break
    if report_res.status_code != 202:
        raise RuntimeError(f"Falha ao gerar o PDF: {report_res.status_code}")
    time.sleep(int(report_res.headers.get("Retry-After", "15")))

pdf_res = requests.get(report["url"])  # sem Authorization
with open("analise.pdf", "wb") as f:
    f.write(pdf_res.content)
```

Busque o link quando precisar do arquivo e não conte com a URL continuar a mesma: peça o PDF de novo em vez de guardar o link.

## Próximos passos

* Escolha o canal: [OOH](https://docs.myunite.ai/pretests/ooh.md), [Digital](https://docs.myunite.ai/pretests/digital.md) ou [E-mail](https://docs.myunite.ai/pretests/email.md).
* Trate falhas com a lista de [erros](https://docs.myunite.ai/errors.md).
* Conheça os [limites de uso](https://docs.myunite.ai/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.