跳到主要内容

Assinatura em lote (INSS)

Fluxo para agrupar várias operações em um único envelope de assinatura do QI Sign: você abre o lote, cria as operações referenciando o lote, confere (opcionalmente limpa) e dispara o envio para assinatura.

Fluxo legado

Este é o fluxo de lote externo (document_batch_key). Ele permanece disponível, mas o caminho recomendado para novas integrações é a Assinatura em grupo (document_batch_group_key), que reúne as operações em uma pasta e dispara uma única assinatura para o beneficiário. Consulte a tabela de migração.

Regras do lote

Mesma titularidade: todas as operações do lote devem ser do CPF ou do mesmo representante legal. Incluir CPF “A” e CPF “B” no mesmo lote gera erro síncrono no POST da operação.

Tipos permitidos: por ora o fluxo aceita operações INSS de Crédito Novo e Cartão Consignado no mesmo lote.

Abrir o lote​

Request

ENDPOINT
/document/document_batch
MÉTODO
POST

Body

typestringobrigatórioFixo: social_security_external_batch.certifier_typestringobrigatórioFixo: qi_sign.batch_namestringobrigatórioNome do lote para identificação; máximo 100 caracteres. Use um identificador único por lote na sua operação.request_control_keystring (UUID v4)obrigatórioChave de idempotência; não reutilize entre lotes distintos.personal_documentobjectopcionalDocumento de identificação do tomador já coletado pelo parceiro, para dispensar a foto do documento durante a assinatura. Veja Documento de identificação pré-coletado.
ENDPOINT
POST /document/document_batch
REQUEST BODY (exemplo)
{
  "type": "social_security_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote INSS - pedido-2025-03-001",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}

Response

STATUS
201

Atributos

document_batch_keystringIdentificador do lote. Guarde para os próximos passos.
RESPONSE BODY
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}

Documento de identificação pré-coletado​

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

Os arquivos ficam vinculados ao lote, mas não são assinados: eles não entram no envelope como documentos assináveis e não participam do send_to_signature.

O envio acontece em duas etapas.

1. Suba os arquivos​

Faça o upload de cada arquivo pelo fluxo de upload de documentos e guarde a document_key retornada — um arquivo por lado do documento, ou um arquivo único no caso de documento digital.

Não é preciso classificar o arquivo no upload: é o campo em que você informa a chave que declara qual lado do documento ela representa.

CampoArquivo esperado
document_identification_front_keyFrente do documento de identificação
document_identification_back_keyVerso do documento de identificação
document_identification_full_keyDocumento digital completo, em arquivo único

2. Referencie as chaves na abertura do lote​

Personal Document Object

typestringobrigatórioTipo do documento de identificação. Veja Tipos aceitos.document_identification_front_keystringcondicionaldocument_key da frente. Obrigatório no modo frente e verso, junto com ..._back_key.document_identification_back_keystringcondicionaldocument_key do verso. Obrigatório no modo frente e verso, junto com ..._front_key.document_identification_full_keystringcondicionaldocument_key do arquivo único (documento digital). Não pode ser combinado com as chaves de frente e verso.
REQUEST BODY (abertura do lote com documento pré-coletado)
{
  "type": "social_security_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote INSS - pedido-2025-03-001",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
  "personal_document": {
    "type": "rg",
    "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
    "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
  }
}

Tipos de documento aceitos​

typeDocumentoFrente e versoArquivo único
rgRegistro Geral (RG)✔—
cnhCarteira Nacional de Habilitação✔✔
cinCarteira 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).

O conjunto de tipos efetivamente aceito também depende da jornada de assinatura configurada para o seu requester. Um type fora dessa configuração retorna DOC000130.

Regras do documento pré-coletado
  • Envie frente + verso ou o arquivo único — nunca os dois modos juntos.
  • Cada type suporta modos específicos; combinação inválida retorna DOC000128.
  • Os arquivos devem pertencer ao seu requester e já ter o upload concluído. Chave inexistente ou de outro requester retorna DOC000004; arquivo ausente retorna DOC000049.
  • Cada arquivo só pode ser usado em um lote. Reaproveitar uma document_key já vinculada retorna DOC000137.
  • O envio é feito apenas na abertura do lote — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, a criação do lote falha por inteiro (nenhum lote é criado).
  • A requisição precisa identificar o titular dos arquivos: envie o header SELECTED-AGENT. Sem ele, a abertura retorna QIT000004.

Incluir operações no lote​

Ao criar cada operação, envie document_batch_key na raiz do JSON (mesmo nível dos demais campos principais do produto).

Cartão
POST /payroll_card_reservation/social_security
Empréstimo
POST /debt
document_batch_key string obrigatório no fluxo com lote O mesmo document_batch_key retornado na abertura do lote; envie na raiz do payload de criação da operação.
Trecho ilustrativo (raiz do payload)
{
  "document_batch_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.

Consultar documentos do lote​

Request

ENDPOINT
/document/document_batch/DOCUMENT_BATCH_KEY
MÉTODO
GET

Path params

document_batch_keystringobrigatórioChave do lote.

Recomendado antes de fechar o lote para conferir tipos e chaves de documento agrupados.

ENDPOINT
GET /document/document_batch/YOUR_DOCUMENT_BATCH_KEY

Response

STATUS
200

Atributos

document_batch_keystringChave do lote.documentsarrayLista de documentos; cada item costuma trazer document_key e document_type (ex.: ccb_pre_price_days, payroll_card_term).
RESPONSE BODY (exemplo)
{
  "document_batch_key": "1eee4ec2-05f5-45ef-aa64-38bb3d9de02f",
  "documents": [
    {
      "document_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
      "document_type": "ccb_pre_price_days"
    },
    {
      "document_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
      "document_type": "withdrawal_operation_term"
    },
    {
      "document_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
      "document_type": "payroll_card_term"
    },
    {
      "document_key": "eafdb3bd-5c21-415f-bdc2-8e366d54094c",
      "document_type": "payroll_card_consent_term"
    }
  ]
}

Limpar documentos do lote​

Remove todos os documentos vinculados ao lote (para reagrupar do zero, se necessário).

Request

ENDPOINT
/document/document_batch/DOCUMENT_BATCH_KEY/documents
MÉTODO
DELETE

Path params

document_batch_keystringobrigatórioChave do lote.
ENDPOINT
DELETE /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/documents

Response

STATUS
200

Corpo de resposta conforme padrão da API para sucesso neste recurso (pode ser vazio ou objeto mínimo).

RESPONSE BODY (exemplo)
{}

Enviar para assinatura​

Fecha o lote e dispara os documentos para assinatura no QI Sign.

Request

ENDPOINT
/document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature
MÉTODO
PUT

Path params

document_batch_keystringobrigatórioChave do lote.

Body: objeto JSON vazio {}.

ENDPOINT
PUT /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/send_to_signature
REQUEST BODY
{}

Response

STATUS
200
RESPONSE BODY (exemplo)
{}

Erros​

HTTPCódigoTítulo (exemplo)EndpointQuando ocorre
404DOC000007(lote não encontrado)GET /document/document_batch/DOCUMENT_BATCH_KEYdocument_batch_key inexistente
409DOC000103Bad RequestPOST /document/document_batchrequest_control_key duplicado (idempotência violada de forma inválida)
400DOC000128Bad RequestPOST /document/document_batchO type não suporta o modo enviado (frente e verso × arquivo único)
400DOC000129Bad RequestPOST /document/document_batchA jornada configurada para o requester não coleta documento de identificação
400DOC000130Bad RequestPOST /document/document_batchO type não está entre os tipos aceitos pela configuração do requester
400DOC000137Bad RequestPOST /document/document_batchdocument_key do documento pré-coletado já vinculada a outro lote
404DOC000004Bad RequestPOST /document/document_batchdocument_key do documento pré-coletado não encontrada (inclui arquivo de outro requester)
400DOC000049Bad RequestPOST /document/document_batchDocumento pré-coletado sem arquivo — upload não concluído antes da abertura
403QIT000004Bad RequestPOST /document/document_batchpersonal_document enviado sem o header SELECTED-AGENT
Exemplo de erro (idempotência)
{
  "code": "DOC000103",
  "title": "Bad Request",
  "description": "request_control_key already exists",
  "translation": "Chave de controle da request já existe.",
  "http_status": 409
}
Conflito de titularidade ou tipo

Validações de mesmo CPF/representante e de tipo de operação no lote costumam retornar erro no POST da operação (/debt ou /payroll_card_reservation/social_security), não no endpoint do lote. O corpo de erro segue o catálogo do recurso chamado.

Migração de paths

Endpoints antigos foram substituídos pelos paths abaixo:

AntigoNovo
POST /document_batch/externalPOST /document/document_batch
GET /document_batch/external/DOCUMENT_BATCH_KEYGET /document/document_batch/DOCUMENT_BATCH_KEY
PUT /document_batch/DOCUMENT_BATCH_KEY/send_to_signaturePUT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature