{"openapi":"3.1.0","info":{"title":"API de Magifactura","version":"1.0.0","description":"Crea tickets y facturas CFDI 4.0, consulta y configura tu organización. Límites: 120 solicitudes por minuto y 30 timbrados por minuto por credencial. Guía: https://magifactura.com/docs/api"},"servers":[{"url":"https://magifactura.com/api/v1"}],"tags":[{"name":"Cuenta","description":"Qué organización, modo y permisos tiene tu credencial."},{"name":"Facturas","description":"Crear y timbrar CFDI 4.0, consultarlos, descargarlos, cancelarlos y enviarlos."},{"name":"Tickets","description":"Notas de venta que tus clientes pueden facturar después."},{"name":"Clientes","description":"Receptores de tus facturas."},{"name":"Productos","description":"Tu catálogo de productos y servicios."},{"name":"Organización","description":"Datos fiscales del emisor y valores por defecto de la API."},{"name":"Catálogos SAT","description":"Claves válidas para llenar los campos."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clave de API (`mf_live_…` o `mf_test_…`) creada en Ajustes → API."}},"schemas":{},"parameters":{}},"paths":{"/me":{"get":{"operationId":"obtenerMe","summary":"Ver la credencial actual","description":"Cualquier credencial válida.\n\nÚsalo para probar tu clave: devuelve la organización, el modo (live/test) y los permisos.","tags":["Cuenta"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"La credencial","content":{"application/json":{"schema":{"type":"object","properties":{"organizacion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nombre":{"type":"string"},"slug":{"type":"string"}},"required":["id","nombre","slug"],"additionalProperties":false},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"scopes":{"type":"array","items":{"type":"string"}},"credencial":{"type":"object","properties":{"tipo":{"type":"string","enum":["clave","oauth"]},"id":{"type":"string"},"nombre":{"type":["string","null"]}},"required":["tipo","id","nombre"],"additionalProperties":false}},"required":["organizacion","modo","scopes","credencial"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas":{"post":{"operationId":"crearFactura","summary":"Crear y timbrar una factura","description":"Permiso requerido: `invoices:write`.\n\nSolo `receptor` y `conceptos` son obligatorios; `formaPago` también si no tienes una por defecto. Un RFC nuevo crea el cliente. Con una clave de prueba se timbra en el sandbox con el RFC de prueba del SAT.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receptor":{"type":"object","properties":{"clienteId":{"type":"string","format":"uuid","description":"Cliente existente"},"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC; si ya existe se usan sus datos guardados, si es nuevo se crea el cliente"},"nombre":{"type":"string","minLength":1,"maxLength":254,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Razón social (RFC nuevo) o nombre para XAXX010101000 individual"},"cp":{"type":"string","pattern":"^\\d{5}$","description":"Código postal (5 dígitos)"},"regimen":{"type":"string","pattern":"^\\d{3}$","description":"Régimen fiscal SAT (c_RegimenFiscal), p. ej. 601"},"usoCfdi":{"type":"string","enum":["G01","G02","G03","I01","I02","I03","I04","I08","D01","D04","S01","CP01"],"description":"Uso del CFDI (c_UsoCFDI)"}},"additionalProperties":false,"description":"Envía clienteId o rfc (solo uno)"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Descripción del concepto (sin |)"},"claveProdServ":{"type":"string","pattern":"^\\d{8}$","description":"Clave de producto o servicio SAT (8 dígitos); en tickets por defecto 01010101"},"claveUnidad":{"type":"string","pattern":"^[A-Z0-9]{1,3}$","default":"E48","description":"Clave de unidad SAT; por defecto E48"},"cantidad":{"type":"number","exclusiveMinimum":0,"default":1,"description":"Cantidad; por defecto 1"},"precio":{"type":"number","minimum":0,"description":"Valor unitario antes de impuestos"},"descuento":{"type":"number","minimum":0,"default":0,"description":"Descuento en pesos para la línea; por defecto 0"},"tasaIva":{"type":"string","enum":["16","8","0","exento"],"default":"16","description":"Tasa de IVA trasladado: 16, 8 (región fronteriza), 0 o exento"},"retIva":{"type":"string","enum":["10.6667","4"],"description":"IVA retenido (%): 10.6667 o 4"},"retIsr":{"type":"string","enum":["10","1.25","20"],"description":"ISR retenido (%): 10, 1.25 o 20"},"cuentaPredial":{"type":"string","maxLength":150,"pattern":"^\\d+(,\\d+)*$","description":"Número de cuenta predial; obligatorio en arrendamiento (claves 8013…)"},"noIdentificacion":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Número de identificación (SKU o folio del ticket)"}},"required":["descripcion","claveProdServ","precio"],"additionalProperties":false},"minItems":1,"maxItems":500,"description":"De 1 a 500 conceptos"},"formaPago":{"type":"string","enum":["01","02","03","04","28","99"],"description":"Obligatoria si no configuraste una por defecto en /organizacion/preferencias"},"metodoPago":{"type":"string","enum":["PUE","PPD"],"description":"Por defecto la de tus preferencias o PUE"},"serie":{"type":"string","minLength":1,"maxLength":25,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Serie interna (máx. 25)"},"folio":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Folio interno (máx. 40)"},"moneda":{"type":"string","enum":["MXN","USD","EUR"],"default":"MXN","description":"MXN por defecto; USD o EUR requieren tipoCambio"},"tipoCambio":{"type":"number","exclusiveMinimum":0,"description":"Tipo de cambio a MXN (obligatorio si moneda no es MXN)"},"condicionesDePago":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Condiciones de pago (texto libre)"},"regimenFiscalEmisor":{"type":"string","pattern":"^\\d{3}$","description":"Régimen del emisor para esta factura; por defecto el principal"},"informacionGlobal":{"type":"object","properties":{"periodicidad":{"type":"string","enum":["01","02","03","04","05"],"description":"Periodicidad SAT: 01 diaria, 02 semanal, 03 quincenal, 04 mensual, 05 bimestral"},"meses":{"type":"string","pattern":"^\\d{2}$","description":"Mes (01–12) o bimestre SAT (13–18)"},"año":{"type":"integer","minimum":2022,"maximum":2100,"description":"Año del periodo"}},"required":["periodicidad","meses","año"],"additionalProperties":false,"description":"Solo para factura global a XAXX010101000 sin nombre"}},"required":["receptor","conceptos"],"additionalProperties":false}}}},"responses":{"201":{"description":"Factura timbrada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"202":{"description":"Timbrado sin confirmar (`status: pendiente`): verifica antes de reintentar","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"El PAC o el SAT rechazó el comprobante (`rechazo_sat`) o no se pudo timbrar (`no_timbrable`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"listarFacturas","summary":"Listar facturas","description":"Permiso requerido: `invoices:read`.\n\nMás recientes primero. Paginación por cursor.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Resultados por página (1–100, por defecto 50)"},"required":false,"description":"Resultados por página (1–100, por defecto 50)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Valor de nextCursor de la página anterior"},"required":false,"description":"Valor de nextCursor de la página anterior","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"Filtra por estado"},"required":false,"description":"Filtra por estado","name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)"},"required":false,"description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)","name":"desde","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)"},"required":false,"description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)","name":"hasta","in":"query"},{"schema":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC del receptor"},"required":false,"description":"RFC del receptor","name":"rfc","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Busca en nombre del receptor, folio o UUID"},"required":false,"description":"Busca en nombre del receptor, folio o UUID","name":"q","in":"query"}],"responses":{"200":{"description":"Una página de facturas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pásalo como ?cursor= para la siguiente página; null si no hay más"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}":{"get":{"operationId":"obtenerFactura","summary":"Ver una factura","description":"Permiso requerido: `invoices:read`.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"La factura con sus conceptos","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}/xml":{"get":{"operationId":"descargarXml","summary":"Descargar el XML timbrado","description":"Permiso requerido: `invoices:read`.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"XML del CFDI","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}/pdf":{"get":{"operationId":"descargarPdf","summary":"Descargar el PDF","description":"Permiso requerido: `invoices:read`.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"Representación impresa","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}/cancelar":{"post":{"operationId":"cancelarFactura","summary":"Cancelar ante el SAT","description":"Permiso requerido: `invoices:cancel`.\n\nSi el receptor debe aceptar, la factura sigue `timbrada` con `cancelacion.enProceso: true`.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"},{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"motivo":{"type":"string","enum":["01","02","03","04"],"description":"Motivo SAT: 01 con relación (requiere folioSustitucion), 02 sin relación, 03 no se realizó la operación, 04 operación nominativa en factura global"},"folioSustitucion":{"type":"string","format":"uuid","description":"UUID de la factura que sustituye (motivo 01)"}},"required":["motivo"],"additionalProperties":false}}}},"responses":{"200":{"description":"La factura cancelada o en proceso de cancelación","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"El PAC o el SAT rechazó el comprobante (`rechazo_sat`) o no se pudo timbrar (`no_timbrable`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}/enviar":{"post":{"operationId":"enviarFactura","summary":"Enviar por correo (PDF y XML)","description":"Permiso requerido: `invoices:write`.\n\nNo disponible en modo prueba.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"},{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Por defecto el correo de facturas del cliente"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Enviado","content":{"application/json":{"schema":{"type":"object","properties":{"enviado":{"type":"boolean","enum":[true]},"para":{"type":"string"}},"required":["enviado","para"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"502":{"description":"No se pudo enviar el correo (`error_envio`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/facturas/{id}/estatus-sat":{"get":{"operationId":"estatusSatFactura","summary":"Consultar el estatus en el SAT","description":"Permiso requerido: `invoices:read`.","tags":["Facturas"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"Estatus según el servicio de consulta del SAT","content":{"application/json":{"schema":{"type":"object","properties":{"disponible":{"type":"boolean","description":"false para facturas de prueba"},"estado":{"type":["string","null"],"description":"Vigente, Cancelado o No encontrado"},"esCancelable":{"type":["string","null"]},"estatusCancelacion":{"type":["string","null"]},"mensaje":{"type":"string"}},"required":["disponible","estado","esCancelable","estatusCancelacion"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/tickets":{"post":{"operationId":"crearTicket","summary":"Crear un ticket","description":"Permiso requerido: `tickets:write`.\n\nLos totales los calcula el servidor a partir de los conceptos.","tags":["Tickets"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Descripción del concepto (sin |)"},"claveProdServ":{"type":"string","pattern":"^\\d{8}$","default":"01010101","description":"Clave de producto o servicio SAT (8 dígitos); por defecto 01010101"},"claveUnidad":{"type":"string","pattern":"^[A-Z0-9]{1,3}$","default":"E48","description":"Clave de unidad SAT; por defecto E48"},"cantidad":{"type":"number","exclusiveMinimum":0,"default":1,"description":"Cantidad; por defecto 1"},"precio":{"type":"number","minimum":0,"description":"Valor unitario antes de impuestos"},"descuento":{"type":"number","minimum":0,"default":0,"description":"Descuento en pesos para la línea; por defecto 0"},"tasaIva":{"type":"string","enum":["16","8","0","exento"],"default":"16","description":"Tasa de IVA trasladado: 16, 8 (región fronteriza), 0 o exento"},"retIva":{"type":"string","enum":["10.6667","4"],"description":"IVA retenido (%): 10.6667 o 4"},"retIsr":{"type":"string","enum":["10","1.25","20"],"description":"ISR retenido (%): 10, 1.25 o 20"},"cuentaPredial":{"type":"string","maxLength":150,"pattern":"^\\d+(,\\d+)*$","description":"Número de cuenta predial; obligatorio en arrendamiento (claves 8013…)"},"noIdentificacion":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Número de identificación (SKU o folio del ticket)"}},"required":["descripcion","precio"],"additionalProperties":false},"minItems":1,"maxItems":500},"receptor":{"type":"object","properties":{"clienteId":{"type":"string","format":"uuid"},"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC (12 caracteres persona moral, 13 persona física)"},"nombre":{"type":"string","minLength":1,"maxLength":254,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"}},"additionalProperties":false,"description":"Opcional: cliente o RFC y nombre que verá el ticket"},"formaPago":{"type":"string","enum":["01","02","03","04","28","99"],"description":"Forma de pago SAT (c_FormaPago)"},"serie":{"type":"string","minLength":1,"maxLength":25,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"},"folio":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"},"fecha":{"type":"string","format":"date-time","description":"Fecha de venta ISO 8601; por defecto ahora"}},"required":["conceptos"],"additionalProperties":false}}}},"responses":{"201":{"description":"Ticket creado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["activo","cancelado","facturado"]},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":["object","null"],"properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":["string","null"]},"nombre":{"type":["string","null"]}},"required":["clienteId","rfc","nombre"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number","description":"Calculado por el servidor a partir de los conceptos"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false}},"facturaId":{"type":["string","null"],"format":"uuid","description":"Factura generada a partir del ticket"}},"required":["id","status","modo","serie","folio","fecha","receptor","formaPago","moneda","subtotal","descuento","total","conceptos","facturaId"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"listarTickets","summary":"Listar tickets","description":"Permiso requerido: `tickets:read`.","tags":["Tickets"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Resultados por página (1–100, por defecto 50)"},"required":false,"description":"Resultados por página (1–100, por defecto 50)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Valor de nextCursor de la página anterior"},"required":false,"description":"Valor de nextCursor de la página anterior","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["activo","cancelado","facturado"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)"},"required":false,"description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)","name":"desde","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)"},"required":false,"description":"Fecha AAAA-MM-DD (hora de la Ciudad de México)","name":"hasta","in":"query"}],"responses":{"200":{"description":"Una página de tickets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["activo","cancelado","facturado"]},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":["object","null"],"properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":["string","null"]},"nombre":{"type":["string","null"]}},"required":["clienteId","rfc","nombre"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number","description":"Calculado por el servidor a partir de los conceptos"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false}},"facturaId":{"type":["string","null"],"format":"uuid","description":"Factura generada a partir del ticket"}},"required":["id","status","modo","serie","folio","fecha","receptor","formaPago","moneda","subtotal","descuento","total","conceptos","facturaId"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pásalo como ?cursor= para la siguiente página; null si no hay más"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/tickets/{id}":{"get":{"operationId":"obtenerTicket","summary":"Ver un ticket","description":"Permiso requerido: `tickets:read`.","tags":["Tickets"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"El ticket","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["activo","cancelado","facturado"]},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":["object","null"],"properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":["string","null"]},"nombre":{"type":["string","null"]}},"required":["clienteId","rfc","nombre"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number","description":"Calculado por el servidor a partir de los conceptos"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false}},"facturaId":{"type":["string","null"],"format":"uuid","description":"Factura generada a partir del ticket"}},"required":["id","status","modo","serie","folio","fecha","receptor","formaPago","moneda","subtotal","descuento","total","conceptos","facturaId"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/tickets/{id}/cancelar":{"post":{"operationId":"cancelarTicket","summary":"Cancelar un ticket","description":"Permiso requerido: `tickets:write`.","tags":["Tickets"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"},{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Ticket cancelado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["activo","cancelado","facturado"]},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":["object","null"],"properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":["string","null"]},"nombre":{"type":["string","null"]}},"required":["clienteId","rfc","nombre"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number","description":"Calculado por el servidor a partir de los conceptos"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false}},"facturaId":{"type":["string","null"],"format":"uuid","description":"Factura generada a partir del ticket"}},"required":["id","status","modo","serie","folio","fecha","receptor","formaPago","moneda","subtotal","descuento","total","conceptos","facturaId"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/tickets/{id}/facturar":{"post":{"operationId":"facturarTicket","summary":"Facturar un ticket","description":"Permiso requerido: `invoices:write` y `tickets:write`.\n\nTimbra una factura con los conceptos del ticket; el ticket pasa a `facturado`.","tags":["Tickets"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"},{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receptor":{"type":"object","properties":{"clienteId":{"type":"string","format":"uuid","description":"Cliente existente"},"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC; si ya existe se usan sus datos guardados, si es nuevo se crea el cliente"},"nombre":{"type":"string","minLength":1,"maxLength":254,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Razón social (RFC nuevo) o nombre para XAXX010101000 individual"},"cp":{"type":"string","pattern":"^\\d{5}$","description":"Código postal (5 dígitos)"},"regimen":{"type":"string","pattern":"^\\d{3}$","description":"Régimen fiscal SAT (c_RegimenFiscal), p. ej. 601"},"usoCfdi":{"type":"string","enum":["G01","G02","G03","I01","I02","I03","I04","I08","D01","D04","S01","CP01"],"description":"Uso del CFDI (c_UsoCFDI)"}},"additionalProperties":false,"description":"Receptor de la factura"},"formaPago":{"type":"string","enum":["01","02","03","04","28","99"],"description":"Forma de pago SAT (c_FormaPago)"},"metodoPago":{"type":"string","enum":["PUE","PPD"],"description":"PUE: una exhibición; PPD: parcialidades o diferido"},"serie":{"type":"string","minLength":1,"maxLength":25,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"},"folio":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"}},"required":["receptor"],"additionalProperties":false}}}},"responses":{"201":{"description":"Factura timbrada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"202":{"description":"Timbrado sin confirmar (`status: pendiente`)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":["string","null"],"description":"Folio fiscal del SAT; null hasta que se timbra"},"status":{"type":"string","enum":["borrador","pendiente","timbrada","cancelada","error"],"description":"pendiente: no se pudo confirmar el timbrado, verifica antes de reintentar"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"serie":{"type":["string","null"]},"folio":{"type":["string","null"]},"fecha":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"},"receptor":{"type":"object","properties":{"clienteId":{"type":["string","null"],"format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"usoCfdi":{"type":"string"}},"required":["clienteId","rfc","nombre","usoCfdi"],"additionalProperties":false},"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"moneda":{"type":"string"},"subtotal":{"type":"number"},"descuento":{"type":"number"},"total":{"type":"number"},"error":{"type":["string","null"],"description":"Mensaje del PAC o del SAT cuando status es error o pendiente"},"xmlUrl":{"type":["string","null"],"format":"uri"},"pdfUrl":{"type":["string","null"],"format":"uri"},"conceptos":{"type":"array","items":{"type":"object","properties":{"descripcion":{"type":"string"},"claveProdServ":{"type":["string","null"]},"claveUnidad":{"type":["string","null"]},"cantidad":{"type":"number"},"precio":{"type":"number","description":"Valor unitario antes de impuestos"},"descuento":{"type":"number"},"tasaIva":{"type":"string","enum":["16","8","0","exento"]},"retIva":{"type":"string","description":"Tasa de IVA retenido (%)"},"retIsr":{"type":"string","description":"Tasa de ISR retenido (%)"},"cuentaPredial":{"type":"string"},"noIdentificacion":{"type":"string"}},"required":["descripcion","claveProdServ","claveUnidad","cantidad","precio","descuento","tasaIva"],"additionalProperties":false},"description":"Solo en el detalle y al crear"},"cancelacion":{"type":["object","null"],"properties":{"motivo":{"type":"string"},"fecha":{"type":"string"},"enProceso":{"type":"boolean","description":"El receptor debe aceptar la cancelación"}},"required":["motivo","fecha","enProceso"],"additionalProperties":false}},"required":["id","uuid","status","modo","serie","folio","fecha","receptor","formaPago","metodoPago","moneda","subtotal","descuento","total","error","xmlUrl","pdfUrl"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"El PAC o el SAT rechazó el comprobante (`rechazo_sat`) o no se pudo timbrar (`no_timbrable`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/clientes":{"get":{"operationId":"listarClientes","summary":"Listar clientes","description":"Permiso requerido: `clients:read`.","tags":["Clientes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Resultados por página (1–100, por defecto 50)"},"required":false,"description":"Resultados por página (1–100, por defecto 50)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Valor de nextCursor de la página anterior"},"required":false,"description":"Valor de nextCursor de la página anterior","name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC (12 caracteres persona moral, 13 persona física)"},"required":false,"description":"RFC (12 caracteres persona moral, 13 persona física)","name":"rfc","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Una página de clientes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"cp":{"type":["string","null"]},"regimen":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Correo al que se envían sus facturas"},"publicoEnGeneral":{"type":"boolean"},"editable":{"type":"boolean","description":"false si sus datos vienen de una constancia del SAT o es Público en General"},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","rfc","nombre","cp","regimen","email","publicoEnGeneral","editable","creadoEn"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pásalo como ?cursor= para la siguiente página; null si no hay más"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"crearCliente","summary":"Agregar un cliente","description":"Permiso requerido: `clients:write`.\n\nSi el RFC ya existe se usan sus datos guardados y responde 200.","tags":["Clientes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","description":"RFC (12 caracteres persona moral, 13 persona física)"},"nombre":{"type":"string","minLength":1,"maxLength":254,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Razón social (solo para un RFC nuevo)"},"cp":{"type":"string","pattern":"^\\d{5}$","description":"Código postal (5 dígitos)"},"regimen":{"type":"string","pattern":"^\\d{3}$","description":"Régimen fiscal SAT (c_RegimenFiscal), p. ej. 601"},"email":{"type":"string","maxLength":254,"format":"email","description":"Correo electrónico"}},"required":["rfc"],"additionalProperties":false}}}},"responses":{"200":{"description":"El RFC ya era cliente","content":{"application/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","description":"false si el RFC ya era cliente de tu organización"},"cliente":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"cp":{"type":["string","null"]},"regimen":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Correo al que se envían sus facturas"},"publicoEnGeneral":{"type":"boolean"},"editable":{"type":"boolean","description":"false si sus datos vienen de una constancia del SAT o es Público en General"},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","rfc","nombre","cp","regimen","email","publicoEnGeneral","editable","creadoEn"],"additionalProperties":false}},"required":["creado","cliente"],"additionalProperties":false}}}},"201":{"description":"Cliente nuevo","content":{"application/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","description":"false si el RFC ya era cliente de tu organización"},"cliente":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"cp":{"type":["string","null"]},"regimen":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Correo al que se envían sus facturas"},"publicoEnGeneral":{"type":"boolean"},"editable":{"type":"boolean","description":"false si sus datos vienen de una constancia del SAT o es Público en General"},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","rfc","nombre","cp","regimen","email","publicoEnGeneral","editable","creadoEn"],"additionalProperties":false}},"required":["creado","cliente"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/clientes/{id}":{"get":{"operationId":"obtenerCliente","summary":"Ver un cliente","description":"Permiso requerido: `clients:read`.","tags":["Clientes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"El cliente","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"cp":{"type":["string","null"]},"regimen":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Correo al que se envían sus facturas"},"publicoEnGeneral":{"type":"boolean"},"editable":{"type":"boolean","description":"false si sus datos vienen de una constancia del SAT o es Público en General"},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","rfc","nombre","cp","regimen","email","publicoEnGeneral","editable","creadoEn"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"operationId":"actualizarCliente","summary":"Actualizar un cliente","description":"Permiso requerido: `clients:write`.","tags":["Clientes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":["string","null"],"maxLength":254,"format":"email","description":"null para borrarlo"},"nombre":{"type":"string","minLength":1,"maxLength":254,"pattern":"^[^|\\x00-\\x1F\\x7F]*$"},"cp":{"type":"string","pattern":"^\\d{5}$","description":"Código postal (5 dígitos)"},"regimen":{"type":"string","pattern":"^\\d{3}$","description":"Régimen fiscal SAT (c_RegimenFiscal), p. ej. 601"}},"additionalProperties":false}}}},"responses":{"200":{"description":"El cliente actualizado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfc":{"type":"string"},"nombre":{"type":"string"},"cp":{"type":["string","null"]},"regimen":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Correo al que se envían sus facturas"},"publicoEnGeneral":{"type":"boolean"},"editable":{"type":"boolean","description":"false si sus datos vienen de una constancia del SAT o es Público en General"},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","rfc","nombre","cp","regimen","email","publicoEnGeneral","editable","creadoEn"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Conflicto de estado (`conflicto`) o de Idempotency-Key (`idempotency_conflict`, `idempotency_en_proceso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/productos":{"get":{"operationId":"listarProductos","summary":"Listar productos","description":"Permiso requerido: `products:read`.","tags":["Productos"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Resultados por página (1–100, por defecto 50)"},"required":false,"description":"Resultados por página (1–100, por defecto 50)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Valor de nextCursor de la página anterior"},"required":false,"description":"Valor de nextCursor de la página anterior","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Una página de productos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"descripcion":{"type":"string"},"nombre":{"type":["string","null"]},"claveProdServ":{"type":"string"},"claveUnidad":{"type":"string"},"precio":{"type":"number"},"sku":{"type":["string","null"]},"cuentaPredial":{"type":["string","null"]},"tasaIva":{"type":["string","null"]},"retIva":{"type":["string","null"]},"retIsr":{"type":["string","null"]},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","descripcion","nombre","claveProdServ","claveUnidad","precio","sku","cuentaPredial","tasaIva","retIva","retIsr","creadoEn"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pásalo como ?cursor= para la siguiente página; null si no hay más"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"crearProducto","summary":"Crear un producto","description":"Permiso requerido: `products:write`.","tags":["Productos"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h)."},"required":false,"description":"Recomendado en todo POST. 1 a 100 caracteres (letras, números, - _ : .). La misma clave con el mismo cuerpo devuelve la respuesta original sin repetir la operación (24 h).","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"descripcion":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Descripción que irá en la factura (sin |)"},"nombre":{"type":"string","maxLength":100,"description":"Nombre interno (no sale en la factura)"},"claveProdServ":{"type":"string","pattern":"^\\d{8}$","description":"Clave de producto o servicio SAT (8 dígitos)"},"claveUnidad":{"type":"string","pattern":"^[A-Z0-9]{1,3}$","description":"Clave de unidad SAT, p. ej. E48 o H87"},"precio":{"type":"number","minimum":0,"description":"Precio unitario antes de impuestos, máximo 2 decimales"},"sku":{"type":"string","maxLength":100,"description":"SKU o número de identificación interno"},"cuentaPredial":{"type":"string","maxLength":150,"pattern":"^\\d+(,\\d+)*$","description":"Número de cuenta predial (arrendamiento)"},"tasaIva":{"type":"string","enum":["16","8","0","exento"],"default":"16","description":"Tasa de IVA: 16, 8, 0 o exento; por defecto 16"},"retIva":{"type":"string","enum":["10.6667","4"],"description":"IVA retenido (%): 10.6667 o 4"},"retIsr":{"type":"string","enum":["10","1.25","20"],"description":"ISR retenido (%): 10, 1.25 o 20"}},"required":["descripcion","claveProdServ","claveUnidad","precio"],"additionalProperties":false}}}},"responses":{"201":{"description":"Producto creado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"descripcion":{"type":"string"},"nombre":{"type":["string","null"]},"claveProdServ":{"type":"string"},"claveUnidad":{"type":"string"},"precio":{"type":"number"},"sku":{"type":["string","null"]},"cuentaPredial":{"type":["string","null"]},"tasaIva":{"type":["string","null"]},"retIva":{"type":["string","null"]},"retIsr":{"type":["string","null"]},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","descripcion","nombre","claveProdServ","claveUnidad","precio","sku","cuentaPredial","tasaIva","retIva","retIsr","creadoEn"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/productos/{id}":{"get":{"operationId":"obtenerProducto","summary":"Ver un producto","description":"Permiso requerido: `products:read`.","tags":["Productos"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"200":{"description":"El producto","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"descripcion":{"type":"string"},"nombre":{"type":["string","null"]},"claveProdServ":{"type":"string"},"claveUnidad":{"type":"string"},"precio":{"type":"number"},"sku":{"type":["string","null"]},"cuentaPredial":{"type":["string","null"]},"tasaIva":{"type":["string","null"]},"retIva":{"type":["string","null"]},"retIsr":{"type":["string","null"]},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","descripcion","nombre","claveProdServ","claveUnidad","precio","sku","cuentaPredial","tasaIva","retIva","retIsr","creadoEn"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"operationId":"actualizarProducto","summary":"Actualizar un producto","description":"Permiso requerido: `products:write`.","tags":["Productos"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"descripcion":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"Descripción que irá en la factura (sin |)"},"nombre":{"type":"string","maxLength":100,"description":"Nombre interno (no sale en la factura)"},"claveProdServ":{"type":"string","pattern":"^\\d{8}$","description":"Clave de producto o servicio SAT (8 dígitos)"},"claveUnidad":{"type":"string","pattern":"^[A-Z0-9]{1,3}$","description":"Clave de unidad SAT, p. ej. E48 o H87"},"precio":{"type":"number","minimum":0,"description":"Precio unitario antes de impuestos, máximo 2 decimales"},"sku":{"type":"string","maxLength":100,"description":"SKU o número de identificación interno"},"cuentaPredial":{"type":"string","maxLength":150,"pattern":"^\\d+(,\\d+)*$","description":"Número de cuenta predial (arrendamiento)"},"tasaIva":{"type":"string","enum":["16","8","0","exento"],"description":"Tasa de IVA trasladado: 16, 8 (región fronteriza), 0 o exento"},"retIva":{"type":"string","enum":["10.6667","4"],"description":"IVA retenido (%): 10.6667 o 4"},"retIsr":{"type":"string","enum":["10","1.25","20"],"description":"ISR retenido (%): 10, 1.25 o 20"}},"additionalProperties":false}}}},"responses":{"200":{"description":"El producto actualizado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"descripcion":{"type":"string"},"nombre":{"type":["string","null"]},"claveProdServ":{"type":"string"},"claveUnidad":{"type":"string"},"precio":{"type":"number"},"sku":{"type":["string","null"]},"cuentaPredial":{"type":["string","null"]},"tasaIva":{"type":["string","null"]},"retIva":{"type":["string","null"]},"retIsr":{"type":["string","null"]},"creadoEn":{"type":"string","format":"date-time","description":"Fecha y hora ISO 8601 (UTC)"}},"required":["id","descripcion","nombre","claveProdServ","claveUnidad","precio","sku","cuentaPredial","tasaIva","retIva","retIsr","creadoEn"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"eliminarProducto","summary":"Eliminar un producto","description":"Permiso requerido: `products:write`.","tags":["Productos"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"ID del recurso"},"required":true,"description":"ID del recurso","name":"id","in":"path"}],"responses":{"204":{"description":"Eliminado"},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/organizacion":{"get":{"operationId":"obtenerOrganizacion","summary":"Ver los datos de la organización","description":"Permiso requerido: `settings:read`.\n\nRFC y regímenes del emisor y estado del CSD.","tags":["Organización"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"La organización","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nombre":{"type":"string"},"slug":{"type":"string"},"modo":{"type":"string","enum":["live","test"],"description":"live: producción; test: modo prueba (sandbox del PAC)"},"emisor":{"type":["object","null"],"properties":{"rfc":{"type":"string"},"razonSocial":{"type":"string"},"cp":{"type":["string","null"]},"regimenes":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descripcion":{"type":"string"}},"required":["codigo","descripcion"],"additionalProperties":false}}},"required":["rfc","razonSocial","cp","regimenes"],"additionalProperties":false},"csd":{"type":"object","properties":{"estado":{"type":"string","enum":["activo","vencido","sin_csd"]},"vigenteHasta":{"type":["string","null"]}},"required":["estado","vigenteHasta"],"additionalProperties":false},"emisorPrueba":{"type":"object","properties":{"rfc":{"type":"string"},"nombre":{"type":"string"},"regimenFiscal":{"type":"string"},"cp":{"type":"string"}},"required":["rfc","nombre","regimenFiscal","cp"],"additionalProperties":false,"description":"Solo con claves de prueba: el emisor con el que se timbra en el sandbox"}},"required":["id","nombre","slug","modo","emisor","csd"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/organizacion/preferencias":{"get":{"operationId":"obtenerPreferencias","summary":"Ver los valores por defecto de la API","description":"Permiso requerido: `settings:read`.","tags":["Organización"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preferencias","content":{"application/json":{"schema":{"type":"object","properties":{"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"usoCfdi":{"type":["string","null"]},"serie":{"type":["string","null"]}},"required":["formaPago","metodoPago","usoCfdi","serie"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"operationId":"actualizarPreferencias","summary":"Cambiar los valores por defecto de la API","description":"Permiso requerido: `settings:write`.\n\nSe usan cuando una factura no envía forma de pago, método de pago, uso del CFDI o serie.","tags":["Organización"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"formaPago":{"type":["string","null"],"enum":["01","02","03","04","28","99"],"description":"null para borrar el valor por defecto"},"metodoPago":{"type":["string","null"],"enum":["PUE","PPD"],"description":"null para borrar el valor por defecto"},"usoCfdi":{"type":["string","null"],"enum":["G01","G02","G03","I01","I02","I03","I04","I08","D01","D04","S01","CP01"],"description":"null para borrar el valor por defecto"},"serie":{"type":["string","null"],"minLength":1,"maxLength":25,"pattern":"^[^|\\x00-\\x1F\\x7F]*$","description":"null para borrar el valor por defecto"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Preferencias guardadas","content":{"application/json":{"schema":{"type":"object","properties":{"formaPago":{"type":["string","null"]},"metodoPago":{"type":["string","null"]},"usoCfdi":{"type":["string","null"]},"serie":{"type":["string","null"]}},"required":["formaPago","metodoPago","usoCfdi","serie"],"additionalProperties":false}}}},"400":{"description":"Datos inválidos (`validacion`). `field` dice qué campo revisar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"La credencial no tiene el permiso necesario (`sin_permiso`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/catalogos/{nombre}":{"get":{"operationId":"listarCatalogo","summary":"Consultar un catálogo SAT","description":"Cualquier credencial válida.","tags":["Catálogos SAT"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["regimenes","usos-cfdi","formas-pago","metodos-pago","claves-unidad"],"description":"Catálogo"},"required":true,"description":"Catálogo","name":"nombre","in":"path"}],"responses":{"200":{"description":"Claves y descripciones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"descripcion":{"type":"string"}},"required":["clave","descripcion"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Falta la clave o es inválida, está revocada o vencida (`no_autenticado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No existe, es de otra organización o de otro modo (`no_encontrado`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Demasiadas solicitudes (`rate_limit`). Espera los segundos de `Retry-After`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Error interno (`error_interno`). Reintenta con la misma Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estable, p. ej. validacion, sin_permiso, rechazo_sat"},"message":{"type":"string","description":"Mensaje en español para mostrar o registrar"},"field":{"type":"string","description":"Campo con el problema, p. ej. receptor.rfc"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}},"webhooks":{}}