Best Practices & Troubleshooting

Best Practices

1. Date Management

Do

Use ISO 8601 for all dates
Consider merchant's time zone
Validate that next_payment_date is in the future
Verify that end_date is later than next_payment_date

Avoid

Dates in local format without time zone
Dates in the past for next_payment_date

2. State Management

Do

Follow the flow of allowed state transitions
Document reasons for status change
Notify clients about status changes

Avoid

Force transitions not allowed
Change status without validating consequences

3. Notifications

Do

Customize messages with customer information
Use consistent templates
Respect notification limits

Avoid

Send duplicate notifications
Use generic texts without personalization

4. Security

Do

Validate ownership in all operations
Use tokens with short expiration
Implement rate limiting
Log unauthorized access attempts

Avoid

Expose IDs without validation
Tokens without expiration
Allow cross access between accounts

Troubleshooting

Problem: "Cannot transition status from X to Y"

Cause: Attempted invalid state transition

Solution:

// Check current status
GET /api/direct-debits/:id
{ "status": "paused" }

// Use transition allowed
// Example: from 'paused' you can only go to 'active' or 'cancelled'
PATCH /api/direct-debits/:id
{ "status": "active" }

Problem: "CLABE not found"

Cause: CLABE does not exist or does not belong to the account

Solution:

// Verify that the CLABE exists
GET /api/customers/:customerId/clabes

{
    "count": 1,
    "docs": [
        {
            "clabe": "012555555555555555",
            "customer_rfc": "PERJ950714DL2",
            "bank_name": "BBVA México",
            "bank_code": "012",
            "alias": "Juan Perez",
            "is_active": false,
            "id": "6944a5366afaf625504595ea",
            "account_id": "68a4c3150b28a9584305a2a6", // Match
            "customer_id": "6944a4946afaf625504595e3"
        }
    ],
    "pages": 1
}

// Verify that it belongs to the same account
// The account_id must match
GET /api/customers?user_id=123456789

{
    "count": 1,
    "docs": [
        {
            "id": "6944a4946afaf625504595e3",
            "account_id": "68a4c3150b28a9584305a2a6", // Match
            "email": "[email protected]",
            "first_name": "Juan",
            "last_name": "Perez",
            "phone": "12345678",
            "user_id": "123456789",
            "created_at": "2025-12-19T01:04:20.133Z",
            "updated_at": "2025-12-19T01:04:20.133Z"
        }
    ],
    "pages": 1
}