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.
Estratégia recomendada
Seção intitulada “Estratégia recomendada”Modelo “fonte de verdade definida”
Seção intitulada “Modelo “fonte de verdade definida””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.
Componentes
Seção intitulada “Componentes”┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐│ 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) │└─────────────────┘ └──────────────────┘ └──────────────┘Implementação completa em Python
Seção intitulada “Implementação completa em Python”Pré-requisitos
Seção intitulada “Pré-requisitos”pip install requestsVariáveis de ambiente
Seção intitulada “Variáveis de ambiente”export SMART_TOKEN="seu_token"export SMART_ACCOUNT_ID="1"export SMART_BASE_URL="https://app.smart2.com.br/api/v1/accounts/1"Código principal
Seção intitulada “Código principal”import osimport timeimport requestsfrom 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()Agendar execução
Seção intitulada “Agendar execução”Use cron ou similar. Exemplo crontab (a cada 6h):
0 */6 * * * cd /opt/smart-sync && python sync.py >> sync.log 2>&1Sincronia bidirecional (avançado)
Seção intitulada “Sincronia bidirecional (avançado)”Para refletir mudanças do app.smart de volta ao sistema externo, use webhooks.
Endpoint de webhook (Flask)
Seção intitulada “Endpoint de webhook (Flask)”Cadastre o webhook com um segredo na própria URL — não há assinatura para validar:
from flask import Flask, request, abortimport 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)Configurar webhook no app.smart
Seção intitulada “Configurar webhook no app.smart”Via UI ou API, criar webhook apontando para https://seuservidor.com.br/webhook/smart inscrito em:
contact_createdcontact_updated
Cuidados práticos
Seção intitulada “Cuidados práticos”Evitar loop infinito
Seção intitulada “Evitar loop infinito”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 infinitoSolução: marque contatos sincronizados com flag:
# Ao criar no app.smart vindo do external, marca origempayload['custom_attributes']['_sync_source'] = 'external'
# No webhook do app.smart, ignora se origem == externalif contact['custom_attributes'].get('_sync_source') == 'external': return # já está sincronizadoDedup via identifier
Seção intitulada “Dedup via identifier”Sempre use identifier único e estável. Permite ao app.smart deduplicar automaticamente em casos de re-execução de sync.
Rate limit
Seção intitulada “Rate limit”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.
Resolução de conflitos
Seção intitulada “Resolução de conflitos”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 smartPara casos críticos (dados financeiros), prefira fonte de verdade unilateral.
Logging para debug
Seção intitulada “Logging para debug”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}")Variações por caso de uso
Seção intitulada “Variações por caso de uso”E-commerce (Shopify)
Seção intitulada “E-commerce (Shopify)”Webhook do Shopify dispara em customer.created / customer.updated → endpoint cria/atualiza no app.smart. Sem polling.
CRM (RD Station, HubSpot)
Seção intitulada “CRM (RD Station, HubSpot)”Polling a cada 1h via API do CRM. Custom attribute _rd_station_id para mapeamento.
ERP custom
Seção intitulada “ERP custom”Adicionar trigger no banco do ERP que chama webhook do app.smart via service no DB.
Próximos passos
Seção intitulada “Próximos passos”- Contacts (referência) — referência completa
- Webhooks — Introdução
- Etiquetar e segmentar contatos