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

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

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

publicId

path

string

Sim

Identificador público do employee (16 caracteres)

Response

Campo
Tipo
Descrição

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

employmentRelationships

array

Vínculos com margem e dados Dataprev (ver abaixo).

Código
Significado

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:

Situação
Resposta

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:

  1. GET /margin → 422 MARGIN_REFRESH_REQUIRED

  2. POST /margin → 202

  3. Aguarde o webhook MARGIN_QUERY_COMPLETED (ou consulte o GET até 200)

Ramifique pelo properties.errorCode, que é estável; o detail é texto livre e pode mudar. Exemplo de corpo:

Campos da resposta (employmentRelationships)

Grupo
Campos

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)

Empréstimos legados (Dataprev)

legacyLoans (ver Empréstimos legados)

FGTS

fgtsAvailability: último resultado de FGTS disponível do vínculo, ou null

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.

Campo
Tipo
Descrição

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.

Campo
Tipo
Descrição

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.

Consultar Margem

get
/api/v1/originator/employees/{publicId}/margin

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.

Autorizações
AuthorizationstringObrigatório

JWT token fornecido pelo administrador

Parâmetros de rota
publicIdstringObrigatório

Identificador público do employee (16 caracteres)

Respostas
200

Margem retornada com sucesso

application/json
statusstring · enumOpcional

Status da consulta de margem no convênio.

ValorSignificado
OKMargem disponível e elegível
PENDINGConsulta em análise
PROCESSINGProcessando dados no convênio
EXPIREDMargem expirada (prazo Dataprev)
TERM_EXPIREDPrazo do contrato expirado
NO_BONDSSem vínculos ativos
NOT_ELIGIBLENão elegível às regras do produto
NO_MARGINSem margem disponível
ERRORErro na consulta
Valores possíveis:
reasonstring · anulávelOpcional

Motivo associado ao status (ex. quando NOT_ELIGIBLE ou ERROR).

get/api/v1/originator/employees/{publicId}/margin
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