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":"..."} → store token. On success, call GET /user/me to greet.

Registro: Guide step by step (empresa, email, contraseña, celular, nombre, apellido) → POST /auth/user/by/phone body {"companyName":"...", "email":"...", "password":"...", "phone":"...", "names":"...", "lastnames":"..."} → auto-login after.

Verification (if needed): POST /auth/send/verification-code → ask code → POST /auth/check/verification-code

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

Token header: Authorization: Bearer ${TOKEN}

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.