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
NSUretornado 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
nsue para o reenvio. Para só conferir a situação, use Consultar Status.Reenvio: se o
nsujá está emSIGNED,PROCESSEDouSUPERSEDED, todo termo vivo do employee viraSUPERSEDEDe um documento novo é criado emSIGNED, comnsunovo. A resposta traz onsunovo, 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
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)
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
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.
JWT token fornecido pelo administrador
Identificador público do employee (16 caracteres)
NSU do documento de autorização
Arquivo PDF do termo assinado
Upload realizado com sucesso. No reenvio de um documento já assinado, o nsu
retornado é o do documento novo — diferente do informado no path.
Resposta do upload do documento de autorização assinado.
Identificador público opaco do documento de autorização. Pode vir ausente em registros antigos.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b07Status do envio do documento para processamento Dataprev
nsu inválido, estratégia diferente de ORIGINATOR_MANAGED, ou falha ao processar o arquivo (pode ser transitória — reenvie com chave nova).
Não autenticado
Permissão insuficiente
Employee não encontrado ou de outro originador.
Documento em transição de estado durante o reenvio: outra requisição simultânea
sobre o mesmo nsu reivindicou o documento primeiro. Só uma delas cria o documento
novo. Repetir a requisição resolve e reenvia de novo.
Janela de suspensão da Dataprev aberta (virada de competência). A operação não foi
registrada — reenvie depois de windowEnd.
Onde olhar para reagendar: o header Retry-After traz os segundos que faltam (é sempre
delta-seconds, nunca HTTP-date) e o corpo traz windowEnd como date-time. Use um dos dois —
não faça backoff exponencial, a volta tem hora marcada.
Falha ao fazer upload do documento para o armazenamento
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