Assinatura em grupo (INSS)

Disponibilidade

Este fluxo está em implantação. Por ora, ele cobre operações INSS (social_security) com o certificador qi_sign. Alinhe com o time de integração da QI Tech a liberação para o seu requester antes de iniciar a integração em produção.

O fluxo de assinatura em grupo agrupa várias operações em uma única pasta de assinatura do QI Sign. O beneficiário faz uma única jornada de assinatura (prova de vida, documento e OTP) e assina todas as operações do grupo de uma só vez, com um único link.

Fluxo

(opcional) Faça upload do documento de identificação do beneficiário, para que ele não precise fotografá-lo durante a assinatura
Abra o grupo com POST /document/document_batch_group e guarde a document_batch_group_key.
Crie cada operação (/debt, /v2/credit_transfer/proposal, etc) enviando document_batch_group_key na raiz do payload.
(Opcional) Consulte o grupo e remova operações antes do envio.
Envie o grupo para assinatura com PUT /document/document_batch_group/{key}/send_to_signature e obtenha o link único do beneficiário.
O beneficiário assina todas as operações de uma vez; cada operação evolui individualmente e o grupo é concluído quando todas chegam a um status terminal.

Grupo × lote

Cada operação (dívida, proposta de portabilidade/refin ou reserva de cartão) continua sendo um lote (envelope). O grupo é a camada acima dos lotes (pasta), responsável por reunir os envelopes e disparar uma única assinatura. Se você ainda utiliza o fluxo de lote externo, consulte a tabela de migração ao final desta página.

Regras do grupo

Assinante único: o grupo suporta apenas um assinante (o beneficiário). Não é possível informar múltiplos assinantes na pasta.
Mesma titularidade: o assinante informado na abertura do grupo deve ser o mesmo de todas as operações anexadas. Operação com assinante divergente retorna erro síncrono (DOC000121).
Tipos permitidos: o grupo aceita operações INSS de Crédito Novo, Portabilidade/Refinanciamento e Cartão Consignado, desde que compartilhem o mesmo assinante.
Limite de operações: o grupo aceita no máximo 7 operações (lotes). A inclusão de uma operação além do limite retorna erro síncrono (DOC000127).
Contato obrigatório: informe signer_email e/ou signer_phone no assinante. Sem um meio de contato, não é possível gerar o link de assinatura.
Certificador: derivado automaticamente da configuração do requester (qi_sign); não é enviado na requisição.

Convivência com os fluxos atuais (período de transição)

O fluxo de grupo é opcional e aditivo: ele só é acionado quando document_batch_group_key é enviado na criação da operação. Os fluxos existentes — assinatura individual por operação com o certificador configurado para o requester (inclusive certificadores externos, como client_side) e o lote externo — continuam funcionando sem alteração durante o período de transição. Dentro do grupo, a assinatura é sempre coletada via QI Sign, mesmo que o requester utilize outro certificador nos fluxos regulares.

1. Abrir o grupo

ENDPOINT

/document/document_batch_group

MÉTODO

POST

Request Body

{
    "batch_group_type": "social_security",
    "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
    "signer": {
        "signer_document_number": "14471835092",
        "signer_name": "Nome devedor",
        "signer_email": "maria.silva@email.com",
        "signer_phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999538380"
        },
        "signer_role": "issuer",
        "signature_method": "whatsapp"
    },
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    }
}

Body Params

Certificador

O certificador (qi_sign) é derivado da configuração do requester e não é enviado na requisição. Requesters cuja configuração não use qi_sign recebem DOC000118.

Campo	Tipo	Descrição	Caracteres
`batch_group_type`	string	Tipo do grupo. Atualmente o único valor é `social_security`.	Batch Group Type
`request_control_key`	string	Chave de idempotência (UUID v4), obrigatória. Reenviar o mesmo valor retorna o grupo já existente (evita grupos/pastas duplicados em retentativas). Não reutilize entre grupos distintos.	36
`signer`	object	Dados do beneficiário que assinará todas as operações do grupo.	Signer Object
`personal_document`	object	(Opcional) Documento de identificação do beneficiário coletado previamente, para dispensar a foto do documento durante a jornada de assinatura.	Documento pré-coletado

Signer Object

Campo	Tipo	Descrição	Caracteres
`signer_document_number`	string	CPF/CNPJ do assinante (apenas dígitos).	11 a 14
`signer_name`	string	Nome do assinante.	100
`signer_email`	string	E-mail para envio do link de assinatura. (opcional)	255
`signer_phone.country_code`	string	Código do país (ex.: `"55"`). (opcional)	5
`signer_phone.area_code`	string	DDD do assinante. (opcional)	5
`signer_phone.number`	string	Número de telefone do assinante. (opcional)	15
`signer_role`	string	Papel do assinante (ex.: `issuer`). Deve ser igual ao papel do assinante nas operações anexadas, caso contrário a inclusão retorna `DOC000121`.	100
`signature_method`	string	Canal de envio do link de assinatura. (opcional)	Signature Method
`birth_date`	string	Data de nascimento do assinante (`AAAA-MM-DD`). (opcional)	10

Documento de identificação pré-coletado

Se o seu fluxo já coleta o documento de identificação do beneficiário (RG, CNH etc.) antes da assinatura, envie-o na abertura do grupo pelo objeto personal_document. As imagens são encaminhadas ao QI Sign junto com a criação da pasta e a etapa de captura do documento chega pré-atendida na jornada — o beneficiário não precisa fotografar o documento novamente durante a assinatura.

O envio acontece em duas etapas:

Faça o upload dos arquivos previamente pelo fluxo de upload de documentos e guarde a document_key de cada arquivo (um arquivo por lado do documento, ou um arquivo único no caso de documento digital).
Referencie as chaves no objeto personal_document da abertura do grupo.

Trecho ilustrativo (raiz do payload de abertura do grupo)
{
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    }
}

Personal Document Object

Campo	Tipo	Descrição	Caracteres
`type`	string	Tipo do documento de identificação.	Personal Document Type
`document_identification_front_key`	string	`document_key` do arquivo com a frente do documento. Obrigatório no modo frente e verso (junto com `..._back_key`).	36
`document_identification_back_key`	string	`document_key` do arquivo com o verso do documento. Obrigatório no modo frente e verso (junto com `..._front_key`).	36
`document_identification_full_key`	string	`document_key` do arquivo único com o documento completo (documento digital). Não pode ser combinado com as chaves de frente/verso.	36

Regras do documento pré-coletado

Envie frente + verso (document_identification_front_key + document_identification_back_key) ou o arquivo único (document_identification_full_key) — nunca os dois modos juntos.
Cada type suporta modos específicos — veja Personal Document Type. Combinação inválida retorna DOC000128.
Os documentos referenciados devem pertencer ao seu requester e já ter o arquivo enviado (upload concluído). Chave inexistente ou de outro requester retorna DOC000004; documento sem arquivo retorna DOC000049.
O envio é feito apenas na abertura do grupo — não é possível adicionar ou trocar o documento depois que o grupo foi criado. Se algum arquivo for rejeitado, a criação do grupo falha por inteiro (nenhum grupo é criado).

O objeto personal_document enviado é ecoado nas consultas do grupo.

Response

STATUS

201

Response Body

{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_batches"
}

Campo	Tipo	Descrição
`document_batch_group_key`	string	Identificador do grupo. Guarde para os próximos passos.
`status`	string	Status inicial do grupo: `pending_batches`. Veja Status do grupo.

2. Incluir operações no grupo

Ao criar cada operação, envie document_batch_group_key na raiz do JSON (mesmo nível dos demais campos principais do produto). A operação é criada normalmente, mas a sua assinatura fica vinculada à pasta do grupo — não é gerado link de assinatura individual.

Crédito Novo / Refin

POST /debt

Portabilidade / Refin

POST /v2/credit_transfer/proposal

Cartão

POST /payroll_card_reservation/social_security

Campo	Tipo	Descrição	Caracteres
`document_batch_group_key`	string	A `document_batch_group_key` retornada na abertura do grupo; enviada na raiz do payload de criação da operação. Obrigatório no fluxo com grupo.	36

Trecho ilustrativo (raiz do payload)
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}

O restante do body segue o contrato de cada endpoint. Consulte os roteiros de crédito consignado INSS conforme o produto.

Resposta da operação no fluxo com grupo

Como o link de assinatura passa a ser único e no nível do grupo, a resposta de criação da operação não retorna dados de assinatura individuais (ex.: signature_information na proposta de portabilidade/refin). O link é obtido apenas no envio do grupo para assinatura.

3. Consultar o grupo

ENDPOINT

/document/document_batch_group/{document_batch_group_key}

MÉTODO

GET

Recomendado antes de enviar para assinatura, para conferir as operações agrupadas e seus status.

Path Params

Campo	Tipo	Descrição
`document_batch_group_key`	string	Chave do grupo.

Consulta por idempotência

Também é possível consultar pela request_control_key: GET /document/document_batch_group/request_control_key/{request_control_key}.

Exemplo de chamada

GET /document/document_batch_group/17f35e19-a039-468f-aaa7-84aa8edec3dc

Response

STATUS

200

Response Body

{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
    "external_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
    "group_name": "Assinatura de operações INSS",
    "batch_group_type": "social_security",
    "status": "pending_batches",
    "signature_url": null,
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    },
    "batches": [
        {
            "document_batch_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
            "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3",
            "origin_type": "credit_operation",
            "status": "pending_signature"
        },
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}

Campo	Tipo	Descrição
`document_batch_group_key`	string	Identificador do grupo.
`request_control_key`	string	Chave de idempotência informada na abertura do grupo.
`external_key`	string	Identificador da pasta no QI Sign.
`group_name`	string	Nome gerado para o grupo (ex.: `Assinatura de operações INSS`).
`batch_group_type`	string	Tipo do grupo. Veja Batch Group Type.
`status`	string	Status do grupo. Veja Status do grupo.
`signature_url`	string	Link único de assinatura do beneficiário. Disponível após o envio para assinatura. Com o preenchimento automático do login habilitado, retorna o link já autenticado.
`personal_document`	object	Documento de identificação pré-coletado informado na abertura do grupo (`null` se não enviado).
`batches`	array	Operações anexadas ao grupo. Batch Object

Batch Object

Campo	Tipo	Descrição
`document_batch_key`	string	Chave do lote (envelope) da operação.
`origin_key`	string	Chave da operação de origem. Veja Origin Type.
`origin_type`	string	Tipo da operação de origem. Veja Origin Type.
`status`	string	Status da operação dentro do grupo. Veja Status da operação.

4. Remover operação do grupo

Desvincula e cancela uma operação específica antes do envio para assinatura (para reagrupar, se necessário). Só é permitido enquanto o grupo está em pending_batches.

ENDPOINT

/document/document_batch_group/{document_batch_group_key}/remove_batch

MÉTODO

PUT

Path Params

Campo	Tipo	Descrição
`document_batch_group_key`	string	Chave do grupo.

Request Body

{
    "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3"
}

Body Params

Campo	Tipo	Descrição
`origin_key`	string	Chave da operação a remover (a mesma `origin_key` retornada na consulta do grupo).

Response

STATUS

201

Retorna o grupo atualizado, já sem a operação removida em batches (mesmo formato da consulta do grupo).

Response Body

{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_batches",
    "signature_url": null,
    "batches": [
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}

5. Enviar para assinatura

Fecha o grupo e dispara a pasta para assinatura no QI Sign. Retorna o link único (signature_url) que o beneficiário usa para assinar todas as operações de uma só vez.

ENDPOINT

/document/document_batch_group/{document_batch_group_key}/send_to_signature

MÉTODO

PUT

Path Params

Campo	Tipo	Descrição
`document_batch_group_key`	string	Chave do grupo.

Body: objeto JSON vazio {}.

Pré-condições do envio

O grupo precisa estar em pending_batches.
Deve haver ao menos uma operação anexada (DOC000120).
Todas as operações devem ter o mesmo assinante do grupo (DOC000121).

Response

STATUS

201

O grupo passa para pending_signature e a signature_url é preenchida.

Response Body

{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_signature",
    "signature_url": "https://sign.sandbox.qitech.app/f/17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "batches": [
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}

Campo	Tipo	Descrição
`status`	string	Status do grupo após o envio: `pending_signature`.
`signature_url`	string	Link único de assinatura do beneficiário.
`batches`	array	Operações do grupo. Batch Object

Link com preenchimento automático do login

Sob demanda, é possível habilitar o preenchimento automático do login. Com a opção habilitada, a signature_url retornada no envio para assinatura e nas consultas do grupo passa a ser um link autenticado: a tela de login da jornada de assinatura já vem preenchida com os dados do beneficiário.

Acompanhamento

Após o envio, o beneficiário assina todas as operações com um único link. Na jornada de assinatura, o beneficiário pode aceitar ou recusar cada operação individualmente — desfechos parciais são normais (ex.: duas operações assinadas e uma recusada no mesmo grupo). Cada operação evolui de forma independente e o grupo é concluído (completed) quando nenhuma operação permanece em pending_signature, independentemente da combinação de desfechos. Acompanhe o desfecho de cada operação pelos webhooks do respectivo produto (abaixo) ou pela consulta do grupo.

Submissão automática (Portabilidade/Refin)

No fluxo com grupo, após a assinatura da proposta de portabilidade/refin a submissão à registradora é feita automaticamente — a proposta avança para pending_response sem necessidade do PATCH manual de submissão.

Webhook de operação assinada

Cada operação assinada segue o mesmo fluxo de webhooks do produto (dívida emitida, proposta submetida etc.) — nenhum campo muda em relação ao fluxo sem grupo. Consulte os webhooks de cada produto nos roteiros INSS.

Webhook de assinatura recusada

Quando o beneficiário recusa uma operação do grupo, a operação é cancelada no respectivo produto e o parceiro recebe o webhook de mudança de status com o motivo signature_rejected:

Crédito Novo / Refin (dívida):

{
    "key": "324caa35-ba10-4590-ae2b-5efef71709c3",
    "data": {
        "cancel_reason": "Operação cancelada porque o assinante recusou a assinatura.",
        "cancel_reason_enumerator": "signature_rejected"
    },
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2026-07-06 14:30:00"
}

Portabilidade / Refin (proposta):

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
    "event_datetime": "2026-07-06T14:30:00",
    "proposal_status": "canceled",
    "cancel_reason": "signature_rejected"
}

Produto	`webhook_type`	Campo de status	Motivo da recusa
Crédito Novo / Refin	`debt`	`status: "canceled"`	`data.cancel_reason_enumerator: "signature_rejected"`
Portabilidade / Refin	`credit_transfer.proposal`	`proposal_status: "canceled"`	`cancel_reason: "signature_rejected"`

Na consulta do grupo, a operação recusada aparece com status sign_rejected.

Erros

HTTP	Código	Quando ocorre
400	`DOC000118`	O certificador configurado para o requester não é suportado (apenas `qi_sign`).
404	`DOC000117`	Grupo não encontrado para a chave informada.
409	`DOC000119`	Grupo não está em `pending_batches` e não pode ser modificado.
400	`DOC000120`	Envio para assinatura sem nenhuma operação anexada.
400	`DOC000121`	Assinante de uma operação difere do assinante do grupo.
400	`DOC000122`	`origin_key` não informado na remoção.
404	`DOC000123`	`origin_key` não encontrado entre as operações do grupo.
400	`DOC000127`	O grupo já possui o número máximo de operações (5).
400	`DOC000128`	O `type` do documento pré-coletado não suporta o modo enviado (frente e verso × arquivo único). Veja Personal Document Type.
400	`DOC000129`	A jornada de assinatura configurada para o requester não coleta documento de identificação — o envio de documento pré-coletado não se aplica.
400	`DOC000130`	O `type` do documento pré-coletado não está entre os tipos aceitos pela configuração do requester.
404	`DOC000004`	`document_key` do documento pré-coletado não encontrada (inclui documento pertencente a outro requester).
400	`DOC000049`	Documento pré-coletado sem arquivo — o upload não foi concluído antes da abertura do grupo.
400	`DOC000126`	Configuração do requester incompleta.
404	`DOC000091`	Configuração de certificador não encontrada para o requester.

Enumeradores

Batch Group Type

Enumerador	Descrição
`social_security`	Operações de crédito consignado INSS.

Signature Method

Enumerador	Descrição
`email`	Link de assinatura enviado por e-mail.
`sms`	Link de assinatura enviado por SMS.
`whatsapp`	Link de assinatura enviado por WhatsApp.

Personal Document Type

Tipos aceitos no documento de identificação pré-coletado e os modos de envio suportados por cada um:

Enumerador	Documento	Frente e verso	Arquivo único
`rg`	Registro Geral (RG)	✔	—
`cnh`	Carteira Nacional de Habilitação	✔	✔
`cin`	Carteira de Identidade Nacional	—	✔

Frente e verso: envie document_identification_front_key + document_identification_back_key.
Arquivo único: envie apenas document_identification_full_key (documento digital, ex.: CNH digital).

Origin Type

Enumerador	Operação	`origin_key`
`credit_operation`	Crédito Novo / Refin (`POST /debt`)	`credit_operation_key`
`credit_transfer_proposal`	Portabilidade / Refin (`POST /v2/credit_transfer/proposal`)	`proposal_key`
`payroll_card_reservation`	Cartão Consignado (`POST /payroll_card_reservation/social_security`)	chave da reserva

Status do grupo

Status	Descrição
`pending_batches`	Grupo aberto, recebendo operações. Permite incluir/remover operações.
`pending_signature`	Enviado para assinatura; aguardando o beneficiário assinar.
`completed`	Todas as operações do grupo chegaram a um status terminal.
`canceled`	Grupo cancelado.

Status da operação

Status	Descrição
`pending_signature`	Operação anexada ao grupo, aguardando assinatura.
`signed`	Operação assinada com sucesso.
`sign_rejected`	Beneficiário recusou a assinatura da pasta.
`canceled`	Operação/pasta cancelada.

Migração do lote externo para o grupo

O fluxo de lote externo (document_batch_key) é substituído pelo fluxo de grupo (document_batch_group_key). Principais diferenças:

Você não cria mais o lote e adiciona documentos manualmente: cada operação (/debt, /v2/credit_transfer/proposal, cartão) já é um lote, e o grupo apenas os reúne.
O link de assinatura passa a ser único e no nível do grupo, retornado no envio para assinatura — não há link por operação.

Antigo (lote externo)	Novo (grupo)
`POST /document/document_batch` (`type: social_security_external_batch`)	`POST /document/document_batch_group`
`document_batch_key` na raiz da operação	`document_batch_group_key` na raiz da operação
`GET /document/document_batch/{key}`	`GET /document/document_batch_group/{key}`
`DELETE /document/document_batch/{key}/documents` (limpar tudo)	`PUT /document/document_batch_group/{key}/remove_batch` (remover uma operação)
`PUT /document/document_batch/{key}/send_to_signature`	`PUT /document/document_batch_group/{key}/send_to_signature`

1. Abrir o grupo​

Body Params​

Signer Object​

Documento de identificação pré-coletado​

Personal Document Object​

Response​

2. Incluir operações no grupo​

3. Consultar o grupo​

Path Params​

Exemplo de chamada​

Response​

Batch Object​

4. Remover operação do grupo​

Path Params​

Body Params​

Response​

5. Enviar para assinatura​

Path Params​

Response​

Acompanhamento​

Webhook de operação assinada​

Webhook de assinatura recusada​

Erros​

Enumeradores​

Batch Group Type​

Signature Method​

Personal Document Type​

Origin Type​

Status do grupo​

Status da operação​

Migração do lote externo para o grupo​

1. Abrir o grupo

Body Params

Signer Object

Documento de identificação pré-coletado

Personal Document Object

Response

2. Incluir operações no grupo

3. Consultar o grupo

Path Params

Exemplo de chamada

Response

Batch Object

4. Remover operação do grupo

Path Params

Body Params

Response

5. Enviar para assinatura

Path Params

Response

Acompanhamento

Webhook de operação assinada

Webhook de assinatura recusada

Erros

Enumeradores

Batch Group Type

Signature Method

Personal Document Type

Origin Type

Status do grupo

Status da operação

Migração do lote externo para o grupo