{"version":"2026-08-10.3","base_url":"/api/v1","precios":{"moneda":"MXN","iva_incluido":false,"modo":"cantidad_completa","compra_minima":50,"compra_maxima":100000,"escalonado":[{"desde":1,"hasta":99,"precio_mxn":0.95},{"desde":100,"hasta":499,"precio_mxn":0.9},{"desde":500,"hasta":null,"precio_mxn":0.8}],"paquetes":[{"code":"PACK_50","credits":50,"precio_mxn":47.5},{"code":"PACK_100","credits":100,"precio_mxn":90.0},{"code":"PACK_500","credits":500,"precio_mxn":400.0}],"regla_tarifa":"Sin suscripción aplica el precio por volumen sobre la cantidad completa. Con plan activo aplica la tarifa del plan a cualquier cantidad. Los folios se compran siempre por separado de la renta.","iva_tasa":0.16,"planes":[{"plan":"free","nombre":"Gratis","mensual_mxn":0,"anual_mxn":0,"precio_por_timbre_mxn":null},{"plan":"starter","nombre":"Starter","mensual_mxn":99,"anual_mxn":1188,"precio_por_timbre_mxn":0.75},{"plan":"pro","nombre":"Pro","mensual_mxn":199,"anual_mxn":2388,"precio_por_timbre_mxn":0.65},{"plan":"enterprise","nombre":"Enterprise","mensual_mxn":399,"anual_mxn":4788,"precio_por_timbre_mxn":0.6}]},"errores":[{"http":400,"code":"PAC_ERROR","titulo":"El PAC rechazó el comprobante","significado":"El comprobante no se timbró. El PAC devolvió una incidencia, por ejemplo CFDI40144 cuando el nombre fiscal no coincide con la constancia del SAT.","cfdi_generado":false,"folios_consumidos":0,"retriable":true,"retry_with_same_idempotency_key":true,"accion":"Corregir los datos y reintentar. El cargo de folios se reembolsa automáticamente.","ejemplo":{"detail":{"code":"PAC_ERROR","message":"El PAC rechazó el timbrado: CFDI40144 - El nombre del emisor no coincide"}}},{"http":400,"code":"BUILD_OR_SIGN","titulo":"Error al construir o sellar el CFDI","significado":"El payload no pudo convertirse en un CFDI válido, o el sellado con el CSD falló. No se llegó al PAC.","cfdi_generado":false,"folios_consumidos":0,"retriable":true,"retry_with_same_idempotency_key":true,"accion":"Revisar catálogos, importes y vigencia del CSD.","ejemplo":{"detail":{"code":"BUILD_OR_SIGN","message":"Error al construir/sellar el CFDI: ..."}}},{"http":402,"code":"INSUFFICIENT_CREDITS","titulo":"Sin folios disponibles","significado":"No hay saldo para timbrar. Nunca ocurre en sandbox.","cfdi_generado":false,"folios_consumidos":0,"retriable":false,"retry_with_same_idempotency_key":false,"accion":"Comprar folios y reintentar.","ejemplo":{"detail":{"code":"INSUFFICIENT_CREDITS","message":"Saldo de créditos insuficiente"}}},{"http":401,"code":"UNAUTHORIZED","titulo":"Credencial ausente o inválida","significado":"El token o la API Key no son válidos.","cfdi_generado":false,"folios_consumidos":0,"retriable":false,"retry_with_same_idempotency_key":false,"accion":"Reautenticar.","ejemplo":{"detail":"Not authenticated"}},{"http":403,"code":"SUBSCRIPTION_REQUIRED","titulo":"Suscripción inactiva","significado":"La API Key requiere una suscripción activa para uso servidor a servidor.","cfdi_generado":false,"folios_consumidos":0,"retriable":false,"retry_with_same_idempotency_key":false,"accion":"Activar o renovar la suscripción.","ejemplo":{"detail":"Se requiere una suscripción activa"}},{"http":422,"code":"VALIDATION_ERROR","titulo":"Payload inválido","significado":"Falta un campo obligatorio o un tipo es incorrecto. Lo valida el esquema antes de construir el CFDI.","cfdi_generado":false,"folios_consumidos":0,"retriable":true,"retry_with_same_idempotency_key":true,"accion":"Corregir el payload según el detalle por campo.","ejemplo":{"detail":[{"loc":["body","conceptos",0,"clave_prod_serv"],"msg":"Field required","type":"missing"}]}},{"http":429,"code":"RATE_LIMITED","titulo":"Límite de peticiones excedido","significado":"Se superó el límite por minuto.","cfdi_generado":false,"folios_consumidos":0,"retriable":true,"retry_with_same_idempotency_key":true,"accion":"Esperar los segundos de la cabecera Retry-After y reintentar con la misma Idempotency-Key.","ejemplo":{"detail":"Rate limit exceeded. 30 per 1 minute","code":"RATE_LIMITED","retriable":true,"retry_with_same_idempotency_key":true}},{"http":500,"code":"INTERNAL_ERROR","titulo":"Error interno","significado":"Falla inesperada de nuestro lado. IMPORTANTE: el comprobante PUEDE haberse timbrado. No asumas que no existe.","cfdi_generado":"indeterminado","folios_consumidos":"indeterminado","retriable":true,"retry_with_same_idempotency_key":true,"accion":"Reintentar con la MISMA Idempotency-Key. Si el CFDI ya existía recibirás 200 con el comprobante original y sin cobro nuevo. Nunca reintentes con una llave nueva: eso sí duplicaría el comprobante. Reporta el request_id a soporte.","ejemplo":{"detail":"Internal Server Error","code":"INTERNAL_ERROR","request_id":"9f2c1a7b4e8d4c1fa0b3c5d6e7f80912","retriable":true,"retry_with_same_idempotency_key":true}}],"idempotencia":{"header":"Idempotency-Key","obligatorio":false,"recomendado":true,"formato":"UUID v4, uno por comprobante lógico","alcance":"por tenant","regla_de_oro":"Una factura, una llave. Ante cualquier error reintenta con la MISMA llave; nunca generes una nueva para el mismo comprobante.","al_reintentar_con_la_misma_llave":{"si_ya_se_timbro":{"http":200,"cuerpo":"El comprobante original, con el mismo uuid","vuelve_a_cobrar":false,"devuelve_409":false},"si_habia_fallado":{"http":200,"cuerpo":"Se intenta timbrar de nuevo","vuelve_a_cobrar":"solo si el timbrado tiene éxito"}},"verificado":"2026-07-31, tres intentos con la misma llave devolvieron el mismo uuid"},"descuentos_e_impuestos":{"descripcion":"Un concepto con descuento e IVA 0%. La base del impuesto se calcula después del descuento.","entrada":{"cantidad":1,"valor_unitario":3313.8,"descuento":926.66,"objeto_imp":"02","traslados":[{"impuesto":"002","tipo_factor":"Tasa","tasa_o_cuota":"0.000000"}]},"salida_esperada":{"Concepto@Importe":"3313.80","Concepto@Descuento":"926.66","Traslado@Base":"2387.14","Traslado@Importe":"0.00","Comprobante@SubTotal":"3313.80","Comprobante@Descuento":"926.66","Comprobante@Total":"2387.14"},"variantes_verificadas":[{"caso":"IVA 16%","tasa_o_cuota":"0.160000","base":"2387.14","importe":"381.94","total":"2769.08"},{"caso":"IVA 0%","tasa_o_cuota":"0.000000","base":"2387.14","importe":"0.00","total":"2387.14"},{"caso":"IEPS 8% + IVA 16%","base":"2387.14","importe":"190.97 + 381.94","total":"2960.05"},{"caso":"IVA 16% + retención ISR 1.25% + retención IVA 10.6667%","base":"2387.14","trasladados":"381.94","retenidos":"284.47","total":"2484.61"},{"caso":"Exento","tipo_factor":"Exento","base":"2387.14","importe":null,"total":"2387.14"},{"caso":"No objeto de impuesto","objeto_imp":"01","importe":null,"total":"2387.14"},{"caso":"Cuota fija","tipo_factor":"Cuota","nota":"El importe depende de la unidad gravada y no puede derivarse: enviar `importe` explícito."}]},"sandbox":{"campo":"sandbox","tipo":"boolean","default":false,"endpoints":["/timbrado/timbrar","/timbrado/nomina","/timbrado/pago","/timbrado/retencion","/timbrado/batch (por ítem)"],"verificacion_previa":"GET /timbrado/entorno?emisor_rfc=<rfc>","campo_a_mostrar":"effective_environment","folios_en_sandbox":0,"prefijo_uuid_simulado":"5A4DB0C5","rfc_que_fuerzan_sandbox":["AAA010101AAA","CACX7605101P8","EKU9003173C9","EWE1709045U0","KAHO641101B39","LAN7008173R5","MAG041126GT8","URE180429TM6","XIA190128J61"]},"trazabilidad":{"header_respuesta":"X-Request-Id","presente_en":"todas las respuestas","uso":"citar este id al reportar un problema a soporte"},"folios":{"por_timbrado":1,"por_cancelacion":0,"en_sandbox":0,"reembolso_automatico":"sí, cuando el PAC rechaza el comprobante","texto_timbrado":"1 folio","texto_cancelacion":"Sin costo"},"pdf_con_marca":{"disponible":true,"plan_minimo":"pro","endpoint":"POST /timbrado/cfdi/{uuid}/pdf","listar_plantillas":"GET /timbrado/plantillas-pdf","afecta_xml":false,"comprobantes_soportados":["I","E"],"nota_comprobantes":"Solo facturas (tipo I/E). Nómina, pagos, traslados y retenciones usan GET /pdf (diseño SenHub); el POST responde 422 si no es factura.","campos":[{"campo":"template_id","tipo":"string","requerido":false,"nota":"Si se omite, se usa la plantilla default."},{"campo":"accent_color","tipo":"string","requerido":false,"nota":"Hexadecimal #RGB o #RRGGBB."},{"campo":"logo_base64","tipo":"string","requerido":false,"nota":"PNG/JPG en Base64, máx. 512 KB. No se aceptan URLs remotas."},{"campo":"notes","tipo":"string","requerido":false,"nota":"Notas comerciales; respeta saltos de línea \\n."},{"campo":"page_format","tipo":"string","requerido":false,"nota":"A4 (default) o Letter."}],"reglas":["Los campos de marca son opcionales e independientes.","Sin template_id: se usa la default y se omiten logo y color.","Con template_id sin logo_base64: la plantilla se renderiza sin logo.","Con template_id sin accent_color: se usa el color propio de la plantilla.","No se cachea; no altera el GET /pdf (diseño SenHub por defecto)."]},"historial":{"endpoint":"GET /timbrado/timbres/buscar","legacy":"GET /timbrado/timbres (array, solo limit; se mantiene por compatibilidad)","respuesta":"sobre { items, total, limit, offset, has_more, next_cursor }","paginacion":{"offset":"simple: offset += limit mientras has_more","cursor":"keyset: reenviar next_cursor; solo con orden por defecto"},"filtros":["status (draft|stamped|canceled|error)","tipo_comprobante (I|E|T|N|P)","rfc_emisor","rfc_receptor","serie","environment (sandbox|production)","date_field (created|stamped)","date_from / date_to (ISO-8601)","q (búsqueda parcial en uuid o folio)"],"orden":{"sort":["fecha","total","rfc_emisor"],"order":["asc","desc"],"default":"sort=fecha, order=desc"},"item_campos":["id","uuid","status","tipo_comprobante","rfc_emisor","rfc_receptor","serie","folio","total","subtotal","descuento","moneda","metodo_pago","forma_pago","uso_cfdi","credits_charged","sandbox","pac_environment","pac_provider","has_xml","has_pdf","error_code","error_message","created_at","stamped_at","canceled_at"]},"cfdi_detalle":{"detalle":{"endpoint":"GET /timbrado/cfdi/{uuid}/detalle","descripcion":"Conceptos e impuestos parseados del XML + estado en la plataforma.","campos":["version","serie","folio","fecha","tipo_comprobante","forma_pago","metodo_pago","moneda","tipo_cambio","subtotal","descuento","total","lugar_expedicion","exportacion","emisor","receptor","conceptos[]","impuestos","timbre_fiscal"],"nota":"No altera GET /timbrado/cfdi/{uuid} (resumen). 409 si no hay XML."},"saldo":{"endpoint":"GET /timbrado/cfdi/{uuid}/saldo","descripcion":"saldo = total − Σ ImpPagado de complementos de pago (REP) vigentes.","campos":["uuid","metodo_pago","moneda","total","pagado","saldo","liquidado","num_pagos","pagos[]"],"nota":"Relevante para PPD. Los pagos cancelados no reducen el saldo."}},"catalogos":{"fuente_de_verdad":"servidor","idempotencia":"client_ref (referencia externa del integrador, única por tenant).","products":{"crud":"GET/POST/PUT/DELETE /products","sync":"GET /products/sync?since=<iso> → { items, count, server_time, has_more }","bulk":"POST /products/bulk (upsert por client_ref, máx 500)","impuestos_default":["tasa_iva","tasa_ieps","ret_iva","ret_isr"]},"customers":{"crud":"GET/POST/PUT/DELETE /customers","sync":"GET /customers/sync?since=<iso> → { items, count, server_time, has_more }","bulk":"POST /customers/bulk (upsert por client_ref; adopta por RFC, máx 500)"},"reglas_sync":["POST con client_ref existente devuelve el registro (200), no duplica.","/sync incluye inactivos (borrados lógicos) para reflejar bajas.","Usar server_time de la respuesta como próximo since; paginar con has_more."]},"impuestos_locales":{"complemento":"ImpuestosLocales 1.0 (http://www.sat.gob.mx/implocal)","endpoint":"POST /timbrado/timbrar (campo opcional impuestos_locales)","casos":"ISH (hospedaje/hoteles), impuestos estatales (construcción), etc.","campo":{"impuestos_locales":{"traslados_locales":[{"imp_loc_trasladado":"str (ej. ISH)","tasa_de_traslado":"número % (ej. 3.0)","importe":"número"}],"retenciones_locales":[{"imp_loc_retenido":"str","tasa_de_retencion":"número %","importe":"número"}]}},"limite":"Máx 1 traslado local y 1 retención local por comprobante.","lectura":"GET /timbrado/cfdi/{uuid}/detalle -> campo impuestos_locales.","nota":"Los importes son explícitos (reglas estatales); las tasas van en porcentaje, no fracción."}}