Production checklist

Before putting the integration into production, verify the following:

Auth and security

• The API key lives only in the backend, never in the frontend.
• The key is stored in a secrets manager (not in code or committed .env files).
• The webhookSecret is stored securely.
• The key has only the scopes it needs (principle of least privilege).
• HMAC verification is implemented in the webhook receiver.
• timingSafeEqual (not ===) is used to compare signatures.

Error handling

• 429 and 5xx are retried with exponential backoff.
• 4xx errors are not retried (except 429).
• Errors are logged with enough context for debugging.
• Alerts exist for Hacienda errors.

Idempotency and duplicates

• Idempotency-Key is used on every POST /facturas.
• The key is generated before the first attempt, not inside the retry loop.
• The webhook receiver deduplicates using nonce.

Performance

• Appropriate timeouts (30 s on POST, 10 s on GET).
• Webhooks are processed asynchronously (respond 2xx promptly).
• HTTP connections are reused (keep-alive).
• The rate limit is respected (no request bursts).

Operation

• Monitoring exists (latency, error rate).
• Alerts exist (5xx, rejected documents).
• Basic dashboards exist.
• The key’s prefix is logged for support purposes.
• The procedure to rotate the key without downtime is known.

Data

• The clave of every issuance is persisted in the integrator’s database.
• The rechazado case is handled with a notification to the user.
• PDFs/XMLs are stored locally if needed (you should not rely solely on LX).

Compliance

• The procedure to follow in case of rejection is known (notify the customer, reissue, etc.).
• The retention policy of the relevant jurisdiction is known.
• The accountant was consulted about special flows (NC, ND, contingency).