Vindo do Autentique

Se a sua integração já fala com o Autentique v2, o modelo de domínio que você construiu continua valendo inteiro: documento, signatários, ordem, prazo, lembrete, pastas, arquivos e eventos são os mesmos conceitos, com os mesmos comportamentos. O que muda é a forma de chamar. Esta página é a tabela de tradução, campo por campo, com franqueza sobre o que ainda não temos.

A diferença de fundo: GraphQL contra REST

O Autentique expõe um endpoint único, POST /v2/graphql, e você descreve na consulta quais campos quer de volta. Aqui, cada recurso tem a sua rota, o verbo HTTP diz a intenção e a resposta traz o objeto inteiro. Isso tem três consequências práticas na migração, e nenhuma delas é grande:

Você para de escolher os campos. Onde havia uma query pedindo id name status signatures { email signed }, passa a haver um GET /v1/documentos/{documentoId} que devolve tudo. A resposta é maior e você descarta o que não usa, o que em rede de servidor não é problema mensurável.

Você para de tratar erro em corpo de sucesso. Em GraphQL, uma operação que falha ainda responde 200 com um arranjo errors; aqui o status HTTP é a verdade. O tratamento fica mais simples e o seu cliente HTTP passa a ser útil de novo.

Você ganha idempotência de verdade. O cabeçalho Idempotency-Key não tem equivalente no endpoint único, e é ele que impede um timeout de rede de virar contrato duplicado. Veja Idempotência.

O upload de arquivo, que no Autentique usa a especificação de multipart request do GraphQL com as partes operations, map e file, aqui é um multipart/form-data comum, com as partes dados e arquivo. Na prática, o seu código de upload fica mais curto.

Mutations

Estas operações não existem no Autentique e passam a existir para você:

Queries

Campos do documento

Sobre qualified: no Autentique ele é um booleano que liga a assinatura qualificada. Aqui a mesma decisão virou uma escala, porque entre "clicou no link" e "certificado ICP-Brasil" existem dois degraus que a maioria dos contratos realmente usa. A tradução direta é qualified: true para nivelAssinatura: "ICP_BRASIL" e qualified: false para nivelAssinatura: "ELETRONICA"; mas se os seus signatários já recebem código por SMS hoje, o equivalente honesto é SEGURA. A tabela dos quatro está na visão geral.

Campos do signatário

Ações do signatário e método de entrega

Os seis papéis são exatamente os mesmos, com o mesmo significado. Só o nome muda:

// traduzir.mjs
// Converte um payload no formato do Autentique para o nosso. Serve para
// migrar sem reescrever de uma vez o codigo que monta o documento: voce
// mantem a sua estrutura atual e traduz na borda.
//
// O que ele NAO faz: converter positions. Nao ha formula publicada para
// isso, e chutar produziria campo no lugar errado em contrato real.

const ACAO = {
  SIGN: "ASSINAR",
  APPROVE: "APROVAR",
  RECOGNIZE: "RECONHECER",
  ACKNOWLEDGE: "ACUSAR_RECEBIMENTO",
  ENDORSE: "ENDOSSAR",
  SIGN_AS_A_WITNESS: "TESTEMUNHAR",
};

const ENTREGA = {
  DELIVERY_METHOD_EMAIL: "EMAIL",
  DELIVERY_METHOD_LINK: "LINK",
  DELIVERY_METHOD_WHATSAPP: "WHATSAPP",
  DELIVERY_METHOD_SMS: "SMS",
};

const LEMBRETE = { DAILY: "DIARIO", WEEKLY: "SEMANAL" };

export function traduzirDocumento(document, signers, opcoes = {}) {
  const dados = {
    nome: document.name,
    ordenado: document.sortable ?? false,
    recusavel: document.refusable ?? true,
    pararSeRecusado: document.stop_on_rejected ?? true,
    lembrete: LEMBRETE[document.reminder], // omitir desliga o lembrete
    // Os dois prazos continuam separados, como no Autentique.
    prazoEm: document.deadline_at ?? undefined,
    expiraEm: document.expiration_at ?? undefined,
    modeloEmailId: document.email_template_id ?? undefined,
    responderPara: document.reply_to ?? undefined,
    pastaId: opcoes.pastaId ?? undefined,
    // qualified era booleano; aqui e uma escala de quatro degraus.
    // ELETRONICA e o equivalente literal de qualified: false, mas
    // confira se o seu fluxo real nao e SEGURA.
    nivelAssinatura: document.qualified ? "ICP_BRASIL" : "ELETRONICA",
    // Dois valores aqui = dois fatores simultaneos.
    fatoresExigidos: opcoes.fatoresExigidos ?? ["EMAIL"],

    signatarios: signers.map((s, indice) => ({
      nome: s.name,
      email: s.email,
      telefone: s.phone ?? undefined,
      cpf: s.cpf ?? undefined,
      dataNascimento: s.birthday ?? undefined,
      funcao: ACAO[s.action] ?? "ASSINAR",
      metodoEntrega: ENTREGA[s.delivery_method] ?? "EMAIL",
      travarDados: s.lock_user_data ?? false,
      // No Autentique a ordem vem da posicao no arranjo. Aqui e explicita.
      ordem: indice + 1,
    })),

    // s.positions NAO e convertido: reposicione uma vez no sandbox.
    // Os campos ficam no NIVEL DO DOCUMENTO e apontam o dono por
    // signatarioId, que so existe depois de criar o rascunho.
    campos: [],
  };

  // Campos que saem do documento e viram configuracao da organizacao.
  const avisos = [];
  if (document.footer) avisos.push("footer agora e a marca da organizacao");
  if (document.lifecycle_in) avisos.push("lifecycle_in agora e /v1/lgpd/politicas-retencao");
  if (document.locale) avisos.push("locale nao existe: a interface de assinatura e em portugues");
  if (document.sandbox !== undefined) avisos.push("sandbox agora e a URL base mais o prefixo da chave");

  return { dados, avisos };
}

Arquivos

A diferença de comportamento que importa: no Autentique, files traz URLs dentro da resposta da query. Aqui, a URL é pedida no momento do download, vale 15 minutos e é de uso único. Isso significa que você não pode guardar a URL em banco nem colocá-la em um href de página cacheada; em compensação, pode entregá-la ao navegador do seu usuário sem entregar a sua chave de API.

Webhooks

O Autentique publica dezessete eventos; nós publicamos nove. Não é redução de funcionalidade: é agrupamento. Os quatro eventos de biometria deles, por exemplo, viram informação dentro de signer.authenticated, no campo fatores_confirmados.

A validação da assinatura do webhook é diferente e você vai escrever código novo para isso; ele está pronto, em quatro linguagens, em Webhooks.

O que não existe, de um lado e do outro

Esta seção existe para você não descobrir uma lacuna no meio da migração. Ela é a parte desta página que mais nos custa escrever e a que mais lhe serve.

O que o Autentique tem e nós não temos

O que nós temos e o Autentique não expõe

Lado a lado: o mesmo envio nas duas APIs

# Autentique v2: endpoint unico, multipart request do GraphQL.
# As partes operations, map e file precisam ser montadas na mao.

mutation CriarDocumento($document: DocumentInput!, $signers: [SignerInput!]!, $file: Upload!) {
  createDocument(document: $document, signers: $signers, file: $file) {
    id
    name
    refusable
    sortable
    created_at
    signatures {
      public_id
      name
      email
      created_at
      action { name }
      link { short_link }
      user { id name email }
    }
  }
}

# variables:
# {
#   "document": {
#     "name": "Contrato de prestacao de servicos",
#     "sortable": true,
#     "refusable": true,
#     "stop_on_rejected": true,
#     "reminder": "WEEKLY",
#     "deadline_at": "2026-09-30",
#     "qualified": false
#   },
#   "signers": [
#     { "email": "maria@exemplo.com.br", "action": "SIGN",
#       "delivery_method": "DELIVERY_METHOD_EMAIL" }
#   ],
#   "file": null
# }

# AdigitalMAX: multipart/form-data comum, duas partes.
# A resposta ja traz o documento inteiro; nao ha campos a declarar.

curl --fail-with-body --silent --show-error \
  --request POST "https://api.adigitalmax.com.br/v1/documentos" \
  --header "Authorization: Bearer $ADM_CHAVE" \
  --header "Idempotency-Key: pedido-88231" \
  --form 'dados={
    "titulo": "Contrato de prestacao de servicos",
    "ordenado": true,
    "recusavel": true,
    "pararSeRecusado": true,
    "lembrete": "SEMANAL",
    "prazoEm": "2026-09-15T23:59:59-03:00",
    "expiraEm": "2026-09-30T23:59:59-03:00",
    "nivelAssinatura": "SEGURA",
    "fatoresExigidos": ["EMAIL", "SMS_OTP"],
    "signatarios": [
      {
        "nome": "Maria Oliveira",
        "email": "maria@exemplo.com.br",
        "telefone": "+5511988887777",
        "funcao": "ASSINAR",
        "metodoEntrega": "EMAIL",
        "ordem": 1
      }
    ],
    "campos": [
      { "tipo": "ASSINATURA", "pagina": 7, "x": 0.10, "y": 0.72, "largura": 0.34, "altura": 0.07 }
    ]
  };type=application/json' \
  --form "arquivo=@./contrato.pdf;type=application/pdf"

Roteiro de migração

Este roteiro assume que você não pode parar de enviar documentos durante a troca, que é o caso normal. Ele leva a integração dos dois lados no ar ao mesmo tempo, e o corte acontece quando você decidir, não quando o código exigir.

1. Isole o cliente atual atrás de uma interface

   Se o seu código chama a API do Autentique espalhado por vários lugares, este é o primeiro trabalho e ele vale mesmo que você não migre. Uma interface com quatro ou cinco métodos, algo como enviarParaAssinatura, consultarEstado, baixarAssinado e cancelar, com uma implementação por plataforma. Nada mais do seu sistema precisa saber qual das duas está em uso.

2. Escreva a segunda implementação contra o sandbox

   Use o tradutor pronto para converter o seu payload existente e reduzir o trabalho ao mínimo. Duas coisas exigem código novo de verdade, e não tradução: a paginação por cursor e o posicionamento de campos. Reserve tempo para as duas.

3. Reposicione os campos, uma vez, olhando o PDF

   Não converta coordenadas no escuro. Envie um documento de teste para assina@teste.adigitalmax.com.br, baixe o PDF assinado e olhe. Cinco minutos aqui evitam um contrato com a assinatura em cima de uma cláusula.

4. Monte o receptor de webhook novo, em paralelo

   Um endpoint separado, com o segredo novo e a validação HMAC. Não tente adaptar o receptor existente: os formatos e os nomes de evento são diferentes, e dois receptores independentes são mais simples de operar do que um com dois modos.

5. Exerça os doze casos de aceitação

   A lista está em Sandbox. Os quatro primeiros são o caminho feliz; os oito seguintes são os que geram chamado depois. Recusa, expiração e falha de entrega são os que mais costumam faltar.

6. Corte por fatia, e não de uma vez

   Uma chave de configuração escolhe a plataforma por tipo de documento ou por cliente. Comece pelo tipo de menor risco, deixe rodar uma semana, e vá subindo. Documento já enviado pelo Autentique continua lá até ser concluído; não há como movê-lo, e não precisa haver.

7. Antes de desligar, baixe o acervo antigo

   Este é o passo que não tem volta. Percorra documents no Autentique e baixe, de cada documento concluído, o PDF assinado, o PAdES quando houver e o que a plataforma oferecer de relatório de auditoria. Guarde no seu armazenamento, com o identificador original. Depois de encerrar a conta, isso deixa de estar disponível, e um contrato de doze anos precisa da prova por doze anos.

8. Mantenha as duas implementações por um trimestre

   Custa pouco, já que ambas ficam atrás da mesma interface, e transforma um problema inesperado em uma linha de configuração em vez de um plantão.

Sobre uma fachada GraphQL

Uma fachada GraphQL compatível com a forma do Autentique v2 está prevista, com um objetivo declarado: permitir que quem já integrou com eles reaproveite as consultas praticamente como estão, mudando endpoint e credencial.

Não temos data e não vamos estimar uma. Ela depende de a API REST estar estável em produção primeiro, porque uma fachada sobre um contrato que ainda muda seria duas superfícies instáveis em vez de uma. Se a sua decisão de migrar depende dessa fachada, fale conosco antes de planejar prazo, em vez de contar com ela.

Enquanto isso, a recomendação honesta é migrar para REST. O trabalho é menor do que parece, porque o modelo de domínio é o mesmo e só a chamada muda, e você não fica esperando por algo sem data. As duas coisas que exigem código novo de verdade, paginação e posicionamento, teriam que ser feitas de qualquer forma: uma fachada de compatibilidade não reproduz o que ela não tem por baixo.