Guia de Integração

Fluxos de integração entre sistemas externos (PDV, e-commerce, CRM) e as APIs da Rock Encantech.

---

Integração com PDV

O PDV precisa consultar ofertas ativas e registrar resgates no momento da compra. EDU

Fluxo completo

sequenceDiagram
    autonumber
    participant PDV
    participant Propz as Propz API
    participant Loyalty as LL Loyalty API

    PDV->>Propz: POST /campaigns/validate (customer_id + carrinho)
    Propz-->>PDV: eligible_campaigns + validation_token

    Note over PDV: Exibe ofertas ao operador/cliente

    PDV->>Propz: POST /campaigns/{id}/redeem (validation_token)
    Propz-->>PDV: redemption_id + benefit_applied

    PDV->>Loyalty: POST /points/credit (customer_id + order_id)
    Loyalty-->>PDV: points_credited + new_balance

Checklist de implementação

• [ ] Autenticação OAuth 2.0 configurada com refresh automático
• [ ] Chamada de validação antes de fechar a venda
• [ ] Exibição da lista de ofertas elegíveis ao operador
• [ ] Registro do resgate após confirmação do pagamento
• [ ] Crédito de pontos no LL Loyalty após cada compra
• [ ] Tratamento de timeout (chamada deve responder em < 3s)
• [ ] Fallback offline: se a API não responder, finalizar a venda sem desconto e sincronizar depois

---

Integração com E-commerce

O e-commerce tem um fluxo similar ao PDV, porém com algumas particularidades de canal.

Pontos de integração

Momento	Ação	Endpoint
Carrinho	Exibir selos de campanhas ativas	GET /v1/campaigns?channel=ecommerce
Checkout	Validar ofertas aplicáveis	POST /v1/campaigns/validate
Pós-pagamento	Registrar resgate e creditar pontos	POST /campaigns/{id}/redeem + POST /points/credit
Perfil do cliente	Exibir saldo de pontos e nível	GET /v1/customers/{id}

---

Integração com CRM

Sincronização de cadastros

Para manter os perfis de clientes atualizados no Bnex a partir do CRM:

import requests

def sync_customer(crm_customer: dict, token: str):
    """
    Cria ou atualiza um cliente no Bnex com base no ID externo do CRM.
    """
    external_id = crm_customer["id"]

    # Verifica se já existe
    resp = requests.get(
        f"https://api.rockencantech.com.br/v1/customers",
        params={"search": external_id},
        headers={"Authorization": f"Bearer {token}"}
    )
    existing = resp.json().get("data", [])

    payload = {
        "external_id": external_id,
        "name": crm_customer["name"],
        "email": crm_customer["email"],
        "cpf": crm_customer.get("cpf"),
        "phone": crm_customer.get("phone"),
    }

    if existing:
        # Atualiza
        customer_id = existing[0]["id"]
        requests.patch(
            f"https://api.rockencantech.com.br/v1/customers/{customer_id}",
            json=payload,
            headers={"Authorization": f"Bearer {token}"}
        )
    else:
        # Cria
        requests.post(
            "https://api.rockencantech.com.br/v1/customers",
            json=payload,
            headers={"Authorization": f"Bearer {token}"}
        )

---

Tratamento de erros e resiliência

Retry com backoff exponencial

import time
import requests

def call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            resp = requests.get(url, headers=headers, timeout=5)
            if resp.status_code == 429:
                retry_after = int(resp.headers.get("Retry-After", 60))
                time.sleep(retry_after)
                continue
            resp.raise_for_status()
            return resp.json()
        except requests.exceptions.Timeout:
            wait = 2 ** attempt
            time.sleep(wait)
    raise Exception(f"Falha após {max_retries} tentativas")

Idempotência

Use o header Idempotency-Key ao criar resgates para evitar duplicidade em caso de retentativa:

Idempotency-Key: ped_20260430001_cmp_01ABC123

---

Webhooks (em breve)

A Rock Encantech está desenvolvendo suporte a webhooks para notificações push de eventos como:

• Upgrade/downgrade de nível do cliente
• Expiração iminente de pontos
• Ativação de nova campanha para segmento