Consulta de margem - melhor vínculo
Lê a margem consignável vigente do trabalhador, no melhor vínculo elegível. Não dispara consulta à Dataprev: a primeira consulta é automática após a autorização (webhook MARGIN_QUERY_COMPLETED), e uma margem nova se pede em Solicitar Atualização de Margem (POST no mesmo caminho).
Request
GET /api/v1/originator/employees/{publicId}/margin
Autenticação: Authorization: Bearer {originatorToken}.
Parâmetros
publicId
path
string
Sim
Identificador público do employee (16 caracteres)
Response
status
string (enum)
OK, PENDING, PROCESSING, EXPIRED, TERM_EXPIRED, NO_BONDS, NOT_ELIGIBLE, NO_MARGIN, ERROR.
reason
string
Motivo associado ao status (ex.: em NOT_ELIGIBLE ou ERROR).
200
Resposta com status no corpo. Não significa necessariamente margem disponível: OK traz a margem; TERM_EXPIRED indica autorização vencida e o trabalhador precisa reautorizar (não há webhook para isso)
202
Em processamento (status: PROCESSING). Consulte de novo em alguns segundos
404
Employee não encontrado
422
MARGIN_REFRESH_REQUIRED: sem margem vigente e sem consulta em andamento
O GET read-only
O GET avalia, nesta ordem:
Há margem utilizável vigente
200 com status: OK e os vínculos
Há consulta de margem (ou de vínculos) em andamento
202 com status: PROCESSING
Nenhuma das duas
422 com errorCode: MARGIN_REFRESH_REQUIRED
Repetir só o GET não sai do 422. Trate-o como "chame o POST", não como erro fatal:
GET /margin→422 MARGIN_REFRESH_REQUIREDPOST /margin→202Aguarde o webhook
MARGIN_QUERY_COMPLETED(ou consulte oGETaté200)
Ramifique pelo properties.errorCode, que é estável; o detail é texto livre e pode mudar. Exemplo de corpo:
Campos da resposta (employmentRelationships)
Identificação
publicId, bondPublicId, registrationNumber, employerTaxId, employerName, workerName, birthDate, motherName, gender, admissionDate, status
Margem e elegibilidade
totalEarnings, marginBase, availableMargin, usableMargin, isEligible, ineligibilityReasons, dataprevExpiresAt, marginCacheExpiresAt, eligibility
Dados profissionais (Dataprev)
workerCategory, workerCategoryDescription, workerCboCode, workerCboDescription, employerCnae, employerCnaeDescription, employerActivityStartDate, employerTaxIdType
Outros (Dataprev)
activeConsignmentsCount, nationalityCode, nationalityDescription, blockingTypeCode, blockingTypeDescription, terminationDate, terminationReason, politicallyExposedPerson
Alertas do trabalhador (Dataprev)
alerts (ver Alertas do trabalhador)
Empréstimos legados (Dataprev)
legacyLoans (ver Empréstimos legados)
FGTS
fgtsAvailability: último resultado de FGTS disponível do vínculo, ou null
publicIdé o valor a enviar ememploymentRelationshipPublicIdna simulação, elegibilidade e proposta.bondPublicIdé o aceito nas consultas por vínculo.Valores enumerados: Categoria do Trabalhador, Motivo de Desligamento, Motivo de Inelegibilidade e PEP.
workerNameé o nome que a Dataprev tem cadastrado, e é o nome usado na averbação. Pode virnullem vínculos antigos; nesse caso a averbação usa o nome cadastrado no employee (ASCII em maiúsculas).
Alertas do trabalhador (alerts)
Array opcional com alertas de afastamento ou desligamento informados pela Dataprev. Vem ausente ou null quando não há alertas. Os campos suspension* só são preenchidos em SUSPENSION; termination* e priorNotice*, só em TERMINATION. Os demais vêm null.
alertType
string (enum)
SUSPENSION (afastamento) ou TERMINATION (desligamento).
alertTypeDescription
string
"Afastamento" ou "Desligamento".
referenceDate
string (date) | null
Data de referência do alerta.
eventId
integer | null
Identificador do evento na Dataprev.
suspensionReasonCode
integer | null
Código do motivo do afastamento.
suspensionReasonDescription
string | null
Descrição do motivo do afastamento.
suspensionStartDate
string (date) | null
Início do afastamento.
suspensionEndDate
string (date) | null
Término do afastamento.
terminationReasonCode
integer | null
Código do motivo do desligamento.
terminationReasonDescription
string | null
Descrição do motivo do desligamento.
terminationDate
string (date) | null
Data do desligamento.
priorNoticeDate
string (date) | null
Data do aviso prévio.
priorNoticeEndDate
string (date) | null
Fim do aviso prévio.
Datas no formato AAAA-MM-DD.
Empréstimos legados (legacyLoans)
Array opcional com os contratos (consignados e não consignados) que o trabalhador já tem, informados pela Dataprev. Vem ausente ou null quando não há; campos indisponíveis vêm null.
financialInstitutionCode
integer | null
Código da instituição financeira.
contractNumber
string | null
Número do contrato.
contractType
string (enum) | null
NON_PAYROLL_UNSECURED (não consignado sem garantia) ou PAYROLL_DEDUCTED (com desconto em folha).
contractTypeDescription
string | null
Descrição do tipo do contrato.
contractStartDate
string (date) | null
Início do contrato (AAAA-MM-DD).
contractEndDate
string (date) | null
Fim do contrato (AAAA-MM-DD).
totalInstallments
integer | null
Total de parcelas.
paidInstallments
integer | null
Parcelas pagas.
installmentAmount
number | null
Valor da parcela.
loanAmount
number | null
Valor do empréstimo.
disbursedAmount
number | null
Valor liberado.
outstandingBalance
number | null
Saldo devedor.
monthlyInterestRate
number | null
Taxa mensal.
monthlyCet
number | null
CET mensal.
sourceUpdatedAt
string | null
Data/hora de atualização do registro na Dataprev (texto bruto).
Exemplo
Margem disponível (200)
Alerta de desligamento (TERMINATION)
Item de alerts com alertType: TERMINATION:
Em processamento (202)
Erros
Código
errorCode
Situação
404
EMPLOYEE_NOT_FOUND
Employee não encontrado ou de outro originador
422
CPF_INELIGIBLE
O último termo de autorização foi reprovado pela Dataprev como inelegível. Atualizar Margem reenvia a autorização se o termo tiver menos de 30 dias; senão, colha novo termo
422
MARGIN_REFRESH_REQUIRED
Sem margem vigente e sem consulta em andamento. Chame Solicitar Atualização de Margem
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.
Consulta margem consignável de um employee.
Durante uma janela de suspensão da Dataprev este GET responde 423, apesar de ser leitura local. Durante a janela, o 423 vale para toda a consulta de margem.
JWT token fornecido pelo administrador
Identificador público do employee (16 caracteres)
Margem retornada com sucesso
Status da consulta de margem no convênio.
| Valor | Significado |
|---|---|
| OK | Margem disponível e elegível |
| PENDING | Consulta em análise |
| PROCESSING | Processando dados no convênio |
| EXPIRED | Margem expirada (prazo Dataprev) |
| TERM_EXPIRED | Prazo do contrato expirado |
| NO_BONDS | Sem vínculos ativos |
| NOT_ELIGIBLE | Não elegível às regras do produto |
| NO_MARGIN | Sem margem disponível |
| ERROR | Erro na consulta |
Motivo associado ao status (ex. quando NOT_ELIGIBLE ou ERROR).
Consulta em processamento
Não autenticado
Permissão insuficiente
Employee não encontrado ou de outro originador.
Margem não pode ser lida no estado atual.
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.
GET /api/v1/originator/employees/{publicId}/margin HTTP/1.1
Host: ingress.gtpayroll.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "OK",
"reason": null,
"employmentRelationships": [
{
"id": 7,
"registrationNumber": "12345678901",
"employerTaxId": "12345678000199",
"employerName": "Empresa Exemplo Ltda",
"workerName": "FULANO DA SILVA",
"birthDate": "1990-05-12",
"admissionDate": "2020-03-15",
"status": "ACTIVE",
"totalEarnings": 4850.73,
"marginBase": 4850.73,
"availableMargin": 1697.76,
"usableMargin": 1697.76,
"isEligible": true,
"workerCategory": "GENERAL_EMPLOYEE",
"workerCategoryDescription": "Empregado - Geral",
"workerCboCode": "521130",
"workerCboDescription": "ATENDENTE DE FARMACIA - BALCONISTA",
"employerCnae": "4771701",
"employerCnaeDescription": "COMERCIO VAREJISTA DE PRODUTOS FARMACEUTICOS, SEM MANIPULACAO DE FORMULAS",
"employerActivityStartDate": "2002-09-04",
"activeConsignmentsCount": 1,
"nationalityCode": 76,
"nationalityDescription": "BRASIL",
"employerTaxIdType": "CNPJ",
"blockingTypeCode": 0,
"blockingTypeDescription": "Sem Bloqueio",
"politicallyExposedPerson": "NOT_EXPOSED"
}
]
}Com a margem disponível, siga para Criar Simulação.
Atualizado