Ir para o conteúdo principal

Diretrizes das APIs eDok, v2

Atualizado em 13/01/2017 Link permanente Índice

Cada API descrita em Implementação > Integração > Endpoints possui um conjunto específico de diretrizes que devem ser utilizadas no consumo da API. Estas diretrizes são descritas em detalhes neste capítulo e todas elas referem-se a versão 2 da API do eDok.

DICA: a documentação interativa dos esquemas JSON implementados pelas APIs RESTful do eDok estão disponíveis em https://<cliente>.edok.com.br/api/json/doc/index.html.

Respostas de Exemplo

As respostas das APIs DocMetadata e DocStats, sucesso ou erro, são padronizadas e sempre em JSON. Isto facilita o tratamento programático das requisições executadas.

Todas as repostas da API DocMetadata incluem as mesmas propriedades iniciais. Esse comportamento foi deliberadamente implementado para que as respostas possam ser facilmente utilizadas como fonte de dados em sistemas de terceiros.

AVISO: a resposta da API DocStats também é em JSON, mas não contém as mesmas propriedades iniciais contidas em DocMetadata.

Essas informações podem ser reaproveitadas para, por exemplo, criar trilhas de auditoria e conciliação de dados entre o que foi solicitado e o que foi efetivamente executado pela API do eDok Ingest. Isto fornece uma camada adicional e independente para a verificação de integridade do acervo documental gerenciado pelo eDok, uma vez que os dados enviados na requisição também são retornados para que possam ser efetuadas confirmações e comparações independentes.

Abaixo uma resposta de uma requisição executada com sucesso:

Abaixo uma resposta de uma requisição que retornou erro:

Já as APIs DocView, Same e SameSimple não possuem respostas em JSON. Ao invés disso, elas retornam HTML pronto para ser usado por outras aplicações ou serviços desktop, web ou mobile.

CUIDADO!!! Os navegadores dão a possibilidade do usuário fazer o download ou imprimir os documentos visualizados. Utilize estes recursos com parcimônia. A eDok Consultoria em Sistemas Ltda. e a Nommad Tecnologia da Informação Ltda. não se responsabilizam pelo uso indevido ou não autorizado dos documentos obtidos através do uso das APIs DocView, Same E SimpleSame.

Tratamento de Erros

Como as APIs do eDok são RESTful, elas estão cientes dos códigos de reposta especificados pelo protocolo HTTP. Como benefício, o programador pode tratar apenas o código de resposta do servidor e ignorar completamente as mensagem se assim desejar. Isto vale também para as GET APIs.

Quando uma resposta da API for um erro, as APIs do eDok sempre incluirão o cabeçalho personalizado X-eDok-Error na resposta do servidor. Ele conterá exatamente o mesmo código de erro HTTP emitido pelo servidor. Este cabeçalho não existe para respostas de sucesso (código HTTP 200).

Nas APIs DocMetadata, todas as condições de erro trarão também a diretriz completa enviada na requisição para enventual verificação de problemas.

Na documentação das respostas abaixo, os códigos HTTP são apresentados entre parênteses.

DescribeDoc

Finalidade: obter todos os metadados (primários, secundários e internos ao eDok) do documento requisitado.

Diretriz:

  • Version: declara a versão da API eDok Ingest. Obrigatório.
  • Statement: declaração principal da ação. Obrigatório.
    • PrimaryMeta: metadados primários que devem indicar um documento exclusivo. Obrigatório.
      • DocType: deve ser igual à sigla de duas letras do identificador do DocType. Obrigatório.
      • PRIMD1, PRIMD2: os demais campos requeridos do DocType, quantos forem necessários. Usar o nome dos campos no DocType para rotular estas propriedades adicionais. Obrigatórios.

Schema JSON:

  • Interativo: https://<cliente>.edok.com.br/api/json/doc/DescribeDoc.html
  • Puro: https://<cliente>.edok.com.br/api/json/schemas/DescribeDoc.json
Exemplo de Diretriz:Exemplo de Resposta com Sucesso:

Respostas e Tratamentos:

  • Error (401), API key provided is invalid: a chave de acesso está errada. Verificar a chave de acesso.
  • Error (400), API version not supported: a versão da API não é suportada. Verificar versão da API.
  • Error (400), Action not found: o nome da ação está errado na URL. Verificar URL da requisição.
  • Error (400), Invalid JSON schema: a diretriz em JSON não obedece às restrições do schema. Verificar a validade da diretriz contra o schema.
  • Error (400), DocType not found: o valor informado não corresponde a nenhuma sigla de duas letras do identificador do DocType. Verificar o DocType e informar a sigla correta.
  • Error (400), DocType %identifier% has no required fields: o DocType informado como %identifier% não possui nenhum campo requerido. Confirmar no DocType se a sigla do código de barras está correta e se há campos requeridos.
  • Error (400), Missing required primary metadata properties: nem todas as propriedades de PrimaryMeta que correspondem a campos requeridos no DocType foram informados, mas todos eles são obrigatórios. Verificar o DocType e informar todos os campos requeridos.
  • Error (404), Document not found: os valores informados por PrimaryMeta não correspondem a um documento existente. Verificar os valores enviados na requisição e conferir se eles correspondem a um documento existente.
  • Success (200), Document metadata description for %eDokID%.: requisição concluída com sucesso. %eDokID% é o identificador interno do documento no eDok.

ExportMetadata

Finalidade: exportar todos os metadados (primários, secundários e internos ao eDok) de documentos. O envio da diretriz não é obrigatório. Caso não seja enviada, a API responderá com os documentos de todos os DocTypes compreendidos dentro do intervalo padrão.

Diretriz:

  • Version: declara a versão da API eDok Ingest. Obrigatório.
  • Statement: declaração principal da ação. Obrigatório.
    • DocType: deve ser igual à sigla de duas letras do identificador do DocType. Obrigatório.
    • DateRange: define o intervalo da listagem. Opcional.
      • StartDate: data inicial do intervalo no formato RFC3339, não maior que o intervalo máximo configurado no eDok. Obrigatório se a diretriz incluir a propriedade DateRange.
      • EndDate: data final do intervalo no formato RFC3339. Se não informada, retorna os documentos compreendidos dentro do intervalo padrão configurado no eDok. Opcional.

Schema JSON:

  • Interativo: https://<cliente>.edok.com.br/api/json/doc/ExportMetadata.html
  • Puro: https://<cliente>.edok.com.br/api/json/schemas/ExportMetadata.json
Exemplo de Diretriz:Exemplo de Resposta com Sucesso:

Respostas e Tratamentos:

  • Error (401), API key provided is invalid: a chave de acesso está errada. Verificar a chave de acesso.
  • Error (400), API version not supported: a versão da API não é suportada. Verificar versão da API.
  • Error (400), Action not found: o nome da ação está errado na URL. Verificar URL da requisição.
  • Error (400), Invalid JSON schema: a diretriz em JSON não obedece às restrições do schema. Verificar a validade da diretriz contra o schema.
  • Error (400), DocType not found: o valor informado não corresponde a nenhuma sigla de duas letras do identificador do DocType. Verificar o DocType e informar a sigla correta.
  • Error (400), Date out of %api_max_dayrange% days range: o intervalo de data especificado é maior do que o intervalo máximo padrão do serviço Verificar datas do intervalo.
  • Success (200), Documents from %StartDate% to %EndDate%: requisição concluída com sucesso, retorna todos os documentos dentro do intervalo especificado.
  • Success (200), Documents from %StartDate% to %EndDate% with DocType %doctype%: requisição concluída com sucesso, retorna todos os documentos dentro do intervalo e do DocType especificados.

GetDocWithNoMetadata

Finalidade: Obter uma lista com os documentos que não possuem metadados secundários no período informado.. O envio da diretriz não é obrigatório. Caso não seja enviada, a API responderá com todos os documentos sem metadados secundários compreendidos dentro do intervalo padrão.

Diretriz:

  • Version: declara a versão da API eDok Ingest. Obrigatório.
  • Statement: declaração principal da ação. Obrigatório.
    • DateRange: define o intervalo da listagem. Obrigatório.
      • StartDate: data inicial do intervalo no formato RFC3339, não maior que o intervalo máximo configurado no eDok. Obrigatório.
      • EndDate: data final do intervalo no formato RFC3339. Se não informada, retorna os documentos compreendidos dentro do intervalo padrão configurado no eDok. Opcional.

Schema JSON:

  • Interativo: https://<cliente>.edok.com.br/api/json/doc/GetDocWithNoMetadata.html
  • Puro: https://<cliente>.edok.com.br/api/json/schemas/GetDocWithNoMetadata.json
Exemplo de Diretriz:Exemplo de Resposta com Sucesso:

Respostas e Tratamentos:

  • Error (401), API key provided is invalid: a chave de acesso está errada. Verificar a chave de acesso.
  • Error (400), API version not supported: a versão da API não é suportada. Verificar versão da API.
  • Error (400), Action not found: o nome da ação está errado na URL. Verificar URL da requisição.
  • Error (400), Invalid JSON schema: a diretriz em JSON não obedece às restrições do schema. Verificar a validade da diretriz contra o schema.
  • Error (400), DocType not found: o valor informado não corresponde a nenhuma sigla de duas letras do identificador do DocType. Verificar o DocType e informar a sigla correta.
  • Error (400), Date out of %api_max_dayrange% days range: o intervalo de data especificado é maior do que o intervalo máximo padrão do serviço. Verificar datas do intervalo.
  • Success (200), Documents with no secondary metadata from %StartDate% to %EndDate%: requisição concluída com sucesso.

PostDocMetadata

Finalidade: inserir ou atualizar metadados secundários de um documento específico.

Diretriz:

  • Version: declara a versão da API eDok Ingest. Obrigatório.
  • Statement: declaração principal da ação. Obrigatório.
    • PrimaryMeta: metadados primários que devem indicar um documento exclusivo. Obrigatório.
      • DocType: deve ser igual à sigla de duas letras do identificador do DocType. Obrigatório.
      • PRIMD1, PRIMD2: os demais campos requeridos do DocType, quantos forem necessários. Usar o nome dos campos no DocType para rotular estas propriedades adicionais. Obrigatórios.
      • SecondaryMeta: metadados secundários para inserir/atualizar no documento. Obrigatório.
        • SECMD1: ao menos um metadado secundário. Usar o nome do campo no DocType como nome da propriedade. Obrigatório.
        • SECMD2: metadados secundários adicionais, quantos forem necessários. Opcional.

Schema JSON:

  • Interativo: https://<cliente>.edok.com.br/api/json/doc/PostDocMetadata.html
  • Puro: https://<cliente>.edok.com.br/api/json/schemas/PostDocMetadata.json
Exemplo de Diretriz:Exemplo de Resposta com Sucesso:

Respostas e Tratamentos:

  • Error (401), API key provided is invalid: a chave de acesso está errada. Verificar a chave de acesso.
  • Error (400), API version not supported: a versão da API não é suportada. Verificar versão da API.
  • Error (400), Action not found: o nome da ação está errado na URL. Verificar URL da requisição.
  • Error (400), Invalid JSON schema: a diretriz em JSON não obedece às restrições do schema. Verificar a validade da diretriz contra o schema.
  • Error (400), DocType not found: o valor informado não corresponde a nenhuma sigla de duas letras do identificador do DocType. Verificar o DocType e informar a sigla correta.
  • Error (400), DocType %identifier% has no required fields: o DocType informado como %identifier% não possui nenhum campo requerido. Confirmar no DocType se a sigla do código de barras está correta e se há campos requeridos,
  • Error (400), Missing required primary metadata properties: nem todas as propriedades de PrimaryMeta que correspondem a campos requeridos no DocType foram informados, mas todos eles são obrigatórios. Verificar o DocType e informar todos os campos requeridos.
  • Error (404), Document not found: os valores informados por PrimaryMeta não correspondem a um documento existente. Verificar os valores enviados na requisição e conferir se eles correspondem a um documento existente.
  • Error (400), Missing any secondary metadata to update: não foi enviada nenhuma propriedade SecondaryMeta para atualizar o documento. Verificar diretriz.
  • Error (400), Secondary metadata %fieldname% not found: o nome da propriedade %fieldname% não existe como campo no DocType. Verificar o DocType e informar o nome correto.
  • Error (413), Length of secondary metadata %fieldname% is longer than expected: o comprimento do valor enviado para %fieldname% é maior do que o permitido pelo campo. Verificar o comprimento permitido pelo campo no DocType.
  • Success (200), Document metadata updated: requisição concluída com sucesso.

DocStats

Finalidade: Obter estatísticas do eDok Ingest em dimensões variadas.

Diretriz: esta é uma API do tipo RESTful que responde em JSON sem as propriedades iniciais presentes em DocMetadata. Os parâmetros da requisição são enviados ao eDok via query string na URL.

Os campos reqeridos são:

  • k: chave da API, obrigatório.
  • t: tipo da dimensão, obrigatório. Valores suportados:
    • stat_doc: estatísticas de produtividade em dimensões variadas.
    • stat_src: estatísticas por origem nos últimos 30 dias.
  • d: se t=stat_doc, d é obrigatório, caso contrário é opcional. Valores suportados:
    • 0: produtividade nos últimos sete dias.
    • 1: produtividade nos últimos 30 dias.
    • 2: produtividade nos últimos 12 meses.

Respostas:

  • Error (500), Backend unavailable.
  • Error (400), Missing required parameters: key and/or type.
  • Error (400), eDok API key is not set.
  • Error (400), API key provided is invalid.
  • Error (400), Type unknown.
  • Error (400), Dimension missing.
  • Error (400), Dimension unknown.
  • Success (200).

Exemplos de Requisição e Resposta:

Obter a produtividade nos últimos sete dias:

Obter a produtividade por origem (apenas últimos 30 dias disponíveis):

DocView

Finalidade: mostrar uma página HTML com o documento solicitado.

Diretriz: esta é uma API do tipo GET que responde em HTML. Os parâmetros da requisição são enviados ao eDok via query string na URL.

Os campos reqeridos são:

  • k: chave da API, obrigatório.
  • id: sigla de duas letras do identificador do DocType e código do documento, obrigatório.

Respostas: como esta API é direcionada a humanos, as respostas são mais significativas do que as APIs RESTful.

  • Error (500), Os computadores brigaram e isso é um erro.
  • Error (400), Faltam informações para obter o documento.
  • Error (401), Alguém esqueceu de configurar a chave de acesso e isso é ruim.
  • Error (401), Você não está autorizado a ver o documento.
  • Error (404), O documento solicitado não existe no eDok.
  • Error (404), O documento não foi encontrado.
  • Error (500), Não foi possível gerar a visualização do documento.
  • Error (500), Documento indisponível para visualização.
  • Sucess (200).

Exemplo de Requisição:

Restrições:

  • Apenas documentos em PDF e TIFF são suportados.
  • Documentos em TIFF são convertidos para PDF para exibição.
  • Os documentos visualizados são cópias rastreáveis dos originais digitalizados.
  • Os navegadores Chrome e Firefox possuem visualizador de PDF embutido e não requerem software adicional para visualizar os documentos. O Internet Explorer (Edge) requer o Adobe Acrobat Reader DC instalado. A compatibilidade com outros navegadores não é garantida ou suportada.
  • Em função de retrocompatibilidade, requisições cujo identificador do DocType utilizam BLID são tratados internamente pela API e convertidos para ID. Esse recurso é obsoleto e será desativado nas próximas versões da API.
  • Os navegadores dão a possibilidade do usuário fazer o download ou imprimir os documentos visualizados. Utilize estes recursos com parcimônia. A eDok Consultoria em Sistemas Ltda. e a Nommad Tecnologia da Informação Ltda. não se responsabilizam pelo uso indevido ou não autorizado dos documentos obtidos através do uso das APIs DocView, Same E SimpleSame.

Same e SameSimple

Finalidade: mostrar uma página HTML com o documento solicitado em sistemas SAME (Serviço de Atendimento Médico e Estatísticas).

Diretriz: estas são APIs do tipo GET que respondem em HTML. Para mais detalhes sobre o consumo destas APIs, consulte o suporte eDok.