Ciclo fiscal

Comprobantes y DGI

El ciclo de un comprobante tiene pasos independientes. Firmar no significa enviar. Enviar no significa aceptar. La API conserva el mismo ID del CFE a lo largo del proceso.

Operación	Método y endpoint	Efecto
Consultar CAE	`GET /api/v1/companies/{id}/cae`	Rangos disponibles por empresa y ambiente.
Prechequeo	`GET /api/v1/companies/{id}/issuance-readiness?documentType=111`	Valida configuración básica y autorización por tipo.
Crear borrador	`POST /api/v1/documents`	Persiste y valida datos de entrada, sin numeración.
Una sola llamada	`POST /api/v1/documents/issue-and-submit`	Crea o recupera, firma e intenta transmitir con externalId obligatorio.
Firmar	`POST /api/v1/documents/{id}/issue`	Prepara XML, reserva CAE, firma y valida XSD.
Enviar	`POST /api/v1/documents/{id}/submit`	Intenta transmitir a DGI; puede preparar/firmar un borrador.
Recuperar	`GET /api/v1/documents/lookup?companyId=...&externalId=...`	Buscar el ID después de timeout o pérdida de respuesta.
Leer	`GET /api/v1/documents/{id}`	Datos, historial y estado almacenado.
Consultar DGI	`POST /api/v1/documents/{id}/status`	Consulta/actualiza respuesta fiscal del sobre.
Obtener PDF	`GET /api/v1/documents/{id}/pdf`	PDF fiscal firmado y validado, sin regenerar el CFE.
Obtener XML	`GET /api/v1/documents/{id}/xml`	Descarga XML firmado si fue validado.

El prechequeo es orientativo: canAttemptIssuance no garantiza conectividad SOAP, homologación ni aceptación de DGI. Un rango CAE puede agotarse entre la consulta y la emisión concurrente.

Emisión completa en una sola solicitud

El endpoint POST /api/v1/documents/issue-and-submit acepta el mismo JSON del borrador, con externalId obligatorio, y utiliza los controles existentes de creación y transmisión. Exige permisos documents:write y documents:submit.

Responde 202 cuando el proceso sigue pendiente y 200 si ya existe un resultado fiscal final. Consultá data.status: únicamente ACCEPTED indica aceptación por DGI. En fallos posteriores a la creación incluye documentId para conciliación. Nunca reintentes con otro externalId.

Para PRODUCTION esta modalidad está deshabilitada por defecto: el operador debe habilitar expresamente API_ONE_SHOT_LIVE_ENABLED=true, después de verificar el estado fiscal. Las rutas tradicionales conservan su funcionamiento.

Firmar y enviar

DOCUMENT_ID="ID_RETORNADO_EN_POST"
curl -sS -X POST "https://factumel.com/api/v1/documents/$DOCUMENT_ID/issue" \
  -H "Authorization: Bearer $FACTUMEL_API_KEY"

curl -sS -X POST "https://factumel.com/api/v1/documents/$DOCUMENT_ID/submit" \
  -H "Authorization: Bearer $FACTUMEL_API_KEY"

curl -sS -X POST "https://factumel.com/api/v1/documents/$DOCUMENT_ID/status" \
  -H "Authorization: Bearer $FACTUMEL_API_KEY"

Idempotencia

Reutilizá el mismo externalId de tu sistema por empresa y comprobante. Repetir la creación con exactamente los mismos datos devuelve el existente. Si el ID ya corresponde a un payload diferente, Factumel devuelve un conflicto. Nunca generes otro ID para disimular un timeout: buscá primero por companyId y externalId usando GET /api/v1/documents/lookup, y consultá su estado antes de reintentar.

Estados fiscales

Estado	Interpretación
`DRAFT`	Borrador, todavía no emitido.
`QUEUED`	Preparación/CAE en progreso.
`SIGNED`	Firmado, sin aceptación fiscal confirmada.
`SENT`	Transmitido, esperando respuesta definitiva.
`ACCEPTED`	Aceptado por DGI.
`OBSERVED`	Observado; evaluar los datos de recepción.
`REJECTED`	Rechazado; revisar el motivo y el procedimiento fiscal aplicable.

Los comprobantes fiscales emitidos no deben tratarse como registros CRUD. Una corrección fiscal puede requerir nota de crédito o débito con referencias; no se edita ni elimina un comprobante ya enviado como si fuera un borrador.

Notas, retenciones y operaciones especiales

El body de creación permite references, retentionLines, globalAdjustments, paymentMethods e indicadores DGI. No reutilices valores de un tipo de documento en otro sin validar las reglas oficiales. Consultá el OpenAPI y contrastá cada dato fiscal con el Formato CFE de DGI.