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

Upload de Documento Assinado

Envia o PDF do termo de autorização já assinado, no último passo do fluxo Termo Gerado pela Giro. A Giro envia o documento à Dataprev automaticamente.

  • Requer o NSU retornado por Criar Documento de Autorização e o PDF assinado pelo trabalhador no seu provedor.

  • Sempre reautoriza: mesmo com autorização Dataprev válida, o envio reautoriza na Dataprev e dispara uma consulta de margem nova, com custo real na Dataprev. Vale para o primeiro envio do nsu e para o reenvio. Para só conferir a situação, use Consultar Status.

  • Reenvio: se o nsu já está em SIGNED, PROCESSED ou SUPERSEDED, todo termo vivo do employee vira SUPERSEDED e um documento novo é criado em SIGNED, com nsu novo. A resposta traz o nsu novo, não o do path.

  • Se já existe autorização em andamento para o employee, o reenvio aproveita o resultado dela.

Request

POST /api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed

Parâmetro
Local
Tipo
Descrição

publicId

path

string

Identificador público do employee (16 caracteres)

nsu

path

string

NSU do documento de autorização (retornado ao criar o documento)

signedDocument

body (multipart)

file

Arquivo PDF do termo de autorização assinado

Content-Type: multipart/form-data, com um único campo de arquivo signedDocument.

Response (200)

Campo
Tipo
Descrição

authorizationDocumentPublicId

string (uuid)

Identificador público do documento

nsu

string

NSU do documento (no reenvio, o novo)

status

string

Status do envio: PROCESSING (documento recebido e em processamento), SUCCESS ou ERROR

message

string

Mensagem descritiva

Depois, consulte o status da autorização até AUTHORIZED ou aguarde o webhook AUTHORIZATION_COMPLETED, seguido de MARGIN_QUERY_COMPLETED (a consulta de margem é automática; não é preciso chamar GET /margin).

Exemplo

Resposta:

Erros

Código

errorCode

Situação

400

—

Documento de autorização não encontrado para NSU: <nsu> — nsu inexistente, de outro originador ou de outro employee

400

—

Upload de documento de autorização assinado disponível apenas para ORIGINATOR_MANAGED

400

—

Erro ao processar documento de autorização assinado — falha ao processar o arquivo, inclusive transitória. Consulte o status e reenvie com chave nova

404

—

Employee não encontrado — inexistente ou de outro originador

423

DATAPREV_SUSPENSION_WINDOW

Janela de suspensão da Dataprev

Erros comuns a todos os endpoints — 401, 403 de token, 409 de Idempotency-Key em processamento, 500 e 503 — e o formato ProblemDetail estão em Erros da API.

Upload do documento de autorização assinado

post
/api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed

Envia o PDF do termo de autorização já assinado (ORIGINATOR_MANAGED). O documento é enviado automaticamente para o Dataprev após o upload.

Sempre reautoriza: mesmo que o empregado já possua autorização Dataprev válida, o envio do termo reautoriza na Dataprev (prazo renovado) e dispara uma consulta de margem nova — isso tem custo real na Dataprev. Vale tanto para o primeiro envio do nsu quanto para o reenvio. Para apenas consultar a situação, use GET /{publicId}/authorization/status.

Reenvio (documento já assinado): quando o nsu informado já está em estado terminal de assinatura (SIGNED, PROCESSED ou SUPERSEDED), a requisição não falha mais com 400. Todo termo vivo do employee (SIGNED ou PROCESSED) é congelado como SUPERSEDED (lastro imutável) e um documento novo é criado já em SIGNED, com nsu novo, apontando para o PDF recém-enviado. O employee fica sempre com um único termo assinado vivo, inclusive quando o nsu informado é antigo.

A resposta traz o nsu do documento novo, não o informado no path.

Quando já existe uma autorização em voo para o mesmo empregado, o reenvio não gera um AUTHORIZE_QUERY adicional — o resultado em voo atende os dois envios.

Autorizações
AuthorizationstringObrigatório

JWT token fornecido pelo administrador

Parâmetros de rota
publicIdstringObrigatório

Identificador público do employee (16 caracteres)

nsustringObrigatório

NSU do documento de autorização

Corpo
signedDocumentstring · binaryObrigatório

Arquivo PDF do termo assinado

Respostas
200

Upload realizado com sucesso. No reenvio de um documento já assinado, o nsu retornado é o do documento novo — diferente do informado no path.

application/json

Resposta do upload do documento de autorização assinado.

authorizationDocumentPublicIdstring · uuid · anulávelOpcional

Identificador público opaco do documento de autorização. Pode vir ausente em registros antigos.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b07
nsustringOpcional
statusstring · enumOpcional

Status do envio do documento para processamento Dataprev

Valores possíveis:
messagestringOpcional
post/api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed
POST /api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed HTTP/1.1
Host: ingress.gtpayroll.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 27

{
  "signedDocument": "binary"
}
{
  "authorizationDocumentPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b07",
  "nsu": "20250115000001",
  "status": "PROCESSING",
  "message": "Documento recebido e enviado para processamento."
}

Atualizado