{
    "version": "1.3.0",
    "updated_at": "2026-05-18",
    "reference": "frete-center-flex",
    "docs_url": "https://rallydevendas.com.br/docs/partner-webhook",
    "spec_repo": "https://github.com/andrehocsis/rally-de-vendas/blob/main/DOCUMENTACAO/ARQUITETURA/FRETE_CENTER_FLEX.md",
    "auth": {
        "type": "HMAC-SHA256",
        "signature_header": "X-Rally-Signature",
        "timestamp_header": "X-Rally-Timestamp",
        "replay_window_seconds": 300,
        "signature_format": "sha256=<hex_digest>",
        "signed_payload": "raw request body"
    },
    "rally_inbound_webhooks": [
        {
            "method": "POST",
            "path": "/webhooks/{partner-name}/status",
            "description": "Partner notifies Rally about a job status change",
            "body_schema": {
                "rally_user_id": "string (required) — Rally user UUID",
                "rally_dispatch_id": "string (optional) — Rally internal dispatch ID (echoed from /api/v1/dispatch meta)",
                "dispatch_id": "string (required) — partner external dispatch ID",
                "status": "enum (required) — accepted|picked_up|in_transit|delivered|refused|cancelled",
                "note": "string (optional) — human-readable context"
            },
            "response_200": {
                "ok": "boolean"
            },
            "errors": [
                "401 invalid_signature",
                "401 stale_timestamp",
                "422 missing_required_fields",
                "503 webhook_secret_missing"
            ]
        },
        {
            "method": "POST",
            "path": "/webhooks/{partner-name}/invite-code",
            "description": "Sync invite code generated/used in partner system",
            "body_schema": {
                "code": "string (required, 8 chars, uppercase)",
                "carrier_id": "string (required) — partner service ID",
                "carrier_name": "string (required) — display name",
                "generated_at": "ISO 8601 (optional, defaults to now)",
                "expires_at": "ISO 8601 (required) — code expiration"
            }
        },
        {
            "method": "POST",
            "path": "/webhooks/{partner-name}/payment-confirmed",
            "description": "Partner confirmed PIX receipt",
            "body_schema": {
                "rally_user_id": "string (required)",
                "rally_dispatch_id": "string (required)"
            }
        }
    ],
    "partner_outbound_endpoints_expected": {
        "GET /api/v1/carriers/by-invite-code?code={code}": "Validate invite code; return service metadata { carrier_id, carrier_name, pix_key, pix_key_type, logo_url, expires_at }",
        "GET /api/v1/quote?carrier_id&cep_o&cep_d&peso_g&pacotes": "Estimated price",
        "GET /api/v1/pickup-points?carrier_id&cep": "Nearby pickup points",
        "POST /api/v1/dispatch": "Create dispatch — body: { external_order_id, ml_shipment_id, carrier_id, pickup_point_id, buyer_address, package, callback_url, meta }",
        "POST /api/v1/dispatch/{id}/cancel": "Cancel dispatch",
        "GET /api/v1/dispatch/{id}": "Current state (poll fallback)"
    },
    "rally_concepts_used": {
        "PlanGuard": "Feature gate per plan (paid/managed for premium integrations)",
        "AggregateCache": "File-based TTL cache pra admin dashboards (5min default)",
        "Webhook HMAC pattern": "Body raw + SHA256 hex + ±5min replay window",
        "Killswitch files": "storage/logs/.{feature}_paused — 100% disable sem deploy",
        "finfo MIME validation": "Server-side file type check (nunca confiar em $_FILES.type)",
        "WA throttle 2s": "Mínimo 2 segundos entre envios + idempotência per-event"
    },
    "reference_implementation": {
        "name": "Frete.Center Flex",
        "status": "live in production since 2026-05-18",
        "files": [
            "app/Models/CarrierLink.php",
            "app/Models/FlexDispatch.php",
            "app/Models/PickupPoint.php",
            "app/Models/CarrierInviteCode.php",
            "app/Models/FlexSettlement.php",
            "app/Services/FreteCenterClient.php",
            "app/Services/FlexDispatchService.php",
            "app/Services/FlexSettlementService.php",
            "app/Services/FlexAdminMetricsService.php",
            "app/Services/FlexDispatchWaNotifier.php",
            "app/Controllers/Painel/PainelTransportadorasController.php",
            "app/Controllers/Admin/AdminFreteCenterController.php",
            "app/Controllers/Webhooks/FreteCenterWebhookController.php"
        ]
    },
    "contact": {
        "whatsapp": "+5511985042880",
        "email": "devs@rallydevendas.com.br"
    }
}