SignXP Docs

Consultar o status

GET /api/v1/documents/{id}

{
  "id": 128,
  "external_id": "contrato-2026-0001",
  "title": "Contrato de Prestação de Serviços",
  "environment": "live",
  "status": "completed",
  "delivery": "email",
  "error": null,
  "customer": { "reference": "cli-4471", "name": "Acme Indústria Ltda." },
  "created_at": "2026-07-28T13:40:00-03:00",
  "completed_at": "2026-07-28T14:03:11-03:00",
  "verification_url": "https://app.signxp.com.br/validar/9f2c...",
  "signers": [
    {
      "key": "contratante",
      "name": "Maria Souza",
      "email": "maria@empresa.com.br",
      "status": "signed",
      "signed_at": "2026-07-28T13:58:02-03:00",
      "signing_url": "https://app.signxp.com.br/assinar/9f2c7a1b..."
    }
  ]
}

O email do signatário vem null quando o documento foi enviado sem ele — nesse caso o SignXP não notifica essa pessoa, e a entrega do link é sua. Veja signatário sem e-mail.

O link de assinatura

signing_url vem em todos os ambientes, inclusive produção. É por ele que você entrega o convite pelo seu próprio canal — veja entregando o link você mesmo.

O link é a credencial de quem assina: quem o tem assina no lugar da pessoa. Trate-o como trata a sua chave de API — nunca em página pública, nunca em log compartilhado.

Status do documento

Status	Significado
`draft`	Recebido; o PDF ainda está sendo processado.
`awaiting_placement`	Esperando alguém posicionar os campos. `placement_url` vem junto na resposta. Ninguém foi convidado ainda.
`pending`	Pronto e aguardando assinatura.
`awaiting_review`	Todos assinaram, mas uma imagem de evidência ficou sem veredito da IA e o licenciado precisa conferir. O documento ainda não vale: não há cópia selada, e ele pode terminar como `completed` ou `rejected`. Veja validação por IA.
`completed`	Todos assinaram; o PDF selado está disponível.
`rejected`	Um signatário recusou.
`cancelled`	A tentativa foi encerrada — por você, pela API, pelo licenciado no portal dele, ou pela equipe SignXP a pedido. Os links pendentes deixaram de valer. Veja cancelar um documento.
`failed`	Falha no processamento — veja `error` (página inexistente, PDF ilegível, selagem que não fechou).

Status do signatário

Status	Significado
`pending`	Ainda não assinou.
`opened`	Abriu o link.
`signed`	Assinou.
`rejected`	Recusou.
`cancelled`	O documento foi cancelado antes desta pessoa assinar. Diferente de `rejected`: a decisão foi de quem enviou, não de quem assinaria.

Listando o acervo

GET /api/v1/documents

Devolve os documentos da sua licença, do mais recente para o mais antigo, com o mesmo formato de item da consulta acima — quem lista e depois abre um documento não precisa aprender dois vocabulários para a mesma coisa.

É com isto que você monta o acervo dentro do seu sistema, em vez de mandar o seu usuário ao portal.

{
  "data": [ { "id": 128, "status": "completed", "...": "..." } ],
  "meta": { "current_page": 1, "last_page": 4, "per_page": 25, "total": 87 }
}

Filtros

Parâmetro	O que faz
`status`	Um dos status da tabela acima.
`phase`	`active` (em andamento) ou `archived` (encerrado ou arquivado à mão pelo licenciado). Ver abaixo.
`customer_reference`	Só os de um cliente seu. Use `none` para os que foram enviados sem `customer`.
`from` / `to`	Intervalo de datas de criação (`AAAA-MM-DD`), inclusivo nas duas pontas.
`search`	Busca no título, no `external_id` e no nome do cliente.
`per_page`	Itens por página. Padrão 25, teto 100.
`page`	A página desejada.

Os filtros combinam entre si:

GET /api/v1/documents?status=pending&customer_reference=cli-4471&per_page=50

A ordenação é estável (por id, decrescente), então paginar não faz um documento aparecer duas vezes nem sumir entre uma página e a seguinte.

O que `phase` separa

phase divide o trabalho do dia a dia do histórico, e olha dois eixos ao mesmo tempo:

O status. O que encerrou — completed, rejected, cancelled, failed — sai do active sozinho, sem ninguém precisar fazer nada.
O arquivamento manual, feito pelo licenciado no portal. Ele existe para tirar da frente um documento que ainda está aberto e que ninguém vai tocar.

Então phase=active é em curso e não arquivado, e phase=archived é encerrado ou arquivado. Um pending esquecido pode ser arquivado; um completed vai para o histórico por conta própria.

O awaiting_review conta como em curso: a assinatura já aconteceu, mas o documento só vale depois de uma decisão humana — e é o estado que mais depende de alguém agir, então escondê-lo no histórico o tiraria da vista de quem precisa resolvê-lo.

Esta consulta não consome quota e continua respondendo com a licença bloqueada — cortar o acesso ao próprio acervo por causa de uma fatura em atraso seria punir o lado errado.

Polling ou callback?

Prefira o callback: ele avisa no momento exato da mudança. Todo desfecho tem evento — inclusive failed e cancelled. Use a consulta de status como rede de segurança — por exemplo, uma varredura a cada 30 minutos nos documentos que ainda estão pending.

Se precisar fazer polling frequente, respeite o limite de requisições da sua licença (veja Erros e limites).