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

# Importa colaboradores em massa via CSV

> Cria múltiplos colaboradores em uma única chamada a partir de arquivo CSV (multipart/form-data). **Caminho recomendado para volumes acima de 50 colaboradores** — muito mais rápido e robusto que loop de `POST /colaborador`.

**Pré-requisitos:**
- Departamentos, cargos, equipes e centros de custo já cadastrados na UN (ver [Estrutura Organizacional](/referencia/estrutura-organizacional))
- Arquivo CSV no schema esperado (UTF-8 com BOM, separador `;`, primeira linha = cabeçalho)

**Como funciona:**
1. Endpoint recebe o arquivo, valida estrutura e cabeçalhos
2. Processa linha por linha — cada linha vira tentativa de criação
3. Retorna **relatório consolidado** com totais e erros linha-a-linha
4. Linhas que dão erro **não bloqueiam** as demais — successo parcial é normal

**Erros comuns por linha:**
- CPF já existe na UN
- Departamento/cargo informado não encontrado
- CPF inválido (dígito verificador)
- Data de admissão fora de ISO 8601 (`yyyy-MM-dd`)

**Volumetria recomendada:** lotes de 100 colaboradores por chamada. Volumes maiores podem atingir timeout de gateway (60s).

Veja o guia [Importar colaboradores em massa via CSV](/guias-praticas/importar-em-massa-csv) para schema completo, exemplos e estratégias de retry.



## OpenAPI

````yaml https://api.pre.pontua.tech/api/public/doc-json post /colaborador/import
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/import:
    post:
      tags:
        - Colaborador
      summary: Importa colaboradores em massa via CSV
      description: >-
        Cria múltiplos colaboradores em uma única chamada a partir de arquivo
        CSV (multipart/form-data). **Caminho recomendado para volumes acima de
        50 colaboradores** — muito mais rápido e robusto que loop de `POST
        /colaborador`.


        **Pré-requisitos:**

        - Departamentos, cargos, equipes e centros de custo já cadastrados na UN
        (ver [Estrutura Organizacional](/referencia/estrutura-organizacional))

        - Arquivo CSV no schema esperado (UTF-8 com BOM, separador `;`, primeira
        linha = cabeçalho)


        **Como funciona:**

        1. Endpoint recebe o arquivo, valida estrutura e cabeçalhos

        2. Processa linha por linha — cada linha vira tentativa de criação

        3. Retorna **relatório consolidado** com totais e erros linha-a-linha

        4. Linhas que dão erro **não bloqueiam** as demais — successo parcial é
        normal


        **Erros comuns por linha:**

        - CPF já existe na UN

        - Departamento/cargo informado não encontrado

        - CPF inválido (dígito verificador)

        - Data de admissão fora de ISO 8601 (`yyyy-MM-dd`)


        **Volumetria recomendada:** lotes de 100 colaboradores por chamada.
        Volumes maiores podem atingir timeout de gateway (60s).


        Veja o guia [Importar colaboradores em massa via
        CSV](/guias-praticas/importar-em-massa-csv) para schema completo,
        exemplos e estratégias de retry.
      operationId: ColaboradorController_import
      parameters: []
      requestBody:
        required: true
        description: Multipart com campo `arquivo` contendo CSV no formato Pontua
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportCollaboratorsDto'
      responses:
        '201':
          description: >-
            Relatório de importação com `totalLinhas`, `totalImportados`,
            `totalErros` e detalhamento de erros
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkDto'
        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: []
components:
  schemas:
    ImportCollaboratorsDto:
      type: object
      properties:
        base64:
          type: string
          description: Base64 do arquivo CSV de colaboradores
          format: base64
          example: data:text/csv;base64,SGVsbG8sIFdvcmxkIQ==
      required:
        - base64
    OkDto:
      type: object
      properties:
        status:
          type: boolean
          description: Status da operação
          example: true
        mensagem:
          type: string
          description: Mensagem de retorno
          example: OK
      required:
        - status
    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

````