Quickstart

# -w agrega el status code al final de la respuesta, para poder detectar
# errores sin depender de que el body "se vea" como error.
response=$(curl -s -w "\n%{http_code}" -X POST https://api.timbrix.mx/customers \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "PUBLICO EN GENERAL",
    "taxId": "XAXX010101000",
    "taxSystem": "616",
    "email": "facturas@cliente-prueba.mx",
    "defaultInvoiceUse": "S01",
    "addressStreet": "Blvd. Atardecer",
    "addressExterior": "142",
    "addressNeighborhood": "Centro",
    "addressCity": "Huatabampo",
    "addressMunicipality": "Huatabampo",
    "addressZip": "86500",
    "addressState": "Sonora"
  }')
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  # El error más común aquí es un RFC con formato inválido, p. ej.:
  # {"message":["Invalid RFC format"],"error":"Bad Request","statusCode":400}
  echo "Error al crear cliente ($http_code): $body" >&2
  exit 1
fi

curl -X POST https://api.timbrix.mx/products \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Servicio de prueba",
    "productKey": 84111506,
    "unitKey": "E48",
    "price": 100.00
  }'

# customerId y productId vienen del campo "id" de cada respuesta anterior.
# `date` va en hora de Ciudad de México (no UTC) — ver nota abajo.
curl -X POST https://api.timbrix.mx/invoices \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "I",
    "series": "A",
    "folioNumber": "1",
    "date": "'"$(TZ="America/Mexico_City" date +"%Y-%m-%dT%H:%M:%S")"'",
    "paymentForm": "01",
    "paymentMethod": "PUE",
    "use": "S01",
    "customerId": "{customerId}",
    "items": [
      { "productId": "{productId}", "quantity": 1 }
    ]
  }'
# La respuesta incluye "uuid" — el folio fiscal asignado por el SAT vía PAC

// npm install @timbrix/sdk
import { Timbrix, TimbrixApiError } from "@timbrix/sdk"

const client = new Timbrix({ apiKey: "sk_..." })

// La organización se resuelve automáticamente a partir de la key.
let customer
try {
  customer = await client.customers.create({
    legalName: "PUBLICO EN GENERAL",
    taxId: "XAXX010101000",
    taxSystem: "616",
    email: "facturas@cliente-prueba.mx",
    defaultInvoiceUse: "S01",
    addressStreet: "Blvd. Atardecer",
    addressExterior: "142",
    addressNeighborhood: "Centro",
    addressCity: "Huatabampo",
    addressMunicipality: "Huatabampo",
    addressZip: "86500",
    addressState: "Sonora",
  })
} catch (error) {
  if (error instanceof TimbrixApiError) {
    // El error más común aquí es un RFC con formato inválido.
    throw new Error(`No se pudo crear el cliente: ${error.message}`)
  }
  throw error
}

const product = await client.products.create({
  description: "Servicio de prueba",
  productKey: 84111506,
  unitKey: "E48",
  price: 100.0,
})

// fecha_expedicion va en hora de Ciudad de México (no UTC) — ver
// /api-reference/invoices/create#date
const mexicoCityNow = () =>
  new Date()
    .toLocaleString("sv-SE", { timeZone: "America/Mexico_City" })
    .replace(" ", "T")

const invoice = await client.invoices.create({
  type: "I",
  series: "A",
  folioNumber: "1",
  date: mexicoCityNow(),
  paymentForm: "01",
  paymentMethod: "PUE",
  use: "S01",
  customerId: customer.id,
  items: [{ productId: product.id, quantity: 1 }],
})

console.log(invoice.uuid)

<?php
// composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$client = new Client([
    "base_uri" => "https://api.timbrix.mx",
    "headers" => [
        "X-API-Key" => "sk_...",
        "Content-Type" => "application/json",
    ],
]);

try {
    $customerRes = $client->post("customers", [
        "json" => [
            "legalName" => "PUBLICO EN GENERAL",
            "taxId" => "XAXX010101000",
            "taxSystem" => "616",
            "email" => "facturas@cliente-prueba.mx",
            "defaultInvoiceUse" => "S01",
            "addressStreet" => "Blvd. Atardecer",
            "addressExterior" => "142",
            "addressNeighborhood" => "Centro",
            "addressCity" => "Huatabampo",
            "addressMunicipality" => "Huatabampo",
            "addressZip" => "86500",
            "addressState" => "Sonora",
        ],
    ]);
} catch (ClientException $e) {
    $error = json_decode($e->getResponse()->getBody()->getContents(), true);
    // El error más común aquí es un RFC con formato inválido.
    $message = is_array($error["message"] ?? null)
        ? implode(", ", $error["message"])
        : ($error["message"] ?? "Error desconocido");
    throw new Exception("No se pudo crear el cliente: $message");
}

$customer = json_decode($customerRes->getBody()->getContents(), true);

$productRes = $client->post("products", [
    "json" => [
        "description" => "Servicio de prueba",
        "productKey" => 84111506,
        "unitKey" => "E48",
        "price" => 100.00,
    ],
]);
$product = json_decode($productRes->getBody()->getContents(), true);

// fecha_expedicion va en hora de Ciudad de México (no UTC) — ver
// /api-reference/invoices/create#date
$fechaExpedicion = (new DateTime("now", new DateTimeZone("America/Mexico_City")))
    ->format("Y-m-d\TH:i:s");

$invoiceRes = $client->post("invoices", [
    "json" => [
        "type" => "I",
        "series" => "A",
        "folioNumber" => "1",
        "date" => $fechaExpedicion,
        "paymentForm" => "01",
        "paymentMethod" => "PUE",
        "use" => "S01",
        "customerId" => $customer["id"],
        "items" => [
            ["productId" => $product["id"], "quantity" => 1],
        ],
    ],
]);

$invoice = json_decode($invoiceRes->getBody()->getContents(), true);
echo $invoice["uuid"];

import requests

base_url = "https://api.timbrix.mx"
headers = {"X-API-Key": "sk_...", "Content-Type": "application/json"}

customer_res = requests.post(
    f"{base_url}/customers",
    headers=headers,
    json={
        "legalName": "PUBLICO EN GENERAL",
        "taxId": "XAXX010101000",
        "taxSystem": "616",
        "email": "facturas@cliente-prueba.mx",
        "defaultInvoiceUse": "S01",
        "addressStreet": "Blvd. Atardecer",
        "addressExterior": "142",
        "addressNeighborhood": "Centro",
        "addressCity": "Huatabampo",
        "addressMunicipality": "Huatabampo",
        "addressZip": "86500",
        "addressState": "Sonora",
    },
)

if not customer_res.ok:
    error = customer_res.json()
    # El error más común aquí es un RFC con formato inválido.
    detail = ", ".join(error["message"])
    raise ValueError(f"No se pudo crear el cliente: {detail}")

customer = customer_res.json()

product = requests.post(
    f"{base_url}/products",
    headers=headers,
    json={
        "description": "Servicio de prueba",
        "productKey": 84111506,
        "unitKey": "E48",
        "price": 100.00,
    },
).json()

# fecha_expedicion va en hora de Ciudad de México (no UTC) — ver
# /api-reference/invoices/create#date
from datetime import datetime
from zoneinfo import ZoneInfo

fecha_expedicion = datetime.now(ZoneInfo("America/Mexico_City")).strftime(
    "%Y-%m-%dT%H:%M:%S"
)

invoice = requests.post(
    f"{base_url}/invoices",
    headers=headers,
    json={
        "type": "I",
        "series": "A",
        "folioNumber": "1",
        "date": fecha_expedicion,
        "paymentForm": "01",
        "paymentMethod": "PUE",
        "use": "S01",
        "customerId": customer["id"],
        "items": [
            {"productId": product["id"], "quantity": 1}
        ],
    },
).json()

print(invoice["uuid"])