Cancelar um documento

POST /api/v1/documents/{id}/cancel

{
  "reason": "Contrato substituído pela revisão 2."
}

O reason é opcional (texto livre, até 500 caracteres), mas escreva-o. Meses depois, um cancelled sem motivo é indistinguível de um cancelamento feito por engano — e como o documento continua consultável, o motivo passa a fazer parte do registro.

O que o cancelamento faz

Derruba os links de assinatura que ainda estão pendentes. É o efeito principal. Quem recebeu o convite antes do cancelamento e abrir o link agora vê "documento cancelado" em vez do fluxo de assinatura, e nenhuma assinatura é mais aceita naquele documento.

Isso resolve o caso real: o contrato foi substituído, ou foi assinado por outro caminho, e o link que já saiu por e-mail continuaria valendo.

Muda o status para cancelled e dispara o callback document.cancelled.

Encerra as assinaturas que ainda não aconteceram. Quem estava pending ou opened passa a cancelled. Sem isso, a assinatura ficaria "pendente" para sempre — e a página de verificação seguiria prometendo uma assinatura que nunca viria.

Quem já assinou ou já recusou não é tocado. Aquilo aconteceu, está no Termo de Evidências, e reescrever apagaria o que a pessoa fez.

Não apaga o documento. Ele continua no acervo, continua aparecendo na listagem e a URL de verificação continua respondendo. Cancelar é registrar que a tentativa terminou, não sumir com ela — inclusive porque quem já assinou antes do cancelamento tem o direito de encontrar o que assinou.

A resposta

Devolve o documento no mesmo formato da consulta de status, acrescido do bloco de quota:

{
  "id": 128,
  "status": "cancelled",
  "cancelled_at": "2026-08-04T16:22:41-03:00",
  "cancellation_reason": "Contrato substituído pela revisão 2.",
  "verification_url": "https://app.signxp.com.br/validar/9f2c...",
  "quota": {
    "refunded": false,
    "limit": 500,
    "used": 139,
    "period": "2026-08"
  }
}

cancelled_at e cancellation_reason também vêm na consulta de status e na listagem do acervo — você não precisa guardar a resposta desta chamada para saber depois por que o documento foi cancelado.

O cancelamento não devolve a quota

quota.refunded é sempre false. O consumo é contado no momento do envio, no período do envio, e não volta.

São duas razões, e as duas importam:

• Devolver creditaria o mês errado. Um documento enviado em julho e cancelado em agosto abateria a quota de agosto, que não foi onde ele foi gasto.
• Quota que volta é quota que se contorna. Enviar e cancelar em sequência permitiria disparar convites sem limite — e o convite é e-mail que já saiu, com o link e o seu nome dentro.

Se isso apertar o seu volume, o caminho é rever a quota do plano com o time SignXP, não cancelar para reciclar.

Envios no ambiente de teste (sk_test_) nunca consumiram quota, então aqui não há o que devolver.

Quando o cancelamento é recusado

Um documento completed já foi selado, e a via com validade jurídica pode já estar na mão das partes. Mudar o status aqui não desassinaria nada — só faria o seu acervo mentir. Se o contrato assinado precisa ser desfeito, isso é um distrato, e um distrato é um documento novo.

Em awaiting_review todos já assinaram e o documento espera a conferência de uma pessoa. A saída dali é reprovar a validação, que encerra o documento com o motivo ligado à assinatura reprovada — cancelar por fora apagaria essa ligação.

Em rejected e failed a tentativa já acabou, e a causa está registrada. Sobrescrever com "cancelado" perderia a informação de que houve uma recusa ou uma falha.

Repetir é seguro

Cancelar um documento que já está cancelled devolve 200 com o mesmo corpo — inclusive o cancelled_at e o reason do cancelamento original, que não são reescritos.

A repetição também não dispara o callback de novo: quem recebe document.cancelled vê o evento uma vez por documento. Isso torna a chamada segura para reenviar quando você perdeu a resposta e não sabe se ela chegou.

Cancelar não é arquivar

Cancelar encerra a tentativa; arquivar apenas tira o documento das telas do dia a dia. São coisas diferentes:

• Um documento completed pode ser arquivado, mas nunca cancelado.
• Um documento ainda aberto pode ser arquivado sem ser cancelado: o link segue valendo e a assinatura ainda pode acontecer — ele só saiu da lista de trabalho.

O arquivamento é uma ação do portal, feita pelo licenciado. Na listagem do acervo, status=cancelled filtra pelo cancelamento, e phase separa o dia a dia do histórico olhando o status e o arquivamento juntos. Um documento cancelado já sai do active por causa do status, sem precisar ser arquivado.

Erros

Vale a tabela de erros e limites. Específico daqui:

Esta chamada continua funcionando com a licença fora de vigência ou com a quota esgotada — o que fica bloqueado nessa situação é o envio, não o cancelamento. É deliberado: quem está assim é justamente quem mais precisa conseguir derrubar um link pendente, e recusar aqui manteria vivos os links que você está tentando matar.

A exceção é o cliente inativo, que recebe 403 em toda a API, aqui como em qualquer outra rota.