Em Desenvolvimento
Esta documentação ainda está em desenvolvimento. Agradecemos sua paciência!
Pular para o conteúdo principal
Versão: 03.008.000 🚧 (em desenvolvimento)

Ingestão nato-digital via API

Esta página é destinada a integradores. Um documento nato-digital (nunca foi papel) precisa entrar na guarda sem passar pela captura e digitalização, por exemplo uma nota fiscal eletrônica que o ERP quer arquivar diretamente com classe de guarda, prazo e origem. O endpoint de importação nato-digital recebe, numa única chamada, o arquivo, os metadados e a classe de guarda.

Diferentemente do endpoint usado internamente pelo fluxo de captura, este endpoint foi desenhado para sistemas externos: autentica uma conta de serviço, exige capacidade própria, não marca o documento como digitalizado e devolve códigos HTTP reais (erro de verdade vem com código de erro).

Licença: exige o módulo de servidor do GCVD licenciado. Sem licença, a chamada é recusada com 403. Ver Licenciamento.

Requisição​

POST /htf/toolkit/captureimportnative
Content-Type: multipart/form-data

A requisição tem duas partes: o arquivo (file) e um JSON de metadados (metadata).

--boundary
Content-Disposition: form-data; name="file"; filename="nota-fiscal-123.pdf"
--boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
"site": "financeiro",
"path": "contas-a-pagar/2026/09",
"externalId": "erp-nf-000123",
"sourceSystem": "SAP-FI",
"classCode": "NF-ENTRADA",
"contentType": "cm:content",
"properties": [ { "name": "cm:title", "value": "NF 123 - Fornecedor X" } ],
"mode": "create"
}

Exemplo com curl:

curl -u conta-servico:SENHA \
-F "file=@nota-fiscal-123.pdf" \
-F 'metadata={"site":"financeiro","path":"contas-a-pagar/2026/09","externalId":"erp-nf-000123","sourceSystem":"SAP-FI","classCode":"NF-ENTRADA","mode":"create"};type=application/json' \
https://SEU-SERVIDOR/.../htf/toolkit/captureimportnative

Substitua o endereço base pelo da sua instalação, mantendo o caminho /htf/toolkit/captureimportnative.

Campos de metadados​

CampoObrigatórioSignificado
siteSimSite de destino no repositório
pathNão (padrão: raiz do site)Caminho relativo dentro da biblioteca de documentos do site. É recusado com 400 se contiver o segmento literal documentLibrary
externalIdRecomendadoIdentificador do documento no sistema de origem; é a chave de deduplicação
sourceSystemObrigatório se externalId for enviadoRótulo do sistema de origem (por exemplo SAP-FI, TOTVS)
classCodeNãoCódigo da classe de guarda; o documento passa pelo motor de classificação. Com o recurso Classificação desligado, a classe é ignorada: o documento é criado normalmente, sem classe, e a resposta traz classificationIgnored: true. Nunca é erro
contentTypeNão (padrão: cm:content)Subtipo estrutural do conteúdo
propertiesNãoLista de pares name e value com propriedades adicionais
modeNão (padrão: create)create ou upsert

O tipo documental não é campo de entrada: é derivado exclusivamente da classe de guarda, que é a fonte única de verdade. A associação do documento a um dossiê também não é informada na ingestão; ela é derivada pela reconciliação de dossiês a partir do mapeamento do perfil (ver Dossiê).

Um documento nato-digital recebe o hash de identidade do arquivo, mas nunca o hash por página, que só existe para documentos digitalizados.

Idempotência​

A idempotência é controlada pelo par externalId e sourceSystem:

  • create (padrão): se já existe documento com o mesmo par, a resposta é 409, trazendo a referência do documento existente.
  • upsert: atualiza o conteúdo (gerando nova versão) e os metadados do documento existente, por exemplo quando o ERP reenvia a mesma nota fiscal retificada. Se o documento existente já estiver em guarda com o recurso Proteger documentos em guarda ligado, a troca de conteúdo é recusada: o conteúdo de um documento em guarda protegido não é trocado por ninguém.

Autenticação e autorização​

  • Autenticação HTTP Basic com uma conta de serviço real (não uma pessoa).
  • A conta precisa da capacidade Ingestão de documento nato-digital (API de integração). O perfil Integração nato-digital (conta de serviço) já traz somente essa capacidade (ver Capacidades e papéis).
  • Módulo de servidor do GCVD licenciado.

Respostas​

StatusSituação
201Documento criado. Corpo: {"nodeRef": "...", "path": "...", "status": "created"}; com a Classificação desligada e classCode informado, acrescenta "classificationIgnored": true (o documento entrou sem classe)
200mode=upsert atualizou um documento existente
400Requisição inválida: site ausente, path com o segmento documentLibrary, classe inexistente, inativa ou que não é folha. O corpo traz error com o motivo (por exemplo class_not_found ou class_inactive)
403Conta sem a capacidade de importação nato-digital ou sem licença
409mode=create com externalId e sourceSystem já existentes
500Erro não tratado

Auditoria​

Cada importação gera o evento Documento importado (nato-digital, integração), irmão de Documento digitalizado (capturado), visível na auditoria no subgrupo de conferência e entrada.

Outros canais de ingestão​

Este endpoint cobre a ingestão por API ou ERP. Documentos digitalizados entram pelo fluxo de captura e documentos já existentes no repositório, pela migração do legado.