Enviar Documento Assinado
Anexa o PDF assinado da CCB a um contrato submetido no Modo B — ou seja, que está em AWAITING_SIGNED_DOCUMENT. Ao receber o documento, o contrato transita para RECEIVED e a formalização prossegue.
Request
POST /api/v1/fgts/contracts/{contractNumber}/documents
Autenticado: Authorization: Bearer {originatorToken} (perfil ROLE_ORIGINATOR).
Parâmetros
contractNumber
path
string (^\d{1,20}$)
Sim
Número do contrato gerado na submissão.
Corpo
Content-Type: application/json. O PDF trafega como base64 em campo JSON (não há upload multipart).
signedDocumentBase64
string (base64)
Sim
PDF assinado da CCB codificado em base64.
Response
contractNumber
string
Número do contrato.
status
string
RECEIVED — documento anexado; a formalização prossegue.
clientReference
string (nullable)
Eco do clientReference informado na submissão, ou null.
201 Created — documento assinado anexado; contrato em
RECEIVED.
Exemplo
O campo signedDocumentBase64 contém o PDF assinado da CCB codificado em base64 (valor encurtado no exemplo).
Próximo passo
Acompanhe a formalização por Consultar contrato ou pelo webhook (source = CONTRACT).
Erros
400
signedDocumentBase64 ausente, em branco, Base64 inválido, sem cabeçalho %PDF- ou acima de 10 MiB decodificado — errorCode = VALIDATION_ERROR, com o motivo em errors.signedDocumentBase64
401
Token ausente, inválido ou expirado — errorCode = UNAUTHORIZED
404
Contrato inexistente ou fora do escopo do token — errorCode = CONTRACT_NOT_FOUND
409
Contrato não está em AWAITING_SIGNED_DOCUMENT — errorCode = CONTRACT_IDEMPOTENCY_CONFLICT
415
Content-Type da requisição não é application/json — resposta padrão do framework, sem errorCode
4xx
O serviço de formalização recusou a requisição — o errorCode dele é repassado, ou CONTRACT_REQUEST_REJECTED quando não há código próprio. Ver Erros de formalização
429
Rate limit excedido (30 req/min por originator) — errorCode = RATE_LIMIT_EXCEEDED (headers Retry-After, X-RateLimit-*)
503
Serviço de formalização temporariamente indisponível — errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE (header Retry-After: 5)
500
Erro interno inesperado — errorCode = INTERNAL_ERROR
Os erros seguem o formato ProblemDetail (RFC 7807), com o campo errorCode. Ver Erros da API.
Upload posterior do documento assinado para um contrato submetido em Modo B (status: AWAITING_SIGNED_DOCUMENT). A requisição é application/json (AttachSignedDocumentRequest) com o campo signedDocumentBase64 (obrigatório). O ingress repassa o corpo ao formalizer e devolve o 201 { contractNumber, status, clientReference } com o status atualizado.
JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints /api/v1/**.
Inclua no header: Authorization: Bearer <token>.
Número do contrato gerado pelo formalizer. Validado na borda contra o padrão ^\d{1,20}$ para prevenção de path traversal antes do gateway.
00012345Pattern: ^\d{1,20}$Corpo JSON de POST /api/v1/fgts/contracts/{contractNumber}/documents (Modo B). Carrega o PDF assinado da CCB em base64; o contrato deve estar em AWAITING_SIGNED_DOCUMENT.
PDF assinado da CCB codificado em base64 (obrigatório). Deve representar um application/pdf válido de até 10 MiB decodificado. Ausente, em branco, base64 inválido, sem o cabeçalho %PDF- ou acima do limite → 400 VALIDATION_ERROR, com o motivo em errors.signedDocumentBase64.
JVBERi0xLjQKJ...Documento aceito; o status do contrato é atualizado pelo formalizer.
Resposta de POST /api/v1/fgts/contracts (e /documents, /reprocess). Repassa a resposta do formalizer. O ingress não gera o contractNumber; não há contractId (D16) nem s3Key (interno ao formalizer).
Número do contrato gerado pelo formalizer, sequencial por originador. O ingress NÃO gera este número.
00012345Status inicial atribuído pelo formalizer na admissão. RECEIVED: contrato recebido (PDF presente). AWAITING_SIGNED_DOCUMENT: aguardando upload posterior do documento assinado.
RECEIVEDValores possíveis: Identificador do cliente no originador, ecoado da requisição.
orig-ref-2026-0001Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo errors contém um mapa { "campo": "mensagem" } para cada campo inválido. O campo title é sempre "Bean validation error" e detail é sempre "One or more fields were invalid. See 'errors' for details.".
Rejeições de regra de negócio também chegam como 400, com errorCode próprio (ex.: CONTRACT_INSTALLMENTS_MISMATCH). Quando a rejeição aponta um campo do request, ela traz o mesmo errors e o mesmo detail; quando não há campo associado, errors é omitido e detail é o reason phrase do status.
Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header Authorization: Bearer <token>.
Recurso não encontrado — identificador inexistente ou ainda não processado.
Conflito com o estado atual do recurso — o pedido é válido, mas não cabe no estado em que o recurso está. O caso específico vem no errorCode do corpo; a descrição de cada rota lista os códigos que ela pode devolver.
Content-Type da requisição diferente de application/json. Resposta padrão do framework: type: about:blank e sem errorCode nem timestamp.
Serviço temporariamente indisponível. Aguarde Retry-After segundos e tente novamente.
POST /api/v1/fgts/contracts/{contractNumber}/documents HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"signedDocumentBase64": "JVBERi0xLjQKJ..."
}{
"contractNumber": "00012345",
"status": "RECEIVED",
"clientReference": "orig-ref-2026-0001"
}Resultado no webhook
Os marcos seguintes de formalização chegam ao webhook cadastrado com source = CONTRACT. Consulte Eventos, Payloads e o Fluxo de formalização.
Atualizado