Skip to main content

Welcome to Timbrix API

The Timbrix API lets you integrate CFDI 4.0 electronic invoicing into your own applications. Use it to manage organizations, customers, products, webhooks, and OAuth integrations programmatically.

OpenAPI Specification

Browse the spec that powers this reference

Live OpenAPI Spec (JSON/YAML)

Auto-generated from the live API on every request — the canonical spec for LLMs, AI agents, and codegen. Also available as YAML.

Base URL

All requests must be sent to:

Getting started

  1. Create a Timbrix account
  2. Create an API key from your organization settings
  3. Make your first request using the examples in this reference
Use the @timbrix/sdk TypeScript SDK or the @timbrix/cli CLI to get started faster.

Authentication

The API supports two authentication methods depending on your integration type:

API Key

Recommended for server-to-server integrations. Create a key in your organization settings and include it in every request:

OAuth 2.0

Use OAuth when your application needs to act on behalf of a Timbrix user. Timbrix supports:
  • Client Credentials — machine-to-machine access
  • Authorization Code — user consent flow with redirect
See the OAuth endpoints for token generation and the Authorization Code flow.

Rate limiting

Requests made with an API key are rate-limited per organization, based on your plan: All API keys of an organization share the same limit. You can give a single key a lower limit with rateLimitPerMinute and rateLimitPerHour (for example, for a test script), but a key can never exceed its plan. Keys without those fields use the plan limit. Requests made from the Timbrix dashboard, and requests authenticated with an OAuth access token, don’t count toward this limit. Every response to an API key request that passes authentication includes:
  • X-RateLimit-Limit: the limit that applies to this request.
  • X-RateLimit-Remaining: requests left in the current window.
  • X-RateLimit-Reset: when the window resets, as a Unix timestamp in seconds.
When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header (in seconds) and this body:
Rejected requests don’t count toward your limit, and no CFDI is stamped. Wait Retry-After seconds before retrying:
Some endpoints have their own, stricter limit, for example the PDF export of the invoices report (5 per minute). When you exceed one of those, the API also returns 429 Too Many Requests with a Retry-After header, but the body is different ({ "statusCode": 429, "message": "ThrottlerException: Too Many Requests" }), so check the status code and Retry-After rather than the body. The first time your organization gets a 429 in an hour, Timbrix emails the organization owner and, if you subscribed to it, sends the rate_limit.exceeded webhook. Contact support if you need higher limits.

Request ID

Every API response carries an X-Request-Id header. Include it when you contact support, and look it up with GET /request-logs/{id} or timbrix logs get <id>. See Depurar tu integración. Only requests made with a valid or attributable API key are stored in the log, and they can take a few seconds to appear. The header is not sent on /health, /docs or OPTIONS requests.

Error responses

The API returns standard HTTP status codes: Error responses include a message with details:

Next steps

API Keys

Create and manage API keys for your integration

Organizations

Manage organizations and fiscal settings

Webhooks

Receive real-time event notifications

OAuth

Build apps that authenticate on behalf of users