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
| Campo | Obrigatório | Significado |
|---|---|---|
site | Sim | Site de destino no repositório |
path | Não (padrão: raiz do site) | Caminho relativo dentro da biblioteca de documentos do site. É recusado com 400 se contiver o segmento literal documentLibrary |
externalId | Recomendado | Identificador do documento no sistema de origem; é a chave de deduplicação |
sourceSystem | Obrigatório se externalId for enviado | Rótulo do sistema de origem (por exemplo SAP-FI, TOTVS) |
classCode | Não | Có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 |
contentType | Não (padrão: cm:content) | Subtipo estrutural do conteúdo |
properties | Não | Lista de pares name e value com propriedades adicionais |
mode | Nã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
| Status | Situação |
|---|---|
201 | Documento criado. Corpo: {"nodeRef": "...", "path": "...", "status": "created"}; com a Classificação desligada e classCode informado, acrescenta "classificationIgnored": true (o documento entrou sem classe) |
200 | mode=upsert atualizou um documento existente |
400 | Requisiçã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) |
403 | Conta sem a capacidade de importação nato-digital ou sem licença |
409 | mode=create com externalId e sourceSystem já existentes |
500 | Erro 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.