# Idempotência e duplicados

Agentes repetem chamadas: um timeout, uma resposta perdida, um passo executado de novo. Duas ferramentas evitam que uma repetição publique duas vezes.

## Idempotency-Key

Envie `Idempotency-Key: <valor único>` (um UUID, ou um id do seu sistema; até 255 caracteres) em `POST /v1/posts`, `POST /v1/connect`, `POST /v1/media` (JSON), `POST /v1/partner/workspaces`.

```
curl -X POST https://wyroapi.com/v1/posts \
  -H "Authorization: Bearer $WYRO_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4c55-9e1a-0d2b8f4a7c11" \
  -H "Content-Type: application/json" \
  -d '{"text": "…", "platforms": ["instagram"], "media": [{"url": "https://…/a.jpg"}]}'
```

- A **mesma chave com o mesmo body** do mesmo workspace (ou parceiro) em até **24 h** devolve a **primeira resposta** (mesmo status e body) sem fazer o trabalho de novo. Ela vem com o header `Idempotent-Replayed: true`.
- A **mesma chave com outro body** responde `409 idempotency_conflict`. Se a primeira solicitação ainda estiver rodando, também 409, com `details.reason: "in_progress"`: espere um segundo e tente de novo.
- Respostas que significam "tente de novo" (`429` e `5xx`) não são guardadas: repetir com a mesma chave executa a solicitação de novo.
- Credenciais nunca são guardadas: em `POST /v1/partner/workspaces`, a repetição devolve `api_key`, `webhook_secret` e `mcp_url` como `null` (gire a chave se você a perdeu).
- Guardamos só hashes da chave e da solicitação, junto com a resposta.

## Proteção contra duplicados

`POST /v1/posts` recusa o **mesmo texto na mesma conta em até 24 h** com `409 duplicate_post` e `details.existing_post_id`. O texto é comparado ignorando espaços nas pontas e espaços repetidos (maiúsculas contam). Posts que falharam não contam, e os cancelados são apagados. Vale também para posts simulados, para você ver isso nos testes.

Se a pessoa quiser mesmo publicar de novo, envie `"allow_duplicate": true` no body (no MCP, `permitir_duplicado: true`).
