factadesarrolladores API 0.1.0-esqueleto

Referencia HTTP

Lo que vale para todas las rutas: cómo autentica, cómo se hace idempotente una operación que gasta un correlativo, qué límites tiene y qué significa cada uno de los 112 códigos de error.

URL base y ambiente

URL base https://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1

Es la única URL pública de Facta. La llave selecciona el ambiente del Ministerio de Hacienda: facta_test_ transmite a apitest.dtes.mh.gob.sv y facta_live_ al servicio de producción. Las pruebas se hacen en esta misma URL con el certificado y la llave de pruebas; no se publica una segunda URL.

Todo cuerpo es application/json; charset=utf-8, y toda respuesta también, incluidos los errores. El cuerpo no puede pasar de 1 MB.

Autenticación

X-Facta-Key — la llave

facta_test_<id>.<secreto> en pruebas, facta_live_<id>.<secreto> en producción. La parte antes del punto es pública e identifica la fila; la de después se muestra UNA vez al acuñarla y no se guarda (solo su SHA-256 con pimienta).

El prefijo y el ambiente de la fila tienen que coincidir: una llave facta_test_ que apuntara a una fila de producción es 403, jamás una emisión.

Nunca en Authorization. El gateway lee esa cabecera por su cuenta.

Esta llave sola no firma. Abre nada: identifica y autentica. Para firmar hace falta además X-Facta-Sign-Key (ver los dos vaults del plan, §6).

Lista de IP autorizadas (opcional, se define al acuñar la llave): cada entrada es una dirección —190.53.1.2, 2001:db8::1— o un rango en notación CIDR —190.53.1.0/24, 2001:db8::/32—, IPv4 o IPv6. Un integrador detrás de un NAT con varias salidas pone su prefijo, no cada dirección. La lista vacía significa «desde cualquier parte». Si la llave tiene lista y tu IP no está en ninguna de sus entradas, la respuesta es ip_not_allowed (403) antes de cualquier trabajo. La IP que se compara es la del extremo que nos conecta, y una cabecera X-Forwarded-For puesta por el cliente no la cambia.

X-Facta-Sign-Key — el segundo factor

La contraseña que abre el vault de firma, donde vive el certificado del emisor. 256 bits generados por el navegador en la ceremonia de acuñado y mostrados UNA vez.

Por qué existe: en la web hay dos secretos independientes (la sesión y la llave del vault, que nunca viaja) y robar uno no basta. En una API hay un solo token, y si ese token bastara para firmar, un .env filtrado sería poder de emitir DTE reales con el certificado del cliente. Con esta separación, el token robado no firma.

Qué hacemos con ella: se convierte a bytes al entrar, se deriva la KEK por HKDF-SHA-256, se abre la envoltura y el arreglo se pone a cero. No se guarda, no se registra en ninguna bitácora y no hay hash de ella en nuestra base — el verificador es la propia etiqueta GCM de la envoltura. Lo que sí guardamos es el CONTEO de intentos fallidos: cinco seguidos en una hora suspenden la llave.

No es FACTA_UNLOCK_KEY. Esa otra (prefijo factauk_) abre sus credenciales de almacenamiento en SU servidor y no viaja nunca a Facta. Si la manda aquí, la respuesta se lo dice en vez de intentarlo.

Alcances

Cada ruta exige un alcance, y la llave los lleva escritos desde que se acuñó. Un alcance que falta es 403 forbidden_scope, y details dice cuál hacía falta y cuáles tiene.

AlcancePara quéRutas
issueEmitir, anular y registrar eventos de retorno/v1/dte, /v1/dte/prepare, /v1/dte/sign, …/invalidate, …/return
queryLeer lo emitidoGET /v1/dte, GET /v1/dte/{codigoGeneracion}
downloadÁrea de retención…/file, /v1/dte/holding
ningunoSalud y contrato/v1/status, /v1/openapi.json

Idempotencia

Identificador que el CLIENTE elige para esta operación. Obligatorio en toda ruta que no se pueda deshacer: las tres que gastan correlativo y la anulación. Sin él, un reintento por timeout quemaría un segundo número — o mandaría un segundo evento contra un documento que el primero ya anuló.

Reglas, todas verificables:

  • Alcance (llave, Idempotency-Key). Dos integradores pueden usar la misma cadena sin chocar, y ninguno puede leer la respuesta del otro.
  • Repetir la misma llave con el MISMO cuerpo devuelve la respuesta guardada, con Idempotency-Replayed: true. Eso incluye un rechazo del MH: el reintento devuelve el mismo 422, sin quemar otro número.
  • Repetir con OTRO cuerpo es 422 idempotency_key_reuse. Devolver la factura de ayer para la venta de hoy es peor que fallar. Si la primera petición ya terminó, details nombra su codigoGeneracion. Excepción: las altas de cliente y producto (POST /v1/customers, POST /v1/products). Ahí el otro cuerpo se aplica al registro que la llave creó (semántica de PATCH) y la respuesta es 200 con actualizado: true; solo si esa llave no guarda un registro vuelve el 422.
  • Mientras la primera está en vuelo, la segunda es 409 idempotency_in_flight — no se encola. El cliente reintenta.
  • La llave queda atada a su venta para siempre. Desde el 30-oct-2026 esta regla es más estricta que antes: una llave que ya dio origen a un documento NO se libera nunca. La respuesta guardada se conserva 7 días; después se borra, pero Facta recuerda qué solicitud y qué documento eran.
  • Repetir con el mismo cuerpo pasados los 7 días devuelve el documento que ya existe, reconstruido desde sus copias (estado, sello, totales; el archivo se baja con GET /v1/dte/{codigoGeneracion}/file), con Idempotency-Replayed: true y Idempotency-Replay-Source: rebuilt. Nunca emite uno nuevo.
  • Repetir con otro cuerpo es 422 idempotency_key_reuse siempre, también pasados los 7 días.
  • Una llave por venta, para siempre. No reutilice una llave para otra venta aunque haya pasado mucho tiempo. Si perdió la respuesta, repita con la misma llave y el mismo cuerpo, o consulte el documento: nunca invente una llave nueva para «volver a intentar» la misma venta.

Límites de uso

Toda respuesta dice cuánto cupo queda. Los números describen la ventana que está más cerca de morder: con 5 llamadas libres en la hora y 1 en el día, lo que se anuncia es 1.

httpcabeceras de cualquier respuesta
RateLimit-Limit: 57
RateLimit-Remaining: 56
RateLimit-Reset: 3600
RateLimit-Policy: hour;q=60;w=3600, day;q=300;w=86400
CabeceraQué dice
RateLimit-LimitEl techo de la ventana más cercana a morder.
RateLimit-RemainingLo que queda de esa ventana, con esta petición ya descontada.
RateLimit-ResetSegundos hasta que esa ventana se libera del todo.
RateLimit-PolicyLas dos ventanas, hour;q=60;w=3600, day;q=300;w=86400.
Retry-AfterSegundos que conviene esperar. Solo en los errores donde esperar arregla algo.

Consultar /v1/status no gasta el cupo que reporta: se cuenta en una ventana propia y generosa, porque un monitor que pregunta cada minuto se comía el cupo de emitir.

Errores

Un error es siempre la misma forma: { "error": { "code", "message", "details" } }. El code es el contrato y no cambia; el message está escrito en español para la persona que lee un registro a las dos de la mañana, y puede reescribirse.

jsonrespuesta 422 · mh_rejected
{
  "error": {
    "code": "mh_rejected",
    "message": "[receptor.nit] NIT CONTRIBUYENTE NO EXISTE",
    "details": {
      "estado": "RECHAZADO",
      "descripcionMsg": "[receptor.nit] NIT CONTRIBUYENTE NO EXISTE",
      "observaciones": [],
      "codigoGeneracion": "E4311553-DADF-4168-829E-B6B7E50F1D41",
      "numeroControl": "DTE-03-M001P001-000000000000177"
    }
  }
}
Los 112 códigos del contrato
codeHTTPCuándo pasaQué hacer
unauthorized 401

No llegó la cabecera X-Facta-Key.

Mande la llave. Y nunca en Authorization — esa la lee el gateway.

invalid_api_key 401

La llave no existe, está mal escrita o el secreto no coincide.

Los tres casos tardan lo mismo y dicen lo mismo, a propósito. Revise que copió la llave entera, con el punto.

key_revoked 403

Alguien la revocó desde la app.

Una llave revocada no vuelve. Acuñe otra.

key_expired 403

Pasó la fecha de vencimiento que se le puso al acuñarla.

Acuñe otra desde Configuración → Llaves de la API.

key_inactive 403

La llave está desactivada.

Vuelva a activarla desde la app.

forbidden_scope 403

A la llave le falta el alcance que la ruta exige.

details.required dice cuál hacía falta y details.granted los que tiene. Los alcances de emitir y consultar se eligen al acuñar; el dueño concede catalog:read y catalog:write por llave desde Cuenta → API.

dte_type_not_allowed 403

La llave no tiene permitido ese tipoDte.

details.allowed trae la lista. Acuñe una llave que incluya el tipo.

ip_not_allowed 403

La llave tiene lista de direcciones y la suya no está en ninguna entrada.

Añada su dirección o su rango CIDR al acuñar. La dirección que se compara es la del extremo que conecta; una cabecera puesta por el cliente no la cambia.

environment_not_allowed 403

El prefijo de la llave y su fila no coinciden, o el ambiente de la llave no es el de su empresa.

Si su empresa ya pasó a producción, acuñe una llave de producción; una de pruebas no puede emitir documentos reales.

company_mismatch 403

La petición trae X-Facta-Company con el NIT o el id de una empresa, y la llave es de otra.

Use la llave de esa empresa (cada empresa tiene las suyas). /v1/status dice de qué empresa es la llave que mandó. No se reservó, firmó ni envió nada.

sign_key_required 401

Falta X-Facta-Sign-Key en una ruta que firma — o llegó la de apertura de almacenamiento (factauk_), que no es esta.

Mande la contraseña del vault de firma, la que empieza con factask_ y se mostró una vez al acuñar.

sign_key_invalid 401

Esa contraseña no abre el vault de firma.

details.intentosRestantes dice cuántos quedan antes de que la llave se suspenda sola.

sign_vault_locked 403

Cinco intentos fallidos en una hora. La llave queda suspendida.

Esperar no lo arregla. Hay que reactivarla desde la app.

sign_vault_missing 409

La llave no está provisionada para firmar, o el certificado que guarda es de otro NIT que el de la empresa.

Reintentar no la arregla. Acuñe la llave de nuevo, que es lo que provisiona su vault de firma.

invalid_request 400

Cuerpo ausente, que no es JSON, de más de 1 MB, un campo con la forma equivocada, o un código de generación que no tiene forma de UUID.

details.field señala el campo cuando lo hay. No gasta correlativo.

fse_withholding_mode_invalid 400

El modo no es per_line, o incomeWithholding tiene una clave ajena al control admitido.

Use solo {mode: per_line}.

fse_withholding_legacy_conflict 400

Se combinaron incomeWithholding o decisiones por línea con aplicarReteRenta.

Elija un solo modo de retención.

fse_withholding_not_supported 400

Se mandaron controles de retención FSE por línea en otro tipo de DTE.

Quite incomeWithholding y applyIncomeWithholding.

fse_withholding_selection_required 400

El modo por línea no tiene líneas o falta una decisión applyIncomeWithholding.

Envíe una decisión booleana para cada línea.

fse_withholding_selection_invalid 400

Una decisión applyIncomeWithholding no es boolean.

Envíe true o false sin convertir otros valores.

fse_withholding_mode_required 400

Se envió applyIncomeWithholding sin el modo por línea.

Añada incomeWithholding.mode per_line o quite las decisiones.

global_discount_not_supported 400

Se mandó descuentoGlobal en una nota de crédito (05) o de débito (06).

Los montos de una nota salen del documento que corrige: ajuste el valor de las líneas y quite descuentoGlobal. No gasta correlativo.

validation_failed 422

El documento no cumple el esquema oficial del Ministerio de Hacienda, un código no es del catálogo (formaPago, pagos[].codigo, exportacion.recintoFiscal, .tipoRegimen, .regimen), o pagos no suma el total o se manda en una venta a crédito (condicionOperacion 2).

details.issues lista cada campo; un código de catálogo trae details.field, details.catalog y details.supported; pagos trae details.totalPagar y details.sumaPagos. Si pagos iba en una venta a crédito, el remedio es formaPago + plazo + periodo: vea «Forma de pago, tipo por tipo» en el esquema SolicitudDte. No gasta correlativo: la validación corre antes de reservar.

non_taxed_requires_sale_line 400

Una línea con noGravado (cargo o abono que no afecta la base imponible) va en un documento sin ninguna línea de venta gravada, exenta o no sujeta mayor que $0.00 (Manual Funcional v2.0 §XII).

Añada la venta a la que se refiere el cargo o el abono. details.field señala la línea. No gasta correlativo.

non_taxed_not_supported 400

Se mandó items[].noGravado en una factura de sujeto excluido (14), cuyo esquema no tiene ese campo.

Quite la línea: en la FSE no existen los cargos ni abonos que no afectan la base imponible. details.supported lista los tipos que sí. No gasta correlativo.

non_taxed_total_negative 400

Los abonos (noGravado negativos) dejan el total a pagar por debajo de cero.

details.totalPagarVenta es lo que suma la venta y details.totalNoGravado lo que restan las líneas; baje el abono. Un total exactamente cero sí vale. No gasta correlativo.

retention_mixed_class_unsupported 422

Se pide aplicarReteRenta en un documento con alguna línea exenta o no_sujeta (items[].tipoVenta).

No se firmó nada ni se gastó correlativo. La FSE no admite tipoVenta en esas líneas; revise los datos y vuelva a emitir sin esa combinación.

retention_agent_required 403

Se pidió un comprobante de retención (07) y la empresa no está marcada como agente de retención (companies.is_retention_agent).

La persona titular activa «agente de retención» en Cuenta → Perfil fiscal de Facta, y solo si Hacienda designó a la empresa como tal; solo un agente designado puede emitir el 07. La llave además tiene que llevar el tipo 07 (si no, dte_type_not_allowed: acuñe otra). Se rechaza antes de reservar, así que no gasta correlativo.

not_found 404

No existe el documento, o el customerId, o la ruta.

Un documento de otra empresa contesta exactamente lo mismo que uno que no existe. Es a propósito.

drive_not_configured 503

Este servicio no tiene configurado el cliente OAuth de Google Drive.

No lo arregla el cliente. Escriba a soporte; mientras tanto, las copias a Drive esperan a que alguien abra Facta.

drive_reauthorization_required 409

Google retiró el permiso de la llave larga de ese Drive (revocado, vencido o cambio de contraseña).

Una persona debe abrir Facta y pulsar «Confirmar en Google» en ese destino de Google Drive. Reintentar no lo arregla.

drive_token_failed 502

Google no contestó o rechazó la renovación por una razón distinta a un permiso retirado.

Reintente en unos segundos. No se reenvía el texto de Google.

drive_not_available_for_api 403

Se llamó a la ruta de renovación de Google Drive. Drive está desactivado para la API (decisión de seguridad del 17-oct-2026) y no cuenta como almacenamiento de la API.

No reintente. Conecte Almacenamiento Facta u otro destino compatible (S3 y compatibles, Supabase Storage, FTP/SFTP). Una empresa cuyo único destino es Drive se trata como una empresa sin destino.

method_not_allowed 405

La ruta existe, pero no con ese método.

El mensaje dice cuál es el bueno.

idempotency_key_required 400

Falta Idempotency-Key en una ruta que no se puede deshacer (emitir, anular o devolver).

Elija una cadena por operación. Sin ella, un reintento por timeout quemaría un segundo número.

idempotency_key_reuse 422

Ya usó esa Idempotency-Key con un cuerpo distinto (o, con X-Facta-Request-Fingerprint, con otra huella). Si la primera petición terminó, details trae codigoGeneracion. Ya no se devuelve en POST /v1/customers ni POST /v1/products cuando la llave creó un registro: ahí se actualiza ese registro (200, actualizado: true).

Use una nueva. Para cambiar un registro de catálogo, use PATCH con el id. Devolver la factura de ayer para la venta de hoy sería peor que fallar.

idempotency_in_flight 409

La primera petición con esa llave todavía se está procesando.

Reintente en unos segundos. No se encola a propósito: la primera puede estar gastando un correlativo ahora mismo.

document_not_retryable 409

POST /v1/dte/{codigoGeneracion}/reintentar sobre un documento que la API no puede terminar. details.motivo: documento_de_la_aplicacion (lo emitió la aplicación), sin_copia_firmada (no hay copia firmada que reenviar) o sin_documento_firmado (ese número nunca llegó a firmarse).

documento_de_la_aplicacion: reintente desde Documentos → Pendientes con Hacienda, en la aplicación. sin_copia_firmada: escriba a soporte con el código. sin_documento_firmado: no hay nada pendiente; consulte GET /v1/dte/{codigoGeneracion}.

retry_in_progress 409

Otro reintento del mismo documento está en curso.

Espere Retry-After (unos segundos) y vuelva a llamar o consulte GET /v1/dte/{codigoGeneracion}. No se envió nada.

prepare_token_invalid 422

El prepareToken venció, es de otra llave, o el documento cambió aunque sea un centavo.

Vuelva a llamar a /v1/dte/prepare. Lo que se firma tiene que ser lo que obtuvo el número.

return_exceeds_available 422

Se pide devolver más de lo que queda de una línea del documento, contando los eventos de retorno anteriores.

details.lineas trae, por cada línea (desde 1), lo solicitado y lo disponible. Pida como máximo lo disponible; no se firmó nada.

return_window_closed 422

fechaEvento es anterior al documento, está en el futuro o cae después del plazo de retorno (tres meses; dos años en ciertas actividades).

Registre el evento de retorno dentro del plazo. Pasado, el documento ya no admite el evento y la salida es otra operación fiscal.

return_type_not_allowed 422

El documento no es una factura (01), una factura de exportación (11) ni una de sujeto excluido (14).

Los demás tipos se corrigen con una nota de crédito, no con un evento de retorno.

return_pdf_unavailable 404

Se pidió el PDF de un evento de retorno y ya no tenemos su JSON firmado para dibujarlo, o se pidió su ticket (no existe).

Use el PDF de la respuesta original (representacionGrafica) o el que guardó en su almacenamiento. La hoja de un evento de retorno es solo carta.

has_return_events 409

Se intenta anular un documento que ya tiene eventos de retorno registrados.

Hacienda no permite anularlo (Anexo V 44.4). No se mandó nada; corrija con los eventos de retorno y, si hace falta, una nota de crédito.

include_limit_exceeded 400

Se pidió GET /v1/dte?include=dte con limit mayor que 25.

Pida limit=25 o menos y siga con siguiente. details.maximo dice el tope. Sin include la página sigue siendo de hasta 100.

not_sealed 409

Se descarga el JSON (kind=json, sin raw=true) de un documento que todavía no tiene sello, o sea, en contingencia. El Archivo DTE necesita selloRecibido.

Espere a que la contingencia se retransmita y el documento se selle, o descargue lo guardado con raw=true. details.estado dice en qué estado está.

rate_limited 429

La llave alcanzó su techo por hora o por día.

details.window, details.remaining y details.retryAfterSeconds dicen cuál y cuánto esperar.

amount_limit 429

El documento pasa del monto máximo por documento de la llave.

Se comprueba antes de reservar, así que no gasta correlativo. Suba el techo de la llave o divida la operación.

mh_rejected 422

Hacienda leyó el documento y lo negó.

Sí gastó correlativo, y details nombra codigoGeneracion y numeroControl para que la corrección reuse ESE número (§167). No es 502 porque es un veredicto sobre los datos, no una caída.

mh_unreachable 502

Reservado: la versión actual nunca lo devuelve.

Todo fallo de transporte sale como 202 contingencia, porque para entonces el documento ya está firmado y se le debe a Hacienda.

mh_auth_failed 424

Hacienda contestó el inicio de sesión y no aceptó el usuario y la contraseña de transmisión (API) de la empresa.

No reintente igual: la persona titular debe actualizar la contraseña de la API del Ministerio en la app (Cuenta → Conexión con Hacienda). En una emisión sí gastó correlativo (details.codigoGeneracion, details.numeroControl, copia en details.almacenamiento): el documento quedó firmado, no lo emita otra vez.

mh_network_blocked 502

La pasarela de Hacienda rechazó la conexión (403 HTML) desde la región donde se procesó la solicitud; no leyó las credenciales.

Envíe x-region: us-west-2 (la region de GET /v1/status) y reintente; details.servedRegion dice dónde se atendió. En una emisión pudo gastarse el correlativo: reintente con la MISMA Idempotency-Key.

correlative_unavailable 503

No se pudo reservar el correlativo a tiempo.

Reintente con la MISMA Idempotency-Key después de Retry-After. Si la base alcanzó a reservar el número tras el aviso, Facta lo devuelve antes de contestar (y, para un borrador, el barrido de cinco minutos lo suelta); no queda un número huérfano.

paid_plan_required 402

La empresa es una empresa adicional de su propietario (Multiempresa) y emite en producción con plan gratuito o de prueba. En pruebas (00) no aplica.

Contrate el plan Lite o Pro de esa empresa desde la app (Cuenta → Plan) y reintente. No se gastó número.

no_storage_destination 422

Un destino propio (BYOS) reportado no está entre los destinos publicados de la llave. La emisión ya NO devuelve este error por falta de almacenamiento (desde el 6-oct-2026).

Sincronice los destinos desde la app. Para emitir sin almacenamiento disponible no hace falta nada: el documento se emite y la respuesta trae advertencias.

storage_unsupported 501

El servidor todavía no publica la capacidad o ruta de almacenamiento administrado.

El SDK conserva compatibilidad y marca la capacidad como desconocida; actualice el servidor antes de depender de ella.

storage_unavailable 503

La copia administrada no se pudo consultar o reparar temporalmente. También lo devuelve la emisión, con Retry-After, cuando el interruptor de emergencia está abierto (la copia temporal viene fallando para esa empresa y no hay otro almacenamiento): no se gastó correlativo.

Reintente solo la operación de almacenamiento. No vuelva a emitir el DTE. Si fue una emisión rechazada por el interruptor, espere Retry-After y reintente con la MISMA Idempotency-Key.

entrega_token_invalido 401

El token de entrega no corresponde a este documento y canal, está mal escrito, o el documento no tiene token (estaba en contingencia, o ningún canal se podía entregar).

Use el token exacto que devolvió la emisión (entrega.token). Si no lo tiene, el estado se lee con GET /v1/dte/{codigoGeneracion}/entrega.

entrega_vencida 410

Pasaron más de 5 minutos desde la emisión y el canal todavía no se había entregado.

No se reintenta con ese token. El documento ya está emitido; entréguelo por sus propios medios o desde la app.

canal_no_marcado 409

El documento no marcó ese canal en entrega al emitirse.

Los canales se marcan al emitir. Revise con GET /v1/dte/{codigoGeneracion}/entrega cuáles quedaron marcados.

catalog_write_disabled 403

Una ruta de escritura del catálogo (POST, PATCH o DELETE en /v1/customers y /v1/products) y el dueño de la cuenta no ha permitido administrar clientes y productos desde el API.

El dueño lo activa en Cuenta → API → «Permitir administrar clientes y productos desde el API» (eso guarda el catálogo sin cifrar en Facta DTE) y concede catalog:write a la llave. Se comprueba antes que el alcance y no cambia nada.

catalog_encrypted 409

Una ruta del catálogo y los clientes y productos de la empresa están cifrados (o una ficha quedó cifrada a medias de una conversión).

El servidor no puede leer ese catálogo con esta llave. La persona titular puede darle acceso a la clave de datos compartida (Cuenta → Datos) o guardar el catálogo sin cifrar en Cuenta → API; hasta entonces, envíe el receptor y las líneas completos.

catalog_duplicate 409

Ya existe un cliente con ese documento, o un producto con ese código.

details.id dice cuál y details.activo si está desactivado. Edítelo con PATCH, o reactívelo con {"activo": true}.

content_hash_mismatch 422

El contentHash no es el SHA-256 del JSON canónico (RFC 8785) del plaintext.

Recalcule el hash sobre exactamente lo que cifró y reenvíe.

id_conflict 409

El id ya existe con otro contenido, o es de otra empresa.

Elija un UUID v4 nuevo. Con el mismo contenido sería una repetición.

item_final 409

El pendiente ya está resuelto (aplicado, emitido, cancelado, vencido...) y se le pidió un cambio.

Léalo con GET y, si necesita otro, cree uno con un id nuevo.

draft_claimed 409

Una persona de la empresa tiene el borrador abierto en la app.

Reintente en unos minutos; la reserva vence sola.

draft_issuing 409

El borrador se está emitiendo ahora, desde la app o desde otra petición.

No reintente. Consulte GET /v1/drafts/{id} hasta que diga emitido.

draft_issued 409

El borrador ya se emitió.

details.codigoGeneracion dice el documento; consúltelo con GET /v1/dte/{codigoGeneracion}.

draft_not_issuable 409

El borrador venció, perdió su contenido, es de otro ambiente o está en un estado que no se emite.

details.reason dice cuál. Cree un borrador nuevo.

version_mismatch 409

La versión del borrador cambió desde que la leyó.

Léalo de nuevo y reaplique su edición sobre la version actual.

inbox_cap_reached 429

Hay demasiados borradores sin resolver (500 por empresa).

Cancele los que no necesite o espere a que el dueño los resuelva.

drafts_not_ready 409

La empresa comparte su clave de datos y la persona titular todavía no ha abierto Facta con su vault desde entonces, así que no hay con qué sellar el borrador.

Pídale a la persona titular que abra Facta con su vault; basta una vez. Después el mismo cuerpo funciona sin cambios.

catalog_write_test_key 403

Una llave de pruebas (00) quiso escribir el catálogo y la empresa ya tiene una llave de producción viva.

Escriba el catálogo con la llave de producción; la de pruebas sigue leyendo y emitiendo.

inbox_retired 410

Llamó a /v1/catalog/changes o a una de sus rutas. Ese buzón de cambios de catálogo sellados se retiró; no se aplica nada.

Escriba el catálogo con POST y PATCH en /v1/customers y /v1/products (alcance catalog:write). Los borradores no cambiaron.

data_grant_unavailable 503

El catálogo de la empresa está compartido y Facta no pudo abrir el acceso de esta llave (su mitad, la clave de la época o un bloqueo de la empresa). Nada de lo que usted mandó lo causa.

Reintente en un momento. Si se repite, details.reason dice cuál fue; escriba a soporte con la hora y el keyId. No cambie ni rote la llave por esto.

data_grant_revoked 403

El dueño de la empresa revocó o suspendió el acceso de esta llave al catálogo cifrado.

Pídale que le dé acceso otra vez en Cuenta → API, o que cree una llave nueva.

data_epoch_stale 503

La clave de los datos de la empresa se rotó y el acceso de esta llave todavía no se renovó.

Reintente en unos minutos; el dueño lo renueva al abrir Facta. No hace falta cambiar la llave.

catalog_revision_conflict 409

Mandó If-Match con una revisión que ya no es la actual, o el registro cambió tres veces mientras lo editaba.

details.revisionActual trae la revisión vigente; léalo de nuevo, reaplique su cambio y repita con ese If-Match.

catalog_record_inactive 409

Quiso editar datos de un cliente o producto desactivado.

Mande también "activo": true para reactivarlo, o deje el registro como está.

catalog_search_too_broad 422

La búsqueda de texto libre (buscar) sobre un catálogo cifrado con más de 5 000 registros activos.

Busque por documento exacto (documento=) o pagine con cursor sin buscar.

catalog_cursor_expired 410

GET /v1/catalog/changes?since= con un cursor desde el que Facta ya no puede continuar: otra generación (una restauración), historial anterior a 90 días, un since mayor que la cabeza, o más de 1 000 cambios pendientes.

details.reason dice cuál; lea el catálogo completo y siga con since=details.cabeza y generacion=details.generacion.

webhook_limit_reached 409

Quiso registrar un sexto webhook en la misma llave.

Borre uno (DELETE /v1/webhooks/{id}) o cambie la dirección de uno existente con PATCH.

webhook_duplicate 409

Esa dirección ya está registrada en esta llave.

Cambie los eventos del webhook que ya existe con PATCH /v1/webhooks/{id}.

temporary_copy_expired 410

Pidió un documento sellado cuya copia temporal cifrada ya se borró (30 días después de sellado, o 2 días después de que Facta verifique una copia) y Facta no tiene otra copia (Almacenamiento Facta).

Búsquelo en su propio almacenamiento: es el JSON que guardó. Para que no vuelva a pasar, confirme cada documento (POST /v1/dte/{codigoGeneracion}/storage-confirmation) y revise GET /v1/storage/unconfirmed cada día.

nothing_to_repair_from 409

POST /v1/storage/copies/{codigoGeneracion}/repair sobre un documento cuya copia temporal ya se borró: no queda de dónde reescribir.

Recupere el JSON de su propio almacenamiento. Esta ruta solo repara copias de Facta mientras la copia temporal existe.

storage_hash_mismatch 422

El sha256 de POST /v1/dte/{codigoGeneracion}/storage-confirmation no es el del JSON de ese documento (archivo cortado, otro documento, bytes distintos).

Descargue otra vez con GET /v1/dte/{codigoGeneracion}/file, guarde esos bytes y calcule el hash sobre ellos. No se registró nada.

storage_quota 409

El almacenamiento de compras del plan (por ambiente) está lleno: el archivo no se pudo admitir.

Libere espacio o suba de plan; nada se perdió ni se escribió. Reintente después con POST /v1/purchases/review/{id}/retry o repitiendo la importación.

review_not_pending 409

El archivo «por revisar» ya está resuelto o descartado.

Léalo con GET /v1/purchases/review/{id}; no hay nada que reintentar.

item_not_pdf 409

Se pidió adjuntar un JSON a un archivo «por revisar» que no es un PDF.

Los archivos JSON se reintentan con POST /v1/purchases/review/{id}/retry.

pdf_conflict 409

La compra ya tiene otro PDF; el que está «por revisar» se conserva sin reemplazar nada.

Deje el archivo en revisión o pídale a la persona titular que lo descarte en la aplicación.

code_mismatch 422

El código de generación del JSON no es el del PDF «por revisar».

Mande el JSON del mismo documento. No se registró nada.

not_a_dte 422

El archivo recibido no es un DTE legible.

Revise que sea el JSON original del proveedor. No se registró nada.

receptor_distinto 422

El documento no está dirigido a esta empresa o es de otro ambiente.

Facta no registra compras de otra empresa. El archivo queda aparte como rechazado (90 días).

document_rejected 422

El documento no cumple la estructura de un DTE de compra.

details.reason dice por qué; el original se conserva. No se registró la compra.

unsupported_file 422

Un archivo de la importación no es JSON ni PDF.

El buzón solo recibe JSON y PDF. Quite los demás archivos y repita.

payload_too_large 413

La importación pasa de los límites: 25 archivos, 5 MiB en total, JSON de 1 MiB, PDF de 3 MiB.

Divida la importación en solicitudes más pequeñas.

verify_key_required 401

POST /v1/purchases/{id}/verify sin X-Facta-Verify-Key, o con una contraseña que no es la de verificación (factask_ o factauk_).

Mande la contraseña del vault de verificación (factavk_…). No cuenta como intento fallido.

verify_key_invalid 401

La contraseña factavk_ tiene la forma correcta pero no abre el vault de verificación de esta llave.

Revise que es la de esta llave. details.intentosRestantes dice cuántos quedan: cinco fallos en una hora suspenden la llave.

verify_vault_locked 403

Demasiados intentos fallidos de abrir un vault de la llave; quedó suspendida.

Esperar no lo arregla: la persona titular reactiva la llave desde la app.

verify_vault_missing 409

La llave no tiene vault de verificación, o el que tiene está incompleto.

La persona titular lo agrega desde Configuración → Llaves de la API. Hasta entonces la llave puede leer y procesar compras, pero no verificarlas.

plan_required 403

El buzón de compras necesita un plan de pago vigente (Lite o Pro) para esta acción: activar, escribir, importar o editar.

Leer, descargar y descartar siguen funcionando aunque el plan haya vencido. details.requerido dice compras.

mailbox_full 409

El buzón de compras agotó el límite mensual y su margen del 10 %: este documento no se guardó, ni siquiera en «por revisar».

Espere al reinicio del mes o a un cambio de plan (o un «Plan a medida») y envíe el documento otra vez. details trae limite, tope, usado y reiniciaEn cuando la respuesta las incluye.

purchases_limit_reached 403

Se usó el límite mensual de compras registradas del plan.

details trae limite, usado y reiniciaEn. Los archivos que llegaron quedan «por revisar» con motivo limite_mensual (hasta un 10 % más que el límite; pasado ese margen, mailbox_full) y se registran con POST /v1/purchases/review/{id}/retry tras el reinicio o un cambio de plan.

inbox_not_enabled 409

El buzón de compras de este ambiente nunca se activó.

La persona titular lo activa en Compras → Buzón, o una llave con purchases:admin con POST /v1/purchases/inbox.

purchase_conflict 409

PATCH /v1/purchases/{id} con un If-Match que ya no es la revisión de la compra.

details.rev trae la actual. Lea la compra otra vez, aplique su cambio sobre ella y reintente.

copy_not_in_managed_storage 409

La compra no tiene copia en el almacenamiento de Facta (solo en sus propios destinos), o no hay de dónde leer el JSON para verificarla.

details.copias lista los destinos con la copia: léala con su SDK. Para verificar, mande el JSON en archivo.

purchase_pdf_unavailable 404

GET /v1/purchases/{id}/file?tipo=pdf sobre una compra cuyo proveedor no envió PDF.

Facta nunca dibuja el PDF de un proveedor. Pídaselo a quien lo emitió.

rotation_cooldown 429

La dirección del buzón ya se rotó hace menos de una hora.

Espere Retry-After (también en details.retryAfterSeconds). La dirección anterior sigue recibiendo mientras tanto.

service_unavailable 503

Algo nuestro no contestó (la base, el registro de peticiones, el de idempotencia) o no se pudo dejar constancia del documento firmado antes de enviarlo.

Espere Retry-After y reintente con la MISMA Idempotency-Key y el mismo cuerpo. Si no se pudo dejar constancia, no se envió nada a Hacienda y el correlativo se devolvió: el reintento es seguro. Si el documento ya quedó firmado, error.details trae estado: "firmado_sin_transmitir", codigoGeneracion, numeroControl, confirmado y siguientePaso: no emita otro, use POST /v1/dte/{codigoGeneracion}/reintentar; repetir con la misma Idempotency-Key devuelve esta misma respuesta. Si no sabe qué pasó, mire GET /v1/dte/pendientes antes de emitir: nunca use una llave nueva para la misma venta.

internal_error 500

Un fallo que no estaba previsto.

El mensaje nunca describe nuestras entrañas. Si se repite, escriba a soporte con la hora y el keyId.

El SDK de TypeScript añade un código más que el servidor nunca manda, network_error: la petición no llegó a recibir respuesta.

Las diez rutas

RutaQué haceAlcanceFirma
GET /v1/status Salud, ambiente y techos restantes ninguno no
POST /v1/dte Emitir un DTE en una sola llamada issue sí
GET /v1/dte Listar lo emitido, por rango de fechas query no
POST /v1/dte/prepare Reservar el correlativo y obtener el documento canónico issue no
POST /v1/dte/sign Firmar y transmitir un documento preparado issue sí
GET /v1/dte/{codigoGeneracion} Consultar un documento por su código de generación query no
POST /v1/dte/{codigoGeneracion}/invalidate Anular un documento que Hacienda ya selló issue sí
POST /v1/dte/{codigoGeneracion}/return Registrar el evento de retorno de una factura que Hacienda ya selló issue sí
GET /v1/dte/{codigoGeneracion}/file Descargar JSON/PDF o regenerar un ticket de un DTE sellado download no
GET /v1/dte/holding Qué hay en tu área de retención ahora mismo download no
GET /v1/storage/status Consultar capacidad administrada y destino BYOS verificado download no
GET /v1/storage/copies Consultar recibos de copias JSON/PDF/evento de invalidación download no
POST /v1/storage/copies/{codigoGeneracion}/repair Reintentar JSON/PDF de un DTE ya sellado download no
GET /v1/storage/unconfirmed Documentos sellados que solo tienen la copia temporal cifrada de Facta download no
POST /v1/dte/{codigoGeneracion}/storage-confirmation Informar que ya guardó el JSON de un documento sellado issue no
GET /v1/openapi.json El contrato de esta API, servido por ella misma ninguno no

La ruta decide, y el método se comprueba después. Una ruta que existe con el método equivocado responde 405 method_not_allowed; una que no existe, 404 not_found.

Esquemas

Los 76 objetos del contrato. Cada campo, con su tipo y si es obligatorio, está en la página de la operación que lo usa y en el contrato descargable.

EsquemaQué describe
BuzonCompras

El estado del buzón de compras de la empresa y el ambiente de la llave.

ProveedorCompra

El proveedor tal como lo trae el documento (en claro, como las ventas).

Compra

Una compra registrada. verificacion es solo lo que contestó Hacienda: estructural (todavía no se preguntó), sellado, no_encontrado, invalidado o discrepancia. totalesCuadran y receptorVerificable son avisos de la lectura del archivo; no se recalculan en el servidor y el archivo del proveedor nunca se corrige.

ItemPorRevisar

ResultadoImportacion

RespuestaVerificacion

CambiosDeCatalogo

Webhook

WebhookConSecreto

WebhookEvento

WebhookNuevo

WebhookCambio

WebhookEntrega

El cuerpo que Facta le envía (Content-Type: application/json), junto con Facta-Signature. Solo ids: ni nombres, ni documentos, ni importes.

Error

BorradorPlano

El cuerpo de POST /v1/dte (SolicitudDte) más dos campos propios del borrador. Facta lo valida, lo sella a la llave pública de la empresa y no guarda el texto.

PendienteSellado

Lo que la llave deja sellado (formato anterior, inbox-v1). plaintext es lo que cifró (borrador: el cuerpo de POST /v1/dte); solo se valida, no se guarda. contentHash es el SHA-256 hex de su JSON canónico (RFC 8785).

PendienteEstado

Un cambio de catálogo; estado en español (pendiente, aplicado, rechazado…).

BorradorEstado

Un borrador; emitido, trae el documento en que se convirtió.

SolicitudBorrador

Los campos de SolicitudDte más la version del borrador.

Entrega

Qué canales entregan el documento una vez emitido. Solo marca: la entrega se pide después, con el token de la respuesta, y emitir nunca espera a ella. Sin este objeto no se entrega nada (las preferencias de correo de la empresa en la app no aplican a la API).

Los dos canales vienen incluidos en toda llave que emite (issue). WhatsApp además necesita saldo en la billetera, y no se envía si la petición dice consentimiento: false; en esos casos la emisión sale igual y el canal lo reporta. Un entrega mal formado es 400 invalid_request y no gasta correlativo.

EstadoDeCanal

pendiente marcado y esperando su petición de entrega · en_proceso el proveedor aún no contesta · enviado el proveedor aceptó el mensaje · fallido no se pudo (mire motivo) · sin_credito la billetera de WhatsApp no tiene saldo · sin_consentimiento falta la atestación · no_permitido la llave no tiene el alcance del canal · vencido pasaron los 5 minutos sin entregarse · esperando_sello el documento estaba en contingencia al emitirse (no hay token; la entrega de estos queda para más adelante).

CanalDeEntrega

EntregaMarcada

Lo que la emisión devuelve cuando marcó canales. Sin token ni venceEn cuando no hay nada entregable (documento en contingencia, o ningún canal con alcance y consentimiento).

SolicitudEntrega

EntregaDeCanal

EstadoDeEntrega

Direccion

Códigos del catálogo oficial del MH (CAT-012/013), no nombres.

Receptor

Un cliente guardado (customerId) lo resuelve el servidor, en cualquier llamada HTTP y con cualquier SDK, cuando la empresa guarda su catálogo sin cifrar, cuando la llave tiene «Catálogo legible por la API», o cuando la empresa comparte su clave de datos y la persona titular le dio acceso a la llave (el servidor abre la ficha solo durante la petición). Si ninguno aplica (catálogo cifrado y la llave sin acceso), el servidor no puede leerlo: envíe el receptor completo. Los campos inline se usan para este DTE y no crean ni actualizan una ficha del catálogo de clientes. Cuando se manda el receptor resuelto, los campos explícitos ganan sobre los datos guardados.

Un CCF (03) y un comprobante de retención (07) exigen numDocumento (NIT), nrc, nombre, codActividad, direccion y correo (en el 07 es el proveedor al que se le retiene).

La nota de remisión (04) exige menos: tipoDocumento + numDocumento, nombre, codActividad (con descActividad) y bienTitulo. nrc, correo y direccion son opcionales (regla de Facta, sobre lo que permite el esquema oficial del 04, donde pueden ir nulos: la Normativa v2.0 pide el NIT del receptor solo en el CCF y en el DCLE). Si se omiten, el documento los lleva en null; un nrc mal formado se omite en vez de rechazarse. Un cliente guardado (customerId) al que le faltan esos datos sirve igual. Una FE (01) admite el receptor entero, parcial o ninguno — sin receptor es el consumidor final anónimo, que es legal.

DocumentoRelacionado

El documento sellado que una nota ajusta. Dos formas:

  • Por código — { "codigoGeneracion": "…" } y nada más. El servidor lee el tipo y la fecha del índice de su empresa. Es la forma que usa quien emitió el original por esta misma API.
  • Entera — tipoDocumento, numeroDocumento y fechaEmision, para ajustar algo que no está en nuestro índice.

Un código que no está en su índice es 404; uno que está pero sin sello es 400 — Hacienda no selló nada que ajustar. Ambas respuestas llegan antes de reservar el correlativo: la nota no gasta ningún número.

ReceptorExportacion

Quien compra desde fuera del país. No tiene NRC ni dirección con códigos del catálogo: tiene país, una dirección en texto y si es persona o empresa. Su descActividad es texto libre — el registro del Ministerio solo cubre a contribuyentes salvadoreños.

Exportacion

Lo que hace de una venta una exportación. La tasa es cero, y tanto la línea como el resumen llevan el tributo C3 con valor 0 — un null ahí lo rechaza Hacienda con «DEBE PROPORCIONAR UN VALOR».

ReceptorSujetoExcluido

El VENDEDOR, no el comprador — el 14 es el único documento del catálogo que corre al revés: lo emite quien compra, para documentar una compra a alguien que no está en el registro de IVA. Por eso no tiene NRC (si lo manda, se ignora: el esquema no tiene dónde ponerlo) y por eso no hay IVA en ninguna parte del documento.

Item

Una línea se describe entera (descripcion, cantidad y precioUni), nombra un producto del catálogo con productId (y cantidad), o es un cargo o abono que no afecta la base imponible (noGravado, ver ese campo), que lleva solo descripcion, noGravado, tipoItem y, si quiere, codigo.

productId lo resuelve el servidor en una llave con «Catálogo legible por la API» (llave.catalogMode: readable en /v1/status), en cualquier llave de una empresa con el catálogo sin cifrar y en una llave con acceso a la clave de datos compartida de la empresa: la descripción, el precio, el código, el tipo y la unidad del producto completan lo que la línea omite, y los campos explícitos ganan. Un producto que no está en el catálogo publicado, o está inactivo, es 404; si el precio del catálogo tiene una base de IVA distinta a la del documento (vat_included), es 400 con reason: catalog_vat_basis — envíe precioUni en la base del documento. En una llave con catálogo cifrado y sin acceso para la llave la API no puede resolverlo, y hay que enviar descripcion y precioUni.

SolicitudDte

Un solo cuerpo para los ocho tipos, y cada tipo exige lo suyo. La tabla de quién pide qué:

01030405 / 06071114
líneacon IVAsin IVAsin IVAsin IVAuna retención (montoSujetoGrav, codigoRetencionMH)sin IVA (tasa cero)el precio, tal cual
receptoropcionalinscritoidentificado (NIT/DUI, nombre, actividad), con bienTitulo; nrc, correo y direccion opcionalesinscritoel PROVEEDOR inscritoextranjeroel VENDEDOR
campos propiosaplicarRetencionIvaaplicarRetencionIva, aplicarPercepcionIvareceptor.bienTitulo (obligatorio), documentosRelacionados (opcional)documentosRelacionados, aplicarRetencionIva, y numPagoElectronico solo en 06hasta 500 líneas; solo empresas agente de retención (403 retention_agent_required)exportacionaplicarReteRenta
descuentoGlobalsí, con IVAsí, sin IVAsí, sin IVAno (400 global_discount_not_supported)se ignora (advertencia)sísí

La nota de remisión (04) y el comprobante de retención (07) no liquidan nada: sus esquemas no tienen pagos ni condición de la operación. Si el cuerpo trae condicionOperacion, formaPago, pagos, plazo o periodo (y, en el 07, descuentoGlobal), el campo se ignora, el documento sale igual y la respuesta lleva una advertencia campo_ignorado por cada uno. La nota de remisión sí acepta descuentoGlobal: lleva el valor de los bienes y ese valor puede llevar descuento. Tampoco llevan apendice (es 400).

Mandar el campo propio de un tipo en otro es 400, no un campo ignorado en silencio: si alguien manda aplicarReteRenta en una factura, cree que está reteniendo y no está reteniendo nada.

## Forma de pago, tipo por tipo

El pago no viaja aparte: se escribe en este mismo cuerpo y Facta lo convierte en documento.resumen.pagos. No hay otro endpoint ni otro momento para informarlo.

CasoQué mandaQué queda en resumen.pagos
Contado, un solo medio (01, 03, 11, 14)formaPago (CAT-017); sin él, 01 (05 en el 11)una fila: { codigo, montoPago = total a pagar, referencia: null, plazo: null, periodo: null }
Contado, varios medios (01, 03, 11, 14)pagos[] y no formaPago; la suma de montoPago = total a pagar, al centavotal cual sus filas, cada una con plazo y periodo en null
Crédito (condicionOperacion 2)formaPago + plazo (CAT-018) + periodo; nunca pagosuna fila con montoPago = total a pagar, más plazo y periodo
Nota de crédito (05) / de débito (06)nada: no liquidan, el esquema oficial no tiene resumen.pagos; formaPago se ignora y pagos es 400. La 06 puede llevar numPagoElectronicoel campo no existe

montoPago es siempre el total a pagar (resumen.totalPagar), es decir, ya con retenciones y percepción aplicadas. Ejemplo de una factura (01) de $25.00 a crédito a 30 días, con formaPago: "05", condicionOperacion: 2, plazo: "01", periodo: 30:

``json "pagos": [ { "codigo": "05", "montoPago": 25, "referencia": null, "plazo": "01", "periodo": 30 } ] ``

Y la misma factura al contado con dos medios (pagos de [{ "codigo": "01", "montoPago": 10 }, { "codigo": "02", "montoPago": 15, "referencia": "VOUCHER-0042" }]):

``json "pagos": [ { "codigo": "01", "montoPago": 10, "referencia": null, "plazo": null, "periodo": null }, { "codigo": "02", "montoPago": 15, "referencia": "VOUCHER-0042", "plazo": null, "periodo": null } ] ``

Una venta a crédito que manda pagos es 422 validation_failed antes de gastar correlativo: Hacienda no publica cómo se reparte un plazo entre varios medios. Se resuelve con formaPago + plazo + periodo.

## Exportación (11): lo que Hacienda exige y el esquema marca opcional

En una exportación de bienes (tipoItemExpor 1, o 3 que se envía como 1) Hacienda exige exportacion.tipoRegimen, exportacion.regimen y exportacion.recintoFiscal, aunque su esquema los marque opcionales: sin tipoRegimen Hacienda rechaza el documento y sin los otros dos lo sella con una advertencia (prueba en vivo, ambiente 00, 30-oct-2026). Facta los exige: falta cualquiera de los tres y la respuesta es 400 invalid_request con details.field, sin gastar correlativo. En servicios (tipoItemExpor 2) pueden ir null.

Hacienda no admite tipoItemExpor 3 (CAT-011 no tiene los códigos 3 y 4; prueba en vivo, ambiente 00, 31-oct-2026: el 3 se rechazó y el mismo documento con 1 se selló). Para una exportación de bienes y servicios use 1. Si manda 3, Facta lo acepta como alias, lo envía como 1, exige los datos de aduana y la respuesta lleva advertencias: [{ codigo: "tipo_item_expor_mapped", mensaje }].

  • recintoFiscal es una aduana o zona franca concreta, código de CAT-027: 01 Terrestre San Bartolo, 02 Marítima de Acajutla, 03 Aérea de Comalapa, 04 Terrestre Las Chinamas, 05 Terrestre La Hachadura, 06 Terrestre Santa Ana, 07 Terrestre San Cristóbal, 08 Terrestre Anguiatú, 09 Terrestre El Amatillo, 10 Marítima La Unión, 11 Terrestre El Poy, 12 Terrestre Metalío, 15 Fardos Postales, 16 Z.F. San Marcos, 17 Z.F. El Pedregal, 18 Z.F. San Bartolo, 20 Z.F. Exportsalva, 21 Z.F. American Park, 23 Z.F. Internacional, 24 Z.F. Diez, 26 Z.F. Miramar, 27 Z.F. Santo Tomás, 28 Z.F. Santa Tecla, 29 Z.F. Santa Ana, 30 Z.F. La Concordia, 31 Aérea Ilopango, 32 Z.F. Pipil, 33 Puerto Barillas, 34 Z.F. Calvo Conservas, 35 Feria Internacional, 36 Aduana El Papalón, 37 Z.F. Sam-Li, 38 Z.F. San José, 39 Z.F. Las Mercedes, 40 Z.F. EMCO, 41 Z.F. Gigante, 42 Z.F. NOVABES, 43 Z.F. INHDELVA, 71 Aldesa, 72 Agdosa Merliot, 73 Bodesa, 76 Delegación DHL, 77 Transauto, 80 Nejapa, 81 Almaconsa, 83 Agdosa Apopa, 85 Gutiérrez Courier y Cargo, 99 San Bartolo Envío Hn/Gt.
  • tipoRegimen (CAT-033): EX-1 Exportación definitiva, EX-2 Exportación temporal, EX-3 Reexportación, TA-1 Tránsito aduanero.
  • regimen (CAT-028): 1000.000 (exportación definitiva, régimen común). En bienes solo el código llano.

Exportación definitiva de bienes, completa:

``json "exportacion": { "tipoItemExpor": 1, "incoterms": "09", "recintoFiscal": "02", "tipoRegimen": "EX-1", "regimen": "1000.000", "flete": 150, "seguro": 20 } ``

## Retención de renta (14), tal como funciona hoy

aplicarReteRenta es opcional: omitido o false no retiene; true aplica la tasa vigente de renta al subtotal completo de la FSE después de los descuentos por línea, y la resta del total a pagar (totalPagar = subTotal − reteRenta). No selecciona líneas por tipoItem: incluye los bienes usados como insumos de un servicio. Una compra solo de bienes no queda sujeta automáticamente por no llevar IVA. El monto se lee en documento.resumen.reteRenta y también en totales.reteRenta de la respuesta. Nunca es automática: se pide.

Retener solo sobre algunas líneas. Envíe incomeWithholding: { "mode": "per_line" } (en lugar de aplicarReteRenta) y un applyIncomeWithholding booleano en cada línea; el servidor nunca lo deduce de tipoItem. La retención es la tasa vigente sobre la suma de las líneas marcadas, después de sus descuentos y de su parte proporcional del descuentoGlobal: una compra de bienes de $100 sin marcar y un servicio de $50 marcado dan subTotal 150, reteRenta 5 y totalPagar 145. Disponible cuando GET /v1/status responde capabilities.fseIncomeWithholdingPerLine: true; los errores fse_withholding_* explican cada rechazo. El tratamiento de una compra de bienes independiente mezclada con servicios sigue pendiente de confirmación de la DGII: confírmelo con su contador.

Pago

Una forma de pago de pagos[].

FilaApendice

Representacion

Datos solo de la hoja (la representación gráfica). Nunca entran al JSON firmado ni viajan a Hacienda: existen únicamente para que una plantilla los dibuje (mesa y mesero de un restaurante, la placa de un taller, los puntos de un programa de lealtad…). Un documento emitido con y sin representacion produce exactamente los mismos bytes firmados (una prueba lo fija), así que no hay cifra fiscal que se pueda colar por aquí.

Se guardan con el índice del documento para que la hoja que se vuelve a descargar o a dibujar salga igual. Una plantilla imprime solo los bloques cuyos datos llegaron; las plantillas que no declaran una clave la ignoran, así que mandarla es seguro y no cambia la hoja. Solo la API los acepta: desde la aplicación esos bloques no se imprimen.

Todo texto va en una sola línea, sin caracteres de control. Hasta 20 valores en total entre las claves conocidas y las filas. En prepare este objeto se rechaza con 400: se manda en /v1/dte/sign junto al prepareToken.

SolicitudFirma

PersonaDeLaAnulacion

SolicitudAnulacion

DteAnulado

SolicitudRetorno

ItemRetorno

Lleva cantidad o noGravado, una sola.

Disponible

Lo que queda por devolver de una línea del documento.

RetornoSellado

RetornoPendiente

El evento está firmado y registrado, pero Hacienda no contestó. Es la misma estructura que RetornoSellado, sin sello.

RetornoResumen

Un evento de retorno registrado sobre un documento, en retornos de GET /v1/dte/{codigoGeneracion}.

Totales

Los calcula dte-core en el servidor. El cliente los transporta y no los recalcula nunca.

totalIva es el IVA de verdad, venga de donde venga: una FE lo lleva en resumen.totalIva y un CCF lo desglosa en resumen.tributos código 20 dejando aquel campo vacío. Leer un solo sitio acierta la mitad de las veces, y la mitad en la que falla es cada crédito fiscal.

DteSellado

DteEnContingencia

Firmado y sin respuesta del MH. Lleva los mismos campos que el sellado salvo los que solo existen con sello: no hay selloRecibido, no hay fhProcesamiento y no hay representacionGrafica — la hoja necesita el sello y el QR, así que todavía no se puede dibujar.

DtePreparado

DteConsultado

PaginaDeDocumentos

DteEnLista

Lo que hace falta para reconciliar: qué número, qué estado, cuánto y a quién. El documento entero se pide por su código con GET /v1/dte/{codigoGeneracion} o …/file.

DocumentoPendiente

Un documento firmado que Hacienda no ha contestado (o rechazó). Solo metadatos.

ReintentoSellado

ReintentoPendiente

DocumentoRetenido

Una fila del área de retención — evidencia de estado, nunca una ruta de bucket ni contenido.

ManagedStorageArtifactReceipt

ManagedInvalidationReceipt

El recibo de un archivo único: el evento de invalidación sellado, guardado bajo el código del documento ORIGINAL y junto a su json.

ManagedStorageReceipt

PlantillasDisponibles

ManagedStorageStatus

ManagedDocumentCopy

UnconfirmedDocuments

StorageConfirmation

ManagedDocumentCopies

Status

Ventana

SyncRevision

Cliente

ClienteEntrada

ClienteCambio

Los mismos campos que ClienteEntrada, todos opcionales, más activo.

Producto

ProductoEntrada

ProductoCambio

Los mismos campos que ProductoEntrada, todos opcionales, más activo.

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar