# API do curtei: encurte links pelo seu sistema

> Crie links curtos, QR Codes e leia métricas de clique pela API REST do curtei. Chave de API, respostas em JSON e exemplos em cURL, JavaScript, PHP e Python.

Fonte: https://curtei.com/docs/api


A API do curtei é REST, fala JSON em UTF-8 e só aceita HTTPS. A base é `https://api.curtei.com/v1`. Ela é gratuita como o resto do curtei: a conta não tem plano pago nem cota mensal de links.

## Primeiro link em 3 passos

1. [Crie uma conta grátis](https://curtei.com/cadastro) e confirme o e-mail. Sem a confirmação a conta só lê.
2. Em [Painel › Integrações](https://curtei.com/painel/integracoes), crie uma chave e escolha os escopos. O token (`<id>|wsk_live_...`) aparece uma vez só: guarde num cofre de segredos.
3. Chame a API com o cabeçalho `Authorization: Bearer <token>`.

cURL:

```bash
curl -X POST https://api.curtei.com/v1/links \
  -H "Authorization: Bearer $CURTEI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://minhaloja.com.br/promo","tags":["newsletter"]}'
```

JavaScript:

```js
const res = await fetch("https://api.curtei.com/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CURTEI_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ url: "https://minhaloja.com.br/promo", tags: ["newsletter"] }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const link = await res.json();
console.log(link.short_url);
```

PHP:

```php
$ch = curl_init('https://api.curtei.com/v1/links');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CURTEI_TOKEN'),
        'Content-Type: application/json',
        'Idempotency-Key: '.bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode(['url' => 'https://minhaloja.com.br/promo', 'tags' => ['newsletter']]),
]);
$link = json_decode(curl_exec($ch), true);
echo $link['short_url'];
```

Python:

```python
import os, uuid, requests

res = requests.post(
    "https://api.curtei.com/v1/links",
    headers={
        "Authorization": f"Bearer {os.environ['CURTEI_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"url": "https://minhaloja.com.br/promo", "tags": ["newsletter"]},
    timeout=10,
)
res.raise_for_status()
print(res.json()["short_url"])
```

Resposta `201 Created`:

```json
{
  "id": "0193a0b2-7c1e-7d3a-9f10-5b2c8e4a1d22",
  "short_url": "https://l.curtei.com/aB3xK9",
  "slug": "aB3xK9",
  "domain": "l.curtei.com",
  "url": "https://minhaloja.com.br/promo",
  "status": "active",
  "has_password": false,
  "qr_code_url": "https://api.curtei.com/v1/links/0193a0b2-7c1e-7d3a-9f10-5b2c8e4a1d22/qr",
  "total_clicks": 0,
  "unique_clicks": 0,
  "external_id": null,
  "metadata": null,
  "created_at": "2026-11-13T21:30:00Z"
}
```

## O que a API faz

| Recurso | O que dá para fazer | Página |
| --- | --- | --- |
| Links | Criar, listar, buscar por `external_id`, editar, desativar e apagar. | [Links](https://curtei.com/docs/api/links) |
| Lote | Até 1.000 links por chamada; até 50.000 em segundo plano. | [Links em lote](https://curtei.com/docs/api/links-em-lote) |
| Roteamento e A/B | Destino por país, estado, cidade, sistema, dispositivo ou idioma; variantes com peso. | [Roteamento e A/B](https://curtei.com/docs/api/roteamento) |
| QR Code | PNG ou SVG com cores, legenda e logo. | [QR Code](https://curtei.com/docs/api/qr-code) |
| Métricas | Resumo, série temporal, distribuição por dimensão, cliques e exportação CSV. | [Métricas](https://curtei.com/docs/api/metricas) |
| Conversões | Postback servidor a servidor ou pixel, com receita por moeda. | [Conversões](https://curtei.com/docs/api/conversoes) |
| Webhooks | Eventos de clique, expiração e bloqueio, assinados com HMAC. | [Webhooks](https://curtei.com/docs/api/webhooks) |
| Domínios | Links no seu próprio domínio, com código personalizado. | [Domínios](https://curtei.com/docs/api/dominios) |
| Páginas de links | A página /@usuario com os seus links agrupados. | [Páginas de links](https://curtei.com/docs/api/paginas-de-links) |
| Campanhas | Agrupar links e somar as métricas. | [Campanhas](https://curtei.com/docs/api/campanhas) |

## Limites e regras

| Item | Valor |
| --- | --- |
| Base da API | `https://api.curtei.com/v1` |
| Requisições | 120 por minuto por conta (cabeçalhos `X-RateLimit-Limit` e `X-RateLimit-Remaining`) |
| Criação de links | 1.000 por hora e 5.000 por dia por conta (teto antiabuso; cada item de lote conta) |
| Código personalizado (`slug`) | Só em domínio próprio |
| Idempotência | `Idempotency-Key` em todo `POST`, vale 24 h |
| Paginação | Por cursor: `{ "data": [...], "next_cursor": "..." }` |
| Versão | No caminho (`/v1`). Mudança incompatível vira `/v2`, com 6 meses de convivência |

## Usando uma IA para integrar

Cole `https://curtei.com/llms-full.txt` no ChatGPT, Claude, Cursor ou Copilot e peça a integração: o arquivo traz toda a API em texto puro. Cada página desta documentação também existe em Markdown, com `.md` no fim do endereço (por exemplo, [/docs/api/links.md](https://curtei.com/docs/api/links.md)).