Skip to main content

Auto-assinatura do Emissor

A auto-assinatura permite que a QI Tech assine automaticamente, em nome do emissor, os documentos das emissões seguintes — sem que um representante precise assinar operação por operação.

Para isso, o emissor assina uma única vez um termo de adesão à auto-assinatura. Enquanto esse termo não estiver assinado, as emissões continuam seguindo o fluxo normal de assinatura manual.

Habilitação por cliente

A auto-assinatura não vem habilitada por padrão. Ela é configurada pela QI Tech por cliente (tenant), incluindo o template do termo de adesão utilizado. Para habilitar, entre em contato com o time suporte-dcm@qitech.com.br.

Pré-requisitos​

Pré-requisitoComo é atendido
Cliente habilitado para auto-assinaturaConfigurado pela QI Tech, com o template do termo de adesão
Emissor com cadastro aprovadoFluxo normal de homologação do emissor
Emissor com grupo de assinantes ativoCadastro de assinantes do emissor

O grupo de assinantes cadastrado no emissor é exatamente quem assina o termo de adesão. Se ele estiver vazio ou desatualizado no momento da aprovação, corrija o cadastro antes de prosseguir.

Fluxo ponta a ponta​

A habilitação é solicitada pelo integrador, e só é aceita depois que o cadastro do emissor está aprovado. Não há criação automática: enquanto a solicitação não for feita, o emissor não tem auto-assinatura.

  1. Emissor aprovado. O cadastro passa pelo fluxo normal de homologação até o status approved. Nada é criado nesse momento.
  2. Solicitação da habilitação. O integrador chama POST /issuer_management/issuer/{issuer_key}/auto_signature. Na mesma chamada, a QI Tech cria a auto-assinatura, gera o termo de adesão a partir do template configurado para o cliente e abre o envelope de assinatura — independente de qualquer operação. A resposta já vem no status pending_signature, com issuer_auto_signature_key e envelope_key.
  3. Assinatura do termo. O integrador consulta os links de assinatura e direciona cada assinante do emissor ao seu próprio link. O termo é assinado fora de qualquer operação, e pode ser assinado antes da primeira emissão.
  4. Termo assinado. Quando todas as assinaturas necessárias são concluídas, a auto-assinatura passa para enabled e os campos signed_at e enabled_at são preenchidos. A QI Tech emite então o certificado privado do emissor, utilizado para assinar os documentos das emissões.
  5. Recusa ou expiração. Se o envelope for recusado, cancelado ou expirado, a auto-assinatura vai para reproved e as emissões seguem pelo fluxo de assinatura manual. Uma nova habilitação precisa ser solicitada.

Os passos 2, 4 e 5 disparam o webhook issuer_management.auto_signature_status_change — ou seja, os status pending_signature, enabled e reproved. O cancelamento (canceled) não gera webhook e é observado por consulta. Como o pending_signature já vem na resposta da solicitação, o webhook desse status é redundante para quem chamou o endpoint — ele é útil para outros consumidores do mesmo tenant.

Não assuma a auto-assinatura ativa

A solicitação abre o envelope, mas não conclui a habilitação: o termo ainda precisa ser assinado. Só considere a assinatura automática disponível para uma emissão depois que a auto-assinatura estiver em enabled. Em qualquer outro status, o documento segue para assinatura manual — a integração precisa tratar os dois caminhos.

Máquina de status​

StatusSignificadoAssinatura de uma nova emissão
pending_term_generationEstado transitório durante a solicitaçãoManual
pending_signatureTermo gerado e enviado para assinatura; links dos assinantes disponíveisManual
enabledTermo assinado; emissor habilitado à assinatura automáticaAutomática
reprovedEnvelope do termo recusado, cancelado ou expiradoManual
canceledAuto-assinatura canceladaManual

Transições possíveis:

  • pending_term_generation → pending_signature (ambos dentro da solicitação) → enabled
  • pending_signature → reproved (envelope recusado, cancelado ou expirado)
  • pending_term_generation ou pending_signature → canceled

A auto-assinatura é cancelada automaticamente quando o emissor deixa o status approved — ou seja, quando passa para reproved, expired ou canceled. Nesse caso, a habilitação precisa ser refeita após a nova aprovação do cadastro.

Endpoints​

EndpointPara quê
POST .../auto_signatureSolicitar a habilitação para um emissor aprovado
GET .../auto_signatureConsultar o estado atual e o histórico de eventos
GET .../auto_signature/signersObter o link de assinatura de cada assinante do termo

Como acompanhar​

Há dois caminhos, complementares:

O bloco resumido também aparece na consulta do emissor, no campo auto_signature:

{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "status": "approved",
    "auto_signature": {
        "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
        "status": "enabled",
        "signed_at": "2026-02-11T14:02:31",
        "enabled_at": "2026-02-11T14:02:31"
    }
}

O campo é null para emissores que nunca tiveram uma auto-assinatura solicitada.