Obter Status da Nota
Retorna o status atual de transcrição de uma nota específica.Rate Limiting: ⚡ Este endpoint NÃO possui rate limiting, mas recomendamos fazer chamadas com intervalo de pelo menos 5 segundos para evitar sobrecarga desnecessária.
Casos de Uso
Este endpoint é ideal para:- Polling de status: ⚡ Verificar periodicamente se uma transcrição foi concluída (sem rate limiting!)
- Integração assíncrona: Aguardar conclusão antes de buscar dados completos
- Monitoramento: Acompanhar o progresso de processamento em lote
- UI responsiva: Atualizar interface com status em tempo real
Exemplo de Polling Eficiente
async function pollNoteStatus(noteId, maxAttempts = 60) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(`/notes/${noteId}/status`, {
headers: { 'X-API-KEY': 'sua_api_key' }
});
const { data } = await response.json();
if (data.status === 'completed' || data.status === 'failed') {
return data;
}
// Aguardar 5 segundos antes da próxima verificação
await new Promise(resolve => setTimeout(resolve, 5000));
}
throw new Error('Timeout: Status polling exceeded maximum attempts');
}
Notas Importantes
Rate Limiting: ⚡ Este endpoint NÃO possui rate limiting, permitindo verificações frequentes quando necessário.
Recomendação: Mesmo sem rate limiting, implemente um intervalo de pelo menos 5 segundos entre verificações de status da mesma nota para evitar sobrecarga desnecessária do servidor.
Notas com status
completed podem ainda ter valid: false se falharam na validação. Use o endpoint /notes/{noteId} para obter detalhes sobre possíveis erros.OpenAPI
GET /notes/{noteId}/status
openapi: 3.0.3
info:
title: ConnectVets Notes API
description: API para transcrição e análise de consultas veterinárias
version: 1.0.0
contact:
name: ConnectVets Support
email: [email protected]
url: https://connectvets.com.br
license:
name: Proprietary
url: https://connectvets.com.br/terms
servers:
- url: https://api-sandbox.connectvets.com.br/notes/v1
description: Homologação
security:
- ApiKeyAuth: []
paths:
/notes/{noteId}/status:
get:
tags:
- Notes
summary: Obter status da nota
description: >
Retorna o status atual de transcrição de uma nota específica.
**Rate Limiting**: ⚡ Este endpoint **NÃO possui rate limiting**, mas
recomendamos fazer chamadas com intervalo de pelo menos 5 segundos para
evitar sobrecarga desnecessária.
operationId: getNoteStatus
parameters:
- name: noteId
in: path
required: true
schema:
type: string
format: uuid
description: ID da nota para verificar o status
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Status retornado com sucesso
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/StatusResult'
examples:
completed:
summary: Transcrição concluída
value:
data:
status: completed
valid: true
processing:
summary: Em processamento
value:
data:
status: processing
valid: false
failed:
summary: Falha no processamento
value:
data:
status: failed
valid: false
'400':
description: ID da nota inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: bad_request
message: Invalid note id
code: INVALID_NOTE_ID
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: forbidden
message: Note does not belong to tenant
code: NOTE_ACCESS_DENIED
'404':
$ref: '#/components/responses/NotFound'
'429':
description: Rate limit excedido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: too_many_requests
message: Rate limit exceeded
code: RATE_LIMIT_EXCEEDED
components:
schemas:
StatusResult:
type: object
required:
- status
- valid
properties:
status:
type: string
enum:
- pending
- processing
- completed
- failed
description: Status atual da transcrição
example: completed
valid:
type: boolean
description: Indica se a nota foi validada após o processamento
example: true
example:
status: completed
valid: true
Error:
type: object
properties:
error:
type: string
description: Código do erro
example: bad_request
message:
type: string
description: Mensagem de erro
example: Invalid audio format
code:
type: string
description: Código específico
example: INVALID_AUDIO_FORMAT
details:
type: object
description: Detalhes adicionais do erro
responses:
Unauthorized:
description: Não autorizado
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
message: API Key missing or invalid
code: INVALID_API_KEY
NotFound:
description: Recurso não encontrado
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: not_found
message: Note not found
code: NOTE_NOT_FOUND
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API Key para autenticação