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

# Introduccion - API Cesiones

> Cesiones de facturas (AEC): listar, obtener detalle, certificado y crear en lote

## Para que sirve la API de Cesiones?

La **API de Cesiones** permite consultar y gestionar las **cesiones de facturas** (AEC - Archivo Electronico de Cesion) desde tu integracion. Una cesion es la transferencia del derecho de credito de una factura a un tercero (por ejemplo una empresa de factoring).

Con esta API puedes:

* **Listar** las cesiones de una entidad (con filtros por fecha, estado, busqueda), tanto las que **emitio** (facturas propias cedidas a un tercero) como las que **recibio** (facturas de sus proveedores cedidas a un tercero) via el parametro `document_type`.
* **Obtener el detalle** de una cesion concreta, incluidos eventos de trazabilidad en el SII.
* **Obtener el certificado de cesion** (PDF) del SII, tanto la URL presignada async (`certificate_pdf_url` en el detalle) como en descarga directa via `?pdf=document-cession`.
* **Crear cesiones en lote** (generar AECs y enviarlos al SII) desde el endpoint de batch.
* **Consultar el estado de un lote** creado (éxito, fallo o parcial, con el detalle y error real por documento) usando el `cession_batch_id` recibido.

## Emitidas vs recibidas

Toda cesion involucra dos entidades del documento cedido: quien **emitio** la factura (cedente) y quien la **recibio** (el deudor, cuya deuda cambia de acreedor cuando se cede). El parametro `document_type` del listado controla desde que lado consultas:

* `document_type=issued` (default): cesiones donde `master_entity_id` es la **emisora** de la factura cedida — tus propias ventas que cediste a un factoring.
* `document_type=received`: cesiones donde `master_entity_id` es la **receptora** de la factura cedida — facturas de tus **proveedores** que ellos cedieron a un tercero. Util para saber a quien pagarle en vez del proveedor original.

## Flujo tipico

1. **Listar cesiones** con `GET /cessions?master_entity_id={id}` (agregando `&document_type=received` si quieres las de tus proveedores) para ver las cesiones de la entidad.
2. **Obtener una cesion** con `GET /cessions/{id}` para ver detalle, eventos y `certificate_pdf_url`. Es accesible tanto si tenes acceso a la entidad emisora como a la receptora del documento cedido.
3. **Crear nuevas cesiones** con `POST /cessions/batch` enviando los IDs de documentos y datos del cesionario. La respuesta es asincrona (`202`) y trae un `cession_batch_id`.
4. **Consultar el resultado** con `GET /cessions/batch/{batch_id}` usando ese `cession_batch_id`, hasta que el `status` deje de ser `pending`/`processing`. Es el unico lugar donde se ve si una cesion fallo en el SII (`DocumentCession` solo existe para las exitosas).

## Autenticacion

Todos los endpoints requieren autenticacion (API Key o JWT). La API Key debe tener permisos de acceso a la entidad cuyas cesiones quieres consultar o crear.

## Referencia rapida

| Accion                             | Metodo | Endpoint                                                 |
| ---------------------------------- | ------ | -------------------------------------------------------- |
| Listar cesiones emitidas (default) | GET    | `/cessions?master_entity_id={id}`                        |
| Listar cesiones recibidas          | GET    | `/cessions?master_entity_id={id}&document_type=received` |
| Detalle de cesion                  | GET    | `/cessions/{id}`                                         |
| Descargar certificado (PDF inline) | GET    | `/cessions/{id}?pdf=document-cession`                    |
| Crear cesiones en lote             | POST   | `/cessions/batch`                                        |
| Consultar estado de un lote        | GET    | `/cessions/batch/{batch_id}`                             |