Manual de Integração

Este manual descreve as integrações possíveis com o eDok através de suas APIs. As APIs são projetadas para facilitar a integração dos documentos gerenciados pelo eDok aos fluxos de negócio utilizando sistemas de terceiros. Por exemplo, um CRM pode carregar diretamente um documento armazenado no eDok de modo transparente, sem que o seu usuário precise deixar o CRM.

O conteúdo deste manual é direcionado a analistas e programadores envolvidos nos projetos de integração de sistemas.

Para saber como utilizar outras funcionalidades do eDok, consulte os manuais na barra lateral.

APIs Disponíveis

As APIs disponíveis no eDok são:

As APIs do eDok são seguras! Suportamos TLS 1.3 com PFS e o acesso depende de chave de API.

DocMetadata

Esta API é um endpoint que unifica as ações relativas à manipulação, controle e obtenção de metadados dos documentos gerenciados pelo eDok.

Para consumir esta API, você deve fazer uma requisição GET ou POST conforme o exemplo abaixo:

curl -H "X-SecretAccessKey: secret" -X método -d 'diretriz' \
  https://<endereço>.edok.com.br/api/DocMetadata.php?Action=ação

Onde:

• secret: chave de acesso da API no eDok;
• método: método GET ou POST, dependendo da ação;
• diretriz: objeto JSON com os parâmetros da requisição, quando necessário;
• ação: ação a ser executada na API DocMetadata.

As ações disponíveis, suas diretrizes, retornos e respostas são descritas abaixo.

Ações Disponíveis

Respostas Comuns

As respostas abaixo são comuns a todas as ações desta API:

DescribeDoc

Diretriz

{
  "Version": 2,
  "Statement": {
    "PrimaryMeta": {
      "DocType": "FI",
      "NR_ATENDIMENTO": "910100",
      "NR_PRONTUARIO": "410100",
      "DATA": "20210817"
    }
  }
}

Retorno

{
    "DocMetadata": {
        "Response": "Success",
        "Message": "Document metadata description for eDokID 18.",
        "Action": "DescribeDoc",
        "Document": {
            "eDokID": "18",
            "RepositoryPath": "f0/c4/JEmDNTlRagqlO16B0j5s1ja5UHhOQ2vXiGvEsN1J.pdf",
            "IngestDate": "2023-06-04T01:17:10-0300",
            "DocType": "FI",
            "PrimaryMeta": {
                "NR_ATENDIMENTO": "910100",
                "NR_PRONTUARIO": "410100",
                "DATA": "20210817"
            },
            "SecondaryMeta": {
                "CAIXA": "CX01"
            }
        }
    }
}

Respostas

Algumas respostas foram alteradas em relação às gerações anteriores:

DocTrashByID

A remoção de um documento com esta ação não é permamente. Para apagar o documento em definitivo, é necessário removê-lo da lixeira.

Esta é uma nova ação que não existia nas gerações anteriores.

Diretriz

{
    "Version": 2,
    "Statement": {
        "eDokID": 11
    }
}

Retorno

{
    "DocMetadata": {
        "Response": "Success",
        "Message": "Document sent to trash by ID.",
        "Action": "DocTrashByID",
        "Document": {
            "eDokID": "11",
            "RepositoryPath": "8f/d9/nsuePWSBUqU6Atyleo8lQ1CzKV8FHNMHSiOQ1aCm.pdf",
            "IngestDate": "2023-06-04T01:17:06-0300",
            "DocType": "WK"
        }
    }
}

Respostas

ExportMetadata

O envio da diretriz não é obrigatório. Caso seja enviada, DocType é opcional e restringe o retorno aos documentos do tipo especificado. Caso a diretriz não seja enviada, o retorno conterá os documentos de todos os tipos compreendidos dentro do intervalo padrão de 30 dias ou do intervalo especificado na diretriz. Ao especificar o intervalo, o máximo é de 30 dias.

Diretriz

{
  "Version": 2,
  "Statement": {
    "DocType": "FI",
    "DateRange": {
      "StartDate": "2023-05-05",
      "EndDate": "2023-06-04"
    }
  }
}

Retorno

{
  "DocMetadata": {
    "Response": "Success",
    "Message": "Documents from 2023-05-05T00:00:00-0300 to 2023-06-04T23:59:59-0300 where document type code is FI.",
    "Action": "ExportMetadata",
    "Documents": [
      {
        "eDokID": "18",
        "RepositoryPath": "f0/c4/JEmDNTlRagqlO16B0j5s1ja5UHhOQ2vXiGvEsN1J.pdf",
        "IngestDate": "2023-06-04T01:17:10-0300",
        "DocType": "FI",
        "Metadata": {
          "NR_ATENDIMENTO": "910100",
          "NR_PRONTUARIO": "410100",
          "DATA": "20210817",
          "CAIXA": "CX01"
        }
      },
      {
        "eDokID": "30",
        "RepositoryPath": "c5/54/6rJLYla3qSlwORx7uCdmRRHd7WJWmDUNluP9Quwd.pdf",
        "IngestDate": "2023-06-04T01:17:40-0300",
        "DocType": "FI",
        "Metadata": {
          "NR_ATENDIMENTO": "989760",
          "NR_PRONTUARIO": "454012",
          "DATA": "20180713",
          "CAIXA": "C123"
        }
      },
      {
        "eDokID": "36",
        "RepositoryPath": "10/77/f1RBd4uUAb64yt76WKf1P7ciMKTJgk1RvRSo9JPn.pdf",
        "IngestDate": "2023-06-04T01:17:50-0300",
        "DocType": "FI",
        "Metadata": {
          "NR_ATENDIMENTO": "989720",
          "NR_PRONTUARIO": "454012",
          "DATA": "20180618",
          "CAIXA": "C123"
        }
      }
    ]
  }
}

Respostas

Algumas respostas foram alteradas em relação às gerações anteriores:

GetDocWithNoMetadata

O envio da diretriz não é obrigatório. Caso a diretriz não seja enviada, o retorno conterá compreendidos dentro do intervalo padrão de 30 dias ou do intervalo especificado na diretriz. Ao especificar o intervalo, o máximo é de 30 dias.

Diretriz

{
  "Version": 2,
  "Statement": {
    "DateRange": {
      "StartDate": "2023-05-05",
      "EndDate": "2023-06-04"
    }
  }
}

Retorno

{
  "DocMetadata": {
    "Response": "Success",
    "Message": "Documents with missing secondary metadata from 2023-05-05T00:00:00-0300 to 2023-06-04T23:59:59-0300.",
    "Action": "GetDocWithNoMetadata",
    "Documents": [
      {
        "eDokID": "17",
        "RepositoryPath": "80/dc/PfbfunIeSxU6Wk1H4ph9uZ9mLF6PlyaMnIrkGSd1.pdf",
        "IngestDate": "2023-06-04T01:17:09-0300",
        "DocType": "RE",
        "PrimaryMeta": {
          "EMPREGADO": "510100"
        },
        "SecondaryMissing": [
          "SALARIO",
          "NUMERO",
          "CPF",
          "CNPJ"
        ]
      }
    ]
  }
}

Respostas

Algumas respostas foram alteradas em relação às gerações anteriores:

PostDocMetadataByID

Esta ação permite alterar qualquer metadado de um documento, sejam primários ou secundários.

Esta é uma nova ação que não existia nas gerações anteriores.

Ao alterar os metadados primários, os demais metadados, as assinaturas digitais e a data de vencimento serão atualizados, bem como as chaves de integridade do documento. Caso o documento contenha alguma assinatura eletrônica, elas serão invalidadas e deverão ser requisitadas novamente.

Diretriz

{
  "Version": 2,
  "Statement": {
    "eDokID": 18,
    "Metadata": {
      "NR_ATENDIMENTO": "910109",
      "NR_PRONTUARIO": "410100",
      "DATA": "20210817",
      "CAIXA": "CX01"
    }
  }
}

Retorno

{
  "DocMetadata": {
    "Response": "Success",
    "Message": "Document metadata updated.",
    "Action": "PostDocMetadataByID",
    "Document": {
      "eDokID": "18",
      "RepositoryPath": "f0/c4/JEmDNTlRagqlO16B0j5s1ja5UHhOQ2vXiGvEsN1J.pdf",
      "IngestDate": "2023-06-04T01:17:10-0300",
      "DocType": "FI",
      "PrimaryMeta": {
        "NR_ATENDIMENTO": "910109",
        "NR_PRONTUARIO": "410100",
        "DATA": "20210817"
      },
      "SecondaryMeta": {
        "CAIXA": "CX01"
      }
    }
  }
}

Respostas

PostDocMetadata

Esta ação permite alterar metadados secundários de um ou mais documentos especificados pelos metadados primários. Todos os documentos que combinem com os metadados primários informados terão seus metadados secundários alterados.

Diretriz

{
  "Version": 2,
  "Statement": {
    "PrimaryMeta": {
      "DocType": "FI",
      "NR_ATENDIMENTO": "910100",
      "NR_PRONTUARIO": "410100",
      "DATA": "20210817",
      "SecondaryMeta": {
        "CAIXA": "CX01"
      }
    }
  }
}

Retorno

{
  "DocMetadata": {
    "Response": "Success",
    "Message": "Document metadata updated.",
    "Action": "PostDocMetadata",
    "Document": {
      "eDokID": "18",
      "RepositoryPath": "f0/c4/JEmDNTlRagqlO16B0j5s1ja5UHhOQ2vXiGvEsN1J.pdf",
      "IngestDate": "2023-06-04T01:17:10-0300",
      "DocType": "FI",
      "PrimaryMeta": {
        "NR_ATENDIMENTO": "910100",
        "NR_PRONTUARIO": "410100",
        "DATA": "20210817"
      },
      "SecondaryMeta": {
        "CAIXA": "CX01"
      }
    }
  }
}

Respostas

Algumas respostas foram alteradas em relação às gerações anteriores:

DocView

Esta API é um endpoint que provê um método para visualizar um documento específico gerenciado pelo eDok. Diferente da API ViewDocs, esta API visualiza somente um documento por vez em cada requisição.

A visualização de documentos nesta API funciona da mesma forma em computadores e dispositivos móveis.

Esta API implementa as seguintes configurações do eDok:

• Restrito na API
• Chave de Acesso

Para consumir esta API, você deve fazer uma requisição POST (recomendado) ou GET para o seguinte endpoint:

https://<endereço>.edok.com.br/api/docview?parâmetros

O endpoint desta API nas gerações anteriores era /api/DocView.php. Esse endpoint está obsoleto, porém redireciona para o novo e será removido no futuro. Atualize as chamadas que utilizem o endpoint obsoleto.

Os parâmetros para o consumo desta API são:

Ao carregar um documento, os campos a seguir são mostrados:

Exemplos

• Requisição com ID:

  K=secret&ID=989760
  

• Requisição com ID e tipo de documento:

  K=secret&ID=989760&DT=2
  

Caso existam mais de um documento no eDok com os mesmos identificadores e tipo, apenas o documento mais recente é visualizado.

Respostas

Algumas respostas foram removidas em relação às gerações anteriores:

Portal

Esta API é um endpoint que provê um método acessar a API ViewDocs de modo simplificado.

A visualização de documentos nesta API funciona da mesma forma em computadores e dispositivos móveis.

Para consumir esta API, você deve fazer uma requisição GET no endpoint:

https://<endereço>.edok.com.br/api/portal

O endpoint desta API nas gerações anteriores era /api/portal/SameCover.php. Esse endpoint está obsoleto, porém redireciona para o novo e será removido no futuro. Atualize as chamadas que utilizem o endpoint obsoleto.

Para visualizar um documento, basta digitar seu primeiro identificador no campo Qual atendimento você procura? e apertar enter. A API ViewDocs será carregada com o documento solicitado (caso exista). Os prefixos p e a suportados pela API ViewDocs também podem ser utilizados (ver exemplos).

O caso de uso típico desta API se aplica a sistemas de gestão (CRM, ERP etc) que cobram por usuário, ou o administrador não deseja criar uma conta de usuário no eDok só para colaboradores visualizarem documentos. Neste caso, pode ser criado um acesso via portal com autenticação própria na aplicação intranet.

Esta API vem desativada por padrão. Para ativá-la, entre em contado com o suporte técnico. Uma autenticação própria é mandatória para utilizar este recurso. Não nos responsabilizamos pelo acesso sem restrições a esta API.

Upload

Esta API é um endpoint que provê um método para enviar documentos utilizando as mesmas capacidades do eDok Ingest, com exceção do reconhecimento de indexadores (via nome de arquivo ou etiquetas).

Utilizando esta API, um integrador pode enviar imediatamente qualquer documento para o eDok, sendo que seus indexadores podem ser obtidos de qualquer fonte desejada. Como ela é síncrona, o documento estará disponível imediatamente no repositório para qualquer operação adicional.

Utilize esta API para integrar ao eDok qualquer sistema de terceiros que produza documentos com indexadores conhecidos, proporcionando um fluxo de admissão de documentos automatizado, seguro, imediato e escalável.

Todas as funcionalidades dos tipos de documentos, conformidade e assinaturas digitais estão presentes nesta API, incluindo as regras dos campos identificadores nos tipos de documentos.

Para consumir esta API, você deve fazer uma requisição POST do tipo multipart/form-data conforme o exemplo abaixo:

$> curl --location 'https://<endereço>.edok.com.br/api/upload' \
     --form 'key="secret"' \
     --form 'doctype_id="2"' \
     --form 'fields[NR_ATENDIMENTO]="910100"' \
     --form 'fields[NR_PRONTUARIO]="410100"' \
     --form 'fields[DATA]="20240310"' \
     --form 'fields[CAIXA]="CX01"' \
     --form 'file=@"/path/to/file.pdf"' \
     --form 'parent_id="8"' \
     --form 'name="Upload API Test Name"' \
     --form 'description="Upload API Test Description"' \
     --form 'archive_original="0"' \
     --form 'user_id="1"' \
     --form 'roles[]="3"' \
     --form 'roles[]="4"' \
     --form 'origin="API"'

Uma requisição POST em multipart/form-data permite apontar diretamente o arquivo do documento, sem que haja a necessidade de codificá-lo em outros formatos (ex. Base64) economizando recursos computacionais, de rede e de tempo. Se sua aplicação gera arquivos dinamicamente, eles devem ser salvos temporariamente no sistema de arquivos antes da requisição, podendo ser eliminados após o envio bem-sucedido.

A tabela abaixo descreve os campos da requisição, com os obrigatórios primeiro:

O usuário padrão para envio de documentos é definido por configuração interna, não acessível pela interface web. Caso necessite alterar o usuário configurado, solicite ao nosso suporte técnico.

Retorno

{
  "Response": "Success",
  "Message": "The document FI910100-HOLGnQbk was successfully created.",
  "URL": "https://<endereço>.edok.com.br/docs/show/document/18"
}

Os atributos do retorno podem ser:

• Response: o tipo da reposta, que pode ser Error, Warning ou Success;
• Fields: caso Response seja Error, descreve todos os erros de validação contidos na requisição;
• Message: descreve o estado do processamento da requisição (pós-validação);
• URL: caso Response seja Warning ou Success, contém o endereço da tela de propriedades do documento criado, sendo o ID do documento no eDok o elemento final da URL, podendo ser utilizado pela linguagem de programação desejada. Por exemplo:

  # Bash
  url="https://<endereço>.edok.com.br/docs/show/document/18"
  ${url##*/} # 18
  
  # PHP
  basename("https://<endereço>.edok.com.br/docs/show/document/18") // 18
  
  # C#
  using System.Linq;
  string url = "https://<endereço>.edok.com.br/docs/show/document/18";
  url.Split('/').Last(); // 18
  

Respostas

ViewDocs

Esta API é um endpoint que provê um método para visualizar e navegar por documentos gerenciados pelo eDok. Diferente da API DocView, esta API permite acessar múltiplos documentos a partir da primeira requisição, desde que estejam relacionados pelos identificadores.

A visualização de documentos nesta API funciona da mesma forma em computadores e dispositivos móveis.

Esta API implementa as seguintes configurações do eDok:

• Restrito na API
• Ordem dos Tipos de Documentos
• Chave de Acesso
• Primeiro Identificador
• Rótulo do Primeiro Identificador
• Segundo Identificador
• Rótulo do Segundo Identificador

Para consumir esta API, você deve fazer uma requisição POST (recomendado) ou GET para o seguinte endpoint:

https://<endereço>.edok.com.br/api/viewdocs?parâmetros

O endpoint desta API nas gerações anteriores era /api/SameCover.php. Esse endpoint está obsoleto, porém redireciona para o novo e será removido no futuro. Atualize as chamadas que utilizem o endpoint obsoleto.

Os parâmetros para o consumo desta API são:

Ao carregar um documento, os campos a seguir são mostrados:

Na lista de documentos, as opções a seguir estarão disponíveis automaticamente (se aplicável):

O segundo identificador funciona como um agrupador de documentos. Por exemplo: múltiplos atendimentos fazem parte do mesmo prontuário do paciente. Havendo múltiplos documentos com atendimentos e prontuário idênticos, o documento mais recente é carregado e os demais poderão ser acessados pelos seletores. Para visualizar outros documentos do conjunto requisitado, basta selecionar o documento desejado na lista. Não é necessário digitar enter após a seleção, pois o carregamento é feito de forma automática ao escolher o novo tipo.

Quando uma opção com múltiplos tipos é selecionada, os documentos relevantes são mostrados simultaneamente. Role a página para vê-los e, caso deseje visualizar um documento de modo exclusivo, clique na ferramenta tela cheia para abri-lo em tela cheia. Para sair do modo tela cheia, pressione esc.

Na visualização de múltiplos tipos, cada documento possui um rótulo com tipo, eDok ID e os estados das assinaturas, que podem ser:

Para verificar os detalhes de cada assinatura, acesse as propriedades do documento no eDok.

Exemplos

• Requisição apenas com o primeiro identificador:

  KEY=secret&NM_USUARIO=admin&NR_ATENDIMENTO=989760
  

• Requisição com ambos identificadores:

  KEY=secret&NM_USUARIO=admin&NR_ATENDIMENTO=989760&NR_PRONTUARIO=454012
  

• Requisição apenas com o segundo identificador para documentos que NÃO contenham o primeiro identificador (note a letra p como prefixo):

  KEY=secret&NM_USUARIO=admin&NR_ATENDIMENTO=p454012
  

  Neste caso, o primeiro documento visualizado será o que porventura contenha somente o segundo identificador, útil para documentos de legado.

• Requisição apenas com o segundo identificador para todos os documentos (note a letra a como prefixo):

  KEY=secret&NM_USUARIO=admin&NR_ATENDIMENTO=a454012
  

  Neste caso, todos os documentos que contenham o identificador serão listados.

Respostas

Algumas respostas foram removidas em relação às gerações anteriores:

Integrando o Philips® Tasy

O Philips® Tasy é um CRM para a área da saúde que pode ser integrado ao eDok de modo muito simples e completamente transparente. Com isso, os usuários do Philips® Tasy têm acesso aos documentos gerenciados diretamente do PEP (Prontuário Eletrônico do Paciente) e outros módulos. A API ViewDocs é ideal para esta integração.

Do mesmo modo que o Philips® Tasy, outros CRMs, ERPs e sistemas diversos de qualquer área podem ser integrados ao eDok com a mesma facilidade.

Você pode usar o Philips® Tasy em Delphi, Java e HTML5. Todos eles são suportados pelo eDok, inclusive simultaneamente.

A configuração é muito fácil e rápida. Veja como fazer no PEP, por exemplo:

1. Acesse o Philips® Tasy como administrador;

2. Navegue até Utilitários > Cadastros Gerais > Aplicação Principal > Médico > Parâmetros PEP;

3. Na opção URL para GED, digite o endereço de integração deste modo, substituindo secret pela chave de acesso configurada no eDok:

   https://<endereço>.edok.com.br/api/viewdocs?KEY=secret&NM_USUARIO=$NM_USUARIO&NR_ATENDIMENTO=$NR_ATENDIMENTO
   

4. Em Método GED, selecione a opção Post;

5. Caso necessário, libere a opção Gestão eletrônica de documentos GED no perfil dos usuários que terão acesso aos documentos.

No passo 3 acima, substitua o valor secret pela chave de acesso da API no eDok. Também recomendamos criar um usuário dedicado e sem privilégios para integrações. Ele pode ser utilizado no lugar do valor $NM_USUARIO, mas sem a parte depois do @, por exemplo: se o usuário eDok for usuario@edok.com.br, utilizar apenas usuario, sem @edok.com.br. Caso isso não seja feito, o usuário logado no PEP será utilizado, mas este usuário também deve existir no eDok. Já o valor $NR_ATENDIMENTO não deve ser alterado. Ele é uma variável interna do Tasy que é substituída automaticamente pelo número do atendimento sendo visualizado no PEP.

Pronto! A integração do Philips® Tasy com o eDok está configurada. Para testar, escolha um atendimento existente, digitalize para o eDok um documento com este número de atendimento, acesse o PEP, abra o atendimento escolhido e clique na opção Gestão eletrônica de documentos GED. O documento vai aparecer no Philips® Tasy sem o usuário precisar sair dele.

Este procedimento é apenas um exemplo pelo qual não nos responsabilizamos. Para mais detalhes e opções, consulte seu integrador Philips® Tasy.

Continuando...

Parabéns! Você concluiu o Manual de Integração. Para continuar aprendendo, siga para Governança e Segurança.