Desenvolvedores · Documentação técnica

Arena Upya

API Followups

Fila de follow-ups, criação, conclusão e penalidade de pontos.

Leiturafollowups.read

Escritafollowups.write

Endpoints

Método	Rota	Escopo	Descrição
`GET`	`/api/v1/followups`	`followups.read`	Fila (?bucket, user_id)
`GET`	`/api/v1/followups/{id}`	`followups.read`	Obter follow-up
`POST`	`/api/v1/followups`	`followups.write`	Criar (owner = user)
`POST`	`/api/v1/followups/{id}/done`	`followups.write`	Marcar concluído
`GET`	`/api/v1/followups/settings`	`followups.read`	Penalidade PTS
`PATCH`	`/api/v1/followups/settings`	`followups.write`	Atualizar penalidade

Por endpoint — assinaturas e exemplos

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`bucket`	`query`	`string`	não	hoje\|vao_vencer\|vencidos
`user_id`	`query`	`integer`	não	Filtrar dono
`external_code`	`query`	`string`	não	Código CRM

FollowupQueue

Resposta de `GET /followups`.

Campo	Tipo	Obrig.	Descrição
`items`	`array<Followup>`	não	Follow-ups abertos no horizonte.
`kpis`	`FollowupKpis`	não	—

FollowupKpis

KPIs da fila de follow-ups.

Campo	Tipo	Obrig.	Descrição
`total`	`integer`	não	— ex.: `8`
`hoje`	`integer`	não	— ex.: `2`
`vao_vencer`	`integer`	não	— ex.: `3`
`vencidos`	`integer`	não	— ex.: `3`

Followup

Follow-up / tarefa comercial.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `55`
`user_id`	`integer`	não	Dono. ex.: `42`
`client_name`	`string`	não	Cliente. ex.: `"Cliente Y"`
`action_text`	`string`	não	Ação a realizar.
`due_at`	`string`	não	Vencimento. ex.: `"2026-03-25"`
`status`	`string`	não	Status atual.

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 55,
                "user_id": 42,
                "client_name": "Cliente Y",
                "action_text": "Retornar ligação",
                "due_at": "2026-03-25",
                "status": "open"
            }
        ],
        "kpis": {
            "total": 1,
            "hoje": 0,
            "vao_vencer": 1,
            "vencidos": 0
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`id`	`path`	`integer`	sim	ID do recurso na empresa

Followup

Follow-up / tarefa comercial.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `55`
`user_id`	`integer`	não	Dono. ex.: `42`
`client_name`	`string`	não	Cliente. ex.: `"Cliente Y"`
`action_text`	`string`	não	Ação a realizar.
`due_at`	`string`	não	Vencimento. ex.: `"2026-03-25"`
`status`	`string`	não	Status atual.

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "followup": {
            "id": 55,
            "user_id": 42,
            "client_name": "Cliente Y",
            "action_text": "Retornar ligação",
            "due_at": "2026-03-25",
            "status": "open"
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

FollowupCreate — body

Body para criar follow-up. Identifique o usuário com `user_id` ou `external_code`.

Campo	Tipo	Obrig.	Descrição
`user_id`	`integer`	não	Usuário dono. ex.: `42`
`external_code`	`string`	não	Código CRM.
`client_name`	`string`	sim	Cliente. ex.: `"Cliente Y"`
`action_text`	`string`	sim	O que fazer. ex.: `"Retornar proposta"`
`due_at`	`string`	sim	Data de vencimento. ex.: `"2026-03-25"`
`client_contact`	`string`	não	Contato do cliente.
`stage`	`string`	não	Estágio do funil (texto livre).

Followup

Follow-up / tarefa comercial.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `55`
`user_id`	`integer`	não	Dono. ex.: `42`
`client_name`	`string`	não	Cliente. ex.: `"Cliente Y"`
`action_text`	`string`	não	Ação a realizar.
`due_at`	`string`	não	Vencimento. ex.: `"2026-03-25"`
`status`	`string`	não	Status atual.

Exemplo

Request POST (body)

{
    "external_code": "CRM-8841",
    "client_name": "Cliente Y",
    "action_text": "Retornar ligação",
    "due_at": "2026-03-25"
}

Response 2xx

{
    "status": "success",
    "data": {
        "followup": {
            "id": 55,
            "user_id": 42,
            "client_name": "Cliente Y",
            "action_text": "Retornar ligação",
            "due_at": "2026-03-25",
            "status": "open"
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

Body de ator é opcional; pode enviar {}.

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`id`	`path`	`integer`	sim	ID do recurso na empresa

UserRefBody — body

Identifica o usuário com `user_id` ou `external_code` (um dos dois).

Campo	Tipo	Obrig.	Descrição
`user_id`	`integer`	não	ID do usuário. ex.: `42`
`external_code`	`string · máx. 120`	não	Código CRM. ex.: `"CRM-8841"`

Followup

Follow-up / tarefa comercial.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `55`
`user_id`	`integer`	não	Dono. ex.: `42`
`client_name`	`string`	não	Cliente. ex.: `"Cliente Y"`
`action_text`	`string`	não	Ação a realizar.
`due_at`	`string`	não	Vencimento. ex.: `"2026-03-25"`
`status`	`string`	não	Status atual.

Exemplo

Request POST (body)

[]

Response 2xx

{
    "status": "success",
    "data": {
        "followup": {
            "id": 55,
            "user_id": 42,
            "client_name": "Cliente Y",
            "action_text": "Retornar ligação",
            "due_at": "2026-03-25",
            "status": "done"
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

FollowupSettings

Configuração de penalidade de follow-up.

Campo	Tipo	Obrig.	Descrição
`followup_penalty_points`	`integer`	não	Pontos debitados por atraso (0–500). ex.: `5`

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "followup_penalty_points": 5
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

FollowupSettings — body

Configuração de penalidade de follow-up.

Campo	Tipo	Obrig.	Descrição
`followup_penalty_points`	`integer`	não	Pontos debitados por atraso (0–500). ex.: `5`

FollowupSettings

Configuração de penalidade de follow-up.

Campo	Tipo	Obrig.	Descrição
`followup_penalty_points`	`integer`	não	Pontos debitados por atraso (0–500). ex.: `5`

Exemplo

Request PATCH (body)

{
    "followup_penalty_points": 5
}

Response 2xx

{
    "status": "success",
    "data": {
        "followup_penalty_points": 5
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

curl — criar

curl -X POST "https://arenaupya.com.br/api/v1/followups" \
  -H "Authorization: Bearer arena_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_code":"CRM-8841","client_name":"Cliente Y","action_text":"Retornar ligação","due_at":"2026-03-25"}'

Endpoints

Por endpoint — assinaturas e exemplos

GET /api/v1/followupsFila (items + kpis)

Parâmetros

FollowupQueue

FollowupKpis

Followup

Exemplo

GET /api/v1/followups/{id}Obter follow-up

Parâmetros

Followup

Exemplo

POST /api/v1/followupsCriar follow-up

FollowupCreate — body

Followup

Exemplo

POST /api/v1/followups/{id}/doneMarcar concluído

Parâmetros

UserRefBody — body

Followup

Exemplo

GET /api/v1/followups/settingsPenalidade em pontos

FollowupSettings

Exemplo

PATCH /api/v1/followups/settingsAtualizar penalidade

FollowupSettings — body

FollowupSettings

Exemplo

curl — criar