Importar Contatos via CSV

Metodo

POST https://oapi.ogmma.com.br/v1/contacts/import

Conceituacao

Este endpoint permite importar multiplos contatos de uma vez a partir de um arquivo CSV. E a forma mais eficiente de popular sua base de contatos quando voce ja possui uma lista existente.

A importacao e processada de forma assincrona — a API retorna imediatamente com um ID de importacao, e voce pode acompanhar o progresso consultando o status.

---

Atributos

Header

Atributo	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Bearer {API_KEY} - Chave de autenticacao
Content-Type	string	Sim	multipart/form-data

Body (multipart/form-data)

Atributo	Tipo	Obrigatorio	Descricao
file	file	Sim	Arquivo CSV (max 5MB)
tags	string	Nao	Tags a aplicar em todos os contatos importados (separadas por virgula)
skipDuplicates	boolean	Nao	Se true, ignora contatos com telefone duplicado. Default: true

---

Formato do CSV

O arquivo deve conter um header na primeira linha com os nomes dos campos. Campos obrigatorios: name e phone.

name,phone,email,tags
Maria Silva,5511999990001,maria@email.com,"vip,cliente"
Joao Santos,5511999990002,joao@email.com,"lead"
Ana Oliveira,5511999990003,,

Campos suportados

Campo	Obrigatorio	Descricao
name	Sim	Nome do contato
phone	Sim	Numero no formato DDI+DDD+NUM (ex: 5511999990001)
email	Nao	Endereco de e-mail
tags	Nao	Tags separadas por virgula (entre aspas no CSV)

---

Request

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/contacts/import" \
  -H "Authorization: Bearer {API_KEY}" \
  -F "file=@contatos.csv" \
  -F "tags=importacao-jan-2025" \
  -F "skipDuplicates=true"

Node.js

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('file', fs.createReadStream('contatos.csv'));
form.append('tags', 'importacao-jan-2025');
form.append('skipDuplicates', 'true');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/contacts/import',
  form,
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      ...form.getHeaders()
    }
  }
);

console.log(response.data);

Python

import requests

with open('contatos.csv', 'rb') as f:
    response = requests.post(
        'https://oapi.ogmma.com.br/v1/contacts/import',
        files={'file': ('contatos.csv', f, 'text/csv')},
        data={
            'tags': 'importacao-jan-2025',
            'skipDuplicates': 'true'
        },
        headers={
            'Authorization': 'Bearer {API_KEY}'
        }
    )

print(response.json())

---

Response

202 - Aceito

A importacao foi aceita e sera processada de forma assincrona.

{
  "importId": "imp_a1b2c3d4e5f6",
  "status": "PROCESSING",
  "totalRows": 150,
  "message": "Importacao iniciada. Acompanhe o progresso consultando o status."
}

400 - Dados invalidos

{
  "message": "Formato de arquivo invalido. Envie um arquivo CSV.",
  "code": "INVALID_FILE_FORMAT"
}

413 - Arquivo muito grande

{
  "message": "O arquivo excede o tamanho maximo permitido (5MB).",
  "code": "FILE_TOO_LARGE"
}

---

Consultar status da importacao

GET https://oapi.ogmma.com.br/v1/contacts/import/:importId

curl -X GET "https://oapi.ogmma.com.br/v1/contacts/import/{importId}" \
  -H "Authorization: Bearer {API_KEY}"

Response

{
  "importId": "imp_a1b2c3d4e5f6",
  "status": "COMPLETED",
  "totalRows": 150,
  "imported": 142,
  "skipped": 5,
  "failed": 3,
  "errors": [
    { "row": 45, "phone": "invalid", "reason": "Numero de telefone invalido" },
    { "row": 89, "phone": "5511", "reason": "Numero de telefone muito curto" },
    { "row": 120, "phone": "", "reason": "Campo phone obrigatorio" }
  ]
}

Status da importacao

Status	Descricao
PROCESSING	A importacao esta em andamento
COMPLETED	Todos os registros foram processados
FAILED	A importacao falhou (arquivo corrompido, formato invalido, etc.)

---

Limites

Parametro	Limite
Tamanho do arquivo	5 MB
Linhas por arquivo	10.000
Importacoes simultaneas	1 por instituicao

---

Boas praticas

• Valide o formato do CSV antes de enviar (encoding UTF-8, separador virgula)
• Use skipDuplicates=true para evitar erros em reimportacoes
• Aplique tags durante a importacao para identificar a origem dos contatos
• Consulte o status apos a importacao para tratar erros linha a linha