Referência da API

Cria um documento a partir de um PDF, com signatários e campos posicionados. O documento nasce em RASCUNHO e não dispara nada: enviar é uma operação separada e explícita, porque disparar por efeito colateral de uma criação é como se envia contrato errado para cliente.

O corpo é multipart/form-data. O arquivo é limitado a 20 MB e apenas application/pdf; o tipo real é conferido pelo conteúdo, e não pela extensão nem pelo cabeçalho declarado. Os demais campos seguem DocumentoEntrada.

{
  "titulo": "Contrato de prestação de serviços",
  "descricao": "Vigência de 12 meses, renovação automática.",
  "nivelAssinatura": "SEGURA",
  "fatoresExigidos": ["EMAIL", "SMS_OTP"],
  "ordenado": true,
  "recusavel": true,
  "pararSeRecusado": true,
  "lembrete": "SEMANAL",
  "prazoEm": "2026-09-15T23:59:59-03:00",
  "expiraEm": "2026-09-30T23:59:59-03:00",
  "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,
      "obrigatorio": true
    }
  ]
}

Lista os documentos da organização, do mais recente para o mais antigo, paginada por cursor.

Parâmetros de consulta

A listagem devolve DocumentoResumo, sem campos nem auditoria. Para o objeto inteiro, use a leitura individual.

O Documento completo, com signatários, campos e o estado de cada assinatura.

Documento de outra organização responde 404, e não 403.

Altera o que o estado atual permite. Em RASCUNHO, quase tudo. Depois de enviado, o conteúdo já foi apresentado a alguém e mudá-lo destruiria a prova: a tentativa devolve 409 com o código DOCUMENTO_IMUTAVEL.

Exclusão lógica com carência. O documento sai das listagens e o arquivo continua guardado até a política de retenção alcançá-lo. Documento concluído é prova documental e não sai por esta rota.

Exigir ADMINISTRADOR aqui, e apenas OPERADOR para criar e enviar, é deliberado: quem opera o dia a dia não apaga acervo.

Tira o documento do rascunho e dispara os convites conforme a ordem configurada. É esta chamada que consome um envelope da franquia do plano. Só funciona a partir de RASCUNHO.

Emite o evento document.sent. Franquia esgotada devolve FRANQUIA_ESGOTADA.

Reenvia o convite a quem ainda não assinou. Não consome envelope novo e não altera o prazo.

Interrompe o processo. Os links dos signatários deixam de funcionar na hora, quem já assinou continua registrado na auditoria, e o motivo entra na trilha. Não tem volta: para retomar, crie um documento novo.

Emite o evento document.cancelled.

Move o documento para outra pasta da mesma organização. pastaId: null devolve à raiz.

Lista as versões do arquivo do documento. Substituir o PDF não apaga o anterior; cria uma versão.

Sobe uma versão nova do arquivo, em multipart/form-data. A anterior permanece registrada e verificável.

Baixa o arquivo do documento. O parâmetro de consulta tipo aceita ORIGINAL, ASSINADO, PADES e CERTIFICADO, com ASSINADO como padrão.

GET /v1/documentos/6f2a1c94-8b3d-4e57-9a20-71c5f0d3ab48/arquivo?tipo=ASSINADO

A API resolve o objeto dentro do escopo da organização, verifica o direito e só então delega a entrega ao servidor web por X-Accel-Redirect, apontando para um caminho marcado como interno. Não existe caminho público previsível para o arquivo, e o diretório nunca é servido como estático.

A trilha de auditoria completa, em ordem cronológica, como uma página de EventoAuditoria. É o mesmo conteúdo que vai para o certificado, em JSON. A trilha é imutável: não há rota que altere ou apague evento.

Note que o escopo é auditoria:ler, e não documentos:ler: uma chave pode ler documentos sem ler a trilha deles.

O certificado de conclusão e as evidências, que é a peça central do produto: o que prova quem assinou, quando, de onde e depois de passar por qual autenticação. Veja Certificado.

{
  "id": "b81d4f9c-2a06-4e13-88f5-3c7e9012ab64",
  "codigo": "ADX-CERT-9F2K4M7Q1B",
  "versao": 1,
  "nivelAssinatura": "SEGURA",
  "hashDocumento": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "hashConteudo": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "hashAnterior": null,
  "hash": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
  "emitidoEm": "2026-08-18T16:04:11-03:00",
  "arquivoUrl": "/v1/documentos/6f2a1c94-8b3d-4e57-9a20-71c5f0d3ab48/arquivo?tipo=CERTIFICADO",
  "qrConteudo": "https://adigitalmax.com.br/validar?codigo=ADM-7K4Q-2M9X-B3TD"
}

Antes de o documento chegar a ASSINADO o certificado não existe, e a rota responde com o código CERTIFICADO_INDISPONIVEL. Certificado parcial seria uma prova de algo que ainda não aconteceu.

Signatários do documento, com estado, marcos e fatores exigidos de cada um.

Acrescenta um signatário. O corpo é um SignatarioEntrada. Quando o método de entrega é LINK, a resposta traz a URL pessoal de assinatura e a entrega passa a ser sua.

Detalhe do signatário, incluindo fatores exigidos, fatores cumpridos e os marcos de cada passo.

Corrige dados de quem ainda não assinou. É a rota para o caso mais comum de todos, o e-mail digitado errado: corrigir e reenviar resolve sem cancelar o documento nem consumir envelope novo. Signatário que já assinou é imutável.

Remove signatário pendente e invalida o link dele na hora. Os campos que eram dele saem junto.

Todos os campos do documento, com página, coordenada relativa e o signatário dono de cada um.

Substitui em lote o mapa inteiro de campos. É PUT, e não PATCH, de propósito: posicionamento de campo é um desenho, e desenho se troca inteiro. O que não vier no corpo deixa de existir.

Lista os envelopes da organização, paginada por cursor.

Cria o envelope. Os documentos entram nele pelo campo envelopeId de DocumentoEntrada, na criação de cada um.

Dispara o envelope inteiro em um ato. Consome um envelope da franquia, independentemente de quantos documentos estejam dentro.

Pastas da organização com a contagem de documentos de cada uma.

Cria pasta. O corpo é { "nome": "Contratos 2026", "paiId": null }.

Detalhe da pasta. Para o conteúdo, use GET /documentos?pastaId=.

Renomeia ou move a pasta. Mover para dentro da própria descendência é recusado.

Remove pasta vazia. Nunca apaga documento em cascata: pasta com conteúdo é recusada, com a contagem do que há dentro.

Modelos de documento visíveis à credencial: os pessoais de quem criou e os publicados na organização.

Cria um modelo a partir de um PDF, em multipart/form-data. O modelo define papéis de signatário, e não pessoas: quem preenche cada papel é decidido ao instanciar.

Detalhe do modelo, com papéis, campos e a lista de variáveis que ele aceita.

Edita o modelo. Documentos já gerados a partir dele não mudam.

Remove o modelo. Documentos gerados a partir dele continuam íntegros e verificáveis.

Instancia um documento a partir do modelo. Sem upload de arquivo, sem posicionar campo de novo: você manda as variáveis e quem preenche cada papel. É a rota que transforma envio em uma chamada de JSON puro, e a mais usada em integração de volume.

Como toda criação, o documento nasce em RASCUNHO; o disparo continua sendo uma chamada separada.

A única operação do produto totalmente sem autenticação, junto com o formulário de contato do site. Ela existe porque quem valida costuma ser exatamente quem não é cliente de ninguém: a contraparte, o cartório, o banco, o juiz.

Corpo, ao menos um dos três

curl --request POST "https://adigitalmax.com.br/api/v1/validacao/consultar" \
  --header "Content-Type: application/json" \
  --data '{"codigo":"ADM-7K4Q-2M9X-B3TD"}'

Os três desfechos, que são diferentes e não podem ser confundidos

A resposta é sempre 200, inclusive em NAO_ENCONTRADO: o desfecho vai no corpo, e não no status, para que o status não vire oráculo de existência consultável sem ler a resposta. A latência é uniforme entre os três desfechos pela mesma razão. O e-mail dos signatários vem mascarado pelo servidor; o mascaramento no navegador é segunda linha, nunca a primeira. Não há busca por título, por nome nem por data: seria transformar a página pública em ferramenta de raspagem.

Abre a sessão de assinatura: o documento, os campos daquele signatário e os fatores que ele ainda precisa cumprir. Registra a visualização na trilha e dispara document.viewed.

Relata até que ponto o signatário percorreu o documento, com paginasLidas e segundos. Quando as páginas lidas alcançam o total, o servidor grava a conclusão da leitura na trilha e passa a permitir o aceite.

A operação existe porque a exigência de "ler o documento inteiro antes de assinar" vivia apenas no navegador, e regra que existe só na interface não existe: uma chamada direta à API pulava a leitura sem deixar rastro. Com ela, a trava passa a ser do servidor.

Registra que o signatário leu e concordou com um texto específico, em uma versão específica, identificado por textoAceiteId ou textoHash. Grava o aceite na trilha com IP, navegador e horário.

É uma operação própria, e não um booleano dentro do assinar, por três razões. Um booleano não prova que alguém concordou com um texto: ele afirma que um campo veio marcado, e dois anos depois a pergunta em disputa nunca é se a pessoa clicou, e sim com o quê ela concordou, exatamente. Aceitar e assinar são atos distintos, e a distância entre eles às vezes é o que se discute. E quem concordava e abandonava não deixava registro nenhum, porque a linha de assinatura nunca chegava a ser criada, descartando um fato relevante em negociação interrompida.

Dispara o código de uso único pelo canal exigido. Cada disparo consome a medição correspondente, e é por isso que o reenvio de código aparece na fatura.

Cumpre um fator: valida o código de OTP, o código do aplicativo autenticador ou os dados pessoais. Quando o último fator exigido é cumprido, dispara signer.authenticated.

Consuma a assinatura com os valores dos campos, registrando IP, agente, horário e localização aproximada. Recusa com AUTENTICACAO_INCOMPLETA se algum fator exigido não foi cumprido.

Recusa com motivo, aplicando pararSeRecusado quando configurado. Dispara document.refused.

Permite ao signatário baixar o documento que está assinando, e a cópia assinada depois da conclusão.

Registra o contato do formulário do site institucional. Junto com a validação pública, é uma das duas únicas operações anônimas do sistema, e mora no host institucional pelo mesmo motivo: manter a chamada de mesma origem, sem CORS e sem afrouxar a política de segurança de conteúdo do site.

Não existe versão em api.adigitalmax.com.br, e a ausência é deliberada: formulário de contato não tem caso de uso servidor a servidor, e uma segunda cópia significaria manter dois conjuntos de defesa anti-robô em sincronia, sendo que o que sai de sincronia vira a porta que o robô usa. Esta rota não interessa à sua integração; está listada para completude do contrato.

A organização dona da credencial, com dados cadastrais, plano e a marca aplicada aos e-mails de convite e à página de assinatura.

Altera dados cadastrais e a marca: cor primária, logotipo, nome do remetente, endereço de resposta e mensagem padrão.

Membros da organização com papel, estado e último acesso.

Convida alguém para a organização. O convite é amarrado ao e-mail e de uso único. Não é possível convidar como PROPRIETARIO: a propriedade se transfere, não se concede.

Troca o papel ou o estado do membro. Não permite remover o último proprietário.

Remove o membro e invalida as sessões dele na organização. Remover precisa cortar o acesso agora, e não no vencimento do token.

Chaves da organização, com prefixo, escopos, último uso e último IP. Nunca devolve o segredo.

Cria a chave com os escopos escolhidos. O valor completo, adx_live_<prefixo>.<segredo>, aparece uma única vez, nesta resposta. A plataforma guarda apenas o hash do segredo.

Revoga a chave imediatamente, sem carência. Requisições com ela passam a responder CREDENCIAL_INVALIDA.

Webhooks cadastrados, com URL, eventos assinados, estado e resultado da última entrega.

Cadastra um endpoint. O segredo de assinatura HMAC é devolvido uma única vez, nesta resposta, e não se repete em nenhuma outra.

A URL é validada a cada entrega, e não só no cadastro: IP privado, loopback, link-local, endereço de metadados de nuvem e redirecionamento para faixa interna são recusados. Validar só no cadastro não basta, porque o DNS pode mudar depois.

O formato do envio e a validação da assinatura estão em Webhooks.

Edita URL, eventos ou estado.

Remove a assinatura de eventos.

Histórico de entregas com evento, estado, número de tentativas, código de resposta do seu servidor e o erro, quando houve.

A medição do período vigente, por tipo, com franquia e excedente. É como você prevê custo sem esperar a fatura. Veja Consumo e o detalhamento em Limites e consumo.

O consumo linha a linha, em vez de agregado por tipo. É o que permite atribuir custo a um cliente seu, e não só ao período.

Plano vigente, franquias e estado de pagamento.

Faturas emitidas, com itens e links de pagamento. Faturamento é do proprietário: o administrador não alcança por padrão.

As políticas de retenção vigentes da organização, por categoria de documento.

Define os prazos por categoria. Exige papel de proprietário porque expurgo é irreversível e alcança prova documental.

Veja o estado da política em Limites. >>> PENDENTE DE BACKEND <<<

Solicitações de titular de dados abertas na organização, com estado e prazo legal.

Abre uma solicitação de titular: acesso, correção, exportação ou exclusão. O tratamento tem carência e confirmação, e nunca apaga documento sob obrigação legal de guarda.

Toda operação com efeito colateral autenticada por cookie exige o cabeçalho X-CSRF-Token, cujo valor acompanha a criação da sessão. Cookie sozinho é vulnerável a requisição forjada entre sites, e SameSite=Lax reduz o problema sem eliminá-lo. Este grupo tem limite próprio de 10 requisições por minuto por IP.

O que vai na parte de dados de POST /documentos. Obrigatório: titulo.

Os campos de SignatarioEntrada, mais os somente-leitura: id, status (StatusSignatario), link (presente quando metodoEntrega é LINK), enviadoEm, visualizadoEm, assinadoEm, motivoRecusa e fatoresCumpridos.

id, titulo, status, criadoEm, enviadoEm e a lista de documentos que ele contém. O envelope é a unidade de medição de ENVELOPE_ENVIADO.

id, nome, paiId (null na raiz), quantidadeDocumentos e criadaEm.

id, nome, descricao, escopo, paginas, vezesUsado, variaveis (nomes declarados no PDF), papeis (cada um com id, rotulo, funcao, ordem e fatoresExigidos) e campos.

id, acao, tipoAtor, ator, ocorridoEm, ip, porta, agenteUsuario, detalhe, hash do elo na cadeia, e geolocalizacao com país, estado, cidade, latitude, longitude e precisão. A geolocalização é aproximada por IP e a precisão vem declarada; não é GPS e não deve ser apresentada como se fosse.

id, codigo (formato ADX-CERT-XXXXXXXXXX), versao, nivelAssinatura, hashDocumento, hashConteudo (SHA-256 do pacote de evidências), hashAnterior, hash, emitidoEm, arquivoUrl, qrConteudo e conteudo.

O conteudo é o pacote de evidências congelado: dados do documento, hashes, e para cada signatário o identificador da transação, nome, contato usado, fatores exigidos e usados, datas de cada passo, IP e dados técnicos, mais a sequência integral de eventos com o hash de cada elo.

resultado (AUTENTICO, ADULTERADO ou NAO_ENCONTRADO), codigo, hashRecebido, documento (nome, páginas, criadoEm, finalizadoEm, algoritmoHash, hashArquivo e nivelAssinatura), signatarios (nome, emailMascarado, papel, status, assinadoEm, ip e uma descrição legível dos fatores usados) e manifesto (versão, emitidoEm e codigoCertificado).

id, url, eventos, ativo, descricao, criadoEm, ultimaEntregaEm e ultimaEntregaStatus. O campo segredo aparece apenas na resposta da criação.

id, eventoId, webhookId, evento, status, tentativas, ocorridaEm, proximaTentativaEm, respostaHttp, duracaoMs e erro. O eventoId é a chave de idempotência do seu lado.

periodo com inicio e fim, e medicoes, uma lista de Medicao com tipo (TipoMedicao), quantidade, franquia, excedente e valorExcedenteCentavos.

itens (array), total (integer, sob o mesmo escopo dos itens) e proximoCursor (string ou null, ausente na última página).

Erro no formato RFC 9457 (problem details), com um campo codigo estável para o cliente ramificar sem depender do texto.

{
  "type": "https://docs.adigitalmax.com.br/erros.html#nao_encontrado",
  "title": "Recurso não encontrado",
  "status": 404,
  "detail": "Recurso não encontrado.",
  "instance": "/v1/documentos/6f2a1c94-8b3d-4e57-9a20-71c5f0d3ab48",
  "codigo": "NAO_ENCONTRADO",
  "requestId": "01J9M4X7QK2ZB8N3P6R0T5V2WY"
}

Em erro de validação há também erros, um arranjo de objetos com campo e mensagem. A mensagem nunca revela nome de tabela, consulta, rastro de pilha nem a razão exata de uma negação entre organizações; o detalhe completo vai para o log interno, ligado ao requestId. O catálogo completo está em Erros.

• ASSINAR
• APROVAR
• RECONHECER
• TESTEMUNHAR
• ACUSAR_RECEBIMENTO
• ENDOSSAR

A equivalência com SIGN, APPROVE, RECOGNIZE, SIGN_AS_A_WITNESS, ACKNOWLEDGE e ENDORSE do Autentique está em Migração.

• PENDENTE
• ENVIADO
• VISUALIZADO
• ASSINADO
• RECUSADO
• CANCELADO
• FALHA_ENTREGA

FALHA_ENTREGA significa que o e-mail voltou ou o SMS não foi aceito. Trate como acionável: quase sempre é endereço errado, e a correção é corrigir e reenviar.

• EMAIL
• LINK
• WHATSAPP
• SMS

LINK não envia nada: devolve a URL no campo link do signatário e a entrega passa a ser sua. É o método certo quando o seu produto já tem um canal com o cliente.

• ASSINATURA
• RUBRICA
• NOME
• DATA
• CPF
• CNPJ
• EMAIL
• TEXTO
• CHECKBOX
• IMAGEM

• organizacao:ler
• organizacao:escrever
• documentos:ler
• documentos:escrever
• signatarios:ler
• signatarios:escrever
• pastas:ler
• pastas:escrever
• modelos:ler
• modelos:escrever
• arquivos:ler
• auditoria:ler
• webhooks:gerenciar
• consumo:ler

O que cada um concede está em Autenticação. Os mesmos nomes valem como escopos de OAuth 2.0.

São os únicos valores minúsculos do contrato, no formato recurso.acao, por serem contrato público já definido. O formato do envio e a validação da assinatura estão em Webhooks.

• ENVELOPE_ENVIADO
• DOCUMENTO_ENVIADO
• ASSINATURA_COLETADA
• REQUISICAO_API
• EMAIL_ENVIADO
• SMS_ENVIADO
• WHATSAPP_ENVIADO
• VERIFICACAO_BIOMETRICA
• CARIMBO_TEMPO
• ARMAZENAMENTO_MB_DIA

O que dispara cada contador está em Limites e consumo.

Os dezesseis valores estáveis do campo codigo. É por eles que o seu cliente ramifica, e não pelo texto nem pelo status.

• NAO_AUTENTICADO
• CREDENCIAL_INVALIDA
• MFA_OBRIGATORIO
• SENHA_FRACA
• TOKEN_INVALIDO
• ESCOPO_INSUFICIENTE
• PAPEL_INSUFICIENTE
• NAO_ENCONTRADO
• ENTRADA_INVALIDA
• DOCUMENTO_IMUTAVEL
• CERTIFICADO_INDISPONIVEL
• AUTENTICACAO_INCOMPLETA
• LINK_INDISPONIVEL
• FRANQUIA_ESGOTADA
• LIMITE_EXCEDIDO
• CONFLITO

O que fazer em cada um está em Erros.