Revisões e conflitos

O mesmo roteiro pode ser editado ao mesmo tempo na web, no app, por um agente e por uma automação. Para que ninguém perca texto, toda alteração usa controle de concorrência otimista.

Como funcionaCopiar link da seção

1. Cada roteiro tem um número revision, que começa em 1.
2. Toda gravação (edição, lixeira ou restauração) incrementa a revisão em uma unidade.
3. Para alterar, você envia expectedRevision com a revisão que leu.
4. Se o roteiro mudou desde a leitura, a API responde 409 conflict e não grava nada.

PUT /api/v1/scripts/67a92051-... HTTP/1.1
Authorization: Bearer ltp_api_...
Content-Type: application/json

{ "title": "...", "content": "...", "status": "ready", "expectedRevision": 3 }

As respostas de leitura e de alteração trazem a revisão atual no corpo e no header ETag (por exemplo, "4").

Tratando um conflitoCopiar link da seção

A resposta 409 traz a versão salva no servidor:

{
  "error": {
    "code": "conflict",
    "message": "O roteiro mudou em outro lugar. Revise antes de substituir.",
    "details": {
      "current": {
        "id": "67a92051-1245-4126-b9b4-2c532084ae16",
        "title": "Lançamento do produto",
        "content": "Texto editado no app...",
        "status": "review",
        "revision": 4,
        "createdAt": "2026-10-30T15:00:00.000Z",
        "updatedAt": "2026-10-30T15:44:02.118Z",
        "deletedAt": null
      }
    }
  }
}

Estratégias comuns:

• Mudança só de status: releia, aplique o novo status sobre o texto atual e grave com a nova revisão.
• Texto gerado por IA: crie um novo roteiro em vez de substituir um que a pessoa está editando.
• Interface própria: mostre as duas versões e deixe a pessoa escolher.

Operações que exigem revisãoCopiar link da seção

A criação não usa revisão. Para repetir uma criação com segurança, envie um id próprio: veja Como evitar roteiros duplicados.

Revisões e webhooksCopiar link da seção

Cada evento de webhook informa a revisão que o gerou. Uma gravação sem mudança real de título, texto ou status avança a revisão, mas não emite evento. Assim, a revisão do evento pode ser menor que a revisão atual do roteiro. Veja Eventos.