Guia Prático

Documentação da API e SDK do ScreenApp

A API do ScreenApps permite transcrever, resumir e analisar automaticamente conteúdo de vídeo e áudio

Por Equipe ScreenApp

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

✨ 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:

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

Obtendo Suas Credenciais da API

  1. Faça login na sua conta ScreenApp
  2. Navegue até Configurações → Integração
  3. 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á

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:

GET /auth/facebook

Redireciona para o Facebook para autenticação

Parâmetros de Query:

Conceitos Essenciais

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

  1. Gravações: Capturas de vídeo e áudio que podem ser carregadas e processadas
  2. Equipes: Grupos que podem compartilhar e gerenciar gravações
  3. Webhooks: Notificações em tempo real para eventos de gravação e resultados de processamento
  4. 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:

Corpo da Requisição:

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

DELETE /team/{teamId}/tag

Remove uma tag da equipe

Parâmetros de Caminho:

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:

Corpo da Requisição:

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

Respostas:

DELETE /team/{teamId}/integrations/webhook

Cancela o registro de uma URL de webhook para a equipe

Parâmetros de Caminho:

Parâmetros de Query:

Respostas:

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

Obtém dados de amostra para Zapier como um array

Parâmetros de Caminho:

Respostas:

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:

DELETE /integrations/webhook

Cancela o registro de um webhook para o usuário

Parâmetros de Query:

Respostas:

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:

Gerenciamento de Arquivos

POST /files/{fileId}/tag

Adiciona uma tag ao arquivo

Parâmetros de Caminho:

Corpo da Requisição:

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

DELETE /files/{fileId}/tag

Remove uma tag do arquivo

Parâmetros de Caminho:

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:

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:

Upload de Arquivo

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

Gera URLs pré-assinadas para uploads de arquivos

Parâmetros de Caminho:

Corpo da Requisição:

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

Respostas:

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

Finaliza arquivos carregados

Parâmetros de Caminho:

Corpo da Requisição:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Weekly sales call with customer",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Respostas:

Upload Multipart (para arquivos grandes)

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

Inicializa um upload multipart para um arquivo grande

Parâmetros de Caminho:

Corpo da Requisição:

{
  "contentType": "video/mp4"
}

Respostas:

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:

Corpo da Requisição:

{
  "contentType": "video/mp4"
}

Respostas:

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:

Corpo da Requisição:

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

Respostas:

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

Carrega parte do arquivo via backend (fallback)

Parâmetros de Caminho:

Dados do Formulário:

Respostas:

Gerenciamento de Conta

POST /v2/account/tag

Adiciona uma tag ao usuário autenticado

Corpo da Requisição:

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

Respostas:

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:

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

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: 'jane@example.com'
      }
    })
  }
);

Obtenha as Credenciais da API no Painel →