Assinatura em Lote

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

Fluxo recomendado para compra de dívida — onde N duplas debt_purchase + refinancing + 1 refin/refin consolidador podem ser assinadas num único envelope (servidor assina uma vez só).

Regras do lote

Mesma titularidade: todas as operações do lote devem ser do CPF (ou do mesmo representante legal) do servidor. Incluir CPF "A" e CPF "B" no mesmo lote gera erro síncrono no POST /debt.

Tipos permitidos: o lote SIAPE aceita apenas POST /debt com collateral_type: federal_payroll.

1. Abrir o lote

ENDPOINT

/document/document_batch

MÉTODO

POST

Request Body

{
  "type": "federal_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote SIAPE compra-divida - 5ed20003-0610-46d2-88cc-a5d0de640696",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}

Campos chave

Campo	Tipo	Descrição
type	string	Fixo: federal_payroll_external_batch
certifier_type	string	Fixo: qi_sign
batch_name	string	Nome identificador do lote (máximo 100 caracteres)
request_control_key	string (UUIDv4)	Idempotência — não reutilize entre lotes

Response Body

{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}

Guarde o document_batch_key retornado — ele é referenciado em todas as próximas chamadas.

2. Incluir operações no lote

Ao criar cada operação SIAPE, envie document_batch_key na raiz do payload do POST /debt (mesmo nível dos demais campos principais).

ENDPOINT

/debt

MÉTODO

POST

{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
  "borrower": { "...": "demais campos do borrower" },
  "financial": { "...": "demais campos financeiros" },
  "operation_type": "refinancing",
  "collaterals": [
    {
      "collateral_type": "federal_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "refinanced_credit_operations": [{ "...": "operation_key + contrato externo" }]
      }
    }
  ]
}

O restante do body segue o contrato do POST /debt. Consulte os roteiros da Margem Livre ou Portabilidade + Refinanciamento conforme a modalidade.

Compra de dívida cabe num lote só

Pra compra de dívida (debt_purchase + refinancing port-enrustido), todas as duplas Op A + Op B + o refin/refin consolidador podem entrar no mesmo lote.

3. Consultar documentos do lote

Recomendado antes de fechar o lote para conferir os documentos agrupados.

ENDPOINT

/document/document_batch/DOCUMENT_BATCH_KEY

MÉTODO

GET

Response Body

{
  "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": "ccb_pre_price_days"
    }
  ]
}

4. Limpar documentos do lote (opcional)

Remove todos os documentos vinculados ao lote — útil pra reagrupar do zero se identificar inconsistência antes do envio.

ENDPOINT

/document/document_batch/DOCUMENT_BATCH_KEY/documents

MÉTODO

DELETE

Body vazio. Response: HTTP 200.

5. Enviar para assinatura

Fecha o lote e dispara os documentos pro QI Sign. Antes desse PUT, os documentos não vão pro servidor. É o gatilho final.

ENDPOINT

/document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature

MÉTODO

PUT

Body: {}. Response: HTTP 200.

Erros comuns

HTTP	Código	Endpoint	Quando ocorre
404	DOC000007	GET /document/document_batch/DOCUMENT_BATCH_KEY	document_batch_key inexistente
409	DOC000103	POST /document/document_batch	request_control_key duplicado (idempotência violada)

Exemplo — DOC000103 (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

Validação de mesmo CPF/representante no lote retorna erro no POST /debt (não no endpoint do lote). O corpo de erro segue o catálogo do /debt.