# Objetos y convenciones

> Cómo son las rutas, los ids, los montos, las fechas, metadata y las versiones de la API.

## Rutas y métodos

- Todo vive en `https://api.fiscalisto.com/v1`.
- Los cuerpos van en JSON con `Content-Type: application/json`, y las respuestas también son JSON (salvo el PDF y el XML).
- `GET` consulta, `POST` crea y también actualiza (`POST /v1/customers/{id}` cambia solo los campos que manda), `DELETE` borra o archiva. No hay `PUT` ni `PATCH`.
- Los nombres de los campos van en inglés y en `snake_case`. El RFC siempre se llama `tax_id`, también dentro de los complementos.

## Objetos

Cada objeto trae `id`, `object` (qué es: `invoice`, `customer`, `event`…) y `livemode`. Los ids empiezan con su tipo:

| Prefijo | Objeto |
| --- | --- |
| `iss_` | Emisor |
| `inv_` | Factura, complemento de pago, nota de crédito, anticipo o recibo de nómina |
| `ret_` | Constancia de retenciones |
| `cus_` | Cliente |
| `prd_` | Producto |
| `emp_` | Empleado |
| `bat_` | Lote de facturas |
| `whe_` | Webhook |
| `evt_` | Evento |

Los comprobantes también se pueden consultar por su folio fiscal (UUID), que siempre va en mayúsculas.

## Montos

Los montos son números en la moneda del comprobante, con decimales (`2500`, `1160.5`), nunca centavos enteros ni texto. Usted manda el precio unitario antes de impuestos (`unit_price`) y Fiscalisto calcula los impuestos, los redondeos del SAT y los totales; la respuesta los trae en `subtotal`, `discount`, `taxes` y `total`.

Las tasas van como fracción, igual que en el XML: `0.10` es 10%. La del IVA trasladado va como texto porque también puede ser `"exento"` (`"0.16"`, `"0.08"`, `"0"`, `"exento"`); las de retención van como número (`0.106667` son dos terceras partes del IVA).

## Fechas

- Lo que pasó en Fiscalisto (`created_at`, `canceled_at`) va en ISO 8601 con la hora de la Ciudad de México: `2026-10-24T10:15:42-06:00`.
- La fecha de emisión del CFDI (`date`) va sin zona, como la lleva el XML: `2026-10-24T10:15:42`, en hora de la Ciudad de México.

## Campos vacíos

Un campo que no aplica viene en `null`, nunca se omite: su código puede leer `invoice.cancellation` sin revisar si existe. Al crear, omita lo que tiene su valor usual. La API puede agregar campos nuevos a los objetos sin cambiar de versión, así que su código debe ignorar los que no conoce.

## metadata

Guarde sus propios datos en un objeto con `metadata`: el id del pedido, del cliente en su sistema, de la sucursal.

```json
{ "metadata": { "pedido": "A-1042", "sucursal": "monterrey" } }
```

- Hasta 50 llaves de hasta 40 caracteres, con valores de texto de hasta 500.
- No van al CFDI ni al PDF: son solo para usted.
- Vuelven en el objeto, en las listas y en los webhooks.
- La aceptan los emisores y todo lo que se timbra (facturas, pagos, notas de crédito, anticipos, recibos de nómina y constancias de retenciones). Cada factura de un lote lleva `reference` en su lugar.

## Versiones

Cada respuesta trae el encabezado `Fiscalisto-Version` con la versión de la API que contestó (hoy `2026-10-24`) y cada evento la trae en `api_version`. Agregar campos, eventos, rutas o códigos de error no cambia la versión. Un cambio que pudiera romper su código (quitar o renombrar un campo, cambiar su tipo) saldría con una versión nueva, con aviso.

## Encabezados de la respuesta

| Encabezado | Qué es |
| --- | --- |
| `Request-Id` | El id de la solicitud. Guárdelo en sus registros: con él la encuentra en **Desarrolladores › Solicitudes**. |
| `Fiscalisto-Version` | La versión de la API. |
| `Idempotent-Replayed` | `true` cuando la respuesta es la guardada de una solicitud anterior con la misma `Idempotency-Key`. |
| `Retry-After` | En un `429`, `409` o `503`: cuántos segundos esperar antes de repetir. |