18. Dodawanie kontaktów przez API

Poziom trudności: Zaawansowany
Czas: 25 minut

Wprowadzenie

Dowiedz się jak automatycznie dodawać kontakty do GoHighLevel używając API - idealne do integracji z zewnętrznymi systemami, formularzami na stronie lub automatyzacji.

Po co API?

• Automatyzacja: Dodawaj kontakty bez ręcznej pracy
• Integracje: Połącz z CRM, bazami danych, formularzami
• Skala: Obsługuj setki/tysiące kontaktów automatycznie
• Real-time: Natychmiastowe dodawanie nowych leadów

Krok 1: Uzyskanie API Key

1. Settings → API Keys
2. Kliknij Create API Key
3. Name: "Import kontaktów"
4. Permissions: Zaznacz "Contacts - Write"
5. Create
6. Skopiuj API Key (nigdy nie udostępniaj!)

Przykład: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Krok 2: Podstawowe zapytanie API

Endpoint

POST https://rest.gohighlevel.com/v1/contacts/

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body (JSON)

{
  "email": "jan.kowalski@example.com",
  "firstName": "Jan",
  "lastName": "Kowalski",
  "phone": "+48123456789",
  "tags": ["lead", "website"]
}

Krok 3: Przykład w JavaScript

const apiKey = 'YOUR_API_KEY';
const locationId = 'YOUR_LOCATION_ID';

async function addContact(contactData) {
  const response = await fetch('https://rest.gohighlevel.com/v1/contacts/', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...contactData,
      locationId: locationId
    })
  });
  
  const result = await response.json();
  return result;
}

// Użycie
addContact({
  email: 'jan.kowalski@example.com',
  firstName: 'Jan',
  lastName: 'Kowalski',
  phone: '+48123456789',
  tags: ['lead', 'website']
}).then(data => console.log('Kontakt dodany:', data));

Krok 4: Przykład w Python

import requests
import json

API_KEY = 'YOUR_API_KEY'
LOCATION_ID = 'YOUR_LOCATION_ID'

def add_contact(contact_data):
    url = 'https://rest.gohighlevel.com/v1/contacts/'
    
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    contact_data['locationId'] = LOCATION_ID
    
    response = requests.post(url, headers=headers, json=contact_data)
    return response.json()

# Użycie
contact = {
    'email': 'jan.kowalski@example.com',
    'firstName': 'Jan',
    'lastName': 'Kowalski',
    'phone': '+48123456789',
    'tags': ['lead', 'website']
}

result = add_contact(contact)
print('Kontakt dodany:', result)

Krok 5: Pola opcjonalne

Pełna struktura kontaktu

{
  "email": "jan.kowalski@example.com",
  "firstName": "Jan",
  "lastName": "Kowalski",
  "phone": "+48123456789",
  "address1": "ul. Marszałkowska 10",
  "city": "Warszawa",
  "state": "Mazowieckie",
  "country": "Poland",
  "postalCode": "00-001",
  "website": "https://example.com",
  "timezone": "Europe/Warsaw",
  "dnd": false,
  "tags": ["lead", "website", "vip"],
  "customField": {
    "firma": "Example Sp. z o.o.",
    "nip": "1234567890"
  },
  "source": "Website Form"
}

Krok 6: Obsługa błędów

async function addContactSafe(contactData) {
  try {
    const response = await fetch('https://rest.gohighlevel.com/v1/contacts/', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Błąd API');
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('Błąd dodawania kontaktu:', error);
    return { success: false, error: error.message };
  }
}

Krok 7: Bulk import (wiele kontaktów)

async function addMultipleContacts(contacts) {
  const results = [];
  
  for (const contact of contacts) {
    const result = await addContactSafe(contact);
    results.push(result);
    
    // Pauza między requestami (rate limiting)
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}

// Użycie
const contacts = [
  { email: 'jan@example.com', firstName: 'Jan', lastName: 'Kowalski' },
  { email: 'anna@example.com', firstName: 'Anna', lastName: 'Nowak' },
  { email: 'piotr@example.com', firstName: 'Piotr', lastName: 'Wiśniewski' }
];

addMultipleContacts(contacts).then(results => {
  console.log(`Dodano ${results.filter(r => r.success).length} kontaktów`);
});

Krok 8: Integracja z formularzem HTML

<!DOCTYPE html>
<html>
<head>
  <title>Formularz kontaktowy</title>
</head>
<body>
  <form id="contactForm">
    <input type="text" name="firstName" placeholder="Imię" required>
    <input type="text" name="lastName" placeholder="Nazwisko" required>
    <input type="email" name="email" placeholder="Email" required>
    <input type="tel" name="phone" placeholder="Telefon">
    <button type="submit">Wyślij</button>
  </form>

  <script>
    document.getElementById('contactForm').addEventListener('submit', async (e) => {
      e.preventDefault();
      
      const formData = new FormData(e.target);
      const contact = Object.fromEntries(formData);
      
      // Wyślij do GoHighLevel
      const response = await fetch('YOUR_BACKEND_URL/add-contact', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(contact)
      });
      
      if (response.ok) {
        alert('Dziękujemy! Skontaktujemy się wkrótce.');
        e.target.reset();
      } else {
        alert('Błąd. Spróbuj ponownie.');
      }
    });
  </script>
</body>
</html>

Limity API

• Rate limit: 100 requestów/minutę
• Daily limit: 10,000 requestów/dzień
• Payload size: Max 1MB per request

Najlepsze praktyki

✅ DO:

• Waliduj dane przed wysłaniem
• Obsługuj błędy gracefully
• Respektuj rate limity
• Używaj HTTPS zawsze
• Loguj wszystkie operacje

❌ DON'T:

• Nie hardcode API key w frontend code
• Nie wysyłaj tysięcy requestów naraz
• Nie ignoruj błędów API
• Nie przechowuj wrażliwych danych w logach

Troubleshooting

Błąd 401 Unauthorized

• Sprawdź poprawność API Key
• Upewnij się że key nie wygasł
• Sprawdź permissions (Contacts - Write)

Błąd 429 Too Many Requests

• Zbyt wiele requestów - dodaj opóźnienia
• Rozłóż import w czasie
• Użyj bulk endpoints jeśli dostępne

Błąd 400 Bad Request

• Sprawdź format JSON
• Waliduj email/phone format
• Upewnij się że wymagane pola są obecne

Podsumowanie

✅ Nauczyłeś się:

• Uzyskiwać API Key
• Dodawać kontakty przez API
• Implementować w JavaScript i Python
• Obsługiwać błędy i rate limiting
• Integrować z formularzami

Następny krok: 19. Tagowanie kontaktów