# White-label

> Ofereça cortes, renders e publicação com a sua marca: um workspace por cliente e um link para ele conectar as próprias redes, sem conta na Cut.Pro.

Os [termos de uso](https://cut.pro/terms) liberam a API para revenda, white-label e produto próprio, com a sua marca e o seu preço, sem contrato à parte. Esta página mostra o fluxo: cada cliente ganha um workspace, conecta as redes dele por um link e você opera tudo pela API.

## 1. Crie um workspace por cliente

O workspace separa os vídeos, clipes, renders, contas conectadas e posts de cada cliente.

```bash
curl -X POST https://api.cut.pro/api/v1/workspaces \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Padaria Central" }'
```

```json title="201 Created"
{ "id": "7412990011220001", "name": "Padaria Central", "is_personal": false, "created_at": "2026-11-20T15:00:00.000Z" }
```

A chave que criou já alcança o workspace novo. Guarde o `id` junto do cliente no seu sistema e mande-o em `X-Workspace-Id` em toda chamada daquele cliente:

```bash
curl https://api.cut.pro/api/v1/connections \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "X-Workspace-Id: 7412990011220001"
```

Sem o header, a requisição continua caindo onde caía antes de você criar workspaces, então o que já funcionava não muda. `GET /workspaces` lista todos e `PATCH /workspaces/{id}` renomeia.

> Créditos e plano são de cada workspace. Um workspace novo começa no plano gratuito, sem créditos.

## 2. Peça o link de conexão

```bash
curl -X POST https://api.cut.pro/api/v1/connections/link \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "X-Workspace-Id: 7412990011220001" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "return_url": "https://app.suamarca.com/clientes/42/redes",
    "state": "cliente-42"
  }'
```

```json title="200 OK"
{ "url": "https://api.cut.pro/api/v1/connections/start?link=…", "expires_at": "2026-11-21T15:00:00.000Z" }
```

Entregue o `url` ao cliente: num botão do seu painel, por e-mail ou por mensagem. Ele abre, faz login na rede e autoriza. Ninguém precisa de conta na Cut.Pro.

| Campo | O que faz |
|---|---|
| `platform` | `youtube`, `tiktok`, `instagram`, `facebook`, `threads`, `linkedin`, `pinterest`, `bluesky`, `twitch`, `kick` ou `discord`. |
| `return_url` | Para onde a pessoa vai quando termina. `https`, ou `http` em `localhost` enquanto você testa. Sem ele, ela cai na Cut.Pro. |
| `state` | Qualquer texto seu, até 512 caracteres, devolvido intacto na volta. Use para saber de que cliente é a resposta. |
| `connection_id` | Reconecta uma conta cujo acesso caiu, mantendo o `id` dela e os posts agendados. |

O link vale uma vez e expira em 24 horas. Se a pessoa cancela ou o login falha, o mesmo link funciona de novo. Enquanto um login está em andamento, uma segunda aba recebe `LINK_IN_USE`.

## 3. Receba a volta

Quando a pessoa termina, o navegador vai para o `return_url` com:

| Parâmetro | Valor |
|---|---|
| `status` | `connected` ou `error`. |
| `platform` | A rede do link. |
| `connection_ids` | Os `id` das contas conectadas, separados por vírgula. Vem mais de um quando um login do Facebook autoriza várias Páginas. |
| `warning` | `FACEBOOK_PAGES_PARTIAL` quando parte das Páginas não coube no limite. |
| `code` | No `error`, o motivo, como `LINK_EXPIRED`, `LINK_USED`, `CONNECTION_LIMIT_REACHED` ou o erro devolvido pela rede. |
| `state` | O seu `state`, como foi enviado. |

```text
https://app.suamarca.com/clientes/42/redes?status=connected&platform=instagram&connection_ids=7412990011229001&state=cliente-42
```

A volta passa pelo navegador da pessoa. Para gravar a conexão no seu sistema, confirme com `GET /connections/{id}` no workspace do cliente, em vez de confiar só nos parâmetros da URL.

> A conexão acontece sem nenhuma tela da Cut.Pro no meio. Por isso o Facebook conecta todas as Páginas que a pessoa autorizou, o LinkedIn conecta o perfil e o Tumblr, o blog principal, até o limite de contas do plano.

## 4. Opere como sempre

Com o `X-Workspace-Id` do cliente, o resto da API funciona igual: [corte](https://cut.pro/docs/clipping), [renderize](https://cut.pro/docs/rendering) e [publique](https://cut.pro/docs/publishing) nas contas dele. Para entregar o vídeo com o seu domínio, baixe o MP4 e sirva do seu armazenamento.

## O que ainda aparece

- A tela de autorização do Google, do TikTok e da Meta mostra o nome do aplicativo, que é o da Cut.Pro. Cada rede exige um aplicativo revisado por ela, então esse nome não muda por cliente.
- O link de conexão passa por `api.cut.pro` por um instante, antes de abrir o login da rede.

## Erros

| Code | Quando |
|---|---|
| `WORKSPACE_LIMIT_REACHED` | A conta chegou ao limite de workspaces criados pela API. |
| `INVALID_RETURN_URL` | `return_url` não é `https` (nem `http` em `localhost`). |
| `CONNECTION_LIMIT_REACHED` | O workspace já tem o máximo de contas daquela rede que o plano permite. |
| `PLATFORM_UNAVAILABLE` | O plano do workspace não inclui a rede, ou ela ainda não foi liberada. |
| `CONNECTION_NOT_FOUND` | O `connection_id` para reconectar não é deste workspace ou é de outra rede. |
