Pular para o conteúdo principal

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.

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

Atributos

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

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)
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
Aviso importante!

Não utilize dados reais de pessoas (CPF, CNPJ etc.) em ambiente de sandbox.