Pular para o conteúdo

Exemplo — Sincronizar contatos com sistema externo

Cenário típico: você tem um sistema externo (CRM, ERP, e-commerce) que mantém a base oficial de contatos da sua empresa. Quer que o app.smart espelhe essa base — quando contato muda no sistema externo, atualizar no app.smart; quando contato é editado no app.smart (pelo agente), refletir de volta no sistema externo.

Esta página apresenta arquitetura, código e armadilhas práticas para essa sincronia.

Decida qual sistema é fonte de verdade primária:

  • Sistema externo é primário — agente no app.smart edita mais raramente; sync principal é externo → app.smart
  • app.smart é primário — agente vive no app.smart; sistema externo só recebe atualizações
  • Bidirecional — ambos editam; resolva conflitos com “última atualização vence”

Para a maioria dos casos, sistema externo primário é mais simples e seguro.

┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Sistema │ │ Sync Service │ │ app.smart │
│ Externo │ │ (seu) │ │ │
│ │ │ │ │ │
│ - Cadastra │───►│ - Roda 4x/dia │───►│ POST │
│ contato │ │ - Lê externo │ │ /contacts │
│ │ │ - Compara com │ │ │
│ │ │ app.smart │ │ │
│ - Edita │ │ - Aplica diff │ │ │
│ contato │ │ │ │ │
│ │ │ │ │ │
│ Webhook │◄───┤ Recebe webhook │◄───│ Webhook │
│ recebido │ │ do app.smart se │ │ bidir │
│ │ │ agente editou │ │ (opcional) │
└─────────────────┘ └──────────────────┘ └──────────────┘
Terminal window
pip install requests
Terminal window
export SMART_TOKEN="seu_token"
export SMART_ACCOUNT_ID="1"
export SMART_BASE_URL="https://app.smart2.com.br/api/v1/accounts/1"
import os
import time
import requests
from datetime import datetime
SMART_BASE = os.environ['SMART_BASE_URL']
HEADERS = {
'api_access_token': os.environ['SMART_TOKEN'],
'Content-Type': 'application/json'
}
# === Funções de leitura do sistema externo ===
def fetch_external_contacts(updated_since):
"""Buscar contatos do sistema externo atualizados após data X."""
# Substitua pela API do seu sistema (ex: Shopify, RD Station, Hubspot, ERP custom)
r = requests.get(
"https://meucrm.com.br/api/contacts",
params={"updated_after": updated_since.isoformat()},
headers={"Authorization": f"Bearer {os.environ['CRM_TOKEN']}"}
)
return r.json()['contacts']
# === Funções de escrita no app.smart ===
def upsert_contact_to_smart(external_contact):
"""Cria ou atualiza contato no app.smart baseado no externo."""
payload = {
"name": external_contact['nome'],
"email": external_contact.get('email'),
"phone_number": external_contact.get('telefone'),
"identifier": f"CRM-{external_contact['id']}", # Chave de dedup
"custom_attributes": {
"cpf": external_contact.get('cpf'),
"plano": external_contact.get('plano'),
"valor_ltv": external_contact.get('ltv', 0)
}
}
# Remove campos vazios
payload = {k: v for k, v in payload.items() if v}
r = requests.post(
f"{SMART_BASE}/contacts",
headers=HEADERS,
json=payload
)
if r.status_code in (200, 201):
return r.json()['payload']['contact']
else:
print(f"❌ Erro ao processar {external_contact['id']}: {r.text}")
return None
# === Ciclo principal de sync ===
def sync_loop():
"""Roda sincronia a cada 6 horas."""
last_sync = load_last_sync_date() # Persistir em arquivo/Redis
print(f"Iniciando sync de contatos atualizados após {last_sync}")
external_contacts = fetch_external_contacts(last_sync)
print(f"{len(external_contacts)} contatos para processar")
success = 0
errors = 0
for ec in external_contacts:
result = upsert_contact_to_smart(ec)
if result:
success += 1
else:
errors += 1
# Rate limit: 300 req/min para User Token
time.sleep(0.2) # 5 req/s = 300 req/min seguro
save_last_sync_date(datetime.now())
print(f"✅ Sync concluído: {success} sucesso, {errors} erro")
def load_last_sync_date():
try:
with open('last_sync.txt') as f:
return datetime.fromisoformat(f.read().strip())
except FileNotFoundError:
return datetime(2024, 1, 1) # Início do tempo se primeira execução
def save_last_sync_date(dt):
with open('last_sync.txt', 'w') as f:
f.write(dt.isoformat())
# === Execução ===
if __name__ == '__main__':
sync_loop()

Use cron ou similar. Exemplo crontab (a cada 6h):

0 */6 * * * cd /opt/smart-sync && python sync.py >> sync.log 2>&1

Para refletir mudanças do app.smart de volta ao sistema externo, use webhooks.

Cadastre o webhook com um segredo na própria URL — não há assinatura para validar:

from flask import Flask, request, abort
import os
app = Flask(__name__)
SEGREDO = os.environ['SMART_WEBHOOK_SECRET']
CRM_TOKEN = os.environ['CRM_TOKEN']
@app.post('/webhooks/smart')
def receber():
if request.args.get('k') != SEGREDO:
abort(401)
evento = request.json
# O corpo é o próprio contato, com o campo `event` junto —
# não existe envelope com `contact` dentro
if evento['event'] in ('contact_created', 'contact_updated'):
sincronizar(evento)
return '', 200
def sincronizar(contact):
"""Refletir mudança do app.smart no sistema externo."""
# Identificador externo já existente?
external_id = contact.get('identifier', '').replace('CRM-', '')
if external_id:
# Atualizar existente
requests.patch(
f"https://meucrm.com.br/api/contacts/{external_id}",
headers={"Authorization": f"Bearer {CRM_TOKEN}"},
json={
"nome": contact['name'],
"email": contact.get('email'),
"telefone": contact.get('phone_number')
}
)
else:
# Criar novo no CRM externo
r = requests.post(
"https://meucrm.com.br/api/contacts",
headers={"Authorization": f"Bearer {CRM_TOKEN}"},
json={
"nome": contact['name'],
"email": contact.get('email'),
"telefone": contact.get('phone_number')
}
)
new_external_id = r.json()['id']
# Voltar pro app.smart e gravar identifier
requests.patch(
f"{SMART_BASE}/contacts/{contact['id']}",
headers=HEADERS,
json={"identifier": f"CRM-{new_external_id}"}
)
if __name__ == '__main__':
app.run(port=5000)

Via UI ou API, criar webhook apontando para https://seuservidor.com.br/webhook/smart inscrito em:

  • contact_created
  • contact_updated

Sem cuidado, você cria loop:

External edita → webhook ao app.smart cria contato →
contact_created dispara → sync de volta cria no externo →
external_updated dispara → atualiza app.smart → loop infinito

Solução: marque contatos sincronizados com flag:

# Ao criar no app.smart vindo do external, marca origem
payload['custom_attributes']['_sync_source'] = 'external'
# No webhook do app.smart, ignora se origem == external
if contact['custom_attributes'].get('_sync_source') == 'external':
return # já está sincronizado

Sempre use identifier único e estável. Permite ao app.smart deduplicar automaticamente em casos de re-execução de sync.

User Access Token tem 300 requisições/min. Em sync de 50k contatos:

  • 50.000 / 300 = ~167 minutos = 2h45
  • Use time.sleep(0.2) para distribuir

Para volume maior, use importação batch via POST /contacts/import em vez de loop individual.

Quando ambos os lados editam o mesmo campo simultaneamente:

def merge_strategy(external, smart):
"""Última atualização vence."""
if external['updated_at'] > smart['updated_at']:
return external
return smart

Para casos críticos (dados financeiros), prefira fonte de verdade unilateral.

import logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s [%(levelname)s] %(message)s',
handlers=[
logging.FileHandler('sync.log'),
logging.StreamHandler()
]
)
logger = logging.getLogger(__name__)
# Em vez de print:
logger.info(f"Processando contato {external_id}")
logger.error(f"Falha na sync: {e}")

Webhook do Shopify dispara em customer.created / customer.updated → endpoint cria/atualiza no app.smart. Sem polling.

Polling a cada 1h via API do CRM. Custom attribute _rd_station_id para mapeamento.

Adicionar trigger no banco do ERP que chama webhook do app.smart via service no DB.