> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mapa de endpoints de facturas

> Qué rutas son canónicas para facturas comerciales y DTE, y cuáles se mantienen por compatibilidad

## Dos recursos, dos identificadores

En Wasabil, `POST /api/documents` recibe el tipo de documento en el payload. En Raúl, el ciclo comercial y el tributario tienen recursos y estados propios. Usa el **ID de factura** en `/api/v1/billing/invoices/{invoiceId}` y el **ID de DTE** en `/api/v1/dte/documents/{dteId}`. Ambos IDs son UUID y no son intercambiables. Todas las rutas de esta página usan la base `https://api.raul.ugps.io`.

```text theme={null}
/api/v1/billing/invoices           factura comercial, cobro y publicación
  /{invoiceId}/publish             publica e intenta emitir el DTE

/api/v1/dte/documents              XML, folio y estado tributario
  /by-invoice/{invoiceId}/status   resumen comercial + tributario
  /{dteId}/sync                    consulta el veredicto del SII
  /{dteId}/annul                   emite la nota de crédito de anulación
```

Si tu operación parte de una factura comercial, comienza por `billing/invoices`. Si ya existe una fuente y necesitas solo el DTE, usa `dte/documents`. Crear un DTE directamente para una `invoice_id` no ejecuta por sí mismo la publicación, los eventos ni los cambios de estado comerciales.

## Factura comercial

| Método y ruta | Uso | Resultado clave |
| - | - | - |
| `POST /api/v1/billing/invoices` | Crear la factura | `201`, `DRAFT` e `id` de factura |
| `GET /api/v1/billing/invoices` | Buscar facturas | Filtros comerciales y `sii_status` por estado local del DTE |
| `GET /api/v1/billing/invoices/{invoiceId}` | Consultar factura y DTE asociados | `status`, `dte_document_id`, `dte_documents[]` |
| `PATCH /api/v1/billing/invoices/{invoiceId}` | Corregir borrador | Requiere estado editable |
| `POST /api/v1/billing/invoices/{invoiceId}/publish` | Publicar e intentar emitir | `PUBLISHED` si falló la emisión; `DTE_SENT` si hay envío con TrackID |
| `POST /api/v1/billing/invoices/{invoiceId}/references` | Agregar una referencia OC/HES | Debe estar lista antes de publicar si el cliente la exige |
| `POST /api/v1/billing/invoices/{invoiceId}/register-payment` | Registrar pago comercial | Actualiza el ciclo de cobro; no emite otro DTE |

`publish` es la entrada normal de emisión comercial. Su respuesta HTTP exitosa confirma la operación de Raúl, **no** la aceptación del SII. Después consulta el recurso y, si existe un DTE, el resumen tributario.

## Documento tributario

| Método y ruta | Uso | Identificador |
| - | - | - |
| `POST /api/v1/dte/documents` | Crear/emitir un DTE desde `invoice_id` o `factura_id`; también admite guía 52 independiente | ID de la fuente en el body |
| `GET /api/v1/dte/documents` | Listar DTE, incluido `status=SII_UPLOAD_UNCERTAIN` | Filtros en query |
| `POST /api/v1/dte/documents/query` | Búsqueda avanzada por estado, folio, receptor y fechas | Filtros en body |
| `GET /api/v1/dte/documents/{dteId}` | Consultar folio, TrackID y `localStatus` | ID de DTE |
| `GET /api/v1/dte/documents/by-invoice/{invoiceId}/status` | Leer `invoiceStatus` y `sii.status` sin mezclarlos | ID de factura |
| `GET /api/v1/dte/documents/by-folio/{tipo}/{folio}` | Localizar registros para conciliación | Código SII y folio |
| `POST /api/v1/dte/documents/{dteId}/sync` | Consultar el veredicto del SII | ID de DTE con TrackID |
| `POST /api/v1/dte/documents/{dteId}/annul` | Emitir nota de crédito de anulación/corrección | ID del DTE original |
| `GET /api/v1/dte/documents/{dteId}/pdf` | Descargar el PDF tributario | ID de DTE |

La respuesta de `GET /dte/documents/{dteId}` usa `localStatus`, `siiTrackId` y otros nombres en **camelCase**; los filtros del request usan **snake\_case**. Si `sii.status` es `uncertain` o `localStatus` es `SII_UPLOAD_UNCERTAIN`, concilia el folio antes de cualquier nueva emisión o reversión. Consulta [Crear facturas y seguir el DTE](/invoices-guide) para el flujo completo.

## Rutas de compatibilidad

Estas rutas siguen respondiendo, pero la referencia OpenAPI las marca como deprecadas:

| Ruta existente | Ruta canónica o uso actual |
| - | - |
| `POST /api/v1/billing/invoices/{invoiceId}/emit-dte` | `publish` para el flujo normal; `emit-dte` se conserva para retomar una factura que quedó `PUBLISHED` tras fallar la emisión automática |
| `POST /api/v1/billing/invoices/{invoiceId}/sync-dte` | `POST /api/v1/dte/documents/{dteId}/sync` |
| `POST /api/v1/billing/invoices/{invoiceId}/sii-response` | Sincroniza el DTE real con el SII mediante `POST /api/v1/dte/documents/{dteId}/sync` |
| `POST /api/v1/billing/invoices/{invoiceId}/credit-note` | `POST /api/v1/dte/documents/{dteId}/annul` cuando existe un DTE; la ruta comercial conserva un caso sin DTE |
| `POST /api/v1/dte/documents/{dteId}/credit-note` | `POST /api/v1/dte/documents/{dteId}/annul` |
| `POST /api/v1/billing/invoices/{invoiceId}/send-email` | `POST /api/v1/dte/documents/{dteId}/send-email` para el envío tributario; la ruta comercial también transiciona la factura |

`/api/v1/factura`, `/api/v1/boleta` y `/api/v1/facturacion-2` son familias operativas que conviven con este ciclo. No sustituyas una por otra según el nombre: `/boleta` incluye registros operativos y no equivale automáticamente a emitir `BOLETA_39` por el recurso DTE.

La pestaña **API** muestra el contrato OpenAPI completo, con los grupos **Invoices** y **DTE**. Para datos y ejemplos de creación, continúa con [Crear facturas y seguir el DTE](/invoices-guide).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.