Ciclo de vida de un documento

Los estados por los que pasa un documento desde que se emite hasta que el ente tributario lo resuelve.

Como la emisión es asíncrona, un documento pasa por varios estados desde que lo envías hasta que el ente tributario lo acepta o lo rechaza.

Flujo general

1. Recepción

   Envías el documento con POST /api/companies/{company_id}/invoices. Emify lo valida y lo acepta para procesamiento. La respuesta incluye el id del documento.

2. Procesamiento

   Emify genera el documento tributario, lo firma con el certificado de la empresa y lo remite al ente tributario. Este paso ocurre en segundo plano.

3. Resolución

   El ente tributario acepta o rechaza el documento. Emify actualiza el estado y emite el evento de webhook correspondiente.

Estados

Un documento expone dos estados complementarios:

• status — dónde está el documento dentro del procesamiento de Emify.
• fiscal_status — el veredicto del ente tributario sobre el documento.

Estado de procesamiento (status)

Valor	Significado
PEN	Pendiente. El documento fue recibido y aún no se procesa.
RUN	En proceso. Emify lo está generando, firmando y enviando al ente tributario.
APR	Aprobado por el ente tributario.
EML	Notificación por email enviada al receptor.
WHK	Notificación por webhook despachada a tu sistema.
ERR	Error o rechazo durante el procesamiento.

Estado fiscal (fiscal_status)

Refleja la respuesta del ente tributario. Cuando hay un rechazo u objeción, el motivo llega en fiscal_status_reason.

Valor	Significado
PENDING	Sin respuesta aún del ente tributario.
ACCEPTED	Aceptado por el ente tributario.
REJECTED	Rechazado por el ente tributario.
OBJECTED	Aceptado con reparos (objetado).

Un documento aceptado incluye además los identificadores que asigna el ente tributario: track_id (seguimiento en el SII), cae y cae_expiration_date (código de autorización y su vencimiento) y qr_code.

La fuente de verdad sobre los cambios de estado son los eventos de webhook. Consulta GET /api/companies/{company_id}/webhooks/events para ver el catálogo de eventos disponibles.

Cómo obtener el resultado

Con webhooks (recomendado)

Configura un webhook y Emify te notificará cada cambio de estado sin que tengas que consultar. Es la forma eficiente de integrar la emisión asíncrona.

Con polling

Si no usas webhooks, consulta el documento periódicamente hasta que alcance un estado final:

curl https://api.emify.co/api/companies/{company_id}/invoices/{invoice_id} \
  -H "X-Api-Key: tu_api_key"

Usa intervalos razonables (por ejemplo, con backoff) para no saturar la API. Los webhooks evitan el polling por completo.

Documentos emitidos

Una vez que un documento está aceptado, puedes obtener sus representaciones oficiales:

Recurso	Endpoint
XML firmado	GET /api/companies/{company_id}/invoices/{invoice_id}/xml
PDF (A4, 80mm, 58mm)	POST /api/companies/{company_id}/invoices/{invoice_id}/download-pdf/{formato}
PDF en Base64	POST /api/companies/{company_id}/invoices/{invoice_id}/download-base64/{formato}

Los formatos 80mm y 58mm corresponden a impresión en rollo (ticket); A4 a impresión en hoja.