API Autentique — Assinatura digital

Documentação explicativa de cada endpoint REST exposto pelo módulo src/modules/autentique/.

Todas as rotas usam o prefixo /api. Respostas de sucesso seguem:

{
  "status": "success",
  "message": "Texto descritivo",
  "data": { }
}

Respostas de erro seguem:

{
  "status": "error",
  "message": "Motivo do erro",
  "statusCode": 400
}

---

Sumário

1. Visão geral
2. Onde ficam as credenciais
3. Autenticação
4. APIs de configuração
5. APIs de documentos
6. APIs de webhook e SSE
7. Status do documento
8. Fluxo recomendado
9. Pré-requisitos de banco
10. Referência rápida

---

1. Visão geral

A integração conecta o CRM à Autentique via GraphQL v2. O backend:

1. Armazena credenciais por empresa em company.metadata.autentique (não em .env).
2. Cria documentos na Autentique enviando PDF + dados do signatário.
3. Persiste o registro local na tabela documentos_assinatura.
4. Recebe webhooks quando o signatário visualiza, assina ou recusa.
5. Busca o link do PDF assinado quando o status vira ASSINADO.

flowchart LR
  Front["Frontend / sistema externo"] --> Config["POST .../autentique/config"]
  Config --> Meta["company.metadata.autentique"]
  Front --> Create["POST /documentos-assinatura"]
  Create --> Meta
  Create --> Autentique["Autentique GraphQL"]
  Autentique --> WH["POST /webhooks/assinatura"]
  WH --> DB["documentos_assinatura"]
  WH --> SSE["GET /webhooks/assinatura/stream"]

---

2. Onde ficam as credenciais

As credenciais não vão para variáveis de ambiente. Elas são gravadas em:

Tabela: public.company
Coluna: metadata (JSONB)
Chave: autentique

Estrutura persistida

{
  "autentique": {
    "apiToken": "token-bearer-da-autentique",
    "folderCred": "uuid-da-pasta-no-painel",
    "apiUrl": "https://api.autentique.com.br/v2/graphql",
    "signatureSecret": "secret-para-validar-webhook-hmac",
    "updatedAt": "2026-08-20T20:00:00.000Z",
    "updatedBy": "uuid-do-usuario-que-configurou"
  }
}

Campo	Obrigatório	Descrição
apiToken	Sim	Token Bearer da API Autentique
folderCred	Sim	UUID da pasta onde os PDFs serão criados
apiUrl	Não	URL GraphQL (default: https://api.autentique.com.br/v2/graphql)
signatureSecret	Recomendado	Secret para validar header x-autentique-signature nos webhooks

Todas as operações que chamam a Autentique leem esses dados da empresa informada (company_uuid ou empresa vinculada ao documento).

---

3. Autenticação

JWT (padrão)

Rotas protegidas exigem:

Authorization: Bearer <sessionHash>

O sessionHash é retornado no POST /api/auth/login.

Configuração externa (server-to-server)

Os endpoints POST e PATCH de configuração também aceitam:

X-Governance-External-Key: <valor de GOVERNANCE_THEME_TOKENS_EXTERNAL_READ_KEY>

Sem JWT, desde que a variável de ambiente esteja definida no servidor. Útil para sistemas externos configurarem a integração automaticamente.

Rotas públicas

Webhooks e o stream SSE não exigem JWT — a Autentique e o frontend consomem diretamente.

---

4. APIs de configuração

Prefixo: /api/companies/:companyUuid/autentique

---

4.1. GET /companies/:companyUuid/autentique/config

Consulta a configuração da empresa. Token e secret não são expostos em texto claro.

Item	Valor
Auth	JWT
Path param	companyUuid — UUID v4 da empresa

Resposta (data.config)

{
  "configured": true,
  "apiUrl": "https://api.autentique.com.br/v2/graphql",
  "folderCred": "a1000001-0000-4000-8000-000000000001",
  "apiTokenMasked": "abcd...wxyz",
  "signatureSecretConfigured": true,
  "updatedAt": "2026-08-20T20:00:00.000Z",
  "updatedBy": "348e799b-dfdb-465f-a031-e34816203d40"
}

Campo	Descrição
configured	false se a empresa ainda não tem bloco autentique válido
apiTokenMasked	Primeiros 4 + últimos 4 caracteres do token
signatureSecretConfigured	Indica se o secret de webhook foi definido

Erros comuns

HTTP	Motivo
401	JWT inválido ou ausente
404	Empresa não encontrada ou sem permissão de acesso

Exemplo cURL

curl -X GET "https://seu-backend/api/companies/348e799b-dfdb-465f-a031-e34816203d40/autentique/config" \
  -H "Authorization: Bearer SEU_JWT"

---

4.2. POST /companies/:companyUuid/autentique/config

Grava ou substitui a configuração completa da integração.

Item	Valor
Auth	JWT ou X-Governance-External-Key
Content-Type	application/json

Body (todos obrigatórios no POST)

{
  "apiToken": "seu-token-autentique",
  "folderCred": "a1000001-0000-4000-8000-000000000001",
  "apiUrl": "https://api.autentique.com.br/v2/graphql",
  "signatureSecret": "secret-do-webhook"
}

Campo	Obrigatório	Descrição
apiToken	Sim	Token Bearer da Autentique
folderCred	Sim	UUID da pasta no painel Autentique
apiUrl	Não	URL GraphQL customizada
signatureSecret	Não	Secret HMAC para webhooks

Resposta

Mesmo formato do GET — config mascarada após gravação.

Erros comuns

HTTP	Motivo
400	Campos inválidos ou config incompleta após merge
404	Empresa não encontrada

Exemplo cURL (JWT)

curl -X POST "https://seu-backend/api/companies/348e799b-dfdb-465f-a031-e34816203d40/autentique/config" \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "TOKEN_AUTENTIQUE",
    "folderCred": "UUID_DA_PASTA",
    "signatureSecret": "SECRET_WEBHOOK"
  }'

Exemplo cURL (configuração externa)

curl -X POST "https://seu-backend/api/companies/348e799b-dfdb-465f-a031-e34816203d40/autentique/config" \
  -H "X-Governance-External-Key: SUA_CHAVE_EXTERNA" \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "TOKEN_AUTENTIQUE",
    "folderCred": "UUID_DA_PASTA"
  }'

---

4.3. PATCH /companies/:companyUuid/autentique/config

Atualização parcial — envie apenas os campos que deseja alterar.

Item	Valor
Auth	JWT ou X-Governance-External-Key
Content-Type	application/json

Body (todos opcionais)

{
  "signatureSecret": "novo-secret"
}

Após o merge, apiToken e folderCred precisam continuar válidos no metadata. Se a empresa nunca foi configurada e você enviar só um campo parcial, retorna 400.

Exemplo cURL

curl -X PATCH "https://seu-backend/api/companies/348e799b-dfdb-465f-a031-e34816203d40/autentique/config" \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "apiUrl": "https://api.autentique.com.br/v2/graphql" }'

---

4.4. GET /companies/:companyUuid/autentique/test-config

Testa a conexão com a Autentique executando uma query GraphQL leve (ListDocuments com limit: 1).

Item	Valor
Auth	JWT

Resposta (data)

{
  "ok": true,
  "apiUrl": "https://api.autentique.com.br/v2/graphql"
}

Erros comuns

HTTP	Motivo
400	Integração não configurada para a empresa
502 / erro GraphQL	Token inválido, pasta sem permissão ou créditos esgotados

Exemplo cURL

curl -X GET "https://seu-backend/api/companies/348e799b-dfdb-465f-a031-e34816203d40/autentique/test-config" \
  -H "Authorization: Bearer SEU_JWT"

---

5. APIs de documentos

Prefixo: /api/documentos-assinatura

Todas exigem JWT. As credenciais Autentique são lidas de company.metadata.autentique da empresa informada no body ou vinculada ao registro.

---

5.1. POST /documentos-assinatura

Cria um documento na Autentique e persiste o registro local com status PENDENTE.

Item	Valor
Auth	JWT
Content-Type	multipart/form-data
Limite PDF	10 MB

Campos do formulário

Campo	Obrigatório	Descrição
proposta_id	Sim	UUID do cliente/proposta (clientes.uuid)
nome_documento	Sim	Nome exibido na Autentique
signatario_email	Sim	E-mail de quem assina
signatario_nome	Sim	Nome do signatário
company_uuid	Sim	UUID da empresa dona da config Autentique
representante_cpf	Não	CPF do representante (até 14 caracteres)
arquivo	Sim	Arquivo PDF

Validações antes da chamada à Autentique

1. proposta_id deve existir em clientes no tenant do JWT.
2. PDF obrigatório e dentro do limite de 10 MB.
3. company.metadata.autentique deve ter apiToken e folderCred.

Resposta (data.documento)

{
  "id": "b2000001-0000-4000-8000-000000000001",
  "tenantId": "...",
  "companyId": "348e799b-dfdb-465f-a031-e34816203d40",
  "propostaId": "...",
  "documentoId": "uuid-retornado-pela-autentique",
  "nomeDocumento": "Contrato de Credenciamento",
  "linkAssinatura": "https://assinar.link/...",
  "linkPdfAssinado": null,
  "status": "PENDENTE",
  "representanteCpf": "12345678901",
  "arquivado": false,
  "metadata": {},
  "createdAt": "2026-08-20T20:00:00.000Z",
  "updatedAt": "2026-08-20T20:00:00.000Z"
}

Caso especial: falha ao salvar no banco

Se o documento foi criado na Autentique mas o INSERT local falhou, a resposta inclui:

{
  "_notSavedInDb": true
}

O documento já existe na Autentique — trate manualmente ou reprocesse.

Exemplo cURL

curl -X POST "https://seu-backend/api/documentos-assinatura" \
  -H "Authorization: Bearer SEU_JWT" \
  -F "proposta_id=348e799b-dfdb-465f-a031-e34816203d40" \
  -F "nome_documento=Contrato de Credenciamento" \
  -F "signatario_email=signatario@email.com" \
  -F "signatario_nome=Fulano de Tal" \
  -F "company_uuid=348e799b-dfdb-465f-a031-e34816203d40" \
  -F "arquivo=@contrato.pdf;type=application/pdf"

---

5.2. GET /documentos-assinatura/documento/:documentoId

Busca o registro local pelo ID do documento na Autentique (não confundir com o UUID interno).

Item	Valor
Auth	JWT
Path param	documentoId — ID retornado pela Autentique em createDocument.id

Resposta

{
  "documento": { "...mesma estrutura do POST..." }
}

Erros comuns

HTTP	Motivo
404	Documento não encontrado ou empresa sem acesso

Exemplo cURL

curl -X GET "https://seu-backend/api/documentos-assinatura/documento/UUID_AUTENTIQUE" \
  -H "Authorization: Bearer SEU_JWT"

---

5.3. PATCH /documentos-assinatura/:id/sync-autentique

Sincroniza manualmente o status local consultando a Autentique.

Item	Valor
Auth	JWT
Path param	id — UUID interno do registro (documentos_assinatura.id)

O que acontece

1. Consulta GraphQL enriquecida na Autentique (files.signed, signatures.viewed/signed/rejected).
2. Deriva o status local.
3. Se ASSINADO, busca e persiste linkPdfAssinado.

Lógica de status derivada

Condição na Autentique	Status local
Alguma assinatura rejected: true	RECUSADO
files.signed existe ou alguma signed: true	ASSINADO
Alguma viewed: true	VISTO
Caso contrário	PENDENTE

Resposta

{
  "documento": { "...registro atualizado..." }
}

Exemplo cURL

curl -X PATCH "https://seu-backend/api/documentos-assinatura/b2000001-0000-4000-8000-000000000001/sync-autentique" \
  -H "Authorization: Bearer SEU_JWT"

---

5.4. GET /documentos-assinatura/:id/download

Retorna o link do PDF assinado. Exige status local ASSINADO.

Item	Valor
Auth	JWT
Path param	id — UUID interno do registro

Internamente executa sincronização antes de validar o status.

Resposta (data)

{
  "link": "https://url-do-pdf-assinado.autentique.com.br/..."
}

Erros comuns

HTTP	Motivo
400	Documento ainda não assinado
404	Registro não encontrado

Exemplo cURL

curl -X GET "https://seu-backend/api/documentos-assinatura/b2000001-0000-4000-8000-000000000001/download" \
  -H "Authorization: Bearer SEU_JWT"

---

5.5. GET /documentos-assinatura/test-config/:companyUuid

Alias do teste de configuração — mesmo comportamento de
GET /companies/:companyUuid/autentique/test-config.

Útil quando o frontend já trabalha no contexto de documentos.

---

6. APIs de webhook e SSE

---

6.1. POST /webhooks/assinatura (recomendado)

Endpoint público para a Autentique enviar eventos de assinatura.

Item	Valor
Auth	Nenhuma (pública)
Content-Type	application/json
Header opcional	x-autentique-signature — HMAC SHA256 do body

Configure no painel Autentique:

https://seu-dominio/api/webhooks/assinatura

Formatos de payload aceitos

Moderno (preferencial):

{
  "event": {
    "type": "signature.accepted",
    "data": {
      "object": {
        "document": "uuid-do-documento",
        "public_id": "uuid-da-assinatura"
      }
    }
  }
}

Legado:

{
  "event": "signature.accepted",
  "document": { "id": "uuid-do-documento" },
  "signature": { "id": "uuid-da-assinatura" }
}

Eventos e status

Evento Autentique	Status local
signature.created	PENDENTE
signature.viewed	VISTO
signature.updated	Derivado de flags (viewed, signed, rejected)
signature.accepted	ASSINADO
signature.rejected	RECUSADO
signature.refused	RECUSADO
document.finished	ASSINADO

Pós-processamento quando vira ASSINADO

1. Busca files.signed na Autentique.
2. Persiste link_pdf_assinado.
3. Emite evento no stream SSE.

Validação HMAC

Se signatureSecret estiver em company.metadata.autentique, o backend valida:

HMAC-SHA256(rawBody, signatureSecret) → hex

Comparado ao header x-autentique-signature.

Comportamento atual: assinatura inválida gera warning no log e o processamento continua (não bloqueia).

Resposta

Sempre HTTP 200, mesmo em erro interno — evita reenvio infinito pela Autentique.

{
  "status": "success",
  "message": "Webhook processado"
}

---

6.2. Rotas legadas de webhook

Mesmo handler do endpoint recomendado:

Rota	Uso
POST /autentique/webhook	Legado
POST /documentos-assinados	Legado

Preferir sempre /webhooks/assinatura em novas integrações.

---

6.3. GET /autentique/webhook/status

Retorna as URLs que devem ser configuradas no painel Autentique.

Item	Valor
Auth	JWT

Resposta (data)

{
  "webhookUrls": [
    "https://seu-dominio/api/webhooks/assinatura",
    "https://seu-dominio/api/autentique/webhook",
    "https://seu-dominio/api/documentos-assinados"
  ],
  "rawBodyEnabled": true
}

Exemplo cURL

curl -X GET "https://seu-backend/api/autentique/webhook/status" \
  -H "Authorization: Bearer SEU_JWT"

---

6.4. GET /webhooks/assinatura/stream

Stream SSE (Server-Sent Events) com atualizações de status em tempo real.

Item	Valor
Auth	Nenhuma (pública)
Content-Type resposta	text/event-stream

Eventos emitidos

Conexão:

data: {"type":"connected","at":"2026-08-20T20:00:00.000Z"}

Atualização de status (após webhook processado):

data: {
  "type": "status",
  "documentoAssinaturaId": "uuid-interno",
  "documentoId": "uuid-autentique",
  "status": "ASSINADO",
  "linkPdfAssinado": "https://...",
  "updatedAt": "2026-08-20T20:05:00.000Z"
}

Heartbeat (a cada 25 s):

: heartbeat

Exemplo no browser

const source = new EventSource('https://seu-backend/api/webhooks/assinatura/stream');

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  if (payload.type === 'status') {
    console.log('Status atualizado:', payload.status, payload.documentoId);
  }
};

---

7. Status do documento

Valores possíveis

Status	Significado
PENDENTE	Documento criado, aguardando ação do signatário
VISTO	Signatário visualizou o documento
ASSINADO	Documento assinado — PDF disponível
RECUSADO	Signatário recusou a assinatura

Hierarquia (não regride, exceto regras de RECUSADO)

PENDENTE (1) → VISTO (2) → ASSINADO (3)
RECUSADO (4)

---

8. Fluxo recomendado

Setup inicial (uma vez por empresa)

sequenceDiagram
  participant Admin
  participant API
  participant DB

  Admin->>API: POST /companies/{uuid}/autentique/config
  API->>DB: Grava company.metadata.autentique
  Admin->>API: GET /companies/{uuid}/autentique/test-config
  API-->>Admin: { ok: true }
  Admin->>Autentique: Configura webhook → /api/webhooks/assinatura

Envio de documento para assinatura

sequenceDiagram
  participant Front
  participant API
  participant Autentique
  participant DB

  Front->>API: POST /documentos-assinatura (PDF + dados)
  API->>DB: Valida proposta_id
  API->>Autentique: createDocument (multipart)
  Autentique-->>API: documento_id + link_assinatura
  API->>DB: INSERT status PENDENTE
  API-->>Front: linkAssinatura para o signatário

Atualização automática via webhook

sequenceDiagram
  participant Signatario
  participant Autentique
  participant API
  participant DB
  participant SSE

  Signatario->>Autentique: Assina documento
  Autentique->>API: POST /webhooks/assinatura
  API->>Autentique: getSignedPdfLink
  API->>DB: status ASSINADO + link_pdf_assinado
  API->>SSE: Emite evento status

---

9. Pré-requisitos de banco

Antes de usar as APIs de documento, execute a migration:

psql -h HOST -U USER -d DATABASE -f db/migrations/create_documentos_assinatura.sql

Tabela criada: public.documentos_assinatura

Coluna	Descrição
id	PK interna (UUID)
tenant_id	Tenant do registro
company_id	Empresa dona da config
proposta_id	FK para clientes.uuid
documento_id	ID único na Autentique
nome_documento	Nome do documento
link_assinatura	URL curta para o signatário
link_pdf_assinado	URL do PDF assinado
status	PENDENTE | VISTO | ASSINADO | RECUSADO
representante_cpf	CPF opcional
arquivado	Flag booleana (default false)

---

10. Referência rápida

Método	Rota	Auth	Descrição
GET	/companies/:companyUuid/autentique/config	JWT	Lê config (mascarada)
POST	/companies/:companyUuid/autentique/config	JWT ou External Key	Grava config completa
PATCH	/companies/:companyUuid/autentique/config	JWT ou External Key	Atualiza config parcial
GET	/companies/:companyUuid/autentique/test-config	JWT	Testa conexão Autentique
POST	/documentos-assinatura	JWT	Cria documento (multipart)
GET	/documentos-assinatura/documento/:documentoId	JWT	Busca por ID Autentique
PATCH	/documentos-assinatura/:id/sync-autentique	JWT	Sincroniza status
GET	/documentos-assinatura/:id/download	JWT	Link do PDF assinado
GET	/documentos-assinatura/test-config/:companyUuid	JWT	Alias de teste de config
POST	/webhooks/assinatura	Pública	Webhook (recomendado)
POST	/autentique/webhook	Pública	Webhook legado
POST	/documentos-assinados	Pública	Webhook legado
GET	/autentique/webhook/status	JWT	URLs do webhook
GET	/webhooks/assinatura/stream	Pública	SSE de status

---

Arquivos de código relacionados

Responsabilidade	Arquivo
Config (controller)	src/modules/autentique/autentique-config.controller.ts
Documentos (controller)	src/modules/autentique/documento-assinatura.controller.ts
Webhooks / SSE (controller)	src/modules/autentique/autentique-webhook.controller.ts
Lógica de negócio	src/modules/autentique/autentique.service.ts
Cliente GraphQL	src/modules/autentique/utils/autentique-api.utils.ts
Metadata da empresa	src/modules/autentique/utils/company-autentique-metadata.util.ts
Parser de webhook	src/modules/autentique/utils/autentique-webhook-payload.utils.ts
Repositório	src/repositories/documentos-assinatura.repository.ts
Migration	db/migrations/create_documentos_assinatura.sql
Testes unitários	test/unit/modules/autentique/utils/autentique-api.utils.spec.ts