> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md).

# Solicitar Atualização de Margem

Descarta a margem vigente do trabalhador e dispara uma consulta nova à Dataprev, uma por vínculo elegível. A primeira consulta já é automática após a autorização; use este `POST` quando quiser margem mais recente que a vigente, por exemplo antes de uma nova simulação dias depois da autorização.

* O employee precisa ser do originador e estar com a [autorização Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md) em `AUTHORIZED`; senão, `422 EMPLOYEE_NOT_AUTHORIZED`.
* **Rate limit dedicado**, menor que o do resto da API, porque cada chamada gera consultas cobradas na Dataprev. Estourou, `429`: respeite o `Retry-After`. Não use este `POST` para acompanhar o resultado; use o webhook ou o `GET /margin`.
* A margem vigente é descartada **antes** do disparo, para um `GET /margin` concorrente não devolver a margem antiga como se fosse nova. Até o resultado chegar, o `GET /margin` responde `202 PROCESSING` (ou `422 MARGIN_REFRESH_REQUIRED`, ver [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md)): não espere `200` logo depois do `POST`.

## Request

`POST /api/v1/originator/employees/{publicId}/margin`

Autenticação: `Authorization: Bearer {originatorToken}`. Sem corpo.

### 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                                                                                                                                                                                                                                                                                                                    |
| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`  | `string` \| `null`  | Primeira consulta criada. Acompanhe em [`GET /margin-queries/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md).                                                                                                                    |
| `requestIds` | `array` de `string` | Todas as consultas criadas, uma por vínculo elegível. Vazio quando não houve consulta a criar.                                                                                                                                                                                                                               |
| `status`     | `string` (enum)     | `PROCESSING` quando o refresh foi despachado; qualquer outro valor é terminal. Mesmos valores do [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md): `OK`, `PENDING`, `PROCESSING`, `EXPIRED`, `TERM_EXPIRED`, `NO_BONDS`, `NOT_ELIGIBLE`, `NO_MARGIN`, `ERROR`. |

`requestId` pode vir `null` com `202`: a lista de vínculos também precisou ser atualizada e ainda não há consulta por vínculo. O resultado chega pelo webhook `MARGIN_QUERY_COMPLETED`. Trate `requestId` como opcional.

| Código | Significado                                                                                                                                                                                                        |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `202`  | Refresh despachado (`status: PROCESSING`). Aguarde o webhook `MARGIN_QUERY_COMPLETED` ou consulte o [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) |
| `200`  | Encerrou sem consulta pendente (ex.: `NO_BONDS`, `NOT_ELIGIBLE`). **Não** significa margem atualizada: veja o `status`                                                                                             |

## Exemplo

```http
POST /api/v1/originator/employees/Kj8mP2xQ9nR4sT6v/margin HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
```

### Refresh despachado (202)

```json
{
  "requestId": "0198f319-cf57-706a-d08d-bf4a6c9e7d5c",
  "requestIds": ["0198f319-cf57-706a-d08d-bf4a6c9e7d5c"],
  "status": "PROCESSING"
}
```

### Encerrado sem consulta pendente (200)

```json
{
  "requestId": null,
  "requestIds": [],
  "status": "NO_BONDS"
}
```

## Erros

| Código  | `errorCode`                  | Situação                                                                                                                                                                                                                                                           |
| ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 404     | `EMPLOYEE_NOT_FOUND`         | Employee não encontrado ou de outro originador                                                                                                                                                                                                                     |
| 422     | `EMPLOYEE_NOT_AUTHORIZED`    | Employee sem autorização Dataprev válida e sem termo assinado de menos de 30 dias para reenviar                                                                                                                                                                    |
| 423     | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev                                                                                                                                                                                                                                    |
| 429     | —                            | Mais de 20 requisições por segundo. Respeite o `Retry-After`                                                                                                                                                                                                       |
| webhook | —                            | Falhas da consulta chegam por `MARGIN_QUERY_FAILED`; sem vínculo ou sem vínculo elegível chega `MARGIN_QUERY_COMPLETED` com `status` `NO_BONDS`/`NOT_ELIGIBLE`. Ver [Erros assíncronos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md#async) |

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](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

## Solicitar refresh de margem

> Descarta a margem vigente do employee e dispara uma consulta por vínculo elegível.\
> Diferente do \`POST .../authorized-bonds/{bondPublicId}/margin-queries\`, que é cirúrgico por\
> vínculo, este endpoint cobre o employee inteiro.\
> \
> Descarta antes de despachar de propósito: sem isso um \`GET /margin\` concorrente\
> devolveria \`200\` com a margem antiga enquanto o refresh roda.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Margin","description":"Consulta de margem consignável"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/employees/{publicId}/margin":{"post":{"operationId":"refreshMargin","summary":"Solicitar refresh de margem","description":"Descarta a margem vigente do employee e dispara uma consulta por vínculo elegível.\nDiferente do `POST .../authorized-bonds/{bondPublicId}/margin-queries`, que é cirúrgico por\nvínculo, este endpoint cobre o employee inteiro.\n\nDescarta antes de despachar de propósito: sem isso um `GET /margin` concorrente\ndevolveria `200` com a margem antiga enquanto o refresh roda.\n","tags":["Margin"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}}],"responses":{"200":{"description":"Refresh encerrado sem consulta pendente (`NO_BONDS`, `NOT_ELIGIBLE`, ...).\nNão há `requestId` a consultar.\n","content":{"application/json":{"schema":{"type":"object","description":"Resultado do refresh explícito de margem. O refresh sempre começa listando os vínculos na\nDataprev, então `requestId` vem nulo e `requestIds` vazio: a consulta por vínculo só é criada\ndepois que a listagem volta. Os identificadores chegam no webhook `MARGIN_QUERY_COMPLETED`,\num por vínculo.\n","properties":{"requestId":{"type":"string","nullable":true,"description":"Sempre nulo — mantido por compatibilidade. Use o `requestId` do webhook\n`MARGIN_QUERY_COMPLETED`, consultável em `GET /api/v1/originator/margin-queries/{requestId}`.\n"},"requestIds":{"type":"array","description":"Sempre vazio — mantido por compatibilidade. Ver `requestId`.","items":{"type":"string"}},"status":{"type":"string","enum":["OK","PENDING","PROCESSING","EXPIRED","TERM_EXPIRED","NO_BONDS","NOT_ELIGIBLE","NO_MARGIN","ERROR"],"description":"`PROCESSING` (HTTP 202) quando o refresh foi despachado. Qualquer outro valor é\nterminal (HTTP 200) — não há consulta pendente a aguardar.\n"}}}}}},"202":{"description":"Refresh despachado; acompanhe pelo `requestId` ou pelo webhook.","content":{"application/json":{"schema":{"type":"object","description":"Resultado do refresh explícito de margem. O refresh sempre começa listando os vínculos na\nDataprev, então `requestId` vem nulo e `requestIds` vazio: a consulta por vínculo só é criada\ndepois que a listagem volta. Os identificadores chegam no webhook `MARGIN_QUERY_COMPLETED`,\num por vínculo.\n","properties":{"requestId":{"type":"string","nullable":true,"description":"Sempre nulo — mantido por compatibilidade. Use o `requestId` do webhook\n`MARGIN_QUERY_COMPLETED`, consultável em `GET /api/v1/originator/margin-queries/{requestId}`.\n"},"requestIds":{"type":"array","description":"Sempre vazio — mantido por compatibilidade. Ver `requestId`.","items":{"type":"string"}},"status":{"type":"string","enum":["OK","PENDING","PROCESSING","EXPIRED","TERM_EXPIRED","NO_BONDS","NOT_ELIGIBLE","NO_MARGIN","ERROR"],"description":"`PROCESSING` (HTTP 202) quando o refresh foi despachado. Qualquer outro valor é\nterminal (HTTP 200) — não há consulta pendente a aguardar.\n"}}}}}},"401":{"description":"Não autenticado","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"Employee não encontrado ou de outro originador.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"422":{"description":"Employee sem autorização Dataprev válida e sem termo recente para reenviar.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}},"429":{"description":"Mais de 20 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

## Comparação com a consulta por vínculo

|                           | **Atualizar margem** (esta página)                  | [**Consultar Margem por Vínculo**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md)         |
| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Escopo                    | O employee inteiro, um disparo por vínculo elegível | Um vínculo (`bondPublicId`)                                                                                                                                              |
| Precisa do `bondPublicId` | Não                                                 | Sim, de [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) |
| Vínculo inelegível        | Não é consultado                                    | Pode ser consultado com `forceIneligible=true`                                                                                                                           |
| Margem gravada            | Sempre invalidada antes do disparo                  | Sobrescrita quando a consulta conclui                                                                                                                                    |
| Resposta                  | `requestIds` (uma por vínculo)                      | `requestId` único                                                                                                                                                        |

Quando chegar o `MARGIN_QUERY_COMPLETED`, leia a margem em [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) e siga para [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md).

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
