Ir para o conteúdo principal

Implementação

Atualizado em 09/06/2017 Link permanente Índice

Agora que conhecemos como o eDok Ingest e as APIs funcionam, mostraremos as informações técnicas necessárias para a sua implementação no cotidiano dos processos de digitalização dos clientes.

Os métodos de implementação apresentados neste documento são uma sugestão de uso. O que importa é o resultado final da automação: ganhos de produtividade e/ou de eficiência. O método exato para que isso ocorra é parte da inteligência de cada negócio. Sinta-se a vontade para adaptar essas instruções básicas para adequarem-se as suas necessidade no mundo real.

Admissão

Conforme demostrado no capítulo que expõe a arquitetura, a admissão necessita da implementação de um identificador. Este identificador pode se materializar como uma etiqueta com códigos de barras ou QR-Code, uma página que serve de capa para um documento com várias páginas, um nome de arquivo ou mesmo ser inserida manualmente, etc.

A origem dos dados presentes no identificador pode ser o próprio eDok ou um sistema de terceiros. Nos exemplos apresentados aqui não haverá essa distinção. Mostraremos de modo genérico como os dados no identificador devem ser parametrizados e apresentados.

Identificação

O identificador do eDok Ingest foi pensado para ser flexível o suficiente para permitir a implementação nos mais variados sistemas de terceiros.

DICA: consulte o Manual do Administrador para detalhes sobre a configuração do eDok Ingest.

A composição do identificador se dá pela criação de um padrão para o rótulo de identificação (string). Essa string é utilizada para gerar o identificador materializado como etiqueta ou nome de arquivo. O identificador materializado é o que será utilizado pelo eDok para indexar o documento.

A definição do padrão da string do identificador obedece as seguintes regras:

  1. O campo que identifica o tipo do documento deve ser igual ao definido na Administração de Tipos de Documentos do eDok Core. Ver o Manual Administrativo do eDok.
  2. Os campos obrigatórios definidos na Administração de Tipos de Documentos do eDok Core devem existir na string. Ver Manual Administrativo do eDok.
  3. O caractere reservado para separação de campos é - (hífem).
  4. O caractere separador não pode ser utilizado dentro de campos.
  5. O conjunto de caracteres permitidos em campos é [A-Z] e [0-9].
  6. Datas, quando presentes, são no formato Unix Time.
  7. Obedecer o comprimento especificado na seção Materialização, incluindo o separador.
  8. O padrão da string do identificador é uniforme.

Sobre a regra 8, cabe uma explicação mais detalhada: uma vez definido um padrão da string do identificador, ele deve ser usado em todos os processos de digitalização do cliente. Os identificadores podem conter dados completamente diferentes, mas devem seguir o mesmo e único padrão. O padrão pode ser alterado a qualquer tempo, mas todos os processos serão alterados para o novo padrão, sem prejuízo para os documentos já admitidos.

Materialização

A materialização do identificador é o processo de estabelecer um modo como a string do identificador será representada e anexada a um documento do mundo real.

A materialização é fruto de uma decisão exigida pelo processo de digitalização de documentos que deve ser tomada de modo soberano pelo cliente e levando-se em conta os fatores operacionais e ambientais identificados no processo.

Como orientação para as decisões relativas a materialização do identificador, utilize como base as premissas da tabela a seguir. Não deixe de levantar suas próprias premissas, uma vez que fatores particulares em cada cliente podem apontar rumos diferentes para a materialização.

Fatores Operacionais
FatorAnáliseFonte e Tratamento
Scanner suporta a customização do nome do arquivo?O scanner possui a capacidade de gravar arquivos com strings geradas pelo usuário.Fabricante do scanner. Se suporta, preferir.
Scanner suporta FTPS?O scanner possui suporte ao envio de arquivos via protocolo FTPS ou somente FTP e/ou CIFS.Fabricante do scanner. Se suporta, preferir.
Quantos bytes existem na string de identificação?O comprimento mínimo necessário para formar a string de identificação completa.Metadados primários. Cada caractere alfanumérico é um byte.
O sistema de terceiro suporta a geração de códigos de barras ou QR?A capacidade do sistema de terceiro de gerar identificadores próprios.Fabricante do sistema. Se suporta, preferir.
Fatores Ambientais
FatorAnáliseFonte e Tratamento
As etiquetas ou capas são expostas a condições severas?A manipulação das etiquetas ocorrem em ambientes com umidade, impactos e outros agentes externos que podem danificá-las.Análise ambiental. Em caso positivo, preferir QR-Code.
A equipe que manipula as etiquetas possui treinamento para aplicá-las corretamente?Baixa especialização pode diminuir o índice de sucesso do reconhecimento ótico.Análise ambiental. Em caso negativo, preferir QR-Code.

A seguir são descritas as materializações suportadas pelo eDok Ingest e suas características principais.

CaracterísticaNome do ArquivoReconhecimento Ótico
CODE-128QR-Code
TipoString como nome do arquivoString codificada em código de barras unidimensionalString codificada em QR-Code bidimensional
Conjunto de caracteres*1[A-Z], [0-9] e -
Comprimento*2255 bytes (incluindo extensão)33 bytes1.852 bytes
InclinaçãoN/A<5°Qualquer
Correção de errosN/ANãoSim (até 30%)
SLA*399,9%96%99%
Observações:
*1 Imposto pelo eDok.
*2 Imposto por características sistêmicas (tipo do filesystem, largura da página, nível de ECC, versão etc).
*3 Com os parâmetros ótimos para controle de qualidade fornecidos por padrão no eDok. A alteração destes parâmetros anula estes SLAs.

Utilize as especificações apresentadas para estabelecer o método mais adequado de materialização para o processo desejado. Lembre-se que processos diferentes podem ter materializações diferentes.

A materialização híbrida (diferentes métodos num mesmo processo) também é suportada pelo eDok Ingest. Neste caso, o eDok Ingest procura pelos identificadores suportados simultaneamente e usa o que primeiro que foi encontrado. Isso aumenta as chances de sucesso da identificação do documento, mas não altera o SLA informado acima.

AVISO: a definição da materialização da string do identificador é o ponto mais importante a ser considerado na admissão automatizada de documentos. Ele determina o sucesso ou fracasso na implantação de um processo de digitalização em massa de documentos.

Geração

Com o identificador e suas materializações definidas, é chegado o momento de implementar a geração das etiquetas ou capas.

DICA: se a materialização é do tipo nome do arquivo, este passo não é necessário uma vez que o scanner ficará encarregado de preencher a string.

A geração pode ocorrer no próprio eDok, ou em sistemas e dispositivos de terceiros. Em qualquer caso, as especificações de materialização mostradas anteriormente devem ser observadas.

Se a geração dos identificadores ocorrerá em capas, o layout da página em torno do identificador é livre e pode ser personalizado a vontade pelo cliente desde suas especificações sejam rigorosamente seguidas.

PERIGO!!! Seja em etiquetas ou capas, jamais obstrua o identificador e mantenha uma área livre de pelo menos 0,5mm em torno dele.

Para mostrar como os identificadores podem ser gerados, vamos abordar dois exemplos de string:

Exemplo 1: string de 10 bytes, ID12345678.

Para gerar um código de barras no formato CODE-128:

Para gerar um QR-Code:

Os comandos acima produzirão etiquetas conforme as mostradas abaixo.

String do exemplo 1 codificada em CODE-128.

String do exemplo 1 codificada em CODE-128.

String do exemplo 1 codificada em QR-Code.

String do exemplo 1 codificada em QR-Code.

Exemplo 2: string de 33 bytes, 123456-123456-123456-ABCD12345678.

Para gerar um código de barras no formato CODE-128:

Para gerar um QR-Code:

Os comandos acima produzirão etiquetas conforme as mostradas abaixo.

String do exemplo 2 codificada em CODE-128.

String do exemplo 2 codificada em CODE-128.

String do exemplo 2 codificada em QR-Code.

String do exemplo 2 codificada em QR-Code.

No exemplo 2, o comprimento do código de barras CODE-128 gerado cobre praticamente toda a página. Como redimensionar códigos é uma prática perigosa e que jamais deve ser executada, a string de 33 bytes é na prática o limite físico de um códio de barras. Se a string tiver mais de 33 bytes, prefira o QR-Code.

PERIGO!!! Nunca redimensione as etiquetas geradas em qualquer formato, uma vez que isso causa efeitos devastadores nos índices de reconhecimento com sucesso. Utilize apenas a resolução e tamanho padrão fornecidos pelo gerador de sua escolha.

Se o gerador for operar com CODE-128, sempre imprima os caracteres da string abaixo do código de barras. Eles serão úteis para uma admissão manual em caso de erros de reconhecimento.

Nos dois exemplos acima, note o parâmetro --secure=4 que é passado ao gerador de QR-Code. Este parâmetro implementa o mais alto nível de correção de erros em etiquetas QR-Code. Com este nível, o reconhecimento ótico é capaz de ler um QR-Code com sucesso quando até aproximadamente 30% de sua área está danificada. Os níveis suportados de correção de erro são de 1 até 4 ou, que conforme a especificação do QR-Code, correspondem a L (7%), M (15%), Q (25%) e H (30%), respectivamente.

AVISO: sempre que possível, prefira o mais alto nível de correção de erros para gerar o QR-Code.

Manipulação

De posse das etiquetas ou capas materializadas, é necessário manipular os documentos para anexar os identificadores.

Se o identificador está impresso em uma capa, basta inserir a capa como a primeira página do documento.

Se o identificador está impresso em etiquetas, destacar a etiqueta e colar no documento, Algumas regras devem ser observadas neste caso.

  1. Se a etiqueta for de código de barras: colar a etiqueta o mais alinhada possível com o documento. O reconhecimento do código de barras tem uma baixa tolerância para inclinações da etiqueta (ver especificações na seção Materialização).
  2. Para todos os tipos de etiquetas: colar em uma área em branco do documento, jamais riscar ou carimbar sobre a etiqueta e sempre verificar se a etiqueta está bem colada para evitar que ela se dobre quando inserida no scanner.
AVISO: a observação de todas as regras acima são essenciais para um índice de reconhecimento ótimo e acima do SLA de cada materialização.

Ambiente

Com os identificadores definidos, materializados, gerados e devidamente aplicados nos documentos, resta efetuar a parametrização do ambiente começar o evnio de documentos para o eDok Ingest.

Estes dados devem ser inseridos nos scanners ou no cliente de FTP instalado nos concentradores para estabelecer a comunicação e a transferência dos documentos digitalizados.

Os parâmetros de configuração para acesso FTP e FTPS são:

  1. Endereço do servidor: ftp.edok.com.br
  2. Porta: 21 (padrão)
  3. Usuário e senha: obtidos na ativação do serviço eDok.
  4. FTPS: escolher a opção usar FTP sobre TLS explícito (se houver). Em alguns casos pode ser necessário informar o endereço do servidor como ftps://ftp.edok.com.br:21. Consulte a documentação do seu software de FTP ou dispositivo para mais informações.
PERIGO!!! Recomendamos o uso de FTPS para o envio de documentos digitalizados. O uso de FTP convencional (não seguro), apesar de suportado, exime automaticamente o eDok de responsabilidades legais e cíveis pelo vazamento de informações de qualquer natureza (credenciais de acesso, documentos etc). Caso opte pelo FTP convencional, o cliente também assume ser o único responsável por tais ocorrências uma vez que a alternativa segura e recomendada, o FTPS, está disponível a todos os clientes sem custo adicional.

Além das parametrizações de acesso, os scanners devem ser configurados de acordo com as especificações abaixo.

  1. Formato da imagem: TIFF (single ou multipage) ou PDF, 300DPI, preto e branco (1bit).
  2. Apenas para TIFF: compressão LZW, fotometria 0 (min-is-white).

Os parâmetros acima compõem os ajustes de controle de qualidade padrão do eDok Ingest conforme mencionados na arquitetura. Eles foram estabelecidos de modo a garantir o SLA e a operação ótima do reconhecimento ótico.

PERIGO!!! Os parâmetros ótimos para controle de qualidade são fornecidos por padrão no eDok. O cliente pode alterar esses parâmetros quando desejar para acomodar as suas necessidades. A alteração das configurações fornecidas (exceto fotometria) invalida o SLA do reconhecimento ótico.
DICA: mais informações sobre como configurar os scanners podem ser obtidas nos manuais dos equipamentos utilizados ou com seus fabricantes.

Com os scanners ou concentradores devidamente configurados, basta iniciar as digitalizações. Isto encerra a implementação do processo de admissão do eDok Ingest.

Regras

O eDok Ingest é uma ferramenta de automação em estado da arte. Ele é projetado e desenvolvido para assumir a responsabilidade sobre a identificação de documentos enviados em grandes volumes para o eDok, ao mesmo tempo em que procura tornar o processo de digitalização o mais simples possível para os humanos.

Estas descisões de projeto do eDok Ingest o tornam uma ferramenta extremamente poderosa e complexa em suas entranhas, ao mesmo tempo que o faz absolutamente simples quanto ao seu uso.

Para que o eDok Ingest possa operar em sua máxima eficência, algumas regras simples de serem lembradas DEVEM ser observadas.

  1. DEVE existir um identificador na primeira página do documento.

    A primeira página do documento DEVE conter um identificador do eDok. Caso não seja encontrado um identificador na primeira página do documento, o eDok Ingest vai emitir o erro:

  2. DEVE existir apenas um identificador na primeira página do documento.

    A primeira página de um documento DEVE conter apenas um identificador do eDok. Ou seja, se o identificador 123456 é usado, não pode haver o identificador 654321 na mesma página. Caso múltiplos identificadores sejam encontrados na primeira página, o eDok Ingest vai emitir o erro:

  3. Identificadores idênticos são IGNORADOS ao longo de todo o documento.

    Suponha o identificador do eDok se repita da primeira a última página do documento. O eDok Ingest só vai olhar para ele na primeira página para identificar o documento e ignorar todas as outras. Um identificador idêntico pode até aparecer mais de uma vez numa página, incluindo a primeira. Nenhum erro é gerado neste caso.

  4. Identificadores PODEM conter múltiplas simbologias.

    Conforme especificado acima neste capítulo, o eDok suporta identificadores híbridos. Isso equivale dizer que um indentificador pode conter, ao mesmo tempo, múltiplas simbologias. Por exemplo: você pode gerar no eDok ou encomendar numa gráfica identificadores que contenham ao mesmo tempo um QR-Code e um código de barras no formato CODE-128. O eDok Ingest vai reconhecer o primeiro identificador e ignorar o seguinte. Isso aumenta as chances do documento ser identificado com sucesso (mas não altera o SLA padrão do eDok que é 96% para CODE-128 e 99% para QR-Code). As simbologias suportadas pelo eDok Ingest são: EAN-13/UPC-A, UPC-E, EAN-8, CCODE-128, CODE-39, ITF e QR-Code.

  5. Enviar um documento único ou um um lote com centenas de documentos é a mesma coisa.

    Para o eDok Ingest, enviar um só documento devidamente identificado ou um lote com 100 deles é essencialmente a mesma coisa. A única diferença é que para reconhecer lotes de documentos, você pode optar por usar as páginas separadoras. Para o envio de lotes de documentos, é fortemente RECOMENDADO o uso de páginas separadoras por ser mais fácil para humanos visualizarem e separarem os diferentes documentos dentre muitos. Se a página separadora está desativada e um lote de documentos for enviado com elas, o eDok Ingest rejeitará o lote. Com a página separadora desativada, monte os lotes de documentos identificados um seguido do outro e digitalize tudo de uma vez. Ou seja, a primeira página do documento seguinte e que contém o seu identificador vem logo depois da última página do documento anterior. Para usar páginas separadoras, você DEVE parametrizar seu uso no painel de administração do eDok. Veja regras abaixo para mais detalhes.

  6. As especificações de formato de imagem DEVEM ser observadas.

    Documentos digitalizados fora da especificação recomendada tem menos chances de serem reconhecidos pelo eDok Ingest e economiza espaço de armazenamento em seu plano eDok (você guarda mais documentos em menos espaço). Observe COM CUIDADO as especificações recomendadas. O eDok Ingest suporta os seguintes formatos: PDF e TIFF, ambos com páginas únicas ou múltiplas.

  7. O fim do arquivo é o fim do documento.

    Seja um documento único com 10 páginas ou o último documento de um lote com 1.000 páginas, a última página do arquivo (ou lote) marca o fim do documento.

  8. Se a página separadora está ATIVADA:

    As regras abaixo se aplicam somente quando as páginas separadoras do eDok são usadas para delimitar os documentos enviados em lotes com múltiplos documentos. Neste caso os documentos são delimitados EXCLUSIVAMENTE pela existência de uma ou mais páginas separadoras no lote. O uso ou não desse recurso é controlado no painel de administração do eDok.

    1. Lotes de documentos DEVEM começar sem página separadora.

      Suponha que um lote digitalizado com 1.000 páginas contenha 100 documentos diferentes. A primeira página do lote é a primeira página do primeiro documento com o identificador único nela (ver regras 1 e 2 acima).

    2. A página após uma separadora DEVE ser a primeira de um novo documento.

      Depois de uma página separadora SEMPRE vem a primeira página de um novo documento, e esta página SEMPRE contém um identificador único (ver regras 1 e 2 acima).

    3. Documento são separados EXCLUSIVAMENTE nas páginas separadoras.

      Ainda com o exemplo acima (1.000 páginas com 100 documentos diferentes), os documentos distintos são delimitados exclusivamente pela página separadora. Se o operador esquecer de colocar uma página separadora entre um documento e outro e digitalizar assim, o documento em questão conterá todas as páginas até a próxima separadora ser encontrada (ver regra a seguir).

    4. Identificadores iguais ou diferentes são IGNORADOS ao longo de todo o documento.

      Suponha que o documento vá da página 1 até a 9, inclusive, e a página 10 seja a página separadora. A primeira página do documento contém o identificador 123456. Este será o identificador do documento. Agora, por exemplo, se a quinta página do mesmo documento contém o identificador 654321, o eDok Ingest vai ignorar este novo identificador pois ele ocorre num documento já identificado como 123456 e ainda não chegou na página separadora para finalizar o documento. Todas as páginas do documento exceto a primeira podem conter identificadores diferentes, incluindo múltiplos identificadores. O eDok Ingest vai ignorar todos até a página separadora. Só a página separadora determina o fim de um documento e o começo do próximo. O mesmo ocorre com identificadores iguais em outras páginas do documento.

    5. Enviar documento único com a página separadora ativada é possível.

      Quando a página separadora está ativada no eDok, o envio de um documento único (do começo ao fim do arquivo um documento só, sem página separadora no final) é permitido.

    6. As páginas separadoras são SEMPRE descartadas depois da separação.

      O eDok Ingest sabe que páginas separadoras servem apenas para delimitar documentos e que elas não fazem parte dos mesmos. Por isso elas sempre são descartadas.

  9. Se a página separadora está DESATIVADA:

    As regras abaixo se aplicam somente quando as páginas separadoras do eDok NÃO SÃO usadas para delimitar os documentos enviados em lotes com múltiplos documentos. Neste caso os documentos são delimitados EXCLUSIVAMENTE pela existência de novos identificadores em páginas diferentes do lote.

    1. Documento são separados SEMPRE que um novo identificador é encontrado.

      Suponha que um lote digitalizado com 20 páginas contenha 2 documentos diferentes. Os documentos distintos são delimitados quando um identificador diferente do atual é encontrado em uma página. Por exemplo: a página 1 contém o indentificador 123456 e a página 10 contém o identificador 654321. O documento 123456 conterá as páginas de 1 a 9, inclusive, e o documento 654321 conterá as páginas de 10 a 20. Todas os identificadores diferentes em páginas distintas marcam o início de um novo documento.

    2. Identificadores iguais são IGNORADOS ao longo de todo o documento.

      Assim como na regra 3 acima, os identificadores iguais são ignorados mesmo que apareçam em todas as páginas do documento. Por força da regra 9.1 acima, identificadores diferentes não são ignorados quando a página separadora não é usada. Eles marcam o fim do documento atual e início do próximo documento.

Sobre as regras acima, cabe lembrar que as regras para página separadora são EXCLUDENTES. Ou seja, se eDok Ingest foi parametrizado para usá-las, as regras para página separadora desativada não se aplicam, e vice-versa.

Integração

Os documentos admitidos pelo método descrito na seção anterior são indexados pelos metadados primários presentes no identificador. Esses identificadores estarão sempre disponíveis imediatamente após a conclusão do processo de admissão de cada documento. Com esses metadados, é possível encontrar qualquer documento gerenciado pelo eDok.

No entanto, entendemos que é conveniente para o processo do negócio que os documentos possam ter outros metadados secundários que também possam ser utilizados para pesquisar e manipular o acervo documental, mas que não são absolutamente essenciais para uma boa indexação.

Para suprir esta demanda, o eDok Ingest implementa um conjunto de APIs que facilita e automatiza o trabalho de inclusão desses metadados. Estas APIs existem para uniformizar a integração dos mais diferentes sistemas internos ou de terceiros. Elas utilizam um método universal, aberto, fortemente padronizado, bem documentado e amplamente utilizado pelo mercado: RESTful com JSON.

O benefício imediato para o cliente que necessita integrar sistemas internos ou de terceiros ao eDok é que o esforço de desenvolvimento requerido para integrar uma aplicação é pequeno em termos absolutos. Principalmente por isso, a integração pode ser rápida e facilmente migrada para outras aplicações quando necessário. O método de integração não muda de sistema para sistema.

Além das RESTful APIs, o eDok também provê outras APIs não podem ser chamadas de RESTful no sentido estrito do termo, mas se comportam como tal. Algumas delas estão mais para webservices, no sentido de que elas fornecem saídas HTML completas ao invés de JSON puro. Esses recursos são chamados de GET APIs.

Neste capítulo abordaremos os aspectos técnicos de implementação destas APIs. Como de costume, a abordagem é genérica o suficiente para que o cliente possa aplicá-las em qualquer sistema requerido por qualquer processo, de qualquer departamento.

Acesso às APIs

Abaixo são descritos os métodos de acesso às APIs do eDok. APIs RESTFul e GET possuem métodos de acesso diferentes.

Em ambos os casos o consumo das APIs só é possível com o protocolo HTTPS (seguro). Isto ocorre em função das APIs necessitarem de uma chave de acesso secreta e, uma vez conectada, é utilizada para trocar dados sensíveis. Usando o protocolo HTTPS temos como garantir a inviolabilidade destes dados.

AVISO: as APIs do eDok só estão disponívels com protocolo HTTPS. Elas não funcionam com protocolo HTTP padrão (não seguro).

RESTful APIs

A API RESTful do eDok Ingest que implementa a integração de metadados secundários é chamada DocMedata. Esta mesma API contém todas as ações que dizem respeito à manipulação, controle e obtenção de metadados dos documentos gerenciados pelo eDok.

DICA: consulte o Manual do Administrador para detalhes sobre a configuração da API.

O endpoint (endereço) para a requisição é:

Onde:

  • <cliente>: é o rótulo de cliente definido na ativação do serviço.
  • <ação>: a ação desejada para consumo.

GET APIs

O acesso às GET APIs é mais simples. Elas requerem apenas o endpoint com a query string válida. Por exemplo:

Chave de Acesso

A chave de acesso é o recurso que autentica e autoriza o consumo da API. Por questões de segurança, o eDok não possui uma chave de acesso padrão para a API. Ela deve ser gerada pelo cliente quando for necessário e deve ser alterada sempre que preciso.

Essa chave é única para cada contrato. Nenhum cliente eDok compartilha chaves de acesso, e mesmo os clientes que possuem mais de uma uma instância eDok ativa possuem chaves de acesso diferentes para cada instância. A chave deve ser mantida em segredo.

PERIGO!!! Jamais compartilhe a chave de acesso. Ao gerá-la no eDok, guarde-a em local seguro e de acesso restrito. A guarda da chave de acesso é uma responsabilidade compartilhada entre o cliente e eDok. Em caso de chave comprometida, o cliente deve gerar uma nova chave imediatamente e entrar em contato com o Suporte eDok para informar o ocorrido.

É obrigatório o envio de chave de acesso válida para cada requisição à API. A chave de acesso é enviada à API por meio do cabeçalho HTTP X-SecretAccessKey (RESTful APIs) pela query string k (GET APIs).

Consumo das APIs

As APIs do eDok possuem métodos de consumo conforme a sua arquitetura: RESTful ou GET. Os diferentes métodos são descritos abaixo.

O consumo das APIs é sempre atômico. Isso significa que apenas as requisições completas e válidas são efetivamente atendidas pelo eDok. As demais são descartadas.

RESTful APIs

O consumo da APIs RESTful ocorre com uma requisição composta conforme mostrado a seguir:

Onde:

  1. Cabeçalho X-SecretAcessKey com o valor da chave de acesso como <segredo> .
  2. Método HTTP como valor de <método> (GET ou POST, onde POST ocorre somente se -d estiver declarado).
  3. Diretriz para a ação escrita em JSON como valor de <json>.
  4. Endpoint da API com o rótulo do cliente como <cliente> e a ação como <ação>.

Para obter uma resposta válida da API, a requisição deve ser composta corretamente quanto aos métodos HTTP, cabeçalhos e, quando houver, a diretriz JSON precisa estar sintaticamente correta e ser válida para o esquema da ação desejada.

DICA: para obter informações detalhadas sobre a sintaxe de JSON, consulte json.org. Para mais informações sobre os esquemas das ações, consulte o capítulo Diretrizes.

GET APIs

Conforme visto anteriormente, o consumo das APIs GET é simplificado e requer apenas parâmetros na query string. Para a documentação destes parâmetros, consulte o capítulo Diretrizes.

Endpoints

Os endpoints disponíveis nas APIs do eDok, suas ações, métodos, disponibilidade e finalidades são detalhados abaixo.

A URL base das APIs do eDok é:

Onde:

  • <cliente>: rótulo de cliente definido na ativação do serviço.
  • <endpoint>: endpoint da API conforme tabela abaixo.
  • <ação>: ação desejada na API DocMetadata. Não se aplica às demais APIs.
EndpointAçãoMétodos HTTPDisponibilidade e VersãoFinalidade
DocMetadata.phpDescribeDocPOSTImediata (v2)Obter todos os metadados (primários e secundários) do documento requisitado.
DocMetadata.phpExportMetadataGET
POST
Imediata (v2)Exportar todos os metadados dos documentos admitidos no período informado.
DocMetadata.phpGetDocWithNoMetadataGET
POST
Imediata (v2)Obter uma lista com os documentos que não possuem metadados secundários e que foram admitidos no período informado.
DocMetadata.phpPostDocMetadataPOSTImediata (v2)Inserir ou atualizar metadados secundários de um documento específico.
DocStats.phpNão se aplicaGETImediata (v2)Obter estatísticas do eDok Ingest em dimensões variadas.
DocView.phpNão se aplicaGETImediata (v2)Visualizar um documento.
Same.phpNão se aplicaGETImediata (v2)Visualizar um documento para SAME.
SameSimple.phpNão se aplicaGETImediata (v2)Visualizar um documento com indexação simplificada para SAME.

As diretrizes e repostas de cada endpoint são descritas em detalhes no capítulo Diretrizes.