Documentos recibidos

Los DTE de tus proveedores y la respuesta comercial: aceptación, reclamo y acuse de recibo.

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.

Método	Ruta	Qué hace
`GET`	`/received_documents`	Lista los DTE de proveedores recibidos por esta empresa
`GET`	`/received_documents/{received_document_id}`	Devuelve un documento recibido
`GET`	`/received_documents/{received_document_id}/xml`	Descarga el XML original del proveedor
`GET`	`/received_documents/{received_document_id}/pdf`	Genera el PDF del documento recibido
`POST`	`/received_documents/{received_document_id}/accept`	Acepta el contenido (acción ACD del SII)
`POST`	`/received_documents/{received_document_id}/reject`	Reclama el documento (RCD / RFP / RFT)
`POST`	`/received_documents/{received_document_id}/acknowledge_receipt`	Otorga el recibo de mercaderías o servicios (acción ERM del SII)

`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.

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}`

Devuelve un documento recibido

Un DTE recibido, incluyendo la respuesta comercial (accept/reject/acknowledge_receipt) que se haya registrado para él.

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`

Descarga el XML original del proveedor

El XML exacto que el SII entregó para este documento recibido.

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`

Genera el PDF del documento recibido

Un PDF renderizado del documento recibido, para mostrar o archivar fuera de la API.

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`

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.

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`

Reclama el documento (RCD / RFP / RFT)

Irreversible. No existe des-reclamar.

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`

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.

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

Documentos recibidos

GET /received_documents

GET /received_documents/{received_document_id}

GET /received_documents/{received_document_id}/xml

GET /received_documents/{received_document_id}/pdf

POST /received_documents/{received_document_id}/accept

POST /received_documents/{received_document_id}/reject

POST /received_documents/{received_document_id}/acknowledge_receipt

En esta página

`GET /received_documents`

`GET /received_documents/{received_document_id}`

`GET /received_documents/{received_document_id}/xml`

`GET /received_documents/{received_document_id}/pdf`

`POST /received_documents/{received_document_id}/accept`

`POST /received_documents/{received_document_id}/reject`

`POST /received_documents/{received_document_id}/acknowledge_receipt`