Documentação · API pública · v1

Integre seu sistema com o Oitiva.

A API pública permite que sistemas externos enviem áudio para transcrição, criem e leiam reuniões — direto no escritório do seu cliente, com a inteligência jurídica do Oitiva.

Visão geral

A API pública do Oitiva é uma API REST que permite que sistemas externos integrem com a plataforma. Com ela você pode:

Enviar áudio (reuniões, audiências, depoimentos) para transcrição.
Criar reuniões e vinculá-las a clientes e casos do escritório.
Ler reuniões, status de processamento, transcrições e atas.

Todas as requisições são autenticadas por API key e isoladas pelo escritório (tenant) dono da chave.

Autenticação

Toda requisição precisa do header Authorization: Bearer <sua_chave>. A chave é criada no painel, em Configurações → API Keys.

A chave secreta é exibida uma única vez, no momento da criação. Guarde-a em local seguro — não há como recuperá-la depois.

Cada chave é vinculada ao seu escritório (tenant) e tem escopos que limitam o que ela pode fazer.

curl

curl https://api.oitiva.com/api/public/v1/meetings \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"

Base URL

Todos os endpoints abaixo são relativos a:

base url

https://api.oitiva.com/api/public/v1

Escopos

Escopos definidos na criação da chave. Uma requisição a um endpoint sem o escopo necessário retorna 401.

`meetings:read`	Listar e ler reuniões.
`meetings:write`	Criar reuniões.
`transcribe:audio`	Enviar áudio para transcrição.

Endpoints

POST/transcribetranscribe:audio

Envia um arquivo de áudio para transcrição. Requisição multipart/form-data com o campo audio (arquivo). Retorna um job que processa de forma assíncrona.

Campo	Tipo	Obrig.	Descrição
`audio`	arquivo	sim	O arquivo de áudio a transcrever (multipart).
`outputType`	string	não	transcript_only para receber só a transcrição (pula o NLP).
`callbackUrl`	string	não	Webhook chamado quando o processamento terminar.

curl

curl -X POST https://api.oitiva.com/api/public/v1/transcribe \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -F "audio=@audiencia.m4a" \
  -F "outputType=transcript_only" \
  -F "callbackUrl=https://seu-sistema.com/webhooks/oitiva"

JavaScript (fetch)

const form = new FormData();
form.append('audio', fileBlob, 'audiencia.m4a');
form.append('outputType', 'transcript_only');
form.append('callbackUrl', 'https://seu-sistema.com/webhooks/oitiva');

const res = await fetch('https://api.oitiva.com/api/public/v1/transcribe', {
  method: 'POST',
  headers: { Authorization: 'Bearer sk_live_sua_chave_aqui' },
  body: form,
});
const job = await res.json();
// { jobId, status: 'PROCESSING', estimatedSeconds }

GET/jobs/:jobId

Consulta o status e o resultado de um job de transcrição. Use polling até status sair de PROCESSING.

curl

curl https://api.oitiva.com/api/public/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"

JavaScript (fetch)

const res = await fetch('https://api.oitiva.com/api/public/v1/jobs/JOB_ID', {
  headers: { Authorization: 'Bearer sk_live_sua_chave_aqui' },
});
const job = await res.json();
// { jobId, status: 'PROCESSING' | 'COMPLETED' | 'FAILED', transcript?, structured? }

GET/meetingsmeetings:read

Lista as reuniões do escritório. Paginado via parâmetro limit.

Campo	Tipo	Obrig.	Descrição
`limit`	number	não	Quantidade de reuniões por página.

curl

curl "https://api.oitiva.com/api/public/v1/meetings?limit=20" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"

JavaScript (fetch)

const res = await fetch('https://api.oitiva.com/api/public/v1/meetings?limit=20', {
  headers: { Authorization: 'Bearer sk_live_sua_chave_aqui' },
});
const { meetings } = await res.json();

GET/meetings/:idmeetings:read

Retorna o detalhe de uma reunião — status, ata/resumo e dados associados.

curl

curl https://api.oitiva.com/api/public/v1/meetings/MEETING_ID \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"

JavaScript (fetch)

const res = await fetch('https://api.oitiva.com/api/public/v1/meetings/MEETING_ID', {
  headers: { Authorization: 'Bearer sk_live_sua_chave_aqui' },
});
const meeting = await res.json();

POST/meetingsmeetings:write

Cria uma reunião. Opcionalmente vincula a um cliente e/ou caso existentes.

Campo	Tipo	Obrig.	Descrição
`type`	string	sim	Tipo da reunião.
`clienteId`	string	não	ID do cliente a vincular.
`casoId`	string	não	ID do caso a vincular.

curl

curl -X POST https://api.oitiva.com/api/public/v1/meetings \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "type": "CLIENT_MEETING", "clienteId": "cli_123" }'

JavaScript (fetch)

const res = await fetch('https://api.oitiva.com/api/public/v1/meetings', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_sua_chave_aqui',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: 'CLIENT_MEETING', clienteId: 'cli_123' }),
});
const meeting = await res.json();

Fluxo típico

O caminho mais comum, ponta a ponta:

Crie uma API key em Configurações → API Keys.
Envie o áudio com POST /transcribe e guarde o jobId.
Faça polling em GET /jobs/:jobId até o status virar COMPLETED.
Leia a transcrição/ata do resultado.

JavaScript (fetch) — ponta a ponta

const KEY = 'sk_live_sua_chave_aqui';
const BASE = 'https://api.oitiva.com/api/public/v1';
const auth = { Authorization: 'Bearer ' + KEY };

// 1. Envia o áudio
const form = new FormData();
form.append('audio', fileBlob, 'audiencia.m4a');
form.append('outputType', 'transcript_only');

const start = await fetch(BASE + '/transcribe', {
  method: 'POST',
  headers: auth,
  body: form,
}).then((r) => r.json());

// 2. Faz polling até concluir
async function waitJob(jobId) {
  while (true) {
    const job = await fetch(BASE + '/jobs/' + jobId, { headers: auth }).then((r) => r.json());
    if (job.status === 'COMPLETED') return job;
    if (job.status === 'FAILED') throw new Error('Job falhou');
    await new Promise((r) => setTimeout(r, 3000));
  }
}

// 3. Lê o resultado
const result = await waitJob(start.jobId);
console.log(result.transcript);

Webhooks

Se você enviar callbackUrl no POST /transcribe, o Oitiva faz uma requisição POST para essa URL quando o processamento terminar — evitando que você precise ficar fazendo polling.

O corpo da requisição inclui o jobId e o status final. Trate o webhook de forma idempotente e responda 2xx rapidamente.

Erros

Erros retornam um JSON no formato { error, code, message } com o status HTTP apropriado.

exemplo de erro

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "message": "Chave inválida ou sem escopo para esta operação."
}

`401`	Chave ausente, inválida, revogada ou sem o escopo necessário.
`404`	Recurso (job, reunião) não encontrado neste escritório.
`422`	Corpo/parâmetros inválidos (validação).
`500`	Erro interno. Tente novamente mais tarde.

Pronto pra integrar?

Crie sua primeira API key no painel e comece a enviar áudio em minutos.

Criar API key