Fibek Collections Skill

Interact with the Fibek B2B collections platform API. Authenticate users, query invoices, manage clients, create payment agreements, and monitor financial metrics.

Environment variable required: FIBEK_BASE_URL

Authentication

Each user logs in with their own account. No pre-configured credentials.

On first message, if no token stored, respond: "¡Hola! Para comenzar necesito que inicies sesión o te registres. ¿Ya tienes cuenta en Fibek o quieres registrarte?" Do NOT process other requests until authenticated.
If token exists, verify with GET /user/me and greet by name.

Login: Ask email + password → POST /auth/login body {"email":"...", "password":"..."} → response: {success, token, expiresAt, user: {id, email, names, lastnames, companyId, roles[]}, error?, message?}. On success, store token and greet by user.names. On failure, show message and ask to retry. Error codes: INVALID_CREDENTIALS, USER_NOT_FOUND, NO_COMPANY, USER_DISABLED.

Registro: Guide step by step in this exact order:

Ask: empresa, nombre, apellido
Ask: email y celular
Verify email: call POST /auth/send/verification-code body {"email":"..."} → tell user a code was sent to their email → ask for the 6-digit code → call POST /auth/check/verification-code body {"email":"...", "code":"..."} → if false, ask to retry
Ask: contraseña (min 6 characters)
Register: POST /auth/user/by/phone body {"companyName":"...", "email":"...", "password":"...", "phone":"...", "names":"...", "lastnames":"..."} → response: {success}. Then auto-login with POST /auth/login.

Do NOT call registration without verifying the email code first.

Logout: Discard token, ask new credentials. Re-auth: On 401, ask credentials again.

Token header: Authorization: Bearer ${TOKEN} (JWT, 5-year validity)

Endpoints

Invoices

GET /invoices?companyRelationshipId={id}&status=open — list invoices
GET /invoices/summary — invoice summary
POST /invoices/sendPaymentReminder — body: {invoiceIds[], relationshipId, communicationChannels[]} (channels: EMAIL, WHATSAPP, CALLS, SMS; optional: contactId)
POST /invoices/sendAccountStatement — body: {clientId, communicationChannels[]} (optional: contactId)
GET /invoices/{invoiceId}/system-actions — invoice history

Clients

GET /companies/clients-with-contacts?searchValue={query} — search by name/NIT
GET /companies/relationships/{relationshipId} — client details
GET /companies/relationships/unique-classifications — classifications

Monitoring

GET /monitoring/clients-summary — filters: search, limit, offset, invoiceStatusFilter (all/open/open_with_due/due_soon), dueSoonDays, minDaysPastDue, actionFilter, actionPeriodDays, onlyOpenInvoices
GET /monitoring/summary — monitoring summary
GET /monitoring/{clientId}/actions — client actions

Aging Analysis

GET /companies/relationships/metrics/clients-with-due-categories — clients with aging buckets (onTime, days1_15, days16_30, days31_60, days61_90, days90Plus). Each has totalPendingAmount, earliestDueDate, dueCategories[]. Sort: sortBy (buyerName/totalPendingAmount/days1_15/etc), sortOrder (ASC/DESC). Filter: limit, name, nit, status, relationshipIds[]
GET /companies/relationships/metrics/strategy-kpi-quarter — per-client quarterly KPIs (sales, collections, DSO, delinquency). Sort: sortBy (quarterSales/quarterCollections/quarterDso/delinquencyRate/etc), sortOrder. Filter: relationshipIds[], name, nit
GET /companies/relationships/metrics/strategy-kpi-month — same, monthly
GET /companies/relationships/metrics/strategy-kpi-week — same, weekly

Financial Metrics

GET /financial-metrics — required: level (general/client/segment), metrics[], startDate, endDate. Metrics: portfolio_days_dso, credit_sales, collection_amount, collection_effectiveness, delinquency_indicator, average_portfolio, weighted_due_days, portfolio_ageing, credit_limit_utilization, term_dso_ratio, dso_term_difference. Optional: relationshipIds[], sortBy, sortOrder, limit
GET /financial-metrics/comparison — required: level, metric (single), startDates[], endDates[], labels[]. Returns period comparison with deltas.
GET /financial-metrics/historical — required: level, metric, granularity (daily/weekly/monthly/quarterly/yearly), periodsBack
GET /financial-metrics/metadata — available metrics info

Payments

GET /account-receivables/payments — filter: accountReceivableId, page, limit. Returns: receiptDate, paymentMethod, totalAmount, currency
GET /account-receivables/payments/{id} — payment detail

Payment Agreements

GET /payment-agreements — filter: status (ACTIVE/COMPLETED/CANCELLED), upcoming=true&daysAhead=7, companyRelationshipId, searchTerm, page, limit
GET /payment-agreements/by-client — filter: period (week/month), status, clientId
GET /payment-agreements/summary
GET /payment-agreements/preview-association?totalAmount={n}&companyRelationshipId={id}
GET /payment-agreements/overdue-schedules
GET /payment-agreements/{id}/schedules
GET /payment-agreements/{id}/payments
POST /payment-agreements/{id}/send-reminder
POST /payment-agreements — required: companyRelationshipId, description, totalAmount, currency, schedules[] (each: scheduledDate required, amount or percentage, optional notes). Optional: invoiceIds[], invoices[] ({invoiceId, amountIncluded?}), autoRemindersEnabled, reminderDays

Dashboard Widgets

GET /widgets/delinquency-indicator, GET /widgets/collection-rate, GET /widgets/receivables-turnover, GET /widgets/weighted-due-days
GET /agent-metrics/kpis, GET /agent-metrics/funnel
GET /payment-agreement-metrics/active, GET /payment-agreement-metrics/adherence
GET /collections-projection/summary

Campaigns

GET /campaigns, POST /campaigns, POST /campaign-execution/validate, POST /campaign-execution/{id}/execute, GET /campaign-analytics/runs/{runId}, GET /campaign-analytics/weekly-metrics

Flows

US-01 Auth: Ask login or register → authenticate → greet by name

US-02 Cartera próxima: "¿Qué vence esta semana?" → GET /monitoring/clients-summary?invoiceStatusFilter=due_soon&dueSoonDays=7 + GET .../metrics/clients-with-due-categories?sortBy=totalPendingAmount&sortOrder=DESC → table: Cliente | Monto | Fecha

US-03 Mayor deuda: "¿Quién me debe más?" → GET .../metrics/clients-with-due-categories?sortBy=totalPendingAmount&sortOrder=DESC&limit=10 → table with aging distribution. Follow-up "último pago": GET .../strategy-kpi-quarter?relationshipIds[]={id}

US-04 Historial pagos: "¿Último pago de [X]?" → search client → GET .../strategy-kpi-quarter?relationshipIds[]={id} + GET /account-receivables/payments?accountReceivableId={id}. Handle name ambiguity.

US-05 DSO drill-down: "¿Por qué está alto el DSO?" → GET /financial-metrics?level=general&metrics[]=portfolio_days_dso → GET /financial-metrics/comparison?level=client&metric=portfolio_days_dso&sortOrder=desc&limit=5 (top 5 worst) → GET /financial-metrics?metrics[]=credit_sales&metrics[]=collection_amount → interpret in natural language. NEVER recalculate, only interpret API data.

US-06 Comparación períodos: "¿Ventas vs mes pasado?" → GET /financial-metrics/comparison?level=general&metric=credit_sales + metric=collection_amount → for client drop: level=client&sortOrder=asc&limit=5 → present deltas absolute + %

US-07 Crear promesa de pago: Guided multi-step: 1) ¿Cliente? (search) 2) ¿Descripción? 3) ¿Monto y moneda? 4) ¿Facturas específicas o libre? 5) ¿Cuotas y fechas? 6) ¿Recordatorios? 7) Mostrar resumen, pedir confirmación 8) POST /payment-agreements 9) Ofrecer enviar recordatorio

US-08 Estado de cuenta: "Avísale a [X]" → search client → ask channel → POST /invoices/sendAccountStatement body {clientId, communicationChannels}

US-09 Promesas activas: "¿Acuerdos esta semana?" → GET /payment-agreements?upcoming=true&daysAhead=7&status=ACTIVE or GET /payment-agreements/by-client?period=week → table: Cliente | Monto | Fecha | Estado

Dashboard: Fetch delinquency, collection rate, monitoring summary, overdue schedules, projection in parallel.

Swagger Discovery

For unlisted endpoints: curl -s "${FIBEK_BASE_URL}/swagger/json" | jq '.paths | keys'

Response Format

Never show raw JSON. Format responses as:

Tables for lists (invoices, clients, agreements)
Monetary: thousand separators + currency ($1.250.000 COP)
Dates: human-readable (15 de mayo de 2026)
Status: translate to Spanish (ACTIVE→Activo, OVERDUE→Vencido, PAID→Pagado)
DSO/metrics: include units (52.3 días)

Error Handling

401: Re-authenticate. 403: No permission. 404: Not found. 400: Bad params, check Swagger.
Connection errors (ECONNREFUSED, timeout, network errors): Tell the user "Estamos teniendo problemas técnicos en este momento. Por favor intentá de nuevo en unos minutos." NEVER mention internal details like URLs, server names, Docker, localhost, ports, or infrastructure. The user is a client, not a developer.