Pular para o conteúdo principal

Captura

Endpoints para institucionalização e registro final de documentos no E-Docs.

Fluxo de Integração

A captura ocorre após o upload físico do arquivo. O fluxo depende da natureza e do tipo de assinatura do documento:

  1. Envio de Metadados: Chamada do endpoint específico conforme o tipo de documento.
  2. Fase de Assinatura (se aplicável): Manifestação dos assinantes.
  3. Enfileiramento: E-Docs processa a captura e retorna um idEvento.
  4. Consulta: Uso do endpoint de eventos para obter o ID do documento capturado.

Tipos de Registro​

1. Nato-Digital com Assinatura Eletrônica (E-Docs), múltiplos assinantes​

Documentos originados digitalmente que exigem manifestação de múltiplos assinantes (ou assinatura posterior, caso o capturador não seja um assinante).

Regras Específicas:

  • Se o documento foi criado por um cidadão, todos os assinantes devem ser cidadãos.
  • O capturador informa o ID do arquivo (nuvem), os metadados e a lista de assinantes. Nenhuma assinatura é feita automaticamente, e o retorno é o identificador do documento em fase de assinatura (IdDocumentoFaseAssinatura).
  • Para restrição de acesso, consulte /api/RestricaoAcesso.
  • Cada assinante usa o endpoint de assinatura (POST /v2/documentos/fase-assinatura/assinar/{IdDocumentoFaseAssinatura}), com o próprio token de usuário.
  • Com a última manifestação (assinatura ou recusa), o documento é capturado. O retorno do endpoint de assinatura traz capturado: true e idCapturaEvento (identificador do evento de captura enfileirado). Antes disso, o documento ainda não existe: não pode ser entranhado nem usado em uma autuação.

2. Nato-Digital com Assinatura do Capturador​

Assinado automaticamente pelo responsável pelo registro (único assinante).

Regras Específicas:

  • A captura e a assinatura ocorrem no mesmo ato: o documento nasce assinado pelo papel informado em idPapelCapturadorAssinante, sem que o usuário acesse o E-Docs.
  • Para restrição de acesso, consulte /api/RestricaoAcesso.
  • O retorno é o identificador do evento de captura enfileirado. Depois que o evento é executado, o documento pode ser entranhado, por exemplo pelo campo idsDocumentosEntranhados da autuação de um processo.

3. Outros Casos​

Inclui Nato-digital cópia, Nato-digital assinado ICP-Brasil ou documentos digitalizados.

Regra Geral:

Assinar sem acessar o E-Docs​

O usuário não precisa abrir o E-Docs para assinar, mas continua sendo ele quem assina: o próprio signatário, logado pelo Acesso Cidadão no sistema integrado, aciona a assinatura com o token dele. O sistema não pode assinar em nome da pessoa.

  • Para um único assinante (o próprio capturador), use o tipo 2: a captura e a assinatura ocorrem no mesmo ato.
  • Para vários assinantes, use o tipo 1: cada signatário assina com o próprio token, também sem acessar o E-Docs.
  • A assinatura é sempre atribuída ao titular do token usado na chamada, e o papel informado deve pertencer a esse titular. Os papéis do titular são consultados em GET /v2/usuario/papeis.
  • Não existe assinatura em nome de terceiro, nem pelo sistema. O token sem usuário (client_credentials) não assina e não captura. Veja Autenticação.
  • É essa vinculação entre o ato e a identidade que sustenta o valor probatório da assinatura.

Informações Complementares​

Na etapa de registro, o Documento é categorizado conforme:

  • Natureza: Nato-digital ou Digitalizado.
  • Valor Legal: Original, Cópia Autenticada Administrativamente ou Cópia Simples.
  • Gênero: Textual (PDF). Áudio e Vídeo estão disponíveis apenas pela interface web do E-Docs.

Operações Pós-Captura​

Exemplos de payload​

Ilustrativo

Os exemplos abaixo apresentam o formato geral dos payloads. Campos exatos, obrigatórios e tipos estão definidos no Swagger V2.

Capturar nato-digital com Assinatura do Capturador (servidor)​

POST /v2/documentos/capturar/nato-digital/auto-assinado/servidor
Authorization: Bearer {token}
Content-Type: application/json
{
  "identificadorTemporarioArquivoNaNuvem": "8f9a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "nomeArquivo": "memorando.pdf",
  "idPapelCapturadorAssinante": "11111111-2222-3333-4444-555555555555",
  "idClasse": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "restricaoAcesso": {
    "transparenciaAtiva": true
  }
}

Resposta: o identificador do evento de captura (idEvento), a ser acompanhado em GET /v2/eventos/{idEvento}.

Capturar nato-digital com múltiplos assinantes (servidor)​

POST /v2/documentos/fase-assinatura/enviar/servidor
Authorization: Bearer {token}
Content-Type: application/json
{
  "identificadorTemporarioArquivoNaNuvem": "8f9a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "nomeArquivo": "termo-de-cooperacao.pdf",
  "idPapelCapturador": "11111111-2222-3333-4444-555555555555",
  "idClasse": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "assinantes": ["22222222-....", "33333333-...."],
  "restricaoAcesso": {
    "transparenciaAtiva": false
  }
}

Resposta: o identificador do documento em fase de assinatura (IdDocumentoFaseAssinatura). Cada assinante então se manifesta:

POST /v2/documentos/fase-assinatura/assinar/{IdDocumentoFaseAssinatura}
Authorization: Bearer {token do assinante}
{
  "capturado": true,
  "idCapturaEvento": "c1d2e3f4-a5b6-7890-1234-567890abcdef"
}

capturado é true apenas na última manifestação. Antes dela, o documento ainda não foi capturado.

Acompanhar a captura (consulta de evento)​

GET /v2/eventos/{idEvento}
Authorization: Bearer {token}

Resposta (após execução):

{
  "idEvento": "f1e2d3c4-...",
  "tipo": "CapturaDocumento",
  "status": "Executado",
  "idDocumento": "9b8a7c6d-5e4f-3a2b-1c0d-eeeeffff0000"
}

Recursos Auxiliares​