Integracao estruturada para terceiros

O SoulScribe devolve transcricao, SOAP e um payload clinico versionado pronto para integracao.

O contrato principal da API e o payload_estruturado. Ele permite exibir SOAP, preencher campos do prontuario, sugerir CID, prescricoes, exames, encaminhamentos e orientacoes sem depender de parsing de texto livre.

O relatorio_soap continua existindo para apoio visual, mas a recomendacao oficial de integracao e consumir o JSON estruturado.

Artefato primario

payload_estruturado com version explicita.

Retorno previsivel

Strings vazias, listas como arrays e objetos vazios quando aplicavel.

Governanca

trace_info, confidence_score e evolucao por especialidade.

Revisao humana

O contrato foi desenhado para revisao antes da persistencia final.

Comecando

Primeira integracao

A forma mais simples de integrar e enviar um audio clinico via POST /api/v1/consultas com o header X-API-Key. No comportamento atual da API, o retorno de sucesso ja vem com a consulta concluida e com o payload_estruturado pronto para consumo.

Base URL
https://soulscribe.soulclinic.com.br/api/v1
Autenticacao
X-API-Key: sua_chave_api
curl -X POST "https://soulscribe.soulclinic.com.br/api/v1/consultas" \
  -H "X-API-Key: sua_chave_api" \
  -F "audio=@/caminho/consulta.mp3" \
  -F "especialidade=clinica_medica" \
  -F 'metadados={"atendimento_id":"AT-9001","origem":"erp_externo"}'
Integracao recomendada: leia o contrato em payload_estruturado ou resultado.payload_estruturado e use o relatorio_soap apenas como apoio visual.
Contrato

O JSON estruturado e o artefato primario da integracao

O contrato foi pensado para ser estavel, extensivel e backward-compatible. O objetivo e permitir que outro sistema consuma os dados clinicos sem depender da narrativa textual da IA.

Garantias do contrato

  • version obrigatoria
  • campos existentes nao mudam de tipo
  • listas sempre sao arrays
  • strings ausentes retornam ""
  • objetos vazios retornam {}

Campos centrais

  • soap
  • queixa_principal, hda, exame_fisico
  • cid_sugeridos e demais sugestoes
  • campos_estruturados_para_preenchimento
  • trace_info
{
  "version": "1.0",
  "source": "soulscribe",
  "soap": {
    "subjetivo": "",
    "objetivo": "",
    "avaliacao": "",
    "plano": ""
  },
  "resumo_clinico": "",
  "queixa_principal": "",
  "hda": "",
  "exame_fisico": "",
  "avaliacao_clinica": "",
  "plano_terapeutico": "",
  "cid_sugeridos": [],
  "prescricoes_sugeridas": [],
  "exames_sugeridos": [],
  "encaminhamentos_sugeridos": [],
  "orientacoes": [],
  "retorno_sugerido": {
    "prazo": "",
    "motivo": ""
  },
  "alertas_clinicos": [],
  "campos_estruturados_para_preenchimento": {
    "historico_clinico_anamnese": {},
    "historico_clinico_exame_fisico": {},
    "historico_clinico_conclusao_diagnostica": {},
    "historico_clinico_plano_tratamento": {},
    "historico_clinico_lista_problemas": {},
    "historico_clinico_carga_tabagica": {},
    "historico_clinico_pressao_arterial": {},
    "historico_clinico_imc": {},
    "campos_personalizados": []
  },
  "confidence_score": 0.0,
  "trace_info": {
    "transcript_id": "",
    "session_id": "",
    "generated_at": "",
    "model": "",
    "provider": "",
    "specialty": "",
    "schema_variant": "core",
    "generation_status": "complete",
    "normalization_applied": true,
    "warnings": [],
    "validation_errors": []
  }
}
Endpoints

Rotas mais importantes para integracao

Metodo Rota Uso principal
POST /api/v1/consultas Enviar audio e receber a consulta com o payload estruturado.
GET /api/v1/consultas Listar consultas do tenant autenticado.
GET /api/v1/consultas/{id} Obter uma consulta completa pelo ID.
POST /api/v1/consultas/{id-ou-uuid}/reprocessar Regerar a analise usando o audio ja armazenado.
GET /api/v1/consultas/{id-ou-uuid}/audio Baixar o audio ou seguir a URL remota preservada.
GET /api/v1/consultas/verificar-ias Listar provedores de IA disponiveis.
GET /api/v1/consultas/verificar-integridade Diagnosticar integridade das midias.

POST /api/v1/consultas

Aceita multipart/form-data com o arquivo em audio.

  • Formatos aceitos: mp3, webm, weba, mp4, m4a
  • Tamanho minimo: 1 KB
  • Tamanho maximo: 50 MB
  • Campos opcionais: especialidade, paciente_id, metadados, paciente_cpf, paciente_nome, paciente_telefone, paciente_email

GET /api/v1/consultas

Aceita filtros como limit, offset, status, especialidade, data_inicio, data_fim e paciente_id.

POST /api/v1/consultas/{id-ou-uuid}/reprocessar

Reprocessa a consulta usando a midia original e devolve novamente o envelope com resultado e payload_estruturado.

Resposta exemplo

Envelope recomendado para integradores

A API expoe o contrato em dois pontos: no topo da resposta e dentro de resultado. Isso reduz friccao para consumidores novos e preserva compatibilidade para fluxos existentes.

{
  "sucesso": true,
  "consulta": {
    "id": 123,
    "uuid": "b0a60f0e-c900-47b7-88f3-8bc5b2651bb9",
    "status": "concluida",
    "created_at": "2026-03-16 16:12:44"
  },
  "processamento": {
    "status": "concluido",
    "artefato_primario": "payload_estruturado",
    "ia_utilizada": "openai + openai",
    "tentativas": 1
  },
  "resultado": {
    "transcricao": "Paciente relata cefaleia frontal ha tres dias...",
    "relatorio_soap": {
      "subjetivo": "Paciente com cefaleia frontal...",
      "objetivo": "Afebril, PA 128/82 mmHg...",
      "avaliacao": "Cefaleia sem sinais de alarme...",
      "plano": "Analgesia simples..."
    },
    "payload_estruturado": {
      "version": "1.0",
      "source": "soulscribe",
      "queixa_principal": "Cefaleia frontal",
      "cid_sugeridos": [
        {
          "codigo": "R51",
          "descricao": "Cefaleia",
          "confidence": 0.82
        }
      ],
      "trace_info": {
        "transcript_id": "b0a60f0e-c900-47b7-88f3-8bc5b2651bb9",
        "session_id": "123",
        "generated_at": "2026-03-16T16:12:43-03:00",
        "model": "gpt-4o-mini"
      }
    }
  },
  "payload_estruturado": {
    "version": "1.0",
    "source": "soulscribe"
  }
}
Compatibilidade

Como integrar sem quebrar no futuro

Faca isso

  • Use payload_estruturado como verdade da integracao
  • Valide version
  • Guarde trace_info para auditoria
  • Ignore campos extras desconhecidos
  • Mantenha revisao humana antes de persistir

Evite isso

  • Regex no relatorio_soap
  • Assumir que campos vazios serao omitidos
  • Acoplar a integracao ao texto narrativo da IA
  • Persistir sugestoes automaticamente sem revisao
  • Rejeitar a resposta apenas porque surgiram campos novos
Especialidades

Preparado para evolucao por especialidade

O contrato atual usa um nucleo comum 1.0. A evolucao futura por especialidade deve acontecer de forma aditiva, sem quebrar o nucleo compartilhado.

  • o nucleo atual permanece estavel
  • campos especificos podem ser adicionados em campos_personalizados
  • trace_info.specialty informa a especialidade aplicada
  • trace_info.schema_variant identifica a variante do schema
Referencias

Arquivos importantes no repositorio

README.md
docs/INTEGRACAO_EXTERNA_SOULSCRIBE.md
docs/API_DOCUMENTATION_COMPLETE.md
docs/CONTRATO_JSON_ESTRUTURADO_SOULCLINIC.md
docs/schemas/soulscribe-clinical-payload-v1.schema.json
exemplos/api_examples.md
exemplos/api_response_example.json