curl --request GET \
--url https://api.example.com/invoices/{uuid} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.example.com/invoices/{uuid}"
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.example.com/invoices/{uuid}', 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.example.com/invoices/{uuid}",
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.example.com/invoices/{uuid}"
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.example.com/invoices/{uuid}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/invoices/{uuid}")
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{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"status": "vigente",
"cancellationStatus": "pendiente",
"cancellationDesynced": false,
"type": "I",
"series": "A",
"folioNumber": "1",
"total": 116,
"date": "2026-07-30T22:50:00",
"xml": "<string>",
"createdAt": "2026-07-30T22:50:03.412Z",
"environment": "production",
"channel": "mcp",
"rfcReceptor": "GODE561231GR8",
"relatedCfdis": [
{
"type": "04",
"uuids": [
"D3BFBC57-44AF-4390-A064-F0AFAB85E5DF"
]
}
],
"substitutedBy": [
{
"uuid": "6F2B1C9A-3D4E-4F5A-8B7C-9D0E1F2A3B4C",
"serie": "A",
"folio": "124",
"status": "vigente"
}
],
"paymentMethod": "PPD",
"balance": 160,
"payment": {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"currency": "MXN",
"exchange": 1,
"amount": 1660,
"operationNumber": "SPEI-123",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"installment": 2,
"previousBalance": 660,
"amountPaid": 500,
"remainingBalance": 160
}
]
},
"warnings": [
{
"code": "RFC_69B_PRESUNTO",
"rfc": "AAA010101AAA",
"role": "receptor",
"message": "El RFC del receptor AAA010101AAA aparece como Presunto en la lista 69-B del SAT (publicado el 25 de junio de 2018). Revisa la operación antes de continuar."
}
]
}Get Invoice
Authenticate with either a Supabase session (member of the invoice’s organization) or an API key belonging to that same organization. Returns the same shape as the POST /invoices response — use this to recover an invoice’s metadata/XML if the original create response was lost.
curl --request GET \
--url https://api.example.com/invoices/{uuid} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.example.com/invoices/{uuid}"
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.example.com/invoices/{uuid}', 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.example.com/invoices/{uuid}",
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.example.com/invoices/{uuid}"
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.example.com/invoices/{uuid}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/invoices/{uuid}")
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{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"status": "vigente",
"cancellationStatus": "pendiente",
"cancellationDesynced": false,
"type": "I",
"series": "A",
"folioNumber": "1",
"total": 116,
"date": "2026-07-30T22:50:00",
"xml": "<string>",
"createdAt": "2026-07-30T22:50:03.412Z",
"environment": "production",
"channel": "mcp",
"rfcReceptor": "GODE561231GR8",
"relatedCfdis": [
{
"type": "04",
"uuids": [
"D3BFBC57-44AF-4390-A064-F0AFAB85E5DF"
]
}
],
"substitutedBy": [
{
"uuid": "6F2B1C9A-3D4E-4F5A-8B7C-9D0E1F2A3B4C",
"serie": "A",
"folio": "124",
"status": "vigente"
}
],
"paymentMethod": "PPD",
"balance": 160,
"payment": {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"currency": "MXN",
"exchange": 1,
"amount": 1660,
"operationNumber": "SPEI-123",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"installment": 2,
"previousBalance": 660,
"amountPaid": 500,
"remainingBalance": 160
}
]
},
"warnings": [
{
"code": "RFC_69B_PRESUNTO",
"rfc": "AAA010101AAA",
"role": "receptor",
"message": "El RFC del receptor AAA010101AAA aparece como Presunto en la lista 69-B del SAT (publicado el 25 de junio de 2018). Revisa la operación antes de continuar."
}
]
}/organizations/{organizationId}/ in the URL. The invoice’s uuid (its folio fiscal, globally unique across all organizations) is enough to resolve the owning organization server-side, combined with the caller’s own auth context (session or API key).
Authentication
Accepts either:- A Supabase Bearer session (
Authorization: Bearer <token>) — the authenticated user must be a member of the invoice’s organization. - An API key (
X-API-Key: sk_...) with theread:invoicesscope — the key’s own organization must match the invoice’s organization, or the request is rejected with403 Forbidden.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string (UUID) | Yes | Folio fiscal UUID (uuidFiscal) of the invoice to fetch — globally unique, not scoped to an organization |
Example Request
curl -X GET https://api.timbrix.mx/invoices/d3bfbc57-44af-4390-a064-f0afab85e5df \
-H "Authorization: Bearer <your_token>"
const invoice = await timbrix.invoices.get(
"d3bfbc57-44af-4390-a064-f0afab85e5df"
)
console.log(invoice.xml)
Example Response
{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"status": "vigente",
"cancellationStatus": null,
"cancellationDesynced": false,
"type": "I",
"series": "A",
"folioNumber": "1",
"total": 116,
"date": "2026-07-30T15:50:00",
"xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><cfdi:Comprobante ...>",
"rfcReceptor": "GODE561231GR8",
"relatedCfdis": [],
"substitutedBy": [
{
"uuid": "a1b2c3d4-5e6f-4890-9abc-def012345678",
"serie": "A",
"folio": "2",
"status": "vigente"
}
],
"channel": "api",
"createdAt": "2026-07-30T15:50:03.412Z"
}
| Field | Type | Description |
|---|---|---|
id | string | Timbrix invoice record ID |
uuid | string | Folio fiscal UUID asignado por el SAT vía PAC |
status | string | Estado fiscal del CFDI registrado en Timbrix: vigente o cancelado. Antes de la API v1.18.0 este campo siempre era "valid" |
cancellationStatus | string | null | Latest cancellation attempt, only while the CFDI is still vigente: en_proceso (sent to the SAT, result being confirmed), pendiente (waiting for the receptor) or rechazada. null if none or already cancelado. A pendiente past the receptor’s 3-business-day response deadline may already be cancelado at the SAT — confirm in the SAT portal. |
cancellationDesynced | boolean | true when the SAT accepted a cancellation but the CFDI still shows vigente — needs manual reconciliation |
type | string | I = Ingreso, E = Egreso, T = Traslado, P = Pago |
series | string | Invoice series |
folioNumber | string | Invoice folio number |
total | number | Invoice total |
date | string | Issuance date-time (ISO 8601, no timezone) |
xml | string | The full stamped CFDI XML, inline (UTF-8) |
rfcReceptor | string | RFC of the receptor (customer) |
relatedCfdis | array | CFDI this one relates to, as { type, uuids }. Empty when none. A substitute CFDI carries [{ "type": "04", "uuids": ["<UUID of the CFDI it substitutes>"] }] — see Substituting a CFDI |
substitutedBy | array | CFDI whose 04 relation points at this one, as { uuid, serie, folio, status } (status is vigente or cancelado). Empty when this CFDI has not been substituted |
createdAt | string | ISO 8601 timestamp of when the CFDI was stamped |
web, api, sdk, cli, mcp). null para
CFDI creados antes de que existiera este campo.null on Traslado, Pago and invoices stamped
before this field existed.vigente or
being-stamped Complementos de Pago). null on the rest. Installments: Get
Payments.type: "P"): the payment and the invoices it
settles. See Register
Payment.type and the full xml — fields not present in the
List Invoices summary shape. If you only need
the XML file itself (not wrapped in JSON), use Download Invoice
XML instead.Common Errors
401 Unauthorized
Missing or invalid Bearer token / API key.403 Forbidden
The authenticated user is not a member of the invoice’s organization, or the API key does not have theread:invoices scope / belongs to a different organization than the one that owns the invoice.
404 Not Found
uuid does not match any invoice.Authorizations
Response
Estado fiscal del CFDI registrado en Timbrix: vigente o cancelado. Antes de TIM-243 este campo era siempre "valid". Con una cancelación pendiente (cancellationStatus: pendiente) cuyo plazo de respuesta del receptor ya venció, el SAT pudo haberlo cancelado automáticamente; confírmalo en el portal del SAT.
vigente, cancelado "vigente"
Latest cancellation attempt's status, only while the invoice is still vigente. null if never attempted or already cancelado. A pendiente past the receptor's response deadline may already be cancelado at the SAT. en_proceso: the cancellation was sent and its outcome is being confirmed with the SAT; don't treat the CFDI as vigente yet.
pendiente, rechazada, en_proceso