> 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/employees/verificar-cpf.md).

# Verificar CPF

Informa se o CPF já tem employee cadastrado no seu originador e, se tiver, o `publicId`.

## Request

`POST /api/v1/originator/employees/lookup`

Autenticação: `Authorization: Bearer {originatorToken}`. O CPF vai no corpo, fora da URL, para não ficar em logs de acesso, proxies, CDNs e histórico do navegador.

### Corpo

| Campo | Tipo     | Obrigatório | Descrição                                                                           |
| ----- | -------- | ----------- | ----------------------------------------------------------------------------------- |
| `cpf` | `string` | Sim         | CPF do trabalhador (11 dígitos numéricos, sem pontos ou traços; pattern `^\d{11}$`) |

## Response

| Campo      | Tipo      | Descrição                                                                   |
| ---------- | --------- | --------------------------------------------------------------------------- |
| `exists`   | `boolean` | `true` se o CPF tem employee cadastrado no originador                       |
| `publicId` | `string`  | Identificador público do employee. Presente apenas quando `exists` é `true` |

Sempre `200`, exista ou não o employee: use `exists`. CPF não cadastrado não gera `404`.

## Exemplo

```http
POST /api/v1/originator/employees/lookup HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "12345678901"
}
```

Employee encontrado:

```json
{
  "exists": true,
  "publicId": "Kj8mP2xQ9nR4sT6v"
}
```

Employee não encontrado:

```json
{
  "exists": false
}
```

## Erros

| Código | `errorCode` | Situação                                                                                                      |
| ------ | ----------- | ------------------------------------------------------------------------------------------------------------- |
| 400    | —           | `cpf` ausente (`CPF é obrigatório`) ou fora de 11 dígitos (`CPF deve conter exatamente 11 dígitos numéricos`) |
| 400    | —           | Corpo ausente ou JSON malformado (`type: about:blank`)                                                        |
| 429    | —           | Mais de 100 requisições por segundo                                                                           |

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

## Verificar Employee por CPF

> Verifica se existe um employee cadastrado para o CPF informado no originator autenticado.\
> Retorna o \`publicId\` quando encontrado.\
> \
> O CPF trafega no corpo da requisição — não é exposto na URL, em logs de acesso\
> nem em históricos de proxy/CDN.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Employees","description":"Gerenciamento de employees (trabalhadores)"}],"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/lookup":{"post":{"summary":"Verificar Employee por CPF","description":"Verifica se existe um employee cadastrado para o CPF informado no originator autenticado.\nRetorna o `publicId` quando encontrado.\n\nO CPF trafega no corpo da requisição — não é exposto na URL, em logs de acesso\nnem em históricos de proxy/CDN.\n","tags":["Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf"],"properties":{"cpf":{"type":"string","minLength":11,"maxLength":11,"pattern":"^\\d{11}$","description":"CPF do trabalhador (11 dígitos numéricos, sem pontuação)."}}}}}},"responses":{"200":{"description":"Resultado da verificação","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean","description":"Indica se o CPF possui um employee cadastrado para o originator."},"publicId":{"type":"string","description":"Identificador público do employee (16 caracteres Base64 URL-safe). Presente apenas quando exists é true."}},"required":["exists"]}}}},"400":{"description":"`cpf` ausente ou fora de 11 dígitos, ou corpo ilegível.","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**."}}}}}}}},"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**."}}}}}}}},"429":{"description":"Mais de 100 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**."}}}}}}}}}}}}}
```

## Endpoint anterior (descontinuado)

{% hint style="warning" %}
**`GET /api/v1/originator/employees/by-cpf/{cpf}` está descontinuado** e será removido em uma release futura. Até lá continua funcionando, com a mesma resposta.

Para migrar: troque para `POST /api/v1/originator/employees/lookup` e envie `{"cpf": "..."}` no corpo com `Content-Type: application/json`. A resposta é a mesma (`exists` e `publicId`).
{% endhint %}

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