API REST Pública — v1

Documentação da API
Integra ID

Integre assinaturas digitais e certificações de autenticidade diretamente no seu sistema. Gerencie documentos, envie solicitações de assinatura e receba notificações via webhook.

Base URL https://api.integraid.com.br/functions/v1/public-api/v1

01 Autenticação

Todas as requisições devem incluir o header X-Api-Key com sua chave de API.

HTTP
POST /v1/documents
X-Api-Key: iid_live_a1b2c3d4e5f6...
Content-Type: application/json

Prefixo	Ambiente
iid_live_	Produção
iid_test_	Homologação

🔐

As chaves são geradas no painel em Configurações → API Keys e armazenadas como hash SHA-256. O valor bruto é exibido apenas uma vez no momento da criação.

02 Formato de resposta

✅ Sucesso

JSON
{
  "document_id": "uuid",
  "name": "contrato.pdf",
  ...
}

❌ Erro

JSON
{
  "error": {
    "code": "document_not_found",
    "message": "Documento não encontrado.",
    "request_id": "uuid",
    "details": null
  }
}

Todo response inclui o header X-Request-Id com o UUID da requisição para rastreabilidade.

03 Escopos

Cada API Key possui um conjunto de escopos que limitam as operações permitidas:

Escopo	Operações permitidas
documents:read	Listar e consultar documentos, obter URL de download
documents:write	Upload de documentos (simples e em dois passos)
certifications:read	Consultar certificações de integridade
certifications:write	Enviar arquivos para certificação (Hashing e ICP-Brasil placeholder)
sign:read	Consultar status de assinaturas
sign:cancel	Cancelar solicitações de assinatura pendentes
sign:send	Enviar e reenviar links de assinatura (`/signatures/send`, `/signatures/:id/resend`)
envelopes:write	Criar envelopes e enviar links de assinatura para múltiplos documentos
envelopes:read	Consultar status e progresso de envelopes

04 Rate Limiting

Limites por API Key, por endpoint, por janela de 1 hora. Ao exceder, a API retorna HTTP 429 com o código rate_limit_exceeded.

POST /v1/documents

100 req/h

POST /v1/documents/upload-url

100 req/h

POST /v1/documents/complete-upload

100 req/h

POST /v1/signatures/send

300 req/h

POST /v1/signatures/:id/cancel

300 req/h

POST /v1/signatures/:id/resend

100 req/h

GET /v1/documents

500 req/h

GET /v1/documents/:id

1000 req/h

GET /v1/documents/:id/download

200 req/h

POST /v1/certifications

100 req/h

POST /v1/certifications/upload-url

100 req/h

POST /v1/certifications/certify

100 req/h

GET /v1/certifications

500 req/h

GET /v1/certifications/:id

1000 req/h

POST /v1/envelopes

100 req/h

GET /v1/envelopes/:id

500 req/h

05 Idempotência

Para operações POST, envie o header Idempotency-Key para evitar duplicatas em caso de retry.

HTTP
Idempotency-Key: <uuid-v4-gerado-pelo-cliente>

Regra	Detalhe
Unicidade	A chave deve ser única por operação e gerada pelo seu sistema
Cache	Responses são cacheados por 24 horas
Conflito	Mesma chave com payload diferente retorna `HTTP 409` (`idempotency_key_conflict`)
Replay	Responses repetidos incluem `X-Idempotent-Replayed: true`

06 Endpoints

POST /v1/documents documents:write

Upload de documento em Base64. Recomendado para arquivos até ~4.5 MB (o payload Base64 equivalente é ~6 MB, limite do corpo da Edge Function). Para arquivos maiores, utilize obrigatoriamente o fluxo de dois passos com /upload-url + /complete-upload, que não possui limite prático de tamanho.

Request Body

JSON
{
  "filename":        "contrato-joao.pdf",
  "file_base64":     "<conteúdo do arquivo em Base64>",
  "document_type":   "contract",
  "external_id":     "ERP-00123",
  "external_source": "totvs",
  "metadata": {
    "cliente": "João Silva",
    "contrato_numero": "2024-001"
  },
  "video_checkpoints": [
    {
      "clause_title": "Consentimento Verbal",
      "clause_summary": "Eu concordo com os termos descritos neste documento.",
      "checkpoint_type": "verbal_consent",
      "requires_verbal_consent": true
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
filename	string	✅	Nome do arquivo (incluindo extensão)
file_base64	string	✅	Conteúdo do arquivo codificado em Base64
document_type	string	—	`document`, `contract` ou `others`. Padrão: `document`
external_id	string	—	ID do documento no seu sistema (único por tenant)
external_source	string	—	Identificador do sistema de origem (ex: `"totvs"`)
video_auditor_template_id	string	—	ID do Template de Auditor de Vídeo criado no painel. O roteiro será montado magicamente para você.
metadata	object	—	Campos livres para uso interno. Dica: As chaves enviadas aqui substituirão automaticamente as `{{variaveis}}` correspondentes caso um Template de Auditor de Vídeo IA seja passado no upload ou no painel.
video_checkpoints	array	—	Roteiro manual de checkpoints em vídeo (alternativa ao uso de templates).

Response — 201

JSON
{
  "document_id":    "3f7a8b2c-...",
  "external_id":    "ERP-00123",
  "name":           "contrato-joao.pdf",
  "document_type":  "contract",
  "status":         "uploaded",
  "signing_status": "draft",
  "created_at":     "2024-01-15T10:30:00Z"
}

Erros específicos

Código	HTTP	Descrição
invalid_payload	422	Campo obrigatório ausente ou `file_base64` inválido
duplicate_external_id	409	`external_id` já existe neste tenant
storage_error	500	Falha ao salvar no storage

POST /v1/documents/upload-url documents:write

Passo 1 do upload em dois passos. Gera uma URL pré-assinada para upload direto ao storage (arquivos grandes).

Request Body

JSON
{
  "filename":      "contrato-grande.pdf",
  "content_type":  "application/pdf",
  "document_type": "contract",
  "external_id":   "ERP-00456"
}

Campo	Tipo	Obrigatório	Descrição
filename	string	✅	Nome do arquivo
content_type	string	—	MIME type. Padrão: `application/pdf`
document_type	string	—	`document`, `contract` ou `others`
external_id	string	—	ID no sistema externo

Response — 200

JSON
{
  "upload_url":   "https://storage.supabase.co/...",
  "storage_path": "api/tenant-id/uuid-contrato-grande.pdf",
  "token":        "eyJ...",
  "expires_in":   3600,
  "next_step":    "POST /v1/documents/complete-upload",
  "hint": {
    "storage_path":  "api/tenant-id/uuid-contrato-grande.pdf",
    "filename":      "contrato-grande.pdf",
    "document_type": "contract",
    "external_id":   "ERP-00456"
  }
}

ℹ️

Fluxo: 1) Receba upload_url e faça PUT diretamente nessa URL com o conteúdo do arquivo. 2) Use storage_path e token para chamar /complete-upload.

POST /v1/documents/complete-upload documents:write

Passo 2: Registra o documento no banco após o upload direto ao storage ter sido concluído.

Request Body

JSON
{
  "storage_path":    "api/tenant-id/uuid-contrato-grande.pdf",
  "filename":        "contrato-grande.pdf",
  "document_type":   "contract",
  "external_id":     "ERP-00456",
  "external_source": "sap",
  "metadata": {}
}

Campo	Tipo	Obrigatório	Descrição
storage_path	string	✅	Retornado por `/upload-url`
filename	string	✅	Nome do arquivo
document_type	string	—	Tipo do documento
external_id	string	—	ID no sistema externo
external_source	string	—	Sistema de origem
metadata	object	—	Campos livres

Response — 201

Mesmo formato do POST /v1/documents.

POST /v1/documents/:id/video-consent documents:write

Configura o roteiro de checkpoints de vídeo (Prova de Vida Audiovisual) para um documento em rascunho. Você pode enviar a lista manual ou ativar um Template IA criado no painel.

Request Body

JSON
{
  "video_auditor_template_id": "uuid-do-template-criado-no-painel",
  "metadata": {
    "cliente": "João Silva"
  }
}

Ou se não utilizar templates, você pode enviar o array checkpoints listando cada cláusula manualmente.

Campo	Tipo	Obrigatório	Descrição
video_auditor_template_id	string	—	ID do template criado no painel (recomendado).
metadata	object	—	Complemento ou substituição do metadata do documento para preencher variáveis `{{...}}`.
checkpoints	array	—	Lista de checkpoints/cláusulas manuais. (Obrigatório caso não use `video_auditor_template_id`).

Response — 200

JSON
{
  "document_id": "3f7a8b2c-...",
  "status": "video_consent_configured",
  "checkpoint_count": 1
}

GET /v1/documents documents:read

Lista documentos do tenant com paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
page	integer	Página atual. Padrão: 1
per_page	integer	Itens por página (máx. 100). Padrão: 20
status	string	`draft` \| `pending` \| `partially_signed` \| `fully_signed` \| `expired`
document_type	string	`document` \| `contract` \| `others`
external_id	string	Filtrar por ID externo exato
created_from	ISO 8601	Documentos criados após esta data
created_to	ISO 8601	Documentos criados antes desta data

Exemplo de requisição

HTTP
GET /v1/documents?status=pending&page=1&per_page=20&created_from=2024-01-01T00:00:00Z

Response — 200

JSON
{
  "data": [
    {
      "id":              "3f7a8b2c-...",
      "name":            "contrato-joao.pdf",
      "document_type":   "contract",
      "signing_status":  "pending",
      "total_signers":   2,
      "signed_count":    1,
      "external_id":     "ERP-00123",
      "external_source": "totvs",
      "created_at":      "2024-01-15T10:30:00Z",
      "updated_at":      "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page":        1,
    "per_page":    20,
    "total":       47,
    "total_pages": 3
  }
}

GET /v1/documents/:id documents:read

Retorna os detalhes completos de um documento, incluindo o status de cada signatário.

Response — 200

JSON
{
  "document_id":     "3f7a8b2c-...",
  "external_id":     "ERP-00123",
  "external_source": "totvs",
  "name":            "contrato-joao.pdf",
  "document_type":   "contract",
  "signing_status":  "partially_signed",
  "total_signers":   2,
  "signed_count":    1,
  "metadata": {
    "cliente": "João Silva"
  },
  "signers": [
    {
      "sign_request_id": "uuid-da-solicitacao",
      "name":            "João Silva",
      "email":           "joao@empresa.com",
      "status":          "signed",
      "auth_methods":    ["email"],
      "require_selfie":  false,
      "sent_at":         "2024-01-15T10:31:00Z",
      "signed_at":       "2024-01-15T14:20:00Z"
    },
    {
      "sign_request_id": "uuid-da-solicitacao-2",
      "name":            "Maria Santos",
      "email":           "maria@empresa.com",
      "status":          "pending",
      "auth_methods":    ["email", "whatsapp"],
      "require_selfie":  true,
      "sent_at":         "2024-01-15T10:31:00Z",
      "signed_at":       null
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:20:00Z"
}

Valores de signing_status

Valor	Descrição
draft	Documento enviado, sem signatários configurados
pending	Aguardando assinaturas
partially_signed	Ao menos um signatário assinou
fully_signed	Todos os signatários assinaram
expired	Prazo expirado

Valores de status (signatário)

Valor	Descrição
pending	Aguardando assinatura
signed	Assinou com sucesso
cancelled	Solicitação cancelada

GET /v1/documents/:id/download documents:read

Gera uma URL pré-assinada (válida por 1 hora) para download do PDF assinado.

⚠️

Só funciona para documentos com pelo menos uma assinatura concluída.

Response — 200

JSON
{
  "document_id":  "3f7a8b2c-...",
  "name":         "contrato-joao.pdf",
  "download_url": "https://storage.supabase.co/...?token=...",
  "expires_in":   3600
}

Erros específicos

Código	HTTP	Descrição
not_signed	409	Documento sem assinaturas concluídas
pdf_not_ready	404	PDF ainda está sendo gerado

POST /v1/signatures/send sign:send

Envia links de assinatura para um ou mais destinatários. O sistema notifica por e-mail e, opcionalmente, por WhatsApp.

Request Body

JSON
{
  "document_id": "3f7a8b2c-...",
  "recipients": [
    {
      "name":                   "João Silva",
      "email":                  "joao@empresa.com",
      "phone":                  "+5511999998888",
      "auth_methods":           ["email"],
      "require_selfie":         false,
      "send_link_via_whatsapp": false
    },
    {
      "name":                   "Maria Santos",
      "email":                  "maria@empresa.com",
      "phone":                  "+5511977776666",
      "auth_methods":           ["email", "whatsapp"],
      "require_selfie":         true,
      "send_link_via_whatsapp": true
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
document_id	string	✅ (ou external_id)	UUID do documento
external_id	string	✅ (ou document_id)	ID externo do documento
recipients	array	✅	Lista de destinatários

Campos por destinatário

Campo	Tipo	Obrigatório	Descrição
email	string	✅	E-mail do signatário
name	string	—	Nome completo
phone	string	Cond.	E.164 (ex: +5511999998888). Obrigatório se auth inclui `whatsapp`
auth_methods	string[]	—	`["email"]` ou `["email","whatsapp"]`. Padrão: `["email"]`
require_selfie	boolean	—	Exige selfie no momento da assinatura. Padrão: `false`
send_link_via_whatsapp	boolean	—	Envia link também via WhatsApp. Padrão: `false`

ℹ️

Anti-duplicidade: Se já existir token pendente para o mesmo e-mail+documento, o sistema reutiliza o token existente e atualiza os dados (não cria duplicatas).

Response — 200

JSON
{
  "document_id": "3f7a8b2c-...",
  "external_id": "ERP-00123",
  "sign_request": {
    "results": [
      {
        "email":       "joao@empresa.com",
        "success":     true,
        "signing_url": "https://integraid.com.br/assinar/uuid-do-token"
      },
      {
        "email":   "maria@empresa.com",
        "success": false,
        "error":   "phone é obrigatório quando auth_methods inclui \"whatsapp\"."
      }
    ]
  }
}

GET /v1/signatures/:id/video documents:read

Resgata a URL segura (Signed URL) da gravação de vídeo (Prova de Vida) associada a uma solicitação de assinatura.

Response — 200

JSON
{
  "signature_id": "uuid-da-solicitacao",
  "video_url": "https://storage.supabase.co/...?token=...",
  "expires_in": 3600,
  "recording_status": "analyzed_success",
  "created_at": "2024-01-15T14:20:00Z"
}

Erros específicos

Código	HTTP	Descrição
video_not_found	404	Assinatura não possui gravação ou não foi encontrada

07+ Envelopes

Um envelope agrupa múltiplos documentos numa única solicitação de assinatura. O signatário recebe 1 link, passa pelo OTP uma vez e assina todos os documentos em sessão única.

📦

Contagem de plano: 1 envelope com N documentos e M signatários consome M assinaturas do seu plano (não N × M). Limite: 50 documentos por envelope.

POST /v1/envelopes sign:send

Cria um envelope e dispara automaticamente os links de assinatura para todos os destinatários informados em uma única chamada. Suporta assinatura sequencial, OTP WhatsApp e exigência de selfie.

Request Body

JSON
{
  "name":        "Kit Admissional — João Silva",
  "description": "Documentos de admissão",
  "documents": [
    "3f7a8b2c-...",
    "EXTERNAL_ID_123"
  ],
  "is_sequential": false,
  "allow_sig_positioning": false,
  "reminder_interval_days": 3,
  "recipients": [
    {
      "name":                   "João Silva",
      "email":                  "joao@empresa.com",
      "phone":                  "+5511999998888",
      "auth_methods":           ["email"],
      "require_selfie":         false,
      "send_link_via_whatsapp": false
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
name	string	✅	Nome do envelope (visível para os signatários)
description	string	—	Descrição opcional
documents	string[]	✅	Array listando UUIDs ou external IDs dos documentos pré-enviados (máx 50)
recipients	array	✅	Lista de destinatários que assinarão
is_sequential	boolean	—	Cada signatário recebe o link somente após o anterior assinar. Padrão: `false`
allow_sig_positioning	boolean	—	Permite posicionar a etiqueta de assinatura em cada folha visualmente. Padrão: `false`
reminder_interval_days	integer	—	Intervalo para reenvio automático.

Campos por destinatário

Campo	Tipo	Obrigatório	Descrição
email	string	✅	E-mail do signatário
name	string	—	Nome do signatário
phone	string	Cond.	Obrigatório se `whatsapp` for usado. (Padrão E.164)
auth_methods	string[]	—	`["email"]` ou `["email","whatsapp"]`
require_selfie	boolean	—	Exige selfie no ato.
send_link_via_whatsapp	boolean	—	Dispara via WhatsApp simultaneamente.

Response — 201

JSON
{
  "envelope_id": "a1b2c3d4-...",
  "name": "Kit Admissional — João Silva",
  "sign_requests": {
    "results": [
      {
        "email": "joao@empresa.com",
        "success": true,
        "signing_url": "https://integraid.com.br/assinar-envelope/uuid"
      }
    ]
  }
}

Erros específicos

Código	HTTP	Descrição
invalid_payload	422	Array de documentos/recipients vazio ou não encontrado
documents_not_found	404	Os Documentos no array não pertencem à chave conectada

GET /v1/envelopes/:id envelopes:read

Retorna o status detalhado do envelope, incluindo a lista de documentos e o progresso de assinatura de cada signatário.

Response — 200

JSON
{
  "envelope_id":     "a1b2c3d4-...",
  "name":            "Kit Admissional — João Silva",
  "description":     "Documentos de admissão",
  "signing_status":  "partially_signed",
  "is_sequential":   false,
  "document_count":  3,
  "total_signers":   2,
  "signed_count":    1,
  "created_at":      "2024-03-01T09:00:00Z",
  "updated_at":      "2024-03-01T14:30:00Z",
  "documents": [
    { "document_id": "3f7a8b2c-...", "name": "Contrato.pdf",       "sort_order": 1 },
    { "document_id": "9d1e4f0a-...", "name": "LGPD.pdf",           "sort_order": 2 },
    { "document_id": "c2b87a11-...", "name": "Ficha Cadastral.pdf","sort_order": 3 }
  ],
  "signers": [
    {
      "sign_request_id": "uuid-a",
      "email":           "joao@empresa.com",
      "name":            "João Silva",
      "status":          "signed",
      "signed_at":       "2024-03-01T14:25:00Z",
      "documents_signed": 3,
      "documents_total":  3
    },
    {
      "sign_request_id": "uuid-b",
      "email":           "maria@empresa.com",
      "name":            "Maria Santos",
      "status":          "pending",
      "signed_at":       null,
      "documents_signed": 0,
      "documents_total":  3
    }
  ]
}

Valores de signing_status do envelope

Valor	Descrição
pending	Nenhum signatário assinou todos os documentos ainda
partially_signed	Ao menos um signatário concluiu todos os seus documentos
fully_signed	Todos os signatários concluíram todos os documentos
expired	Prazo do envelope expirado
cancelled	Envelope cancelado manualmente

POST /v1/signatures/:id/cancel sign:cancel

Cancela uma solicitação de assinatura pendente. Não é possível cancelar assinaturas já concluídas.

Path Parameter

Parâmetro	Descrição
id	UUID da solicitação de assinatura (`sign_request_id`)

Request Body

JSON
{
  "reason": "Contrato substituído por versão atualizada"
}

Campo	Tipo	Obrigatório	Descrição
reason	string	—	Motivo do cancelamento (registrado em auditoria)

Response — 200

JSON
{
  "sign_request_id": "uuid-da-solicitacao",
  "status":          "cancelled",
  "reason":          "Contrato substituído por versão atualizada"
}

Erros específicos

Código	HTTP	Descrição
already_signed	409	Signatário já assinou — não é possível cancelar
already_cancelled	409	Já estava cancelada
not_found	404	Solicitação não encontrada neste tenant

POST /v1/signatures/:id/resend sign:send

Reenvia a notificação de assinatura (e-mail e/ou WhatsApp) para uma solicitação pendente. Não cancela nem cria nova solicitação; apenas dispara os lembretes usando o mesmo link.

Path Parameter

Parâmetro	Descrição
id	UUID da solicitação de assinatura (`sign_request_id`)

Response — 200

JSON
{
  "sign_request_id": "uuid-da-solicitacao",
  "status":          "notifications_sent",
  "email_sent":      true,
  "wa_sent":         true
}

ℹ️

As propriedades email_sent e wa_sent indicam quais notificações o backend tentou disparar com base no que havia salvo no momento do envio send original.

Erros específicos

Código	HTTP	Descrição
already_signed	409	Signatário já assinou
already_cancelled	409	Solicitação cancelada
not_found	404	Solicitação não encontrada
notification_failed	500	Falha na comunicação com os webhooks de notificação

POST /v1/certifications certifications:write

Envia um documento em Base64 para certificação de autenticidade. Recomendado para arquivos até ~4.5 MB (payload Base64 equivalente de ~6 MB). Para arquivos maiores, utilize o fluxo de dois passos: /certifications/upload-url + /certifications/certify. O sistema insere no PDF uma página com hashes criptográficos e QR code de verificação.

Request Body

JSON
{
  "document_title": "Contrato de NDA.pdf",
  "description":    "Versão final para homologação",
  "issuer_name":    "Empresa XYZ",
  "file_base64":    "<conteúdo base64 do PDF>",
  "custom_fields": {
    "Contrato nº": "A192B4",
    "Setor":       "Jurídico"
  }
}

Campo	Tipo	Obrigatório	Descrição
document_title	string	✅	Nome do documento
file_base64	string	✅	Conteúdo do PDF em Base64
description	string	—	Descrição do documento
issuer_name	string	—	Sobrescreve o nome do emissor (dono da API Key)
custom_fields	object	—	Campos personalizados exibidos no certificado

Response — 201

JSON
{
  "cert_id":        "CERT-8HJ2MDQ1",
  "document_title": "Contrato de NDA.pdf",
  "original_hash":  "a1b2c3...",
  "certified_hash": "d4e5f6...",
  "download_url":   "https://api.integraid.com.br/... (expira em 1h)",
  "expires_in":     3600
}

POST /v1/certifications/upload-url certifications:write

Passo 1 para certificar arquivos pesados. Gera URL pré-assinada para upload direto ao Storage Provisório.

Response — 200

JSON
{
  "upload_url":   "https://storage.supabase.co/...",
  "storage_path": "uploads/api_...",
  "token":        "eyJ...",
  "next_step":    "POST /v1/certifications/certify"
}

POST /v1/certifications/certify certifications:write

Passo 2: Efetiva a certificação de um documento grande já enviado para o storage.

Request Body

JSON
{
  "storage_path":   "uploads/api_...",
  "document_title": "Relatório Volumétrico.pdf",
  "description":    "Anexo I",
  "validityDate":   "2026-12-31",
  "custom_fields": {
    "Ano": "2024"
  },
  "layoutOption": {
    "mode": "visual",
    "page_number": 1,
    "preset": "bottom-right"
  }
}

Campo	Tipo	Obrigatório	Descrição
storage_path	string	✅	Retornado por `/certifications/upload-url`
document_title	string	✅	Nome do documento
description	string	—	Descrição do documento
validityDate	string	—	Data limite de validade do documento em formato ISO (ex: `2026-12-31`)
custom_fields	object	—	Campos personalizados via JSON
layoutOption	object	—	Configuração visual. Se mode for `"visual"`, use `preset: "bottom-right"` (ou `top-right`, `bottom-left`, `top-left`) e `page_number`. Se ausente, cria uma capa nova.

Response — 201

Mesmo formato do POST /v1/certifications (com os hashes e download_url).

POST /v1/certifications/:id/revoke certifications:write

Revoga a validade de uma certificação existente. Esta ação não apaga o registro, mas inativa o certificado, fazendo com que validações públicas futuras retornem como expiradas/revogadas.

Path Parameter

Parâmetro	Tipo	Descrição
id	string	`cert_id` único da certificação (ex: `CERT-A1B2C3D4`)

Response — 200

JSON
{
  "cert_id": "CERT-A1B2C3D4",
  "status":  "revoked"
}

Erros específicos

Código	HTTP	Descrição
not_found	404	Certificação não encontrada neste tenant.
already_revoked	400	A certificação já encontra-se revogada ou inativa.

GET /v1/certifications certifications:read

Lista documentos certificados. Retorna apenas metadados — guarde o PDF original durante a geração.

GET /v1/certifications/:id certifications:read

Retorna os detalhes de uma certificação específica por ID.

07 Auditor de Vídeo e Variáveis IA

A plataforma Integra ID possui um recurso avançado de Auditor IA (Prova de Vida Narrada), onde o sistema lê as cláusulas críticas para o usuário no momento da assinatura e exige o consentimento verbal ("Sim").

Através do painel da plataforma (Roteiros IA), o administrador pode criar modelos padronizados de roteiros e utilizar variáveis no formato {{nome_variavel}}.

Como preencher variáveis via API

Para que a voz da IA cite os dados específicos do seu cliente (ao invés de ler chaves vazias), basta enviar os valores no campo metadata durante o upload do documento (POST /v1/documents).

💡

Exemplo no roteiro criado no painel:
"Olá {{nome_cliente}}, o valor do seu apartamento é de {{valor_imovel}}, confirma?"

Exemplo de Request via API:

JSON
{
  "filename": "contrato.pdf",
  "file_base64": "...",
  "metadata": {
    "nome_cliente": "João da Silva",
    "valor_imovel": "R$ 350.000,00"
  }
}

O backend da Integra ID (Edge Function de sessão de vídeo) mapeará automaticamente essas chaves do metadata para o roteiro na hora em que o usuário abrir a tela de assinatura, criando uma experiência mágica, fluida e altamente escalável, sem necessidade de configuração manual por documento.

08 Webhooks de saída

Registre uma URL no painel (Configurações → Webhooks) para receber notificações em tempo real.

document.uploaded

Novo documento enviado via API

signature.sent

Link de assinatura enviado a um destinatário

signature.completed

Um signatário concluiu a assinatura

document.completed

Todos os signatários assinaram

signature.cancelled

Solicitação de assinatura cancelada

Formato do payload

JSON
{
  "event":       "signature.completed",
  "tenant_id":   "uuid-do-tenant",
  "occurred_at": "2024-01-15T14:20:00Z",
  "data": {
    "document_id":     "3f7a8b2c-...",
    "document_name":   "contrato-joao.pdf",
    "external_id":     "ERP-00123",
    "sign_request_id": "uuid",
    "signer": {
      "email": "joao@empresa.com",
      "name":  "João Silva"
    },
    "signed_at":     "2024-01-15T14:20:00Z",
    "document_hash": "sha256-do-pdf"
  }
}

Validação HMAC-SHA256

Se você configurou um secret ao cadastrar o webhook, cada requisição inclui os headers de segurança:

HTTP Headers
X-Integra-Signature: sha256=<hmac-hex>
X-Integra-Timestamp: <unix-ms>
X-Integra-Event:     signature.completed
X-Integra-Delivery:  <uuid-da-entrega>

Algoritmo de validação — Python

Python
import hmac, hashlib

def verify_signature(secret, timestamp, body, signature_header):
    message    = f"{timestamp}.{body}"
    expected   = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Algoritmo de validação — JavaScript

JavaScript
async function verifySignature(secret, timestamp, body, signatureHeader) {
  const encoder = new TextEncoder()
  const key = await crypto.subtle.importKey(
    'raw', encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
  )
  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(`${timestamp}.${body}`))
  const hex = Array.from(new Uint8Array(sig)).map(b => b.toString(16).padStart(2, '0')).join('')
  return signatureHeader === `sha256=${hex}`
}

Comportamento de entrega

Propriedade	Valor
Timeout	10 segundos por tentativa
Política	Best-effort (sem reenvio automático)
Resposta esperada	Qualquer HTTP 2xx confirma o recebimento
Log	Painel → Configurações → Webhooks → Log

09 Códigos de erro

HTTP Status Codes

Status	Significado
200	Sucesso
201	Criado com sucesso
401	Não autenticado (API Key inválida, expirada ou revogada)
403	Sem permissão (escopo insuficiente)
404	Recurso não encontrado
409	Conflito (duplicata, já assinado, já cancelado)
422	Payload inválido (campo obrigatório ausente ou malformado)
429	Rate limit excedido
500	Erro interno do servidor

Códigos internos (error.code)

Código	Descrição
missing_api_key	Header X-Api-Key não enviado
invalid_api_key	Chave com formato inválido ou não encontrada
revoked_api_key	Chave foi revogada
expired_api_key	Chave expirou
insufficient_scope	Escopo necessário não está na chave
rate_limit_exceeded	Limite de requisições excedido
idempotency_key_conflict	Idempotency-Key usada com payload diferente
invalid_payload	Campo obrigatório ausente ou inválido
document_not_found	Documento não existe ou pertence a outro tenant
duplicate_external_id	external_id já cadastrado
not_found	Recurso não encontrado
already_signed	Tentativa de cancelar assinatura já concluída
already_cancelled	Tentativa de cancelar o que já está cancelado
not_signed	Download solicitado antes de qualquer assinatura
pdf_not_ready	PDF assinado ainda sendo gerado
storage_error	Erro no Supabase Storage
database_error	Erro interno de banco de dados
notification_failed	Falha na comunicação com webhooks de notificação

10 Exemplos

Upload + Envio para assinatura

cURL
# 1. Upload do documento
curl -X POST https://api.integraid.com.br/functions/v1/public-api/v1/documents \
  -H "X-Api-Key: iid_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filename":        "contrato-2024-001.pdf",
    "file_base64":     "'$(base64 -i contrato.pdf)'",
    "document_type":   "contract",
    "external_id":     "ERP-2024-001",
    "external_source": "totvs"
  }'

# Resposta: { "document_id": "3f7a8b2c-...", ... }

# 2. Enviar para assinatura
curl -X POST https://api.integraid.com.br/functions/v1/public-api/v1/signatures/send \
  -H "X-Api-Key: iid_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "3f7a8b2c-...",
    "recipients": [
      {
        "name":  "João Silva",
        "email": "joao@empresa.com",
        "auth_methods": ["email"]
      }
    ]
  }'

# 3. Consultar status
curl https://api.integraid.com.br/functions/v1/public-api/v1/documents/3f7a8b2c-... \
  -H "X-Api-Key: iid_live_a1b2c3d4..."

# 4. Download após assinatura
curl https://api.integraid.com.br/functions/v1/public-api/v1/documents/3f7a8b2c-.../download \
  -H "X-Api-Key: iid_live_a1b2c3d4..."

Upload em dois passos (arquivo grande)

cURL
# Passo 1: Solicitar URL pré-assinada
RESPONSE=$(curl -s -X POST https://api.integraid.com.br/functions/v1/public-api/v1/documents/upload-url \
  -H "X-Api-Key: iid_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename":      "relatorio-grande.pdf",
    "document_type": "document",
    "external_id":   "REL-2024-050"
  }')

UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload_url')
STORAGE_PATH=$(echo $RESPONSE | jq -r '.storage_path')

# Passo 2: Upload direto para o storage
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @relatorio-grande.pdf

# Passo 3: Registrar no banco
curl -X POST https://api.integraid.com.br/functions/v1/public-api/v1/documents/complete-upload \
  -H "X-Api-Key: iid_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d "{
    \"storage_path\":    \"$STORAGE_PATH\",
    \"filename\":        \"relatorio-grande.pdf\",
    \"document_type\":   \"document\",
    \"external_id\":     \"REL-2024-050\",
    \"external_source\": \"sistema-bi\"
  }"

Listar documentos pendentes

cURL
curl "https://api.integraid.com.br/functions/v1/public-api/v1/documents?status=pending&per_page=50" \
  -H "X-Api-Key: iid_live_a1b2c3d4..."

Cancelar assinatura

cURL
curl -X POST https://api.integraid.com.br/functions/v1/public-api/v1/signatures/uuid-da-solicitacao/cancel \
  -H "X-Api-Key: iid_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Erro no documento original" }'

Reenviar link de aviso

cURL
curl -X POST https://api.integraid.com.br/functions/v1/public-api/v1/signatures/uuid-da-solicitacao/resend \
  -H "X-Api-Key: iid_live_a1b2c3d4..."

Documentação da APIIntegra ID

01 Autenticação

02 Formato de resposta

03 Escopos

04 Rate Limiting

05 Idempotência

06 Endpoints

07+ Envelopes

07 Auditor de Vídeo e Variáveis IA

08 Webhooks de saída

09 Códigos de erro

10 Exemplos

Documentação da API
Integra ID