{
    "openapi": "3.0.3",
    "info": {
        "title": "Arena Upya API",
        "description": "API REST para integração server-to-server com o Arena Upya (Ranking e vendas).\r\n\r\nAutenticação: **API Key** estática por empresa.\r\n\r\n## Autenticação\r\n\r\nTodas as rotas (exceto health) exigem uma das opções:\r\n\r\n1. `Authorization: Bearer <api_key>`\r\n2. `X-API-Key: <api_key>`\r\n\r\nGere e revogue chaves em **App → API**. Escopo v1: `ranking.entries.write`.\r\n\r\n## Envelope de resposta\r\n\r\n**Sucesso**\r\n```json\r\n{ \"status\": \"success\", \"data\": { }, \"meta\": { \"request_id\": \"…\" } }\r\n```\r\n\r\n**Erro**\r\n```json\r\n{ \"status\": \"error\", \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"…\" }, \"meta\": { \"request_id\": \"…\" } }\r\n```\r\n\r\nCódigos: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`.",
        "version": "1.0.0",
        "contact": {
            "name": "Arena Upya",
            "url": "https://arenaupya.com.br"
        }
    },
    "servers": [
        {
            "url": "https://arenaupya.com.br",
            "description": "Ambiente atual"
        }
    ],
    "tags": [
        {
            "name": "Health",
            "description": "Status da API (sem autenticação)"
        },
        {
            "name": "Ranking",
            "description": "Lançamentos de vendas / ranking"
        }
    ],
    "paths": {
        "/api/v1/health": {
            "get": {
                "tags": [
                    "Health"
                ],
                "summary": "Health check",
                "operationId": "healthCheck",
                "security": [],
                "responses": {
                    "200": {
                        "description": "API disponível",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HealthResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/ranking/entries": {
            "post": {
                "tags": [
                    "Ranking"
                ],
                "summary": "Registrar venda / lançamento",
                "description": "O CRM do cliente envia uma venda para a campanha. Identifique o vendedor com `seller_email`, `external_seller_id` ou `seller_id`. Se `campaign_id` for omitido, usa a campanha ativa.",
                "operationId": "createRankingEntry",
                "security": [
                    {
                        "BearerAuth": []
                    },
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 120
                        },
                        "description": "Chave de idempotência (alternativa ao campo JSON `idempotency_key`)."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/RankingEntryCreate"
                            },
                            "examples": {
                                "porEmail": {
                                    "summary": "Por e-mail do vendedor",
                                    "value": {
                                        "seller_email": "ana@empresa.com",
                                        "amount": 2500,
                                        "occurred_at": "2026-03-20T10:00:00",
                                        "reason": "Venda CRM #123"
                                    }
                                },
                                "porIdExterno": {
                                    "summary": "Por ID externo + campanha",
                                    "value": {
                                        "external_seller_id": "42",
                                        "amount": 990.5,
                                        "campaign_id": 12,
                                        "idempotency_key": "pedido-9981"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Lançamento criado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RankingEntrySuccess"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Mesmo lançamento (idempotente)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RankingEntrySuccess"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key inválida ou ausente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Escopo insuficiente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Campanha ou vendedor não encontrado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Dados inválidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "API Key",
                "description": "Authorization: Bearer arena_live_…"
            },
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "X-API-Key: arena_live_…"
            }
        },
        "schemas": {
            "HealthResponse": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "success"
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "ok": {
                                "type": "boolean",
                                "example": true
                            },
                            "version": {
                                "type": "string",
                                "example": "v1"
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "RankingEntryCreate": {
                "type": "object",
                "required": [
                    "amount"
                ],
                "properties": {
                    "amount": {
                        "type": "number",
                        "description": "Valor do lançamento (obrigatório)",
                        "example": 1500.5
                    },
                    "seller_email": {
                        "type": "string",
                        "format": "email",
                        "description": "E-mail do vendedor (ranking_sellers ou users)"
                    },
                    "external_seller_id": {
                        "type": "string",
                        "description": "ID numérico de ranking_sellers ou user_id"
                    },
                    "seller_id": {
                        "type": "integer",
                        "description": "ID interno do vendedor no Arena"
                    },
                    "campaign_id": {
                        "type": "integer",
                        "description": "Opcional. Default = campanha ativa da empresa"
                    },
                    "occurred_at": {
                        "type": "string",
                        "description": "Data/hora do evento (ISO ou Y-m-d H:i:s)",
                        "example": "2026-03-20T14:30:00"
                    },
                    "reason": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Observação / referência externa"
                    },
                    "idempotency_key": {
                        "type": "string",
                        "maxLength": 120,
                        "description": "Evita duplicar o mesmo evento"
                    }
                }
            },
            "RankingEntrySuccess": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "success"
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer",
                                "example": 101
                            },
                            "campaign_id": {
                                "type": "integer",
                                "example": 12
                            },
                            "seller_id": {
                                "type": "integer",
                                "example": 5
                            },
                            "amount": {
                                "type": "number",
                                "example": 2500
                            },
                            "occurred_at": {
                                "type": "string",
                                "example": "2026-03-20 10:00:00"
                            },
                            "idempotent": {
                                "type": "boolean",
                                "example": false
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "error"
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "UNAUTHORIZED"
                            },
                            "message": {
                                "type": "string"
                            },
                            "details": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "Meta": {
                "type": "object",
                "properties": {
                    "request_id": {
                        "type": "string",
                        "example": "a1b2c3d4e5f6…"
                    }
                }
            }
        }
    }
}