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

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, cartão) 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.
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.

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"
    }
}

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

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

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,
    "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.
`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

Acompanhamento

Após o envio, o beneficiário assina todas as operações com um único link. Cada operação evolui de forma independente conforme o beneficiário assina, e o grupo é concluído (completed) quando nenhuma operação permanece em pending_signature. Acompanhe o desfecho de cada operação pelos webhooks do respectivo produto (dívida, proposta de portabilidade/refin, reserva de cartão) ou pela consulta do grupo.

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	`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.

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​

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​

Erros​

Enumeradores​

Batch Group Type​

Signature Method​

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

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

Erros

Enumeradores

Batch Group Type

Signature Method

Origin Type

Status do grupo

Status da operação

Migração do lote externo para o grupo