Documentos, Envelopes e Signatários

Referência detalhada dos endpoints do XSigner. Para o fluxo completo, veja o Guia de Integração.

Todas as rotas exigem os headers Authorization: Bearer <token> e X-XJUR-SUBSCRIPTION-KEY.

Enviar documento

POST /xsigner/documentos
Content-Type: multipart/form-data

Faz o upload de um arquivo e devolve o documentoId para usar em documentos[].documentoId na criação do envelope. O mesmo documentoId pode ser reutilizado em mais de um envelope.

Campo (form-data)	Tipo	Obrigatório	Descrição
arquivo	file	Sim	Arquivo .pdf, .doc ou .docx, até 25 MB
descricao	string	Não	Descrição do documento. Padrão: nome do arquivo

Resposta — 201

{
  "documentoId": 98765,
  "nomeArquivo": "contrato.pdf",
  "descricao": "Contrato principal",
  "tamanho": 184320
}

Campo	Descrição
documentoId	Identificador do documento para uso nos envelopes
nomeArquivo	Nome do arquivo recebido
descricao	Descrição gravada
tamanho	Tamanho em bytes

Erros: 400 quando o arquivo está ausente, vazio, com extensão não aceita, acima do limite ou estruturalmente inválido. PDFs são validados com a mesma biblioteca usada na assinatura: um arquivo que abre no navegador mas tem xref/startxref inconsistentes é recusado aqui, e não na hora de assinar. A mesma validação vale para conteudoBase64 na criação do envelope.

Criar envelope

POST /xsigner/envelopes

Payload

Campo	Tipo	Obrigatório	Descrição
assunto	string	Sim	Assunto do e-mail (até 100 caracteres)
mensagem	string	Não	Mensagem do e-mail (até 1000 caracteres)
codigo	string	Não	Código livre do integrador
enviarPorOrdem	boolean	Não	Assinatura sequencial. Padrão false
departamentoId	integer	Não	Departamento responsável no Xjur
documentos[]	array	Sim	Ver Documento
signatarios[]	array	Sim	Ver Signatário

Use codigo para guardar o identificador do seu sistema.

Documento

Campo	Tipo	Obrigatório	Descrição
documentoId	integer	Uma das formas	Documento enviado por POST /xsigner/documentos
nomeArquivo	string	Uma das formas	Nome do arquivo com extensão (.pdf, .doc, .docx)
conteudoBase64	string	Com nomeArquivo	Conteúdo em base64 (aceita prefixo data URI). Até 25 MB por arquivo
descricao	string	Não	Descrição do documento. Padrão: nome do arquivo
ordensSignatariosPermitidos	integer[]	Não	Ordens (ordem) dos signatários que podem ver o documento. Vazio = todos

Signatário

Campo	Tipo	Obrigatório	Descrição
nome	string	Sim	Nome e sobrenome
email	string	Sim	E-mail único dentro do envelope
papelSignatarioId	integer	Um dos dois	Id do papel
papel	string	Um dos dois	Nome do papel, sem distinção de maiúsculas
ordem	integer	Se enviarPorOrdem	Posição na sequência (1, 2, 3…). Padrão: posição no array
celular	string	Não	Celular com DDD, somente números são considerados
codigo	string	Não	Código livre

Regras de processamento

1. Documentos com conteudoBase64 são armazenados antes da criação do envelope.
2. Se algum documento falhar no upload, o envelope não é criado.
3. O primeiro documento do array dá o nome ao envelope (nomeDocumento).
4. Cada e-mail só pode aparecer uma vez por envelope.
5. Com enviarPorOrdem = true, as ordens precisam ser distintas; o e-mail vai apenas para o primeiro da sequência.

Resposta — 201

Retorna o EnvelopeResponse completo, com Location: /xsigner/envelopes/{envelopeId}.

Listar envelopes

GET /xsigner/envelopes

Parâmetro	Tipo	Descrição
status	string[]	Nome ou código do status. Repita o parâmetro para vários: ?status=Assinado&status=Cancelado
codigo	string	Busca parcial pelo código
nomeDocumento	string	Busca parcial pelo nome do documento
dataCadastroDe / dataCadastroAte	datetime	Período de criação
dataAssinaturaDe / dataAssinaturaAte	datetime	Período de conclusão
dataCancelamentoDe / dataCancelamentoAte	datetime	Período de cancelamento
offset	integer	Deslocamento. Padrão 0
limit	integer	Itens por página. Padrão 25, máximo 100
sort	string	Campo de ordenação. Padrão EnvelopeId

{
  "totalPaginas": 2,
  "totalRegistros": 42,
  "data": [ { "envelopeId": 1532, "status": "AguardandoSignatarios", "...": "..." } ]
}

Quando nenhum envelope corresponde ao filtro, a resposta é 200 com data vazio.

Consultar envelope

GET /xsigner/envelopes/{envelopeId}

EnvelopeResponse

Campo	Tipo	Descrição
envelopeId	integer	Identificador do envelope
hashEnvelope	string	Hash interno (rastreabilidade)
codigo	string	Código informado na criação
nomeDocumento	string	Nome do primeiro documento
descricaoDocumento	string	Descrição do primeiro documento
plataforma	string	Sempre xsigner
status / statusId	string / integer	AguardandoSignatarios (2), Assinado (3), Cancelado (-1), EmConfeccao (1)
enviarPorOrdem	boolean	Assinatura sequencial
dataCadastro	datetime	Criação
dataAssinatura	datetime	Conclusão (quando Assinado)
dataCancelamento	datetime	Cancelamento (quando Cancelado)
motivoCancelamento	string	Motivo do cancelamento. Na recusa: Recusado por <nome>: <justificativa>
departamento	object	{ departamentoId, nome }
documentoAssinado	object	{ documentoId, url } do PDF final; presente quando Assinado
documentos[]	array	envelopeDocumentoId, documentoId, ordem, url (temporária), signatariosPermitidos
signatarios[]	array	Ver SignatarioResponse

SignatarioResponse

Campo	Tipo	Descrição
signatarioId	integer	Identificador do signatário
hashSignatario	string	Hash interno
nome, email, celular	string	Dados do signatário
ordem	integer	Posição na sequência (0 quando não há ordem)
papelSignatarioId / papel	integer / string	Papel
status / statusId	string / integer	PendenteAssinatura (1), Assinado (2), Recusado (3), Excluido (-1)
dataCadastro	datetime	Inclusão no envelope
dataAssinatura	datetime	Momento da assinatura
dataRecusa / motivoRecusa	datetime / string	Preenchidos quando o signatário recusou o documento (o envelope é cancelado para todos)
linkAssinatura	string	Link público da página de assinatura
documentoIdentificacao	object	{ tipo, numero } informado na assinatura (RG, CPF, CNPJ, DocumentoEstrangeiro)
ip	string	IP de origem da assinatura
codigo	string	Código livre

URLs temporárias

documentos[].url e documentoAssinado.url são URLs pré-assinadas com validade curta. Não as armazene; consulte o envelope novamente quando precisar baixar o arquivo, ou use GET /xsigner/envelopes/{envelopeId}/documento-assinado.

Cancelar envelope

POST /xsigner/envelopes/{envelopeId}/cancelar

Retorna o envelope com status = Cancelado. Envelopes Assinado ou já Cancelado respondem 400.

Signatários

Adicionar

POST /xsigner/envelopes/{envelopeId}/signatarios

Mesmo formato de Signatário. Em envelopes com enviarPorOrdem = true, ordem é obrigatória e os signatários pendentes a partir daquela posição são deslocados. O e-mail com o link é enviado imediatamente (ou quando chegar a vez dele, na assinatura sequencial). Retorna 201 com o envelope atualizado.

Atualizar

PATCH /xsigner/envelopes/{envelopeId}/signatarios/{signatarioId}

{ "nome": "Maria da Silva", "email": "maria.novo@email.com", "celular": "11999998888" }

Envie apenas os campos que deseja alterar. Somente signatários PendenteAssinatura podem ser alterados. Retorna o envelope atualizado.

Remover

DELETE /xsigner/envelopes/{envelopeId}/signatarios/{signatarioId}

O signatário deixa de aparecer no envelope. Se ele era o único pendente e alguém já havia assinado, o envelope é concluído e o PDF final é gerado. Retorna o envelope atualizado.

Reenviar link

POST /xsigner/envelopes/{envelopeId}/signatarios/{signatarioId}/reenviar-link

{
  "envelopeId": 1532,
  "signatarioId": 4101,
  "nome": "Maria Silva",
  "email": "maria.silva@email.com",
  "status": "PendenteAssinatura",
  "linkAssinatura": "https://app.xjur.com.br/xsigner?hashEnvelope=...&hashSignatario=...",
  "mensagem": "Link de assinatura reenviado por e-mail para maria.silva@email.com."
}

Obter link

GET /xsigner/envelopes/{envelopeId}/signatarios/{signatarioId}/link

Mesma resposta do reenvio, sem mensagem e sem disparar e-mail. Use para entregar o link por um canal próprio.

Downloads

Rota	Conteúdo
GET /xsigner/envelopes/{envelopeId}/documento-assinado	application/pdf — PDF final com os documentos e a página de assinaturas. Requer status = Assinado
GET /xsigner/envelopes/{envelopeId}/documentos/zip	application/zip — documentos do envelope

Catálogos

Papéis de signatário

GET /xsigner/papeis-signatario

Retorna apenas os papéis ativos. Use ?incluirInativos=true para listar todos.

[
  { "papelSignatarioId": 5, "nome": "Contratante", "ativo": true },
  { "papelSignatarioId": 6, "nome": "Testemunha", "codigo": "TEST", "ativo": true }
]

Domínios

GET /xsigner/dominios

Retorna statusEnvelope, statusSignatario e extensoesAceitas. Não exige autenticação no Xjur.