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é-requisito	Como é atendido
Cliente habilitado para auto-assinatura	Configurado pela QI Tech, com o template do termo de adesão
Emissor com cadastro aprovado	Fluxo normal de homologação do emissor
Emissor com grupo de assinantes ativo	Cadastro 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

Status	Significado	Assinatura de uma nova emissão
pending_term_generation	Estado transitório durante a solicitação	Manual
pending_signature	Termo gerado e enviado para assinatura; links dos assinantes disponíveis	Manual
enabled	Termo assinado; emissor habilitado à assinatura automática	Automática
reproved	Envelope do termo recusado, cancelado ou expirado	Manual
canceled	Auto-assinatura cancelada	Manual

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

Endpoint	Para quê
POST .../auto_signature	Solicitar a habilitação para um emissor aprovado
GET .../auto_signature	Consultar o estado atual e o histórico de eventos
GET .../auto_signature/signers	Obter o link de assinatura de cada assinante do termo

Como acompanhar

Há dois caminhos, complementares:

• Webhook — issuer_management.auto_signature_status_change é enviado nos status pending_signature, enabled e reproved. Ao receber pending_signature, consulte os links de assinatura.
• Consulta — consulta da auto-assinatura retorna o estado atual e o histórico completo de eventos.

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.