curl --request GET \
--url https://api.timbrix.mx/invoices \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.timbrix.mx/invoices"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.timbrix.mx/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbrix.mx/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.timbrix.mx/invoices"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.timbrix.mx/invoices")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbrix.mx/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"serie": "A",
"folio": "1",
"tipoComprobante": "I",
"rfcReceptor": "GODE561231GR8",
"moneda": "MXN",
"total": 116,
"status": "vigente",
"environment": "production",
"createdAt": "2026-07-30T22:50:03.412Z",
"requiresReceptorApproval": false,
"cancellationDesynced": false,
"cancellationStatus": "pendiente"
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}List Invoices
Authenticate with either a Supabase session (send the X-Organization-Id header, must be a member of that organization) or an API key (external integrations, requires the read:invoices scope). Results are ordered by creation date, newest first.
curl --request GET \
--url https://api.timbrix.mx/invoices \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.timbrix.mx/invoices"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.timbrix.mx/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbrix.mx/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.timbrix.mx/invoices"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.timbrix.mx/invoices")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbrix.mx/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"serie": "A",
"folio": "1",
"tipoComprobante": "I",
"rfcReceptor": "GODE561231GR8",
"moneda": "MXN",
"total": 116,
"status": "vigente",
"environment": "production",
"createdAt": "2026-07-30T22:50:03.412Z",
"requiresReceptorApproval": false,
"cancellationDesynced": false,
"cancellationStatus": "pendiente"
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}This endpoint takes noorganizationIdin the URL. Authenticate with either a Supabase Bearer session (send theX-Organization-Id: <org-id>header — the user must be a member of that organization) or an API key (the organization resolves automatically from the key; anyX-Organization-Idheader sent alongside an API key is ignored).
Authentication
Accepts either:- A Supabase Bearer session (
Authorization: Bearer <token>) with theX-Organization-Id: <org-id>header — the authenticated user must be a member of that organization. - An API key (
X-API-Key: sk_...) with theread:invoicesscope — the organization is resolved from the key itself.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | integer | No | 1 | Page number (1-indexed) |
limit | integer | No | 20 | Results per page (1-100) |
type | string | No | — | Filter by comprobante type — I, E, or T |
status | string | No | — | Filter by status — vigente or cancelado |
dateFrom | string (ISO date) | No | — | Filtra por fecha de registro en Timbrix (createdAt), desde (inclusive). Un valor de solo fecha (YYYY-MM-DD) se ancla al inicio del día en America/Mexico_City. |
dateTo | string (ISO date) | No | — | Filtra por fecha de registro en Timbrix (createdAt), hasta (inclusive). Un valor de solo fecha (YYYY-MM-DD) se ancla al final del día (23:59:59.999) en America/Mexico_City. |
rfcReceptor | string | No | — | Filtra por RFC exacto del receptor |
environment | "sandbox" | "production" | No | — (session) / key’s own (API key) | Filtra por entorno. Ignorado con API key (siempre usa el entorno de la key). Con sesión de Supabase, omitir devuelve ambos entornos. |
Example Request
curl -X GET "https://api.timbrix.mx/invoices?page=1&limit=20" \
-H "Authorization: Bearer <your_token>" \
-H "X-Organization-Id: 550e8400-e29b-41d4-a716-446655440000"
const result = await timbrix.invoices.list(
{ page: 1, limit: 20 },
"550e8400-e29b-41d4-a716-446655440000"
)
console.log(result.data, result.total)
X-Organization-Id header (and the SDK’s organizationId argument) entirely — it’s resolved from the key:
const result = await timbrix.invoices.list({ page: 1, limit: 20 })
console.log(result.data, result.total)
Example Response
{
"data": [
{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"serie": "A",
"folio": "1",
"tipoComprobante": "I",
"rfcReceptor": "GODE561231GR8",
"moneda": "MXN",
"total": 116,
"status": "vigente",
"createdAt": "2026-07-30T22:50:03.412Z",
"requiresReceptorApproval": false,
"cancellationStatus": null,
"cancellationDesynced": false
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}
| Field | Type | Description |
|---|---|---|
data[] | array | Invoice summaries — see below |
total | integer | Total invoices for the organization, before pagination |
page | integer | Current page number |
limit | integer | Results per page |
totalPages | integer | Total number of pages |
data[]
| Field | Type | Description |
|---|---|---|
id | string | Timbrix invoice record ID |
uuid | string | Folio fiscal UUID asignado por el SAT vía PAC |
serie | string | Invoice series |
folio | string | Invoice folio number |
tipoComprobante | string | I = Ingreso, E = Egreso, T = Traslado |
rfcReceptor | string | RFC of the receptor (customer) |
moneda | string | Currency code |
total | number | Invoice total |
status | string | vigente or cancelado |
createdAt | string | ISO 8601 timestamp of when the CFDI was stamped |
requiresReceptorApproval | boolean | Whether cancelling this invoice would require receptor approval per SAT rules, computed server-side — see Cancel Invoice for the rule. Never re-derive this on the client. |
cancellationStatus | "pendiente" | "rechazada" | null | Latest cancellation attempt’s status, only while the invoice is still vigente. null if cancellation was never attempted, or once the invoice is cancelado (at that point status already communicates the outcome). |
cancellationDesynced | boolean | true when a pending cancellation was accepted (aceptada) but the invoice’s own status failed to flip to cancelado — the CFDI may already be cancelled at the SAT even though this endpoint still reports vigente. Needs manual reconciliation; treat as a signal to re-check the invoice via the SAT portal. |
Common Errors
400 Bad Request
MissingX-Organization-Id header on a session-authenticated request.
401 Unauthorized
Missing or invalid Bearer token / API key.403 Forbidden
The authenticated user is not a member of the organization sent inX-Organization-Id, or the API key does not have the read:invoices scope.Authorizations
API Key for authentication (format: sk_...)
Headers
Required for Supabase session auth. Ignored when authenticating with an API key (the organization resolves from the key).
Query Parameters
Page number (1-indexed)
1
Results per page (1-100)
20
Filtra por tipo de comprobante
I, E, T Filtra por estatus
vigente, cancelado Filtra por fecha de registro en Timbrix (createdAt), desde (inclusive, ISO 8601). Un valor de solo fecha (YYYY-MM-DD) se ancla al inicio del día en America/Mexico_City.
"2026-08-01"
Filtra por fecha de registro en Timbrix (createdAt), hasta (inclusive, ISO 8601). Un valor de solo fecha (YYYY-MM-DD) se ancla al final del día (23:59:59.999) en America/Mexico_City, incluyendo el día completo.
"2026-08-31"
Filtra por RFC exacto del receptor
"XAXX010101000"
Filtra por entorno. Ignorado para peticiones autenticadas con API key (siempre se usa el entorno de la key). Para una sesión de Supabase, omitir este parámetro devuelve ambos entornos.
sandbox, production