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

# Importar colaboradores em massa via CSV

> Use POST /colaborador/import para criar dezenas ou centenas de colaboradores de uma vez a partir de arquivo CSV. Ideal para onboarding e migração.

`POST /colaborador/import` é o **caminho recomendado** para criar mais de
\~50 colaboradores. Reduz round-trips, dá relatório consolidado de erros
e é muito mais rápido que loop de POST individuais.

## Pré-requisitos

* Token de API ([Quick Start](/quick-start))
* **Estrutura organizacional pré-cadastrada** — Departamentos e Cargos
  precisam existir antes (ver [Estrutura Organizacional](/referencia/estrutura-organizacional))
* Arquivo CSV no formato esperado (schema na Referência)

## Fluxo geral

```
1. Sync prévio: garantir que Departamentos e Cargos existem
2. Preparar CSV com colaboradores
3. POST /colaborador/import (multipart upload)
4. Inspecionar response — totais + erros linha-a-linha
5. Para erros, decidir: corrigir e reimportar OU criar manualmente
```

## Implementação

```javascript theme={null}
import fs from 'node:fs'

async function importarColaboradoresCsv(token, caminhoArquivoCsv) {
  // POST multipart com arquivo
  const formData = new FormData()
  formData.append('arquivo', new Blob([fs.readFileSync(caminhoArquivoCsv)]), 'colaboradores.csv')

  const resp = await fetch('https://api.pontua.com.br/colaborador/import', {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    // NOTA: Content-Type é setado automaticamente como multipart/form-data
    body: formData,
  })

  if (!resp.ok) {
    const erro = await resp.json()
    throw new Error(`${erro.service}.${erro.method}: ${erro.message}`)
  }

  const resultado = await resp.json()
  console.log(`Total: ${resultado.totalLinhas}`)
  console.log(`Importados: ${resultado.totalImportados}`)
  console.log(`Erros: ${resultado.totalErros}`)

  if (resultado.erros?.length > 0) {
    console.log('Linhas com erro:')
    resultado.erros.forEach((e) => {
      console.log(`  Linha ${e.linha}: ${e.motivo}`)
    })
  }

  return resultado
}
```

O schema exato do response (campos `totalLinhas`, `totalImportados`,
`erros`, etc.) está em [Referência da API](/api-reference#tag/Colaborador).

## Estratégias de tratamento de erro

### Estratégia 1: Re-importar só os erros

```javascript theme={null}
async function importarComRetry(token, caminhoCsv) {
  const resultado = await importarColaboradoresCsv(token, caminhoCsv)

  if (resultado.erros?.length === 0) return resultado

  // Gera novo CSV só com as linhas que deram erro corrigidas
  const csvCorrigido = corrigirErros(caminhoCsv, resultado.erros)
  return importarColaboradoresCsv(token, csvCorrigido)
}
```

### Estratégia 2: Criar individuais como fallback

```javascript theme={null}
async function importarComFallback(token, caminhoCsv, dadosOriginais) {
  const resultado = await importarColaboradoresCsv(token, caminhoCsv)

  for (const erro of resultado.erros ?? []) {
    const dado = dadosOriginais[erro.linha - 1]  // ajuste por 1-index
    try {
      await fetch('https://api.pontua.com.br/colaborador', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(dado),
      })
    } catch (e) {
      console.error(`Falha definitiva linha ${erro.linha}:`, e.message)
    }
  }
}
```

## Erros comuns no CSV

| Erro                          | Causa típica                                    | Como corrigir                        |
| ----------------------------- | ----------------------------------------------- | ------------------------------------ |
| `CPF já existe na unidade`    | Colaborador duplicado                           | Usar PATCH em vez de criar, ou pular |
| `Departamento não encontrado` | ID/nome de departamento inválido na UN          | Verifica catálogo, atualiza CSV      |
| `Cargo não encontrado`        | Idem departamento                               | Mesma correção                       |
| `CPF inválido`                | Formato errado, dígitos verificadores não batem | Limpar CSV: 11 dígitos sem máscara   |
| `Data de admissão inválida`   | Formato fora de ISO 8601                        | Padronizar `yyyy-MM-dd`              |

## Volumetria recomendada

| Volume             | Caminho                                                  |
| ------------------ | -------------------------------------------------------- |
| 1-10 colaboradores | POST individual (mais simples)                           |
| 11-100             | `POST /colaborador/import` em uma chamada                |
| 101-1000           | `POST /colaborador/import` em **lotes de 100**           |
| > 1000             | Lotes de 100 + processar à noite com backoff entre lotes |

Importar muito grande de uma vez pode atingir timeout de gateway (ALB
tem 60s default). Lotes pequenos são mais robustos.

## Veja também

* [Colaboradores](/referencia/colaboradores) — schema completo da entidade
* [Estrutura Organizacional](/referencia/estrutura-organizacional) — pré-requisito de sync
* [Cadastrar primeiro colaborador](/guias-praticas/primeiro-colaborador) — fluxo unitário
* [Idempotência](/conceitos/idempotencia) — evitar duplicatas em retry