> 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/buscar-employee.md).

# Buscar Employee

Retorna os dados cadastrais e a situação de um employee pelo `publicId`.

## Request

`GET /api/v1/originator/employees/{publicId}`

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

### Parâmetros

| Parâmetro  | Local | Tipo     | Obrigatório | Descrição                                               |
| ---------- | ----- | -------- | ----------- | ------------------------------------------------------- |
| `publicId` | path  | `string` | Sim         | Identificador público do employee (recebido na criação) |

## Response

| Campo                     | Tipo                 | Descrição                                                          |
| ------------------------- | -------------------- | ------------------------------------------------------------------ |
| `publicId`                | `string`             | Identificador público do employee (16 caracteres Base64 URL-safe)  |
| `cpf`                     | `string`             | CPF do trabalhador cadastrado                                      |
| `name`                    | `string`             | Nome civil completo do trabalhador                                 |
| `birthDate`               | `string` (date)      | Data de nascimento registrada                                      |
| `motherName`              | `string`             | Nome completo da mãe registrado                                    |
| `gender`                  | `string` (enum)      | Gênero no cadastro: `MALE`, `FEMALE`, `NOT_INFORMED`               |
| `idDocumentType`          | `string` (enum)      | Tipo do documento de identificação                                 |
| `idDocumentNumber`        | `string`             | Número do documento de identificação registrado                    |
| `isPoliticallyExposed`    | `boolean`            | Indicador de Pessoa Politicamente Exposta                          |
| `phone`                   | `string`             | Telefone de contato registrado                                     |
| `email`                   | `string`             | E-mail registrado para contato                                     |
| `partnerName`             | `string`             | Nome do cônjuge/parceiro registrado                                |
| `status`                  | `string` (enum)      | Situação cadastral: `ACTIVE`, `INACTIVE`, `REVOKED`                |
| `createdDate`             | `string` (date-time) | Data e hora de criação do cadastro (UTC)                           |
| `lastModifiedDate`        | `string` (date-time) | Data e hora da última atualização do cadastro (UTC)                |
| `employmentRelationships` | `array`              | Vínculos empregatícios do trabalhador (incluído quando disponível) |

## Exemplo

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

Resposta `200`:

```json
{
  "publicId": "Kj8mP2xQ9nR4sT6v",
  "cpf": "12345678901",
  "name": "João da Silva",
  "birthDate": "1990-05-20",
  "phone": "11987654321",
  "email": "joao.silva@email.com",
  "status": "ACTIVE",
  "createdDate": "2025-01-10T14:30:00Z",
  "lastModifiedDate": "2025-01-10T14:30:00Z"
}
```

## Erros

| Código | `errorCode` | Situação                                       |
| ------ | ----------- | ---------------------------------------------- |
| 404    | —           | Employee não encontrado ou de outro originador |
| 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).

## Buscar Employee

> Retorna os dados cadastrais de um trabalhador a partir do \`publicId\`.

```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/{publicId}":{"get":{"summary":"Buscar Employee","description":"Retorna os dados cadastrais de um trabalhador a partir do `publicId`.","tags":["Employees"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}}],"responses":{"200":{"description":"Employee retornado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","description":"Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v"},"cpf":{"type":"string","description":"CPF do trabalhador cadastrado."},"name":{"type":"string","description":"Nome civil completo do trabalhador."},"birthDate":{"type":"string","format":"date","description":"Data de nascimento registrada."},"motherName":{"type":"string","description":"Nome completo da mãe registrado."},"gender":{"type":"string","enum":["MALE","FEMALE","NOT_INFORMED"],"description":"Gênero no cadastro — o sexo devolvido pela Dataprev na consulta de vínculo, ou o último informado\npelo originador.\n| Valor | Significado |\n|-------|-------------|\n| MALE | Masculino |\n| FEMALE | Feminino |\n| NOT_INFORMED | Não informado |\n"},"idDocumentType":{"type":"string","enum":["MARITIME_CARD","RESERVIST_CERTIFICATE","DRIVERS_LICENSE","WORK_CARD","PASSPORT","GENERAL_REGISTRY","PROFESSIONAL_ID_CARD","INDIGENOUS_BIRTH_REGISTRY","ELECTRONIC_DRIVERS_LICENSE","NATIONAL_ID","PROVISIONAL_MIGRATION_REGISTRY","MILITARY_ID_CARD","FOREIGNER_REGISTRY"],"description":"Mesmos valores de CreateEmployeeRequest.idDocumentType (ver tabela)."},"idDocumentNumber":{"type":"string","description":"Número do documento de identificação registrado."},"isPoliticallyExposed":{"type":"boolean","description":"Indicador de Pessoa Politicamente Exposta no cadastro do trabalhador."},"phone":{"type":"string","description":"Telefone de contato registrado."},"email":{"type":"string","description":"E-mail registrado para contato."},"partnerName":{"type":"string","description":"Nome do cônjuge/parceiro registrado."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","REVOKED"],"description":"Situação cadastral do trabalhador.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Cadastro ativo, pode operar |\n| INACTIVE | Cadastro inativo (ex.: desligado) |\n| REVOKED | Acesso revogado pelo originator |\n"},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do cadastro no sistema (UTC)."},"lastModifiedDate":{"type":"string","format":"date-time","description":"Data e hora da última atualização do cadastro (UTC)."},"employmentRelationships":{"type":"array","description":"Vínculos empregatícios do trabalhador (incluído quando disponível).","items":{"type":"object","properties":{"publicId":{"type":"string","format":"uuid","description":"Identificador público opaco do vínculo empregatício."},"registrationNumber":{"type":"string","description":"Matrícula do trabalhador no empregador."},"employerTaxId":{"type":"string","description":"CNPJ ou CPF do empregador."},"employerTaxIdType":{"type":"string","description":"Tipo do documento fiscal do empregador.\n| Valor | Significado |\n|-------|-------------|\n| CPF | Pessoa física |\n| CNPJ | Pessoa jurídica |\n"},"employerName":{"type":"string","description":"Razão social ou nome do empregador."},"workerName":{"type":"string","maxLength":200,"nullable":true,"description":"Nome do trabalhador conforme retornado pela Dataprev na consulta de vínculo.\nÉ a fonte de verdade para a averbação. Pode ser `null` em vínculos legados\ncujo dado da Dataprev ainda não foi atualizado.\n"},"birthDate":{"type":"string","format":"date","nullable":true,"description":"Data de nascimento do trabalhador (employee). Preenchida a partir do cadastro\nlocal, preenchida pela consulta à Dataprev.\nPode ser `null` se ainda não disponível.\n"},"admissionDate":{"type":"string","format":"date","description":"Data de admissão do trabalhador."},"terminationDate":{"type":"string","format":"date","description":"Data de desligamento (nulo se vínculo ativo)."},"terminationReason":{"type":"string","description":"Motivo do desligamento (nulo se vínculo ativo)."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED","TERMINATED"],"description":"Situação do vínculo empregatício.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Vínculo ativo |\n| INACTIVE | Vínculo inativo |\n| SUSPENDED | Vínculo suspenso |\n| TERMINATED | Vínculo encerrado |\n"},"workerCategory":{"type":"string","description":"Categoria do trabalhador conforme eSocial."},"workerCboCode":{"type":"string","description":"Código CBO da ocupação do trabalhador."},"workerCboDescription":{"type":"string","description":"Descrição da ocupação (CBO)."},"totalEarnings":{"type":"number","format":"decimal","description":"Remuneração total do trabalhador."},"marginBase":{"type":"number","format":"decimal","description":"Base de cálculo da margem consignável."},"availableMargin":{"type":"number","format":"decimal","description":"Margem consignável disponível."},"usableMargin":{"type":"number","format":"decimal","description":"Margem utilizável para novas consignações."},"isEligible":{"type":"boolean","description":"Indica se o vínculo é elegível para consignação."},"ineligibilityReason":{"type":"string","description":"Motivo da inelegibilidade (nulo se elegível)."},"dataprevExpiresAt":{"type":"string","format":"date-time","description":"Validade da margem retornada. Após esse instante os dados de margem estão vencidos e\numa nova consulta de margem deve ser disparada para revalidar.\n"},"employerCnae":{"type":"string","description":"Código CNAE do empregador."},"employerCnaeDescription":{"type":"string","description":"Descrição da atividade econômica (CNAE)."},"employerActivityStartDate":{"type":"string","format":"date","description":"Data de início da atividade do empregador."},"activeConsignmentsCount":{"type":"integer","description":"Quantidade de consignações ativas no vínculo."},"nationalityCode":{"type":"integer","description":"Código da nacionalidade do trabalhador."},"nationalityDescription":{"type":"string","description":"Descrição da nacionalidade."},"blockingTypeCode":{"type":"integer","description":"Código do tipo de bloqueio (se houver)."},"blockingTypeDescription":{"type":"string","description":"Descrição do tipo de bloqueio."},"politicallyExposedPerson":{"type":"string","description":"Indicador de pessoa politicamente exposta."}}}},"authorization":{"type":"object","description":"Resultado do disparo automático de autorização feito durante o cadastro. Presente **apenas**\nquando o request trouxe o objeto `authorization` e o cadastro foi bem-sucedido (o disparo é atômico\ncom a criação; uma falha reverte tudo e retorna erro, então este bloco só aparece em caso de\nsucesso).\n","properties":{"status":{"type":"string","enum":["PROCESSING"],"description":"Sempre `PROCESSING` (reusa `SendAuthorizationStatus`). O termo embutido **sempre**\nreautoriza, mesmo com autorização válida vigente.\n"},"nsu":{"type":"string","description":"NSU do `AuthorizationDocument` gerado."},"dataprevAuthorizationStatus":{"type":"string","enum":["NOT_STARTED","PENDING_SIGNATURE","PENDING_SUBMISSION","AUTHORIZED","EXPIRED"],"description":"Situação da autorização Dataprev associada (enum `DataprevAuthorizationStatus`)."}}}}}}}},"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**."}}}}}}}},"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**."}}}}}}}}}}}}}
```

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