> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Lista colaboradores da unidade de negócio

> Retorna todos os colaboradores da unidade de negócio do token autenticado, com filtros e paginação. Endpoint mais consumido em integrações de RH e ERP.

**Casos de uso típicos:**
- Sincronizar quadro de funcionários com folha de pagamento externa (Domínio, Sage, ERP próprio)
- Popular dropdown "selecionar colaborador" em sistemas internos
- Auditoria de quadro ativo vs. inativo
- Detectar admissões/demissões desde a última sync (use `updatedAt` no filtro)

**Filtros úteis:**
- `status` — filtra por estado: `ATIVO`, `INATIVO`, `AFASTADO`, `DEMITIDO`
- `departamentoId`, `cargoId`, `equipeId`, `unidadeId` — corte organizacional
- `searchText` — busca por nome, código ou CPF
- `pagina` + `limite` — paginação Pontua padrão (ver [Paginação](/conceitos/paginacao))

**Soft-delete:** colaboradores excluídos (status `DEMITIDO`) continuam aparecendo nas consultas — é a fonte de verdade histórica para folha. Para listar **apenas ativos**, filtre explicitamente `status=ATIVO`.

**Multi-tenant:** o token determina a UN. Para listar colaboradores de outras UNs, use uma chave criada na UN-alvo (uma chave por UN).

Veja o guia [Sincronizar frequência com ERP](/guias-praticas/sincronizar-frequencia-erp) para padrão cron noturno.



## OpenAPI

````yaml https://api.pre.pontua.tech/api/public/doc-json get /colaborador
openapi: 3.0.0
info:
  title: Pontua Public API
  description: >-
    API oficial da Pontua para integrações de clientes externos. Autentique com
    o token gerado no dashboard em **Configurações → API**. Envie o token no
    header `Authorization: Bearer <SEU_TOKEN>`.
  version: '1.0'
  contact: {}
servers: []
security: []
tags: []
paths:
  /colaborador:
    get:
      tags:
        - Colaborador
      summary: Lista colaboradores da unidade de negócio
      description: >-
        Retorna todos os colaboradores da unidade de negócio do token
        autenticado, com filtros e paginação. Endpoint mais consumido em
        integrações de RH e ERP.


        **Casos de uso típicos:**

        - Sincronizar quadro de funcionários com folha de pagamento externa
        (Domínio, Sage, ERP próprio)

        - Popular dropdown "selecionar colaborador" em sistemas internos

        - Auditoria de quadro ativo vs. inativo

        - Detectar admissões/demissões desde a última sync (use `updatedAt` no
        filtro)


        **Filtros úteis:**

        - `status` — filtra por estado: `ATIVO`, `INATIVO`, `AFASTADO`,
        `DEMITIDO`

        - `departamentoId`, `cargoId`, `equipeId`, `unidadeId` — corte
        organizacional

        - `searchText` — busca por nome, código ou CPF

        - `pagina` + `limite` — paginação Pontua padrão (ver
        [Paginação](/conceitos/paginacao))


        **Soft-delete:** colaboradores excluídos (status `DEMITIDO`) continuam
        aparecendo nas consultas — é a fonte de verdade histórica para folha.
        Para listar **apenas ativos**, filtre explicitamente `status=ATIVO`.


        **Multi-tenant:** o token determina a UN. Para listar colaboradores de
        outras UNs, use uma chave criada na UN-alvo (uma chave por UN).


        Veja o guia [Sincronizar frequência com
        ERP](/guias-praticas/sincronizar-frequencia-erp) para padrão cron
        noturno.
      operationId: ColaboradorController_getColaboradores
      parameters:
        - name: searchText
          description: Texto pesquisado para filtrar consulta
          required: false
          in: query
          schema:
            type: string
        - name: pagina
          description: Página que deseja retornar os resultados
          required: false
          in: query
          schema:
            example: 0
            type: number
        - name: limite
          description: Quantidade de itens que retorna na consulta. Min 1 - Max 100
          required: false
          in: query
          schema:
            example: 100
            type: number
        - name: situacao
          required: false
          in: query
          description: Filtro por situação do colaborador
          schema:
            enum:
              - ATIVO
              - INATIVO
              - RASCUNHO
            type: string
        - name: tiposCadastro
          required: false
          in: query
          description: Filtro por tipos de cadastro de colaborador, separados por vírgula
          schema:
            example: PRESTADOR_SERVICO,CLT,EXTERNO,API
            type: string
        - name: dataDemissaoInicio
          required: false
          in: query
          description: 'Filtro por data de demissão inicial. Ex: "2020-01-01"'
          schema:
            format: date-time
            type: string
        - name: dataDemissaoFim
          required: false
          in: query
          description: 'Filtro por data de demissão final. Ex: "2030-12-31"'
          schema:
            format: date-time
            type: string
        - name: dataAfastamentoInicio
          required: false
          in: query
          description: 'Filtro por data de afastamento inicial. Ex: "2020-01-01"'
          schema:
            format: date-time
            type: string
        - name: dataAfastamentoFim
          required: false
          in: query
          description: 'Filtro por data de afastamento final. Ex: "2030-12-31"'
          schema:
            format: date-time
            type: string
        - name: dataFeriasInicio
          required: false
          in: query
          description: 'Filtro por data de férias inicial. Ex: "2020-01-01"'
          schema:
            format: date-time
            type: string
        - name: dataFeriasFim
          required: false
          in: query
          description: 'Filtro por data de férias final. Ex: "2030-12-31"'
          schema:
            format: date-time
            type: string
        - name: cargoIds
          required: false
          in: query
          description: 'Filtro por IDs de cargo, separados por vírgula. Ex: "id1,id2"'
          schema:
            type: string
        - name: departamentoIds
          required: false
          in: query
          description: 'Filtro por IDs de departamento, separados por vírgula. Ex: "id1,id2"'
          schema:
            type: string
        - name: equipeIds
          required: false
          in: query
          description: 'Filtro por IDs de equipe, separados por vírgula. Ex: "id1,id2"'
          schema:
            type: string
        - name: localTrabalhoIds
          required: false
          in: query
          description: >-
            Filtro por IDs de local de trabalho, separados por vírgula. Ex:
            "id1,id2"
          schema:
            type: string
        - name: niveisAcesso
          required: false
          in: query
          description: Filtro por níveis de acesso, separados por vírgula
          schema:
            example: ADMIN,GESTOR,USER
            type: string
        - name: regraDePontoIds
          required: false
          in: query
          description: >-
            Filtro por IDs de regra de ponto, separados por vírgula. Ex:
            "id1,id2"
          schema:
            type: string
        - name: batidaPontoIds
          required: false
          in: query
          description: >-
            Filtro por IDs de batida de ponto, separados por vírgula. Ex:
            "id1,id2"
          schema:
            type: string
        - name: turnoIds
          required: false
          in: query
          description: 'Filtro por IDs de turno, separados por vírgula. Ex: "id1,id2"'
          schema:
            type: string
        - name: fusosHorarios
          required: false
          in: query
          description: >-
            Filtro por IDs de fuso horário, separados por vírgula. Ex.:
            "MANAUS,NORONHA,RIO_BRANCO,SAO_PAULO"
          schema:
            type: string
        - name: unidadeNegocioIds
          required: false
          in: query
          description: >-
            Filtro por IDs de unidade de negócio, separados por vírgula, Ex:
            "id1,id2"
          schema:
            type: string
        - name: centroCustoIds
          required: false
          in: query
          description: >-
            Filtro por IDs de centro de custo, separados por vírgula, Ex:
            "id1,id2"
          schema:
            type: string
        - name: cidades
          required: false
          in: query
          description: >-
            Filtro por cidades, separadas por vírgula. Ex: "Belo
            Horizonte,Goiânia"
          schema:
            type: string
        - name: estados
          required: false
          in: query
          description: 'Filtro por estados, separados por vírgula. Ex: "MG,GO"'
          schema:
            type: string
        - name: gestorId
          required: false
          in: query
          description: Retorna apenas colaboradores liderados pelo gestor informado
          schema:
            type: string
        - name: situacaoCadastroFacial
          required: false
          in: query
          description: Retorna apenas colaboradores com cadastro facial ativo ou inativo
          schema:
            enum:
              - ATIVO
              - INATIVO
              - PENDENTE
            type: string
        - name: compensatoryTimeCycleId
          required: false
          in: query
          description: >-
            Retorna apenas colaboradores vinculados ao ciclo de banco de horas
            informado
          schema:
            type: string
        - name: compensatoryTimeMovementId
          required: false
          in: query
          description: >-
            Retorna apenas colaboradores vinculados à movimentação de banco de
            horas informada
          schema:
            type: string
        - name: shutdownId
          required: false
          in: query
          description: Retorna apenas colaboradores vinculados ao fechamento informado
          schema:
            type: string
        - name: paymentSheetExportId
          required: false
          in: query
          description: >-
            Retorna apenas colaboradores vinculados à exportação de folha de
            pagamento informada
          schema:
            type: string
        - name: paymentSheetParameterId
          required: false
          in: query
          description: >-
            Retorna apenas colaboradores vinculados ao ID do parâmetro de folha
            de pagamento informado
          schema:
            type: string
        - name: paymentSheetSource
          required: false
          in: query
          description: >-
            Retorna apenas colaboradores vinculados a um de parâmetro de folha
            de pagamento com a fonte informada
          schema:
            enum:
              - Keevo
              - OneFlow
              - Sankhya
              - Tron
              - Outro
            type: string
        - name: paymentSheetSourceName
          required: false
          in: query
          description: >-
            Nome da fonte do parâmetro de folha de pagamento, para o caso de uma
            fonte desconhecida (Outro) ou não informada
          schema:
            type: string
      responses:
        '200':
          description: >-
            Lista paginada de colaboradores com vínculo organizacional, status e
            dados básicos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindAllColaboradoresDto'
        default:
          description: "\n\t\t\t400 - Bad Request: A solicitação não está no formato correto.\n\t\t\t401 - Unauthorized: A solicitação não foi autorizada. Verifique se o token de acesso é válido.\n\t\t\t403 - Forbidden: Acesso proibido! Requer um nível de permissão mais elevado.\n\t\t\t404 - Not Found: O recurso solicitado não foi encontrado.\n\t\t\t500 - Internal Server Error: Erro de execução no servidor!\n\t\t\t"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
      deprecated: false
      security:
        - bearer: []
        - cookie: []
components:
  schemas:
    FindAllColaboradoresDto:
      type: object
      properties:
        pagina:
          type: number
          description: Pagina que deseja retornar os resultados
          example: 0
        limite:
          type: number
          description: Quantidade de itens que retorna na consulta. Min 1 - Max 100
          example: 25
        total:
          type: number
          description: Total de registros encontrados
          example: 100
        colaboradores:
          description: Resultado da consulta
          type: array
          items:
            $ref: '#/components/schemas/Colaborador'
      required:
        - total
        - colaboradores
    ErrorDto:
      type: object
      properties:
        service:
          type: string
          description: Rota solicitada
        method:
          type: string
          description: Método http
        message:
          description: Mensagem do erro
          oneOf:
            - type: string
              example: message erro
            - type: array
              items:
                type: string
                example:
                  - erro 1
                  - erro 2
      required:
        - service
        - method
        - message
    Colaborador:
      type: object
      properties:
        colaboradorId:
          type: string
          description: ID referente ao Colaborador
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nivelAcesso:
          type: string
          description: Nivel de acesso do usuario
          enum:
            - ADMIN
            - GESTOR
            - USER
          default: USER
        nome:
          type: string
          description: Nome do colaborador
          example: Douglas Coelho
        tipoColaborador:
          type: string
          description: Tipo de colaborador
          enum:
            - PRESTADOR_SERVICO
            - CLT
            - EXTERNO
            - API
          default: CLT
        tipoIdentificacao:
          type: string
          description: Identificação se o documento é um CPF ou CNPJ
          enum:
            - CNPJ
            - CPF
          default: CPF
        numeroDocumento:
          type: string
          description: CPF ou CNPJ
          example: '71055398712'
        numeroPrevidenciario:
          type: string
          description: >-
            Número do tipo de vínculo previdenciário do empregado (NIS, PIS,
            etc)
          example: N586692225
        unidadeNegocio:
          description: Unidade de negócio do colaborador
          allOf:
            - $ref: '#/components/schemas/UnidadeNegocioColaborador'
        cargo:
          description: Cargo referente ao colaborador
          allOf:
            - $ref: '#/components/schemas/Cargo'
        departamento:
          description: Departamento referente ao colaborador
          allOf:
            - $ref: '#/components/schemas/Departamento'
        equipe:
          description: Equipe à qual o colaborador pertence
          allOf:
            - $ref: '#/components/schemas/Equipe'
        email:
          type: string
          description: E-mail de contato do colaborador
          example: douglas@empresa.com.br
        celular:
          type: string
          description: Telefone de contato do colaborador (formato livre)
          example: '+5562999999999'
        dataAdmissao:
          format: date-time
          type: string
          description: Data de admissão do colaborador
          example: '2024-01-15T00:00:00.000Z'
        dataDemissao:
          format: date-time
          type: string
          description: >-
            Data de demissão do colaborador. Quando preenchido (e
            status=INATIVO) indica que existe demissão cancelável via PATCH
            /colaborador/{id}/cancelar-demissao
          example: '2026-05-07T00:00:00.000Z'
        createdAt:
          format: date-time
          type: string
          description: Data de criação do registro
          example: '2024-01-10T12:34:56.000Z'
        updatedAt:
          format: date-time
          type: string
          description: Data da última atualização do registro
          example: '2024-02-20T08:22:11.000Z'
        localTrabalho:
          description: Local de trabalho do colaborador
          allOf:
            - $ref: '#/components/schemas/LocalTrabalho'
        centroCusto:
          description: Centro de custo do colaborador
          allOf:
            - $ref: '#/components/schemas/CentroCusto'
        dataInicio:
          format: date-time
          type: string
          description: >-
            Data de início do colaborador na plataforma Pontua (registro de
            ponto)
          example: '2024-01-15T00:00:00.000Z'
        statusFacial:
          type: string
          description: Status do cadastro facial (PENDENTE/COMPLETO/EXPIRADO/etc)
          example: COMPLETO
        situacao:
          type: string
          description: Situação do empregado
          enum:
            - ATIVO
            - INATIVO
            - RASCUNHO
          default: ATIVO
        foto:
          type: string
          description: Url para download da foto
          example: https://s3-bucket.s3.amazonaws.com/files/tenant_x/file.jpg
        facialId:
          description: Dados do cadastro de reconhecimento facial
          allOf:
            - $ref: '#/components/schemas/FacialId'
      required:
        - colaboradorId
        - nivelAcesso
        - nome
        - tipoColaborador
        - tipoIdentificacao
        - numeroDocumento
        - unidadeNegocio
        - cargo
        - departamento
        - situacao
    UnidadeNegocioColaborador:
      type: object
      properties:
        unidadeNegocioId:
          type: string
          description: ID da unidade de negocio do colaborador
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nome:
          type: string
          description: Nome da unidade de negocio do colaborador
          example: Tron
        foto:
          type: string
          description: Url para download da foto da unidade de negócio
          example: https://s3-bucket.s3.amazonaws.com/files/tenant_x/file.jpg
        tax:
          type: string
          description: Valor do CNPJ ou CPF da unidade de negócio
          example: '71055398712'
      required:
        - unidadeNegocioId
        - nome
    Cargo:
      type: object
      properties:
        cargoId:
          type: string
          description: ID referente ao cargo
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nome:
          type: string
          description: Nome do Cargo
          example: Analista de Marketing
      required:
        - cargoId
        - nome
    Departamento:
      type: object
      properties:
        departamentoId:
          type: string
          description: ID referente ao departamento
          example: c9f447fe-f97f-4f24-974d-9f92eb3049dc
        nome:
          type: string
          description: Nome do departamento
          example: Desenvolvimento
      required:
        - departamentoId
        - nome
    Equipe:
      type: object
      properties:
        equipeId:
          type: string
          description: ID referente à equipe
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nome:
          type: string
          description: Nome da equipe
          example: Squad Plataforma
      required:
        - equipeId
        - nome
    LocalTrabalho:
      type: object
      properties:
        localTrabalhoId:
          type: string
          description: ID referente ao local de trabalho
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nome:
          type: string
          description: Nome do local de trabalho
          example: Sede Goiânia
      required:
        - localTrabalhoId
        - nome
    CentroCusto:
      type: object
      properties:
        centroCustoId:
          type: string
          description: ID referente ao centro de custo
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        nome:
          type: string
          description: Nome do centro de custo
          example: Tecnologia / R&D
      required:
        - centroCustoId
        - nome
    FacialId:
      type: object
      properties:
        id:
          type: string
          description: ID referente do cadastro da FacialId no nosso banco
          example: b5887a64-6aa1-43e8-b233-ffadc7f92ca6
        codigoFacial:
          type: string
          description: Código referente ao rosto da pessoa na FacialId
          example: FULANO.10
        situacao:
          type: string
          description: Stituação de cadastro na FacialId
          example: Ativo
        dataExpiracao:
          format: date-time
          type: string
          description: Data de expiração das fotos enviadas para o cadastro
          example: '2025-07-23T00:00:00.000Z'

````