Skip to main content
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)
  • Estrutura organizacional pré-cadastrada — Departamentos e Cargos precisam existir antes (ver 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

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.

Estratégias de tratamento de erro

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

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

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

ErroCausa típicaComo corrigir
CPF já existe na unidadeColaborador duplicadoUsar PATCH em vez de criar, ou pular
Departamento não encontradoID/nome de departamento inválido na UNVerifica catálogo, atualiza CSV
Cargo não encontradoIdem departamentoMesma correção
CPF inválidoFormato errado, dígitos verificadores não batemLimpar CSV: 11 dígitos sem máscara
Data de admissão inválidaFormato fora de ISO 8601Padronizar yyyy-MM-dd

Volumetria recomendada

VolumeCaminho
1-10 colaboradoresPOST individual (mais simples)
11-100POST /colaborador/import em uma chamada
101-1000POST /colaborador/import em lotes de 100
> 1000Lotes 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