Fibek Collections Skill

You can interact with the Fibek B2B collections platform API. This skill enables you to authenticate, query invoices, manage clients, create payment agreements, run collection campaigns, and monitor financial metrics.

Configuration

The following environment variable must be set:

• FIBEK_BASE_URL: The API base URL (e.g., https://dev.backend.fibek.co or https://backend.fibek.co)

Authentication

The user must authenticate before you can make any API calls. You do NOT have pre-configured credentials — each user logs in with their own account.

Flow

1. When the user sends their first message (or any request that requires API access), check if you already have a token stored from a previous exchange in this conversation.
2. If you don't have a token, ask the user for their email and password.
3. Once the user provides credentials, authenticate:

TOKEN=$(curl -s -X POST "${FIBEK_BASE_URL}/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "USER_EMAIL", "password": "USER_PASSWORD"}' \
  | jq -r '.token')

4. If authentication fails (401 or empty token), tell the user their credentials are invalid and ask them to try again.
5. If authentication succeeds, store the token and use it for all subsequent requests. Do NOT ask for credentials again unless you get a 401 response.
6. The token is valid for a long time. Reuse it across the entire conversation.

Using the token

curl -s "${FIBEK_BASE_URL}/endpoint" \
  -H "Authorization: Bearer ${TOKEN}"

Re-authentication

If any API call returns 401, the token has expired. Ask the user to provide their credentials again.

Available Operations

Invoices

• List invoices: GET /invoices?companyRelationshipId={clientId}&status=open
• Get invoice summary: GET /invoices/summary
• Send payment reminder: POST /invoices/sendPaymentReminder with body {"invoiceIds": [1,2,3], "channel": "WHATSAPP"}
• Send account statement: POST /invoices/sendAccountStatement
• Get invoice history: GET /invoices/{invoiceId}/system-actions

Clients (Company Relationships)

• List clients with monitoring: GET /monitoring/clients-summary?page=1&limit=10
• Get client actions: GET /monitoring/{clientId}/actions
• Get client details: GET /companies/relationships/{relationshipId}
• Get classifications: GET /companies/relationships/unique-classifications
• Search clients: GET /companies/clients-with-contacts?searchValue={query}

Payment Agreements

• List agreements: GET /payment-agreements?status=ACTIVE
• Get agreement summary: GET /payment-agreements/summary
• Preview invoice association: GET /payment-agreements/preview-association?totalAmount={amount}&companyRelationshipId={clientId}
• Create agreement: POST /payment-agreements with body containing companyRelationshipId, totalAmount, currency, and schedules array
• Get overdue schedules: GET /payment-agreements/overdue-schedules
• Send reminder: POST /payment-agreements/{id}/send-reminder

Campaigns

• List campaigns: GET /campaigns?page=1&limit=10
• Create campaign: POST /campaigns
• Validate criteria: POST /campaign-execution/validate
• Test with single client: POST /campaign-execution/{id}/test/execute
• Execute campaign: POST /campaign-execution/{id}/execute
• Get run analytics: GET /campaign-analytics/runs/{runId}
• Weekly metrics: GET /campaign-analytics/weekly-metrics

Metrics & Dashboard

• Delinquency rate: GET /widgets/delinquency-indicator
• Collection rate: GET /widgets/collection-rate
• Agent KPIs: GET /agent-metrics/kpis
• Conversion funnel: GET /agent-metrics/funnel
• Active agreements: GET /payment-agreement-metrics/active
• Cash flow projection: GET /collections-projection/summary
• Financial metrics: GET /financial-metrics

Swagger Spec

For the complete API specification in OpenAPI format:

curl -s "${FIBEK_BASE_URL}/swagger/json" | jq .

Common Flows

Flow 1: Send Payment Reminder to Overdue Client

# 1. Find overdue invoices for a client
INVOICES=$(curl -s "${FIBEK_BASE_URL}/invoices?companyRelationshipId=${CLIENT_ID}&status=overdue" \
  -H "Authorization: Bearer ${TOKEN}")

# 2. Check if client was contacted recently
ACTIONS=$(curl -s "${FIBEK_BASE_URL}/monitoring/${CLIENT_ID}/actions?actionPeriodDays=7" \
  -H "Authorization: Bearer ${TOKEN}")

# 3. Send reminder (only if not recently contacted)
curl -s -X POST "${FIBEK_BASE_URL}/invoices/sendPaymentReminder" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"invoiceIds": [1, 2, 3], "channel": "WHATSAPP"}'

Flow 2: Create Payment Agreement

# 1. Preview which invoices would be covered
curl -s "${FIBEK_BASE_URL}/payment-agreements/preview-association?totalAmount=5000000&companyRelationshipId=${CLIENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

# 2. Create the agreement
curl -s -X POST "${FIBEK_BASE_URL}/payment-agreements" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyRelationshipId": 123,
    "totalAmount": 5000000,
    "currency": "COP",
    "schedules": [
      {"dueDate": "2026-05-15", "amount": 2500000},
      {"dueDate": "2026-06-15", "amount": 2500000}
    ]
  }'

Flow 3: Daily Monitoring Dashboard

# Get all KPIs at once
curl -s "${FIBEK_BASE_URL}/widgets/delinquency-indicator" -H "Authorization: Bearer ${TOKEN}"
curl -s "${FIBEK_BASE_URL}/widgets/collection-rate" -H "Authorization: Bearer ${TOKEN}"
curl -s "${FIBEK_BASE_URL}/monitoring/summary" -H "Authorization: Bearer ${TOKEN}"
curl -s "${FIBEK_BASE_URL}/payment-agreements/overdue-schedules" -H "Authorization: Bearer ${TOKEN}"
curl -s "${FIBEK_BASE_URL}/collections-projection/summary" -H "Authorization: Bearer ${TOKEN}"

Response Format

IMPORTANT: Never show raw JSON to the user. Always present API responses in natural language with clear formatting.

Formatting Rules

• Summaries: Present as a brief narrative with key numbers highlighted
• Lists of items (invoices, clients, agreements): Use tables with the most relevant columns
• Monetary amounts: Always format with thousand separators and currency symbol (e.g., $1.250.000 COP)
• Dates: Use human-readable format (e.g., 15 de mayo de 2026)
• Counts: Use context (e.g., "Tienes 292 facturas en borrador" instead of "draft count: 292")
• Status values: Translate to Spanish if the user speaks Spanish (ACTIVE → Activo, OVERDUE → Vencido, PAID → Pagado, PENDING → Pendiente, DRAFT → Borrador)

Example: Invoice Summary

Instead of showing JSON, present it like:

📊 Resumen de Facturas

Error Handling

• 401 Unauthorized: Token is missing, invalid, or expired. Re-authenticate.
• 403 Forbidden: User doesn't have permission for this operation (check roles).
• 404 Not Found: Resource doesn't exist or belongs to a different company.
• 400 Bad Request: Invalid parameters. Check the Swagger spec for required fields.

Notes

• All monetary amounts are in the company's default currency unless specified otherwise
• Dates use ISO 8601 format (YYYY-MM-DD)
• Pagination: most list endpoints support page and limit query parameters
• The API validates company ownership — you can only access resources belonging to your authenticated company