Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Use esta operação apenas no fluxo Modo B (contrato submetido sem signedDocumentBase64). No Modo A, o documento já foi enviado na própria submissão e o contrato não está em AWAITING_SIGNED_DOCUMENT — anexar novamente retorna 409. Ver Submeter contrato.

Request

POST /api/v1/fgts/contracts/{contractNumber}/documents

Autenticado: Authorization: Bearer {originatorToken} (perfil ROLE_ORIGINATOR).

Parâmetros

Parâmetro
Local
Tipo
Obrigatório
Descrição

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

Campo
Tipo
Obrigatório
Descrição

signedDocumentBase64

string (base64)

Sim

PDF assinado da CCB codificado em base64.

Response

Campo
Tipo
Descrição

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

Código
Situação

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.

Envia o PDF assinado de um contrato (Modo B)

post
/api/v1/fgts/contracts/{contractNumber}/documents

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.

Autorizações
AuthorizationstringObrigatório

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

Parâmetros de rota
contractNumberstringObrigatório

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.

Example: 00012345Pattern: ^\d{1,20}$
Corpo

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.

signedDocumentBase64string · byteObrigatório

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.

Example: JVBERi0xLjQKJ...
Respostas
201

Documento aceito; o status do contrato é atualizado pelo formalizer.

application/json

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

contractNumberstringObrigatório

Número do contrato gerado pelo formalizer, sequencial por originador. O ingress NÃO gera este número.

Example: 00012345
statusstring · enumObrigatório

Status inicial atribuído pelo formalizer na admissão. RECEIVED: contrato recebido (PDF presente). AWAITING_SIGNED_DOCUMENT: aguardando upload posterior do documento assinado.

Example: RECEIVEDValores possíveis:
clientReferencestring · máx: 255 · anulávelOpcional

Identificador do cliente no originador, ecoado da requisição.

Example: orig-ref-2026-0001
post/api/v1/fgts/contracts/{contractNumber}/documents
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