API de Upload de Pacientes - Documentação

A API de Upload de Pacientes permite que instituições enviem registros de pacientes diretamente para o seu workspace Arkangel de forma programática, sem intervenção manual. Após o envio, os arquivos são processados automaticamente e os resultados aparecem no workspace Pandora da sua equipe.

Pré-requisitos

Entre em contato com a Arkangel para receber:

Chave de API — usada para autenticar cada requisição
Team ID — identifica sua organização dentro do Arkangel

Formatos suportados

Formato	Descrição	Notas
PDF	Históricos clínicos, sumários de alta, laudos laboratoriais	1 arquivo = 1 paciente
TXT	Notas clínicas em texto simples	1 arquivo = 1 paciente
CSV	Dados estruturados de pacientes ou eventos	Ver formato CSV abaixo

Tamanho máximo por arquivo: 3MB.

Formato CSV

Os arquivos CSV devem ter patient_id como cabeçalho da primeira coluna. O cabeçalho da segunda coluna determina o tipo de arquivo:

Arquivo de pacientes (1 linha = 1 paciente)

A segunda coluna pode ser qualquer coisa ou estar ausente.

patient_id,nome,data_nascimento,diagnostico
p-001,Ana Silva,1980-03-12,DPOC
p-002,Carlos Santos,1975-07-22,Asma

Arquivo de eventos (várias linhas = 1 paciente)

A segunda coluna deve chamar-se event_id. Todas as linhas com o mesmo patient_id são agrupadas em um único registro de paciente.

patient_id,event_id,data,tipo_evento,valor,unidade
p-001,e-001,2026-01-10,SpO2,94,%
p-001,e-002,2026-01-10,frequencia_cardiaca,88,bpm
p-002,e-001,2026-01-11,SpO2,97,%

Enviar um arquivo

Endpoint

POST /api/pandora/upload-v2/upload

Cabeçalhos

Authorization: Bearer sua_chave_api

Campos do formulário

Campo	Obrigatório	Descrição
`file`	Sim	O arquivo a enviar (PDF, TXT ou CSV)
`teamId`	Sim	Seu Team ID
`groupId`	Sim	ID do grupo Pandora ao qual os pacientes serão adicionados
`anonymize`	Não	Envie `true` para anonimizar os registros após a extração (padrão: `false`)

Requisição

curl -X POST https://arkangel.ai/api/pandora/upload-v2/upload \
  -H "Authorization: Bearer sua_chave_api" \
  -F "file=@pacientes.csv" \
  -F "teamId=seu_team_id" \
  -F "groupId=seu_group_id" \
  -F "anonymize=false"

Exemplo em JavaScript

const formData = new FormData();
formData.append('file', file);
formData.append('teamId', 'seu_team_id');
formData.append('groupId', 'seu_group_id');
formData.append('anonymize', 'false');

const response = await fetch('https://arkangel.ai/api/pandora/upload-v2/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sua_chave_api'
  },
  body: formData
});

const result = await response.json();

Resposta

{
  "success": true,
  "patientCount": 3
}

patientCount indica o número de pacientes ingeridos com sucesso. Para PDF e TXT é sempre 1. Para CSV corresponde ao número de linhas (arquivo de pacientes) ou valores únicos de patient_id (arquivo de eventos).

Se algum paciente não puder ser ingerido por erro de armazenamento, expectedCount também é retornado para detectar a discrepância e reenviar as linhas ausentes:

{
  "success": true,
  "patientCount": 2,
  "expectedCount": 3
}

Tratamento de erros

Código	Erro	Descrição
400	`invalid_file_type`	Formato de arquivo não suportado
400	`file_too_large`	O arquivo ultrapassa o limite de 3MB
400	`invalid_csv_format`	A primeira coluna não é `patient_id`
400	`missing_patient_id`	Uma ou mais linhas têm `patient_id` vazio
401	`unauthorized`	Chave de API ausente ou inválida
403	`forbidden`	A chave de API não tem acesso a esta equipe
413	`payload_too_large`	O corpo da requisição excede o limite do servidor
500	`internal_error`	Erro inesperado do servidor — entre em contato com o suporte

Resultado

Nenhuma chamada adicional é necessária. Após o envio, os dados dos pacientes são processados e ficam disponíveis automaticamente no workspace Pandora da sua equipe.

Próximos passos

Autenticação — Gerencie sua chave de API
Referência HTTP — Ver todos os códigos de status