LighthouseNorth

Para desenvolvedores

Importar contatos pela API

Se você integra o Lighthouse North por API, a importação de contatos tem 3 passos e uma verificação de segurança que protege dados sensíveis.

Crie uma chave de API

No painel, abra Chaves de API e crie uma chave com escopos de leitura e escrita de listas (a leitura acompanha o resultado do import no passo 4). A chave aparece uma única vez: guarde em um gerenciador de segredos.

Nos exemplos abaixo, a chave vive na variável de ambiente $LN_API_KEY: crie a chave no painel e exporte na sua máquina: nunca escreva a chave no código.

Todas as chamadas usam a base https://lighthousenorth.com.br/v1 (referência completa em /docs).

Esta é a base das chamadas; ela não abre uma página no navegador (abrir o endereço sozinho devolve 404). A API responde nos caminhos dos comandos abaixo; sem uma chave válida, toda rota devolve “Não autenticado”.

Prepare a lista e o arquivo

Crie a lista de destino (o “público estático” que recebe a importação):

curl -X POST https://lighthousenorth.com.br/v1/lists \
  -H "X-API-Key: $LN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Clientes outubro"}'

O arquivo é um CSV com cabeçalho na primeira linha. As colunas email, telefone e whatsapp viram canal de contato do contato; nome e id_externo são reconhecidos pelo nome; toda coluna extra vira um campo adicional do contato.

Baixar o CSV de exemplo (modelo-contatos.csv) (dados 100% fictícios, salve como “CSV UTF-8”).

Importe com verificação

Primeiro, uma simulação (dryRun=true): nada é importado; a resposta traz o relatório (colunas identificadas, chaves de contato, linhas duplicadas e conflitos com a base existente).

curl -X POST https://lighthousenorth.com.br/v1/lists/{id}/import-csv \
  -H "X-API-Key: $LN_API_KEY" \
  -F file=@contatos.csv \
  -F dryRun=true

Se o arquivo tiver dados sensíveis (por exemplo CPF ou dados de saúde), a importação é recusada com o erro 422 import_sensitive_attributes até você confirmar explicitamente: só entram na base os dados sensíveis que você declarar necessários, com -F confirmSensitive=true. É uma proteção da LGPD (art. 5º, II): a confirmação fica registrada (quem confirmou, quando e quais colunas).

Os exemplos criam dados reais na conta da chave; rode numa conta de teste.

Acompanhe o resultado

Até 1.000 linhas, a resposta chega na hora com o resumo (criadas, atualizadas, ignoradas, falhas por linha). Acima disso, a importação roda em fila e a resposta traz um importId para consultar o progresso:

curl https://lighthousenorth.com.br/v1/lists/{id}/imports/{importId} \
  -H "X-API-Key: $LN_API_KEY"

Limites da importação

  • arquivo de até 5 MB
  • até 10.000 linhas por arquivo
  • 30 requisições por minuto (por endereço de origem)
  • até 1.000 linhas com resposta imediata (síncrono)

Referência completa de todos os endpoints →