# Documentos recibidos (/docs/referencia/recibidos) Base: `https://api.facturia.cl/v1`. Todos los endpoints de este capítulo se autentican con `Authorization: Bearer` salvo que se diga lo contrario, y el sobre de error es el de [Errores](/docs/errores). | Método | Ruta | Qué hace | | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `GET` | [`/received_documents`](#get-received-documents) | Lista los DTE de proveedores recibidos por esta empresa | | `GET` | [`/received_documents/{received_document_id}`](#get-received-documents-received-document-id) | Devuelve un documento recibido | | `GET` | [`/received_documents/{received_document_id}/xml`](#get-received-documents-received-document-id-xml) | Descarga el XML original del proveedor | | `GET` | [`/received_documents/{received_document_id}/pdf`](#get-received-documents-received-document-id-pdf) | Genera el PDF del documento recibido | | `POST` | [`/received_documents/{received_document_id}/accept`](#post-received-documents-received-document-id-accept) | Acepta el contenido (acción ACD del SII) | | `POST` | [`/received_documents/{received_document_id}/reject`](#post-received-documents-received-document-id-reject) | Reclama el documento (RCD / RFP / RFT) | | `POST` | [`/received_documents/{received_document_id}/acknowledge_receipt`](#post-received-documents-received-document-id-acknowledge-receipt) | Otorga el recibo de mercaderías o servicios (acción ERM del SII) | ## `GET /received_documents` [#get-received-documents] **Lista los DTE de proveedores recibidos por esta empresa** Los DTE de proveedores que llegaron a la casilla de recepción de la empresa, del más nuevo al más antiguo, filtrable por `tipo_dte` y `status` de aceptación. ```bash curl -sS https://api.facturia.cl/v1/received_documents \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | --------------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `limit` | query | — | integer | | | `cursor` | query | — | string | Cursor opaco tomado del `next_cursor` de una respuesta anterior. | | `expand` | query | — | string | En este listado no acepta nada, y lo dice en vez de ignorarlo. `raw_xml` incorpora el sobre firmado completo del proveedor, así que solo existe en `GET /received_documents/\{received_document_id\}`; cualquier valor aquí es `400 invalid_field` (§5.4). | | `tipo_dte` | query | — | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | | | `emisor_rut` | query | — | Rut | | | `commercial_response_state` | query | — | `pending` · `accepted` · `rejected` · `receipt_acknowledged` · `expired_accepted` · `not_applicable` | | | `source` | query | — | `intercambio` · `rcv` · `manual` | | | `issue_date[gte]` | query | — | string | | | `issue_date[lte]` | query | — | string | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `200` | Una lista de documentos recibidos. | lista de ReceivedDocument | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /received_documents/{received_document_id}` [#get-received-documents-received-document-id] **Devuelve un documento recibido** Un DTE recibido, incluyendo la respuesta comercial (`accept`/`reject`/`acknowledge_receipt`) que se haya registrado para él. ```bash curl -sS https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `expand` | query | — | string | `raw_xml` devuelve el XML original del proveedor en línea, con la firma intacta. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `200` | El documento recibido. | ReceivedDocument | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `404` | No existe ese objeto bajo esta llave. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /received_documents/{received_document_id}/xml` [#get-received-documents-received-document-id-xml] **Descarga el XML original del proveedor** El XML exacto que el SII entregó para este documento recibido. ```bash curl -sS https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N/xml \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `200` | El XML tal como llegó. Ese archivo es el artefacto legal. | application/xml | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /received_documents/{received_document_id}/pdf` [#get-received-documents-received-document-id-pdf] **Genera el PDF del documento recibido** Un PDF renderizado del documento recibido, para mostrar o archivar fuera de la API. ```bash curl -sS https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N/pdf \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `200` | El PDF generado. | application/pdf | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /received_documents/{received_document_id}/accept` [#post-received-documents-received-document-id-accept] **Acepta el contenido (acción ACD del SII)** Solo tipos 33/34/43, dentro de la ventana de 8 días y una sola vez. No hacer nada también es una decisión válida y jurídicamente cargada: el silencio acepta al día 8. ```bash curl -sS -X POST https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N/accept \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"note":"…"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con `Facturia-Idempotent-Replay: true`. Misma llave y cuerpo distinto → `409`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | ------ | --------- | ----- | | `note` | string | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `201` | La respuesta comercial registrada. | CommercialResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `409` | Conflicto de estado: reutilización de idempotencia, `external_id` duplicado o artefacto no listo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /received_documents/{received_document_id}/reject` [#post-received-documents-received-document-id-reject] **Reclama el documento (RCD / RFP / RFT)** Irreversible. No existe des-reclamar. ```bash curl -sS -X POST https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N/reject \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"reason":"content"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con `Facturia-Idempotent-Replay: true`. Misma llave y cuerpo distinto → `409`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | | `reason` | `content` · `partial_missing` · `total_missing` | sí | content → RCD, partial\_missing → RFP, total\_missing → RFT. | | `note` | string | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `201` | La respuesta comercial registrada. | CommercialResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `409` | Conflicto de estado: reutilización de idempotencia, `external_id` duplicado o artefacto no listo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /received_documents/{received_document_id}/acknowledge_receipt` [#post-received-documents-received-document-id-acknowledge-receipt] **Otorga el recibo de mercaderías o servicios (acción ERM del SII)** Registra el `acuse de recibo` — de la mercadería o el servicio, distinto de la aceptación comercial de `accept`/`reject` — dentro de la ventana legal de 8 días. ```bash curl -sS -X POST https://api.facturia.cl/v1/received_documents/rdoc_01K2R9M3D8V5QW7N/acknowledge_receipt \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ---------------------- | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `received_document_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con `Facturia-Idempotent-Replay: true`. Misma llave y cuerpo distinto → `409`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `201` | La respuesta comercial registrada. | CommercialResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse |