{"openapi":"3.0.3","info":{"title":"Faqturia External API","version":"2026.09.22-v1","description":"API externa de Faqturia (facturación electrónica CFDI 4.0). Autenticación por API key por organización: `X-API-Key: <key>` o `Authorization: Bearer <key>`.\n\nVersionado: el prefijo canónico es `/api/v1` (cabecera `X-Api-Version: 1` en toda respuesta). `/api/external/**` sigue disponible como alias sin versión con el mismo comportamiento; los cambios incompatibles se publicarán bajo un prefijo nuevo, nunca sobre `/api/v1`.\n\nCada operación exige uno de los scopes indicados en `x-scopes` (`read` cubre todas las lecturas y `write` todas las escrituras). Rate limit por key y minuto: `X-RateLimit-Limit/Remaining/Reset`, 429 con `Retry-After`.\n\nTodos los errores usan `{ \"error\": { \"code\", \"message\", \"request_id\", \"field\"?, \"issues\"? } }` con códigos estables. Toda respuesta lleva `X-Request-Id` (se respeta el enviado por el cliente si es `[A-Za-z0-9._-]{1,64}`). Las operaciones que crean CFDI aceptan `Idempotency-Key`.\n\nWebhooks: ver el esquema `WebhookPayload` y `GET /api/v1/webhooks` (`available_events`). Firma `X-Webhook-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<cuerpo>\")`, tolerancia 5 min, reintentos con backoff sobre el mismo `id` de evento.\n\nServidor MCP para asistentes de IA (misma API key y mismos scopes; 33 tools de lectura y 12 de escritura que ejecutan estas mismas operaciones con `idempotency_key`): `/api/mcp`. Especificación: `/api/v1/openapi` (alias `/api/openapi`)."},"servers":[{"url":"https://app.faqturia.com","description":"Producción"}],"tags":[{"name":"Organizacion"},{"name":"Facturas"},{"name":"Notas de credito"},{"name":"Complementos de pago"},{"name":"Nomina"},{"name":"Traslados"},{"name":"Clientes"},{"name":"Productos"},{"name":"Reportes"},{"name":"Webhooks"},{"name":"Catalogos SAT"}],"paths":{"/api/v1/organization":{"get":{"operationId":"getOrganization","tags":["Organizacion"],"summary":"La organización de la API key (\"quién soy\") y si puede timbrar","description":"Razón social, RFC, régimen, lugar de expedición, series con su folio siguiente y `pac_readiness`: si la organización puede timbrar en este entorno (credenciales de PAC cargadas y descifrables) y, si no, la causa y qué hacer. Consúltalo antes de integrar el timbrado: un `ready: false` explica de antemano el 503 PAC_NOT_CONFIGURED.","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"regimen_fiscal":{"type":"string","nullable":true},"lugar_expedicion":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"series":{"type":"array","items":{"type":"object","properties":{"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"descripcion":{"type":"string"},"serie":{"type":"string"},"folio_siguiente":{"type":"integer"},"is_active":{"type":"boolean"}}}},"pac":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"priority":{"type":"integer"}}},"description":"Cadena de proveedores configurada (pac_provider_configs); vacía = Facturapi por defecto"},"pac_readiness":{"type":"object","description":"Si la organización puede timbrar en ESTE entorno y, si no, por qué. Nunca incluye secretos.","properties":{"ready":{"type":"boolean"},"reason":{"type":"string","enum":["ok","missing_encryption_key","no_credentials","undecryptable_credentials"]},"environment":{"type":"string","enum":["production","sandbox"],"description":"Ambiente de timbrado de la organización (`organizations.pac_environment`): `production` emite CFDI con validez fiscal, `sandbox` contra el ambiente de pruebas del PAC. Decide qué credenciales se usan."},"encryption_key_configured":{"type":"boolean"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["facturapi","fiscalapi"]},"priority":{"type":"integer"},"source":{"type":"string","enum":["organization","environment","none"]},"has_credentials":{"type":"boolean"},"decryptable":{"type":"boolean","nullable":true},"detail":{"type":"string"}}}},"hint":{"type":"string","nullable":true}},"nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"ORGANIZATION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/invoices":{"get":{"operationId":"listInvoices","tags":["Facturas"],"summary":"Listar facturas de ingreso (CFDI I)","x-scopes":["read","invoices:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda difusa por folio, serie o fragmento de UUID"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"description":"Estado del CFDI"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo documentos de este cliente"},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión desde (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión hasta (YYYY-MM-DD, inclusive)"},{"name":"serie","in":"query","required":false,"schema":{"type":"string"},"description":"Serie exacta"},{"name":"folio","in":"query","required":false,"schema":{"type":"string"},"description":"Folio exacto"},{"name":"uuid","in":"query","required":false,"schema":{"type":"string"},"description":"UUID fiscal (búsqueda parcial, sin comodines)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["fecha_emision","total","folio","created_at"],"default":"fecha_emision"},"description":"Campo de orden"},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Dirección"},{"name":"metodo_pago","in":"query","required":false,"schema":{"type":"string","enum":["PUE","PPD"]},"description":"Método de pago"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"400":{"description":"Filtro inválido (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createInvoice","tags":["Facturas"],"summary":"Crear y timbrar una factura de ingreso","description":"Reserva el folio de la serie activa de forma atómica, timbra con el PAC configurado y responde 201 solo tras releer la fila persistida con UUID. `conceptos[].impuestos` acepta `true` (IVA 16 %), una tasa numérica o `{ traslados: [{ impuesto, tasa }], retenciones: [...] }`. `auto_stamp=false` no está soportado.","x-scopes":["invoices:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"conceptos":{"type":"array","items":{"type":"object","properties":{"cantidad":{"type":"number"},"descripcion":{"type":"string"},"precio_unitario":{"type":"number"},"valor_unitario":{"type":"number"},"clave_sat":{"type":"string"},"clave_prod_serv":{"type":"string"},"unidad":{"type":"string"},"clave_unidad":{"type":"string"},"descuento":{"type":"number"},"impuestos":{},"objeto_impuesto":{"type":"string"},"no_identificacion":{"type":"string"},"sku":{"type":"string"},"unidad_nombre":{"type":"string"}},"required":["cantidad","descripcion"],"additionalProperties":true},"minItems":1},"serie":{"type":"string","maxLength":10},"uso_cfdi":{"type":"string","pattern":"^[A-Z]\\d{2}$"},"forma_pago":{"type":"string","pattern":"^\\d{2}$"},"metodo_pago":{"type":"string","enum":["PUE","PPD"]},"moneda":{"type":"string","pattern":"^[A-Z]{3}$"},"tipo_cambio":{"type":"number","exclusiveMinimum":true,"minimum":0},"exportacion":{"type":"string","pattern":"^\\d{2}$"},"lugar_expedicion":{"type":"string","pattern":"^\\d{5}$"},"fecha_emision":{"type":"string"},"fecha_vencimiento":{"type":"string"},"notas":{"type":"string","maxLength":2000,"nullable":true},"auto_stamp":{"anyOf":[{"anyOf":[{"not":{}},{"type":"boolean","enum":[true]}]},{"anyOf":[{"not":{}},{"type":"boolean","enum":[false]}]}]}},"required":["client_id","conceptos"],"additionalProperties":false}}}},"responses":{"201":{"description":"CFDI persistido y verificado (timbrada o pendiente)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"stamped":{"type":"boolean"},"pending_sat_validation":{"type":"boolean","description":"true si el PAC aceptó pero el SAT aún valida (timbrado asíncrono)"},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR (con field/issues), SERIES_NOT_CONFIGURED, INVALID_STATUS, NOT_SUPPORTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"PLAN_LIMIT_EXCEEDED: el plan de la organización agotó sus facturas timbradas en producción; no se llamó al PAC. No se memoriza bajo Idempotency-Key: reintenta la misma petición tras mejorar el plan o comprar timbres","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cliente/empleado/documento relacionado no encontrado en tu organización (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó el documento (STAMP_REJECTED, con el mensaje del proveedor) o IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED: la organización no tiene credenciales de PAC utilizables en este entorno (ver GET /api/v1/organization → pac_readiness); no se memoriza, reintenta tras configurarlas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/invoices/{id}":{"get":{"operationId":"getInvoice","tags":["Facturas"],"summary":"Detalle de una factura (cliente y conceptos incluidos)","x-scopes":["read","invoices:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/invoices/{id}/cancel":{"delete":{"operationId":"cancelInvoice","tags":["Facturas"],"summary":"Cancelar un CFDI timbrado ante el SAT","description":"motivo 01 exige folio_sustitucion (UUID del CFDI que sustituye). Responde 200 solo cuando la fila quedó `cancelada`.","x-scopes":["invoices:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"motivo":{"type":"string","enum":["01","02","03","04"]},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"cancellation":{"type":"object","properties":{"motivo":{"type":"string"},"folio_sustitucion":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR o INVALID_STATUS (solo CFDI timbrados)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"ALREADY_CANCELLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó la cancelación (CANCELLATION_REJECTED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED (ver GET /api/v1/organization → pac_readiness)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/invoices/{id}/pdf":{"get":{"operationId":"getInvoicePdf","tags":["Facturas"],"summary":"URL firmada (1 h) del PDF","x-scopes":["read","invoices:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["own","pac"],"default":"own"},"description":"own = PDF con la plantilla de la organización; pac = el original del PAC"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"download_url":{"type":"string"},"expires_in":{"type":"integer","nullable":true},"source":{"type":"string"},"filename":{"type":"string"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND o PDF_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/invoices/{id}/xml":{"get":{"operationId":"getInvoiceXml","tags":["Facturas"],"summary":"URL firmada (1 h) del XML/CFDI","x-scopes":["read","invoices:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"download_url":{"type":"string"},"expires_in":{"type":"integer","nullable":true},"filename":{"type":"string"},"uuid":{"type":"string"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND o XML_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/credit-notes":{"get":{"operationId":"listCreditNotes","tags":["Notas de credito"],"summary":"Listar notas de crédito (CFDI E)","x-scopes":["read","credit-notes:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda difusa por folio, serie o fragmento de UUID"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"description":"Estado del CFDI"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo documentos de este cliente"},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión desde (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión hasta (YYYY-MM-DD, inclusive)"},{"name":"serie","in":"query","required":false,"schema":{"type":"string"},"description":"Serie exacta"},{"name":"folio","in":"query","required":false,"schema":{"type":"string"},"description":"Folio exacto"},{"name":"uuid","in":"query","required":false,"schema":{"type":"string"},"description":"UUID fiscal (búsqueda parcial, sin comodines)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["fecha_emision","total","folio","created_at"],"default":"fecha_emision"},"description":"Campo de orden"},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Dirección"},{"name":"original_invoice_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo notas que abonan a esta factura"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"400":{"description":"Filtro inválido (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createCreditNote","tags":["Notas de credito"],"summary":"Crear y timbrar una nota de crédito","description":"Relaciona (tipo 01) la factura de ingreso timbrada `original_invoice_id`, que debe pertenecer al mismo cliente.","x-scopes":["credit-notes:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"original_invoice_id":{"type":"string","format":"uuid"},"conceptos":{"type":"array","items":{"type":"object","properties":{"cantidad":{"type":"number"},"descripcion":{"type":"string"},"precio_unitario":{"type":"number"},"valor_unitario":{"type":"number"},"clave_sat":{"type":"string"},"clave_prod_serv":{"type":"string"},"unidad":{"type":"string"},"clave_unidad":{"type":"string"},"descuento":{"type":"number"},"impuestos":{},"objeto_impuesto":{"type":"string"},"no_identificacion":{"type":"string"},"sku":{"type":"string"},"unidad_nombre":{"type":"string"}},"required":["cantidad","descripcion"],"additionalProperties":true},"minItems":1},"uso_cfdi":{"type":"string","pattern":"^[A-Z]\\d{2}$"},"forma_pago":{"type":"string","pattern":"^\\d{2}$"},"metodo_pago":{"type":"string","enum":["PUE","PPD"]},"moneda":{"type":"string","pattern":"^[A-Z]{3}$"},"tipo_cambio":{"type":"number","exclusiveMinimum":true,"minimum":0},"lugar_expedicion":{"type":"string","pattern":"^\\d{5}$"},"fecha_emision":{"type":"string"},"notas":{"type":"string","maxLength":2000,"nullable":true},"auto_stamp":{"anyOf":[{"anyOf":[{"not":{}},{"type":"boolean","enum":[true]}]},{"anyOf":[{"not":{}},{"type":"boolean","enum":[false]}]}]}},"required":["client_id","original_invoice_id","conceptos"],"additionalProperties":false}}}},"responses":{"201":{"description":"CFDI persistido y verificado (timbrada o pendiente)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"stamped":{"type":"boolean"},"pending_sat_validation":{"type":"boolean","description":"true si el PAC aceptó pero el SAT aún valida (timbrado asíncrono)"},"original_invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string"},"serie":{"type":"string"},"folio":{"type":"string"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR (con field/issues), SERIES_NOT_CONFIGURED, INVALID_STATUS, NOT_SUPPORTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"PLAN_LIMIT_EXCEEDED: el plan de la organización agotó sus facturas timbradas en producción; no se llamó al PAC. No se memoriza bajo Idempotency-Key: reintenta la misma petición tras mejorar el plan o comprar timbres","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cliente/empleado/documento relacionado no encontrado en tu organización (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó el documento (STAMP_REJECTED, con el mensaje del proveedor) o IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED: la organización no tiene credenciales de PAC utilizables en este entorno (ver GET /api/v1/organization → pac_readiness); no se memoriza, reintenta tras configurarlas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/payment-complements":{"get":{"operationId":"listPaymentComplements","tags":["Complementos de pago"],"summary":"Listar complementos de pago (REP, CFDI P)","x-scopes":["read","payment-complements:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda difusa por folio, serie o fragmento de UUID"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"description":"Estado del CFDI"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo documentos de este cliente"},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión desde (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión hasta (YYYY-MM-DD, inclusive)"},{"name":"serie","in":"query","required":false,"schema":{"type":"string"},"description":"Serie exacta"},{"name":"folio","in":"query","required":false,"schema":{"type":"string"},"description":"Folio exacto"},{"name":"uuid","in":"query","required":false,"schema":{"type":"string"},"description":"UUID fiscal (búsqueda parcial, sin comodines)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["fecha_emision","total","folio","created_at"],"default":"fecha_emision"},"description":"Campo de orden"},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Dirección"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"400":{"description":"Filtro inválido (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createPaymentComplement","tags":["Complementos de pago"],"summary":"Crear y timbrar un complemento de pago (REP)","description":"Cada documento relacionado se resuelve contra tus facturas timbradas con saldo; `importe_pagado` no puede exceder el saldo. Tras timbrar se registra un pago por documento (monto_pagado/status de cada factura se actualizan).","x-scopes":["payment-complements:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"fecha_pago":{"type":"string"},"forma_pago":{"type":"string","pattern":"^\\d{2}$"},"moneda":{"type":"string","pattern":"^[A-Z]{3}$"},"tipo_cambio":{"type":"number","exclusiveMinimum":true,"minimum":0},"numero_operacion":{"type":"string","maxLength":100},"banco_ordenante":{"type":"string","maxLength":300},"cuenta_ordenante":{"type":"string","maxLength":50},"cuenta_beneficiario":{"type":"string","maxLength":50},"lugar_expedicion":{"type":"string","pattern":"^\\d{5}$"},"documentos_relacionados":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid"},"importe_pagado":{"type":"number","exclusiveMinimum":true,"minimum":0},"numero_parcialidad":{"type":"integer","minimum":1},"importe_saldo_anterior":{"type":"number","exclusiveMinimum":true,"minimum":0}},"required":["importe_pagado"],"additionalProperties":false},"minItems":1},"auto_stamp":{"anyOf":[{"anyOf":[{"not":{}},{"type":"boolean","enum":[true]}]},{"anyOf":[{"not":{}},{"type":"boolean","enum":[false]}]}]}},"required":["client_id","fecha_pago","documentos_relacionados"],"additionalProperties":false}}}},"responses":{"201":{"description":"CFDI persistido y verificado (timbrada o pendiente)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"stamped":{"type":"boolean"},"pending_sat_validation":{"type":"boolean","description":"true si el PAC aceptó pero el SAT aún valida (timbrado asíncrono)"},"related_documents":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"numero_parcialidad":{"type":"integer"},"importe_pagado":{"type":"number","description":"Importe en la moneda del documento"},"saldo_insoluto":{"type":"number","description":"Importe en la moneda del documento"}}}},"payments_recorded":{"type":"boolean"},"warning":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR (con field/issues), SERIES_NOT_CONFIGURED, INVALID_STATUS, NOT_SUPPORTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"PLAN_LIMIT_EXCEEDED: el plan de la organización agotó sus facturas timbradas en producción; no se llamó al PAC. No se memoriza bajo Idempotency-Key: reintenta la misma petición tras mejorar el plan o comprar timbres","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cliente/empleado/documento relacionado no encontrado en tu organización (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó el documento (STAMP_REJECTED, con el mensaje del proveedor) o IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED: la organización no tiene credenciales de PAC utilizables en este entorno (ver GET /api/v1/organization → pac_readiness); no se memoriza, reintenta tras configurarlas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/payroll":{"get":{"operationId":"listPayrollReceipts","tags":["Nomina"],"summary":"Listar recibos de nómina (CFDI N)","x-scopes":["read","payroll:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda difusa por folio, serie o fragmento de UUID"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"description":"Estado del CFDI"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo documentos de este cliente"},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión desde (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión hasta (YYYY-MM-DD, inclusive)"},{"name":"serie","in":"query","required":false,"schema":{"type":"string"},"description":"Serie exacta"},{"name":"folio","in":"query","required":false,"schema":{"type":"string"},"description":"Folio exacto"},{"name":"uuid","in":"query","required":false,"schema":{"type":"string"},"description":"UUID fiscal (búsqueda parcial, sin comodines)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["fecha_emision","total","folio","created_at"],"default":"fecha_emision"},"description":"Campo de orden"},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Dirección"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}}}}}}}},"400":{"description":"Filtro inválido (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createPayrollReceipt","tags":["Nomina"],"summary":"Crear y timbrar un recibo de nómina","description":"El empleado se lee de tu catálogo de empleados (`employee_id`); percepciones, deducciones y otros pagos con códigos SAT de 3 dígitos.","x-scopes":["payroll:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid"},"fecha_pago":{"type":"string"},"fecha_inicial_pago":{"type":"string"},"fecha_final_pago":{"type":"string"},"num_dias_pagados":{"type":"number","exclusiveMinimum":true,"minimum":0},"tipo_nomina":{"type":"string","enum":["O","E"]},"percepciones":{"type":"array","items":{"type":"object","properties":{"tipo_percepcion":{"type":"string","pattern":"^\\d{3}$"},"clave":{"type":"string","minLength":1,"maxLength":20},"concepto":{"type":"string","maxLength":200},"importe_gravado":{"type":"number","minimum":0},"importe_exento":{"type":"number","minimum":0}},"required":["tipo_percepcion","clave"],"additionalProperties":false},"minItems":1},"deducciones":{"type":"array","items":{"type":"object","properties":{"tipo_deduccion":{"type":"string","pattern":"^\\d{3}$"},"clave":{"type":"string","minLength":1,"maxLength":20},"concepto":{"type":"string","maxLength":200},"importe":{"type":"number","minimum":0}},"required":["tipo_deduccion","clave","importe"],"additionalProperties":false}},"otros_pagos":{"type":"array","items":{"type":"object","properties":{"tipo_otro_pago":{"type":"string","pattern":"^\\d{3}$"},"clave":{"type":"string","minLength":1,"maxLength":20},"concepto":{"type":"string","maxLength":200},"importe":{"type":"number","minimum":0},"subsidio_causado":{"type":"number","minimum":0}},"required":["tipo_otro_pago","clave","importe"],"additionalProperties":false}},"emisor":{"type":"object","properties":{"curp":{"type":"string"},"registro_patronal":{"type":"string"},"rfc_patron_origen":{"type":"string"}},"additionalProperties":false},"codigo_postal":{"type":"string","pattern":"^\\d{5}$"},"lugar_expedicion":{"type":"string","pattern":"^\\d{5}$"},"empleado":{"type":"object","additionalProperties":{}},"auto_stamp":{"anyOf":[{"anyOf":[{"not":{}},{"type":"boolean","enum":[true]}]},{"anyOf":[{"not":{}},{"type":"boolean","enum":[false]}]}]}},"required":["employee_id","fecha_pago","fecha_inicial_pago","fecha_final_pago","num_dias_pagados","percepciones"],"additionalProperties":false}}}},"responses":{"201":{"description":"CFDI persistido y verificado (timbrada o pendiente)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"stamped":{"type":"boolean"},"pending_sat_validation":{"type":"boolean","description":"true si el PAC aceptó pero el SAT aún valida (timbrado asíncrono)"},"employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"employee_number":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR (con field/issues), SERIES_NOT_CONFIGURED, INVALID_STATUS, NOT_SUPPORTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"PLAN_LIMIT_EXCEEDED: el plan de la organización agotó sus facturas timbradas en producción; no se llamó al PAC. No se memoriza bajo Idempotency-Key: reintenta la misma petición tras mejorar el plan o comprar timbres","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cliente/empleado/documento relacionado no encontrado en tu organización (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó el documento (STAMP_REJECTED, con el mensaje del proveedor) o IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED: la organización no tiene credenciales de PAC utilizables en este entorno (ver GET /api/v1/organization → pac_readiness); no se memoriza, reintenta tras configurarlas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/transfers":{"get":{"operationId":"listTransfers","tags":["Traslados"],"summary":"Listar CFDI de traslado / Carta Porte (CFDI T)","x-scopes":["read","transfers:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda difusa por folio, serie o fragmento de UUID"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"description":"Estado del CFDI"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Solo documentos de este cliente"},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión desde (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Fecha de emisión hasta (YYYY-MM-DD, inclusive)"},{"name":"serie","in":"query","required":false,"schema":{"type":"string"},"description":"Serie exacta"},{"name":"folio","in":"query","required":false,"schema":{"type":"string"},"description":"Folio exacto"},{"name":"uuid","in":"query","required":false,"schema":{"type":"string"},"description":"UUID fiscal (búsqueda parcial, sin comodines)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["fecha_emision","total","folio","created_at"],"default":"fecha_emision"},"description":"Campo de orden"},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Dirección"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}}}}}}}},"400":{"description":"Filtro inválido (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createTransfer","tags":["Traslados"],"summary":"Crear y timbrar un CFDI de traslado con Carta Porte","description":"Origen = domicilio fiscal de tu organización; Destino = el cliente `client_id`. Requiere distancia recorrida, mercancías con clave SAT y peso, y datos del autotransporte.","x-scopes":["transfers:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"fecha_traslado":{"type":"string"},"tipo_transporte":{"type":"string","enum":["01","02","03","04"]},"permiso_sct":{"type":"string","maxLength":20},"num_permiso_sct":{"type":"string","maxLength":50},"ubicaciones":{"type":"object","properties":{"origen":{"type":"object","properties":{"fecha_hora_salida_llegada":{"type":"string"},"distancia_recorrida":{"type":"number","exclusiveMinimum":true,"minimum":0},"rfc":{"type":"string"},"nombre":{"type":"string"}},"required":["fecha_hora_salida_llegada"],"additionalProperties":true},"destino":{"type":"object","properties":{"fecha_hora_salida_llegada":{"type":"string"},"rfc":{"type":"string"},"nombre":{"type":"string"}},"required":["fecha_hora_salida_llegada"],"additionalProperties":true}},"required":["origen","destino"],"additionalProperties":false},"distancia_recorrida":{"type":"number","exclusiveMinimum":true,"minimum":0},"mercancias":{"type":"array","items":{"type":"object","properties":{"clave_producto_servicio":{"type":"string","pattern":"^\\d{8}$"},"clave_sat":{"type":"string","pattern":"^\\d{8}$"},"clave_unidad":{"type":"string","minLength":1},"unidad":{"type":"string"},"descripcion":{"type":"string","minLength":1},"cantidad":{"type":"number","exclusiveMinimum":true,"minimum":0},"peso_kg":{"type":"number","exclusiveMinimum":true,"minimum":0},"valor_mercancia":{"type":"number","minimum":0},"moneda":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["clave_unidad","descripcion","cantidad","peso_kg"],"additionalProperties":true},"minItems":1},"figura_transporte":{},"autotransporte":{"type":"object","additionalProperties":{}},"auto_stamp":{"anyOf":[{"anyOf":[{"not":{}},{"type":"boolean","enum":[true]}]},{"anyOf":[{"not":{}},{"type":"boolean","enum":[false]}]}]}},"required":["client_id","fecha_traslado","ubicaciones","mercancias"],"additionalProperties":true}}}},"responses":{"201":{"description":"CFDI persistido y verificado (timbrada o pendiente)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"stamped":{"type":"boolean"},"pending_sat_validation":{"type":"boolean","description":"true si el PAC aceptó pero el SAT aún valida (timbrado asíncrono)"},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR (con field/issues), SERIES_NOT_CONFIGURED, INVALID_STATUS, NOT_SUPPORTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"PLAN_LIMIT_EXCEEDED: el plan de la organización agotó sus facturas timbradas en producción; no se llamó al PAC. No se memoriza bajo Idempotency-Key: reintenta la misma petición tras mejorar el plan o comprar timbres","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cliente/empleado/documento relacionado no encontrado en tu organización (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"El PAC/SAT rechazó el documento (STAMP_REJECTED, con el mensaje del proveedor) o IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"PAC_NOT_CONFIGURED: la organización no tiene credenciales de PAC utilizables en este entorno (ver GET /api/v1/organization → pac_readiness); no se memoriza, reintenta tras configurarlas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients":{"get":{"operationId":"listClients","tags":["Clientes"],"summary":"Listar clientes","x-scopes":["read","clients:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"RFC, razón social o email (difuso)"},{"name":"rfc","in":"query","required":false,"schema":{"type":"string"},"description":"RFC exacto"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"default":"all"},"description":"Filtro por activos"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/create":{"post":{"operationId":"createClient","tags":["Clientes"],"summary":"Crear un cliente (receptor)","x-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"razon_social":{"type":"string","minLength":1,"maxLength":300},"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"email":{"type":"string","format":"email","maxLength":200,"nullable":true},"telefono":{"type":"string","maxLength":30,"nullable":true},"regimen_fiscal":{"type":"string","pattern":"^\\d{3}$"},"uso_cfdi":{"type":"string","pattern":"^[A-Z]\\d{2}$"},"codigo_postal":{"type":"string","pattern":"^\\d{5}$"},"es_extranjero":{"type":"boolean"}},"required":["razon_social","rfc"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"DUPLICATE_RFC (details.existing_client_id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/{id}":{"get":{"operationId":"getClient","tags":["Clientes"],"summary":"Detalle de un cliente","x-scopes":["read","clients:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"direccion":{"type":"object","additionalProperties":true},"dias_vencimiento":{"type":"integer","nullable":true},"limite_credito":{"type":"number","nullable":true},"notas":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateClient","tags":["Clientes"],"summary":"Actualizar un cliente (parcial)","x-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"razon_social":{"type":"string","minLength":1,"maxLength":300},"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"email":{"type":"string","format":"email","maxLength":200,"nullable":true},"telefono":{"type":"string","maxLength":30,"nullable":true},"regimen_fiscal":{"type":"string","pattern":"^\\d{3}$"},"uso_cfdi":{"type":"string","pattern":"^[A-Z]\\d{2}$"},"codigo_postal":{"type":"string","pattern":"^\\d{5}$"},"is_active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deactivateClient","tags":["Clientes"],"summary":"Dar de baja un cliente (is_active = false)","x-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"ALREADY_INACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/products":{"get":{"operationId":"listProducts","tags":["Productos"],"summary":"Listar productos/servicios","x-scopes":["read","products:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Nombre, clave SAT o descripción"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","archived"],"default":"all"},"description":"Estado"},{"name":"sku","in":"query","required":false,"schema":{"type":"string"},"description":"SKU exacto de una variante"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createProduct","tags":["Productos"],"summary":"Crear un producto con su variante por defecto","x-scopes":["products:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":300},"descripcion":{"type":"string","maxLength":2000,"nullable":true},"clave_sat":{"type":"string","pattern":"^\\d{8}$"},"clave_unidad_sat":{"type":"string","minLength":1,"maxLength":5},"precio_unitario":{"type":"number","minimum":0},"tasa_iva":{"type":"number","minimum":0,"maximum":1},"ieps_tasa":{"type":"number","minimum":0,"maximum":1},"objeto_impuesto":{"type":"string","pattern":"^\\d{2}$"},"identificador_externo":{"type":"string","maxLength":60,"nullable":true},"peso_kg":{"type":"number","minimum":0,"nullable":true},"is_active":{"type":"boolean"}},"required":["nombre","clave_sat","precio_unitario"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_sat":{"type":"string"},"clave_unidad_sat":{"type":"string"},"nombre":{"type":"string"},"descripcion":{"type":"string","nullable":true},"identificador_externo":{"type":"string","nullable":true},"precio_unitario":{"type":"number","nullable":true},"iva_tasa":{"type":"number"},"ieps_tasa":{"type":"number"},"objeto_impuesto":{"type":"string"},"peso_kg":{"type":"number","nullable":true},"is_active":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"warning":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/products/{id}":{"get":{"operationId":"getProduct","tags":["Productos"],"summary":"Detalle de un producto","x-scopes":["read","products:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_sat":{"type":"string"},"clave_unidad_sat":{"type":"string"},"nombre":{"type":"string"},"descripcion":{"type":"string","nullable":true},"identificador_externo":{"type":"string","nullable":true},"precio_unitario":{"type":"number","nullable":true},"iva_tasa":{"type":"number"},"ieps_tasa":{"type":"number"},"objeto_impuesto":{"type":"string"},"peso_kg":{"type":"number","nullable":true},"is_active":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateProduct","tags":["Productos"],"summary":"Actualizar un producto (parcial); precio/SKU/peso van a la variante por defecto","x-scopes":["products:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":300},"descripcion":{"type":"string","maxLength":2000,"nullable":true},"clave_sat":{"type":"string","pattern":"^\\d{8}$"},"clave_unidad_sat":{"type":"string","minLength":1,"maxLength":5},"precio_unitario":{"type":"number","minimum":0},"tasa_iva":{"type":"number","minimum":0,"maximum":1},"iva_tasa":{"type":"number","minimum":0,"maximum":1},"ieps_tasa":{"type":"number","minimum":0,"maximum":1},"objeto_impuesto":{"type":"string","pattern":"^\\d{2}$"},"identificador_externo":{"type":"string","maxLength":60,"nullable":true},"peso_kg":{"type":"number","minimum":0,"nullable":true},"is_active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_sat":{"type":"string"},"clave_unidad_sat":{"type":"string"},"nombre":{"type":"string"},"descripcion":{"type":"string","nullable":true},"identificador_externo":{"type":"string","nullable":true},"precio_unitario":{"type":"number","nullable":true},"iva_tasa":{"type":"number"},"ieps_tasa":{"type":"number"},"objeto_impuesto":{"type":"string"},"peso_kg":{"type":"number","nullable":true},"is_active":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"archiveProduct","tags":["Productos"],"summary":"Archivar un producto","x-scopes":["products:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"status":{"type":"string"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"ALREADY_ARCHIVED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/sales":{"get":{"operationId":"getSalesReport","tags":["Reportes"],"summary":"Ventas agrupadas por cliente, producto, mes o día","x-scopes":["read","reports:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Desde"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Hasta"},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["client","product","month","date"],"default":"client"},"description":"Agrupación"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","additionalProperties":true},"summary":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/summary":{"get":{"operationId":"getSummaryReport","tags":["Reportes"],"summary":"Resumen del negocio en un periodo","x-scopes":["read","reports:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Desde"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Hasta"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/taxes":{"get":{"operationId":"getTaxesReport","tags":["Reportes"],"summary":"IVA/IEPS trasladados por mes, trimestre o año","x-scopes":["read","reports:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Desde"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Hasta"},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["month","quarter","year"],"default":"month"},"description":"Periodo"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"Listar suscripciones (sin secret) y eventos disponibles","x-scopes":["read","webhooks:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]}},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"has_secret":{"type":"boolean","description":"El secret nunca se devuelve"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true}}}},"available_events":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Crear una suscripción","x-scopes":["webhooks:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Clave única por operación. Misma clave + mismo cuerpo → se devuelve la respuesta original con `Idempotent-Replayed: true` sin repetir la operación; cuerpo distinto → 422 IDEMPOTENCY_KEY_REUSED; en curso → 409. Caduca a las 24 h."}],"requestBody":{"required":true,"description":"La URL debe ser http(s) pública (sin localhost ni redes privadas). El secret (≥16 caracteres) firma cada entrega.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2000},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]},"minItems":1},"secret":{"type":"string","minLength":16,"maxLength":200,"nullable":true},"description":{"type":"string","maxLength":300,"nullable":true},"is_active":{"type":"boolean"}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]}},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"has_secret":{"type":"boolean","description":"El secret nunca se devuelve"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/{id}":{"get":{"operationId":"getWebhook","tags":["Webhooks"],"summary":"Detalle de una suscripción","x-scopes":["read","webhooks:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]}},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"has_secret":{"type":"boolean","description":"El secret nunca se devuelve"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Actualizar una suscripción (parcial)","x-scopes":["webhooks:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2000},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]},"minItems":1},"secret":{"type":"string","minLength":16,"maxLength":200,"nullable":true},"description":{"type":"string","maxLength":300,"nullable":true},"is_active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]}},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"has_secret":{"type":"boolean","description":"El secret nunca se devuelve"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Eliminar una suscripción y sus logs","x-scopes":["webhooks:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/{id}/logs":{"get":{"operationId":"listWebhookLogs","tags":["Webhooks"],"summary":"Entregas de una suscripción","x-scopes":["read","webhooks:read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Por página"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","success","failed"]},"description":"Estado"},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"},"description":"Evento"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","success","failed"]},"http_status_code":{"type":"integer","nullable":true},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_retry_at":{"type":"string","format":"date-time","nullable":true},"error_message":{"type":"string","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"testWebhook","tags":["Webhooks"],"summary":"Enviar un evento webhook.test firmado y devolver el resultado","x-scopes":["webhooks:write"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id de Faqturia del recurso"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"delivery":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"http_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer"},"response_body":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/forma-pago":{"get":{"operationId":"getCatalogFormaPago","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_FormaPago","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"descripcion":{"type":"string"}}}},"total":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/metodo-pago":{"get":{"operationId":"getCatalogMetodoPago","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_MetodoPago","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"descripcion":{"type":"string"}}}},"total":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/regimen-fiscal":{"get":{"operationId":"getCatalogRegimenFiscal","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_RegimenFiscal","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"descripcion":{"type":"string"}}}},"total":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/uso-cfdi":{"get":{"operationId":"getCatalogUsoCfdi","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_UsoCFDI","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"descripcion":{"type":"string"}}}},"total":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/unidades":{"get":{"operationId":"getCatalogUnidades","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_ClaveUnidad","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Clave, nombre o descripción"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/catalogs/productos-servicios":{"get":{"operationId":"getCatalogProductosServicios","tags":["Catalogos SAT"],"summary":"Catálogo SAT c_ClaveProdServ (usar search y paginar)","x-scopes":["read"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Clave o descripción"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Página (empieza en 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Resultados por página"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"401":{"description":"API key ausente o inválida (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope insuficiente (FORBIDDEN_SCOPE) u origen no permitido (FORBIDDEN_ORIGIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit por minuto excedido (RATE_LIMITED); ver Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error interno (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer","description":"La misma API key como Bearer token"}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Código estable para ramificar: UNAUTHORIZED, FORBIDDEN_SCOPE, FORBIDDEN_ORIGIN, RATE_LIMITED, RATE_LIMITER_UNAVAILABLE, VALIDATION_ERROR, NOT_FOUND, INVALID_STATUS, DUPLICATE_RFC, ALREADY_INACTIVE, ALREADY_ARCHIVED, ALREADY_CANCELLED, SERIES_NOT_CONFIGURED, STAMP_REJECTED, STAMP_PERSIST_ERROR, CANCELLATION_REJECTED, CANCELLATION_PERSIST_ERROR, PAC_NOT_CONFIGURED (503: sin credenciales de PAC utilizables en este entorno; no se memoriza bajo Idempotency-Key, reintenta tras configurarlas), PLAN_LIMIT_EXCEEDED (402: el plan de la organización agotó sus facturas timbradas; no se memoriza bajo Idempotency-Key, reintenta tras mejorar el plan), NOT_SUPPORTED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_UNAVAILABLE, INTERNAL_ERROR"},"message":{"type":"string"},"field":{"type":"string","description":"Campo inválido en notación conceptos[0].cantidad (solo VALIDATION_ERROR)"},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}},"required_scopes":{"type":"array","items":{"type":"string"}},"request_id":{"type":"string","description":"Id de la petición (también en la cabecera X-Request-Id). Cítalo al reportar un error a soporte."}},"additionalProperties":true}}},"Organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"regimen_fiscal":{"type":"string","nullable":true},"lugar_expedicion":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"series":{"type":"array","items":{"type":"object","properties":{"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"descripcion":{"type":"string"},"serie":{"type":"string"},"folio_siguiente":{"type":"integer"},"is_active":{"type":"boolean"}}}},"pac":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"priority":{"type":"integer"}}},"description":"Cadena de proveedores configurada (pac_provider_configs); vacía = Facturapi por defecto"},"pac_readiness":{"type":"object","description":"Si la organización puede timbrar en ESTE entorno y, si no, por qué. Nunca incluye secretos.","properties":{"ready":{"type":"boolean"},"reason":{"type":"string","enum":["ok","missing_encryption_key","no_credentials","undecryptable_credentials"]},"environment":{"type":"string","enum":["production","sandbox"],"description":"Ambiente de timbrado de la organización (`organizations.pac_environment`): `production` emite CFDI con validez fiscal, `sandbox` contra el ambiente de pruebas del PAC. Decide qué credenciales se usan."},"encryption_key_configured":{"type":"boolean"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["facturapi","fiscalapi"]},"priority":{"type":"integer"},"source":{"type":"string","enum":["organization","environment","none"]},"has_credentials":{"type":"boolean"},"decryptable":{"type":"boolean","nullable":true},"detail":{"type":"string"}}}},"hint":{"type":"string","nullable":true}},"nullable":true}}},"PacReadiness":{"type":"object","description":"Si la organización puede timbrar en ESTE entorno y, si no, por qué. Nunca incluye secretos.","properties":{"ready":{"type":"boolean"},"reason":{"type":"string","enum":["ok","missing_encryption_key","no_credentials","undecryptable_credentials"]},"environment":{"type":"string","enum":["production","sandbox"],"description":"Ambiente de timbrado de la organización (`organizations.pac_environment`): `production` emite CFDI con validez fiscal, `sandbox` contra el ambiente de pruebas del PAC. Decide qué credenciales se usan."},"encryption_key_configured":{"type":"boolean"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["facturapi","fiscalapi"]},"priority":{"type":"integer"},"source":{"type":"string","enum":["organization","environment","none"]},"has_credentials":{"type":"boolean"},"decryptable":{"type":"boolean","nullable":true},"detail":{"type":"string"}}}},"hint":{"type":"string","nullable":true}}},"Cfdi":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}},"CfdiListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string"},"folio":{"type":"string"},"serie":{"type":"string"},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"moneda":{"type":"string"},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"uuid":{"type":"string","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"employee_id":{"type":"string","format":"uuid","nullable":true,"description":"Solo nómina"},"employee_name":{"type":"string","nullable":true,"description":"Solo nómina"}}},"Client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_sat":{"type":"string"},"clave_unidad_sat":{"type":"string"},"nombre":{"type":"string"},"descripcion":{"type":"string","nullable":true},"identificador_externo":{"type":"string","nullable":true},"precio_unitario":{"type":"number","nullable":true},"iva_tasa":{"type":"number"},"ieps_tasa":{"type":"number"},"objeto_impuesto":{"type":"string"},"peso_kg":{"type":"number","nullable":true},"is_active":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled"]}},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"has_secret":{"type":"boolean","description":"El secret nunca se devuelve"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true}}},"WebhookLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","success","failed"]},"http_status_code":{"type":"integer","nullable":true},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_retry_at":{"type":"string","format":"date-time","nullable":true},"error_message":{"type":"string","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WebhookPayload":{"type":"object","description":"Cuerpo de cada entrega de webhook. Firma en X-Webhook-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<cuerpo>\")","required":["id","event","api_version","created_at","organization_id","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Id del evento, estable entre reintentos: deduplica por él"},"event":{"type":"string","enum":["invoice.created","invoice.stamped","invoice.canceled","invoice.paid","invoice.partially_paid","credit_note.created","credit_note.stamped","credit_note.canceled","payment_complement.created","payment_complement.stamped","payment_complement.canceled","payroll.created","payroll.stamped","payroll.canceled","transfer.created","transfer.stamped","transfer.canceled","webhook.test"]},"api_version":{"type":"string","example":"2026-09-18"},"created_at":{"type":"string","format":"date-time"},"organization_id":{"type":"string","format":"uuid"},"data":{"type":"object","description":"CFDI en la forma que devuelven GET /invoices/:id, los demás detalles y los webhooks (data)","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"tipo_comprobante":{"type":"string","enum":["I","E","P","N","T"]},"serie":{"type":"string"},"folio":{"type":"string"},"uuid":{"type":"string","nullable":true,"description":"Folio fiscal (UUID del SAT)"},"status":{"type":"string","enum":["draft","pendiente","timbrada","parcialmente_pagada","pagada","cancelada"]},"fecha_emision":{"type":"string","format":"date-time"},"fecha_vencimiento":{"type":"string","format":"date-time","nullable":true},"client_id":{"type":"string","format":"uuid","nullable":true},"metodo_pago":{"type":"string"},"forma_pago":{"type":"string"},"uso_cfdi":{"type":"string"},"lugar_expedicion":{"type":"string"},"exportacion":{"type":"string"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"iva":{"type":"number","description":"Importe en la moneda del documento"},"ieps":{"type":"number","description":"Importe en la moneda del documento"},"retenciones":{"type":"number","description":"Importe en la moneda del documento"},"total":{"type":"number","description":"Importe en la moneda del documento"},"monto_pagado":{"type":"number","description":"Importe en la moneda del documento"},"xml_url":{"type":"string","nullable":true},"pdf_url":{"type":"string","nullable":true},"motivo_cancelacion":{"type":"string","nullable":true},"folio_sustitucion":{"type":"string","format":"uuid","nullable":true,"description":"UUID del CFDI que sustituyó al cancelado (motivo 01)"},"fecha_cancelacion":{"type":"string","format":"date-time","nullable":true},"original_invoice_id":{"type":"string","format":"uuid","nullable":true},"notas":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"razon_social":{"type":"string"},"rfc":{"type":"string"},"email":{"type":"string","nullable":true},"telefono":{"type":"string","nullable":true},"regimen_fiscal":{"type":"string","nullable":true},"uso_cfdi":{"type":"string","nullable":true},"codigo_postal":{"type":"string","nullable":true},"es_extranjero":{"type":"boolean"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"nullable":true},"conceptos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clave_prod_serv":{"type":"string"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"unidad":{"type":"string"},"valor_unitario":{"type":"number","description":"Importe en la moneda del documento"},"descuento":{"type":"number","description":"Importe en la moneda del documento"},"importe":{"type":"number","description":"Importe en la moneda del documento"},"impuestos":{"description":"JSON de impuestos tal como lo guardó el proveedor"},"objeto_impuesto":{"type":"string"}}}}}}}}}}}