Ingestão de Sessões de Mesas Virtuais (VTT)

1. Visão Geral

O endpoint de ingestão permite sincronizar anotações, atas de combate e registros de diário gerados durante as partidas em mesas virtuais diretamente no histórico da campanha no Adventure Keeper.

A comunicação exige um Personal Access Token com escopo sessions:write.

2. Endpoints Disponíveis

POST /api/v1/integrations/sessions: Ingestão informando o campaignId no corpo JSON da requisição.
POST /api/v1/integrations/campaigns/:campaignId/sessions: Ingestão informando o campaignId diretamente no parâmetro de rota.

3. Schema do Payload JSON

{
  "campaignId": "b6a7a0e5-7973-455b-8012-70b991316b23",
  "title": "Sessão 14: Os Salões de Ravenloft",
  "subtitle": "Exploração dos andares superiores",
  "sessionDate": "2026-11-14",
  "content": "<p>Os aventureiros cruzaram a ponte levadiça sob forte névoa...</p>",
  "tags": ["combate", "strahd", "castelo"],
  "source": "foundry-vtt",
  "externalId": "journal-entry-89Fh2"
}

Campo	Tipo	Obrigatório	Descrição
`campaignId`	`UUID`	Sim*	ID da campanha (*obrigatório se não fornecido na URL ou restrito no token).
`title`	`string`	Não	Título da sessão (máx. 255 caracteres).
`subtitle`	`string`	Não	Resumo ou subtítulo breve (máx. 500 caracteres).
`sessionDate`	`string`	Não	Data da sessão no formato `YYYY-MM-DD` (padrão: data atual).
`content`	`string`	Sim	Conteúdo textual ou HTML extraído do diário da mesa virtual.
`tags`	`string[]`	Não	Lista de marcadores temáticos.
`source`	`string`	Não	Identificador do cliente emissor (ex: `"foundry-vtt"`, `"roll20"`).
`externalId`	`string`	Não	ID único do registro no sistema externo para rastreabilidade.

4. Exemplo de Envio via cURL

curl -X POST "https://app.adventurekeeper.com.br/api/v1/integrations/sessions" \
  -H "Authorization: Bearer ak_pat_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "b6a7a0e5-7973-455b-8012-70b991316b23",
    "title": "Sessão 14: Os Salões de Ravenloft",
    "content": "<p>A batalha contra as gárgulas começou assim que o portão caiu.</p>",
    "tags": ["combate", "gargulas"],
    "source": "foundry-vtt"
  }'

Resposta de Sucesso (201 Created):

{
  "id": "8f3b6c20-a1e4-4589-b541-1188d92cb621",
  "campaignId": "b6a7a0e5-7973-455b-8012-70b991316b23",
  "number": 14,
  "title": "Sessão 14: Os Salões de Ravenloft",
  "subtitle": null,
  "sessionDate": "2026-11-14",
  "url": "/campaigns/b6a7a0e5-7973-455b-8012-70b991316b23/sessions/8f3b6c20-a1e4-4589-b541-1188d92cb621",
  "createdAt": "2026-11-14T12:00:00.000Z"
}

5. Módulo Oficial para Foundry VTT

Um módulo completo e pronto para uso está disponível no repositório oficial em: integrations/foundry-vtt.