Documentação da API ScreenApp v2.0.0

A API do ScreenApp permite transcrever, resumir e analisar automaticamente conteúdo de vídeo e áudio. Perfeito para empresas que desejam processar chamadas de clientes, vídeos de treinamento e gravações de reuniões em escala.

Principais Casos de Uso

Transcrição e Resumo Automáticos: Converta qualquer vídeo ou áudio em texto pesquisável e resumos concisos. Ideal para equipes de atendimento ao cliente, instituições de ensino e criadores de conteúdo.
Gestão de Conhecimento: Construa um repositório pesquisável de conteúdo de vídeo com transcrições automáticas, resumos e insights alimentados por IA. Perfeito para materiais de treinamento e bases de conhecimento da empresa.
Processamento em Tempo Real: Receba transcrições e resumos via webhooks assim que as gravações são processadas. Ótimo para integração com sistemas CRM e plataformas de atendimento ao cliente.
Gravação Incorporada: Adicione recursos de gravação de nível profissional ao seu aplicativo com nosso gravador incorporável que lida com a captura de tela e áudio.

✨ Caso de Uso Popular: As equipes de atendimento ao cliente usam nossa API para transcrever automaticamente as chamadas de suporte e gerar resumos, que são então sincronizados com seu CRM por meio de webhooks.

Obtenha as Credenciais da API no Painel →

Requisitos do Plano e Acesso à API

Para usar a API do ScreenApp, você precisará de:

Uma assinatura ativa do plano Business
Credenciais da API do seu painel do ScreenApp

Obtendo Suas Credenciais da API

Faça login na sua conta ScreenApp
Navegue até Configurações → Integração
Aqui você encontrará:
- Token da API
- ID da Equipe

Mantenha essas credenciais seguras e nunca as compartilhe publicamente.

Início Rápido

Quer começar imediatamente? Siga estes passos para integrar o ScreenApp ao seu site:

1. Instale o Plugin

Adicione este código ao HTML do seu site:

<script>
  // Código de instalação do plugin aqui
</script>

2. Adicione o Botão de Disparo

Adicione um botão ou elemento de disparo à sua página:

<button onclick="loadScreenApp()">Iniciar Gravação</button>

3. Configure o Callback

Personalize a função de callback para lidar com a conclusão da gravação:

function callback({ id, url }) {
  // Exemplo: Enviar para o seu backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Exemplo: Atualizar a UI
  document.getElementById('status').innerHTML = 
    `Gravação salva! Veja em ${url}`;
}

Autenticação

Todas as solicitações de API exigem autenticação. O ScreenApp usa autenticação baseada em token junto com identificadores específicos da equipe.

Credenciais que Você Precisará

Token da API: Sua chave de API secreta
ID da Equipe: Seu identificador de equipe exclusivo

Exemplo de Autenticação

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

Endpoints de Autenticação

`GET /auth/google`

Redireciona para o Google para autenticação

Parâmetros de Query:

redirectUrl - URL codificada para redirecionar o usuário após a autenticação bem-sucedida
referrerUrl - URL de Referência codificada
intent - Intenção para o usuário (por exemplo, “signup”)

`GET /auth/facebook`

Redireciona para o Facebook para autenticação

Parâmetros de Query:

redirectUrl - URL codificada para redirecionar o usuário após a autenticação bem-sucedida
referrerUrl - URL de Referência codificada
intent - Intenção para o usuário (por exemplo, “signup”)

Conceitos Essenciais

Antes de mergulhar em endpoints específicos, vamos entender os principais conceitos no ScreenApp:

Gravações: Capturas de vídeo e áudio que podem ser carregadas e processadas
Equipes: Grupos que podem compartilhar e gerenciar gravações
Webhooks: Notificações em tempo real para eventos de gravação e resultados de processamento
Tags: Metadados que podem ser anexados a gravações, equipes ou perfis de usuário

Referência da API

Gerenciamento de Equipe

`POST /team/{teamId}/tag`

Adiciona uma tag à equipe

Parâmetros de Caminho:

teamId - ID da equipe

Corpo da Requisição:

{
  "key": "color",
  "value": "red"
}

`DELETE /team/{teamId}/tag`

Remove uma tag da equipe

Parâmetros de Caminho:

teamId - ID da equipe

Corpo da Requisição:

{
  "key": "color"
}

Integração de Webhook da Equipe

`POST /team/{teamId}/integrations/webhook`

Registra uma nova URL de webhook para a equipe

Parâmetros de Caminho:

teamId - ID da equipe

Corpo da Requisição:

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

Respostas:

200 - Webhook registrado com sucesso
400 - Corpo da requisição inválido
500 - Erro interno do servidor

`DELETE /team/{teamId}/integrations/webhook`

Cancela o registro de uma URL de webhook para a equipe

Parâmetros de Caminho:

teamId - ID da equipe

Parâmetros de Query:

url - A URL do webhook para cancelar o registro

Respostas:

200 - Webhook cancelado o registro com sucesso
400 - Requisição inválida
404 - URL do webhook não encontrada
500 - Erro interno do servidor

`GET /team/{teamId}/integrations/zapier/sample/list`

Obtém dados de amostra para Zapier como um array

Parâmetros de Caminho:

teamId - ID da equipe

Respostas:

200 - Dados de amostra recuperados com sucesso
404 - Arquivo de amostra não encontrado

Integrações de Usuário

`POST /integrations/webhook`

Registra um novo webhook para o usuário

Corpo da Requisição:

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

Respostas:

200 - Webhook registrado com sucesso
400 - Corpo da requisição inválido

`DELETE /integrations/webhook`

Cancela o registro de um webhook para o usuário

Parâmetros de Query:

url - A URL do webhook para cancelar o registro

Respostas:

200 - Webhook cancelado o registro com sucesso
400 - Requisição inválida
404 - URL do webhook não encontrada

Eventos de Webhook

Seu endpoint de webhook receberá eventos neste formato:

{
  "event": "recording.completed",
  "fileId": "file789",
  "teamId": "team123",
  "data": {
    "url": "https://screenapp.io/recording/file789",
    "duration": 300,
    "status": "processed"
  }
}

Os eventos comuns incluem:

recording.started
recording.completed
recording.processed
recording.failed

Gerenciamento de Arquivos

`POST /files/{fileId}/tag`

Adiciona uma tag ao arquivo

Parâmetros de Caminho:

fileId - ID do arquivo

Corpo da Requisição:

{
  "key": "color",
  "value": "red"
}

`DELETE /files/{fileId}/tag`

Remove uma tag do arquivo

Parâmetros de Caminho:

fileId - ID do arquivo

Corpo da Requisição:

{
  "key": "color"
}

`POST /files/{fileId}/ask/multimodal`

Faz uma pergunta sobre um arquivo usando vários modelos de IA

Parâmetros de Caminho:

fileId - ID do arquivo a ser analisado

Corpo da Requisição:

{
  "promptText": "What are the key points discussed?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

Respostas:

200 - Pergunta processada com sucesso
403 - Limite de uso de IA excedido
500 - Erro do servidor

Upload de Arquivo

`POST /files/upload/{teamId}/{folderId}/url`

Gera URLs pré-assinadas para uploads de arquivos

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta

Corpo da Requisição:

{
  "files": [
    {
      "contentType": "video/mp4",
      "name": "meeting-recording.mp4"
    }
  ]
}

Respostas:

200 - URLs de upload geradas com sucesso
400 - Parâmetros de requisição inválidos
500 - Erro do servidor

`POST /files/upload/{teamId}/{folderId}/finalize`

Finaliza arquivos carregados

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta

Corpo da Requisição:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Weekly sales call with customer",
    "recorderName": "John Doe",
    "recorderEmail": "[email protected]"
  }
}

Respostas:

200 - Upload de arquivo finalizado com sucesso
400 - Parâmetros de requisição inválidos
403 - Limite de upload excedido
500 - Erro do servidor

Upload Multipart (para arquivos grandes)

`PUT /files/upload/multipart/init/{teamId}/{folderId}`

Inicializa um upload multipart para um arquivo grande

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta

Corpo da Requisição:

{
  "contentType": "video/mp4"
}

Respostas:

200 - Upload inicializado com sucesso
400 - Parâmetros de requisição inválidos
500 - Erro do servidor

Exemplo de Resposta:

{
  "success": true,
  "data": {
    "fileId": "file789",
    "uploadId": "upload123"
  }
}

`PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}`

Obtém a URL de upload para uma parte específica

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta
fileId - ID do arquivo sendo carregado
uploadId - ID da sessão de upload multipart
partNumber - Número da parte (1-10000)

Corpo da Requisição:

{
  "contentType": "video/mp4"
}

Respostas:

200 - URL de upload gerada com sucesso
400 - Parâmetros de requisição inválidos
500 - Erro do servidor

Exemplo de Resposta:

{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned-s3-url.com/part1"
  }
}

`PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}`

Finaliza um upload multipart

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta
fileId - ID do arquivo sendo carregado
uploadId - ID da sessão de upload multipart

Corpo da Requisição:

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "[email protected]",
    "name": "My Recording",
    "description": "A recorded video session",
    "notes": [
      {
        "text": "Important point discussed",
        "timestamp": 1234567890
      }
    ]
  }
}

Respostas:

200 - Upload finalizado com sucesso
400 - Parâmetros de requisição inválidos
404 - Upload ativo não encontrado
500 - Erro do servidor

`PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}`

Carrega parte do arquivo via backend (fallback)

Parâmetros de Caminho:

teamId - ID da equipe
folderId - ID da pasta
fileId - ID do arquivo sendo carregado
partNumber - Número da parte (1-10000)

Dados do Formulário:

file - A parte do arquivo para carregar
contentType - Tipo MIME do arquivo sendo carregado

Respostas:

200 - Parte carregada com sucesso
400 - Parâmetros de requisição inválidos
500 - Erro do servidor

Gerenciamento de Conta

`POST /v2/account/tag`

Adiciona uma tag ao usuário autenticado

Corpo da Requisição:

{
  "key": "color",
  "value": "red"
}

Respostas:

200 - Tag adicionada com sucesso
400 - Parâmetros de requisição inválidos

`PUT /account/profile`

Atualiza o perfil do usuário autenticado

Corpo da Requisição:

{
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "gender": "male",
  "userType": "user",
  "company": "Acme Inc",
  "role": "Developer",
  "goals": "Learn new technologies",
  "phoneNumber": "+1234567890",
  "location": "San Francisco, CA",
  "website": "https://example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "local",
  "providerId": "12345",
  "primaryField": "development"
}

Respostas:

200 - Perfil atualizado com sucesso
400 - Parâmetros de requisição inválidos

Recursos Avançados

Análise de IA

Use IA para analisar suas gravações em busca de insights:

// Solicita análise de IA de uma gravação
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "What are the key discussion points?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Operações em Lote

Gerencie várias gravações de forma eficiente:

// Marca várias gravações
async function batchTag(fileIds, tag) {
  const promises = fileIds.map(fileId => 
    fetch(`/v2/files/${fileId}/tag`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tag)
    })
  );
  await Promise.all(promises);
}

Tratamento de Erros

Códigos de Erro Comuns

400: Parâmetros de requisição inválidos
403: Limite de uso de IA excedido ou acesso não autorizado
404: Recurso não encontrado
500: Erro do servidor

Formato da Resposta de Erro

As respostas de erro normalmente seguem este formato:

{
  "success": false,
  "message": "Detailed error message"
}

Exemplos

Configurando Webhooks de Equipe

Os webhooks permitem que você receba atualizações em tempo real quando as gravações são processadas:

// Registra um novo webhook para sua equipe
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  return await response.json();
}

// Exemplo de uso
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Recording Updates'
);

Carregando e Processando um Arquivo Grande

Para arquivos maiores que 100 MB, use o fluxo de upload multipart:

// 1. Inicializa o upload
const initResponse = await fetch(`/v2/files/upload/multipart/init/${teamId}/${folderId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contentType: 'video/mp4'
  })
});

const { data: { fileId, uploadId } } = await initResponse.json();

// 2. Divide o arquivo em partes e carrega cada parte
const CHUNK_SIZE = 5 * 1024 * 1024; // Partes de 5MB
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Obtém a URL de upload para esta parte
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // Cria a parte do arquivo
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Carrega a parte diretamente para o S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finaliza o upload
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: 'Customer Meeting Recording',
        description: 'Quarterly review with client',
        recorderName: 'Jane Smith',
        recorderEmail: '[email protected]'
      }
    })
  }
);

Obtenha as Credenciais da API no Painel →

Documentação da API ScreenApp v2.0.0

Principais Casos de Uso

Requisitos do Plano e Acesso à API

Obtendo Suas Credenciais da API

Início Rápido

1. Instale o Plugin

2. Adicione o Botão de Disparo

3. Configure o Callback

Autenticação

Credenciais que Você Precisará

Exemplo de Autenticação

Endpoints de Autenticação

GET /auth/google

GET /auth/facebook

Conceitos Essenciais

Referência da API

Gerenciamento de Equipe

POST /team/{teamId}/tag

DELETE /team/{teamId}/tag

Integração de Webhook da Equipe

POST /team/{teamId}/integrations/webhook

DELETE /team/{teamId}/integrations/webhook

GET /team/{teamId}/integrations/zapier/sample/list

Integrações de Usuário

POST /integrations/webhook

DELETE /integrations/webhook

Eventos de Webhook

Gerenciamento de Arquivos

POST /files/{fileId}/tag

DELETE /files/{fileId}/tag

POST /files/{fileId}/ask/multimodal

Upload de Arquivo

POST /files/upload/{teamId}/{folderId}/url

POST /files/upload/{teamId}/{folderId}/finalize

Upload Multipart (para arquivos grandes)

PUT /files/upload/multipart/init/{teamId}/{folderId}

PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}

PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}

PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}

Gerenciamento de Conta

POST /v2/account/tag

PUT /account/profile

Recursos Avançados

Análise de IA

Operações em Lote

Tratamento de Erros

Códigos de Erro Comuns

Formato da Resposta de Erro

Exemplos

Configurando Webhooks de Equipe

Carregando e Processando um Arquivo Grande

We value your privacy

`GET /auth/google`

`GET /auth/facebook`

`POST /team/{teamId}/tag`

`DELETE /team/{teamId}/tag`

`POST /team/{teamId}/integrations/webhook`

`DELETE /team/{teamId}/integrations/webhook`

`GET /team/{teamId}/integrations/zapier/sample/list`

`POST /integrations/webhook`

`DELETE /integrations/webhook`

`POST /files/{fileId}/tag`

`DELETE /files/{fileId}/tag`

`POST /files/{fileId}/ask/multimodal`

`POST /files/upload/{teamId}/{folderId}/url`

`POST /files/upload/{teamId}/{folderId}/finalize`

`PUT /files/upload/multipart/init/{teamId}/{folderId}`

`PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}`

`PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}`

`PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}`

`POST /v2/account/tag`

`PUT /account/profile`