{"openapi":"3.1.0","info":{"title":"CFDI Express API","version":"0.0.1","description":"Multi-tenant CFDI 4.0 invoicing API — stamping (PUE/PPD/global), credit notes, REPs, nómina (payroll) receipts, cancellations, SAT catalogs, signed webhooks."},"servers":[{"url":"https://api.cfdi.express"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key: sk_test_… or sk_live_…"}},"schemas":{"Merchant":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["merchant"]},"livemode":{"type":"boolean"},"rfc":{"type":"string"},"legalName":{"type":"string"},"regimenFiscal":{"type":"string"},"zip":{"type":"string"},"serie":{"type":"string"},"defaultClaveProdServ":{"type":["string","null"]},"defaultClaveUnidad":{"type":["string","null"]},"csd":{"$ref":"#/components/schemas/Csd"},"logoUrl":{"type":["string","null"],"description":"Presigned URL of the merchant logo (15 min TTL), null when no logo is uploaded"},"status":{"$ref":"#/components/schemas/MerchantStatus"},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","object","livemode","rfc","legalName","regimenFiscal","zip","serie","defaultClaveProdServ","defaultClaveUnidad","csd","logoUrl","status","archivedAt","createdAt"]},"Csd":{"type":["object","null"],"properties":{"object":{"type":"string","enum":["csd"]},"serialNumber":{"type":"string"},"rfc":{"type":"string"},"validFrom":{"type":"string"},"validTo":{"type":"string"},"status":{"type":"string","enum":["active","expired"]},"registeredWithPac":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["object","serialNumber","rfc","validFrom","validTo","status","registeredWithPac","updatedAt"]},"MerchantStatus":{"type":"string","enum":["active","archived"],"description":"archived merchants are hidden from the default list and cannot issue new invoices or credit notes; their existing documents stay readable and REPs/cancellations still work"},"MerchantCreate":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","example":"EKU9003173C9"},"legalName":{"type":"string","minLength":1,"maxLength":300,"description":"Razón social exactly as registered with SAT (no SA de CV suffix)","example":"ESCUELA KEMPER URGATE"},"regimenFiscal":{"type":"string","pattern":"^\\d{3}$","example":"601"},"zip":{"type":"string","pattern":"^\\d{5}$","description":"Lugar de expedición (CP)","example":"42501"},"serie":{"type":"string","minLength":1,"maxLength":10,"example":"A"},"defaultClaveProdServ":{"type":"string","pattern":"^\\d{8}$"},"defaultClaveUnidad":{"type":"string","minLength":1,"maxLength":5}},"required":["rfc","legalName","regimenFiscal","zip"]},"MerchantList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"MerchantUpdate":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$","example":"EKU9003173C9"},"legalName":{"type":"string","minLength":1,"maxLength":300,"description":"Razón social exactly as registered with SAT (no SA de CV suffix)","example":"ESCUELA KEMPER URGATE"},"regimenFiscal":{"type":"string","pattern":"^\\d{3}$","example":"601"},"zip":{"type":"string","pattern":"^\\d{5}$","description":"Lugar de expedición (CP)","example":"42501"},"serie":{"type":"string","minLength":1,"maxLength":10,"example":"A"},"defaultClaveProdServ":{"type":"string","pattern":"^\\d{8}$"},"defaultClaveUnidad":{"type":"string","minLength":1,"maxLength":5}},"description":"Any subset of the create fields. The RFC can only change while the merchant has no CSD — the certificate is bound to an RFC, so once one is uploaded the RFC is locked."},"CsdUpload":{"type":"object","properties":{"cer":{"type":"string","minLength":1,"description":"Base64 DER .cer file"},"key":{"type":"string","minLength":1,"description":"Base64 DER .key file (PKCS#8 encrypted)"},"password":{"type":"string","minLength":1,"description":"Private key password"}},"required":["cer","key","password"]},"LogoUpload":{"type":"object","properties":{"logo":{"type":"string","minLength":1,"description":"Base64 PNG/JPEG/WebP image, max 500 KB decoded"}},"required":["logo"]},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["invoice"]},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"kind":{"type":"string","enum":["nominal","global","credit_note"]},"uuid":{"type":["string","null"]},"serie":{"type":"string"},"folio":{"type":["number","null"]},"folioText":{"type":["string","null"]},"metodoPago":{"type":"string","enum":["PUE","PPD"]},"formaPago":{"type":"string"},"usoCfdi":{"type":"string"},"currency":{"type":"string"},"subtotal":{"type":"number"},"discount":{"type":"number"},"total":{"type":"number"},"saldoPendiente":{"type":["number","null"]},"tipoRelacion":{"type":"string","description":"Credit notes only: SAT c_TipoRelacion (01/03)"},"relatedUuid":{"type":"string","description":"Credit notes only: UUID of the related ingreso CFDI"},"relatedInvoiceId":{"type":["string","null"],"description":"Credit notes only: related invoice id when it lives in this API"},"receiver":{},"merchantId":{"type":"string"},"files":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","ready","failed"]}},"required":["status"]},"stampedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","object","livemode","status","kind","uuid","serie","folio","folioText","metodoPago","formaPago","usoCfdi","currency","subtotal","discount","total","saldoPendiente","merchantId","files","stampedAt","createdAt"]},"InvoiceCreate":{"type":"object","properties":{"merchantId":{"type":"string","minLength":1},"metodoPago":{"type":"string","enum":["PUE","PPD"],"default":"PUE"},"formaPago":{"type":"string","pattern":"^\\d{2,3}$"},"usoCfdi":{"type":"string","minLength":2,"maxLength":4},"folio":{"type":"string","pattern":"^[^|]{1,40}$","example":"#1001","description":"Optional display folio stamped on the CFDI (e.g. your order reference). The internal numeric folio is still assigned and remains the PAC reconciliation key."},"receiver":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"name":{"type":"string","minLength":1,"maxLength":300},"zip":{"type":"string","pattern":"^\\d{5}$"},"regimenFiscal":{"type":"string","pattern":"^\\d{3}$"}},"required":["rfc","name","zip","regimenFiscal"]},"items":{"type":"array","items":{"type":"object","properties":{"productCode":{"type":"string","pattern":"^\\d{8}$"},"unitCode":{"type":"string","minLength":1,"maxLength":5},"unit":{"type":"string","maxLength":20},"description":{"type":"string","minLength":1,"maxLength":1000},"noIdentificacion":{"type":"string","pattern":"^[^|]{1,100}$","example":"PN-4821-B","description":"Concepto NoIdentificacion (Anexo 20): part number, product identifier, SKU or equivalent. Printed verbatim on the PDF under the description. Max 100 characters, no '|'."},"pedimentos":{"type":"array","items":{"type":"string","pattern":"^\\s*(\\d{2})\\s*(\\d{2})\\s*(\\d{4})\\s*(\\d{7})\\s*$"},"minItems":1,"maxItems":100,"example":["25  47  3807  5001234"],"description":"Pedimento numbers for this concepto (Anexo 20 InformacionAduanera), for first-hand sales of imported goods. Each is 15 digits — year (2), aduana (2), patente (4), consecutivo (7) — with or without spaces; emitted in the SAT's 21-character form with two spaces between groups. One node per pedimento, duplicates dropped."},"quantity":{"type":"number","exclusiveMinimum":0},"unitPrice":{"type":"number","exclusiveMinimum":0},"taxable":{"type":"boolean"},"ivaRate":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[0.08]},{"type":"number","enum":[0.16]}]},"iepsRate":{"type":"number","minimum":0,"maximum":3,"description":"Transferred IEPS rate as a fraction (e.g. 0.265). IEPS is calculated before IVA and included in the IVA base."},"ivaRetRate":{"type":"number","minimum":0,"maximum":0.16,"description":"Retained (withheld) IVA rate as a fraction of the pre-tax line base, e.g. 0.04 for freight. 0.106667 represents two thirds of 16% IVA only when no IEPS enlarges the IVA base. Adds a Retención to the concepto and subtracts the amount from the invoice total. Unlike transferred taxes, retentions are never considered included in unitPrice."},"iepsRetRate":{"type":"number","minimum":0,"maximum":3,"description":"Retained (withheld) IEPS rate as a fraction. Adds a Retención to the concepto and subtracts the amount from the invoice total."},"isrRetRate":{"type":"number","minimum":0,"maximum":0.35,"description":"Retained (withheld) ISR rate as a fraction, e.g. 0.10 for honorarios/arrendamiento to personas morales or 0.0125 for RESICO. ISR is retention-only in CFDI — there is no transferred ISR. The amount is subtracted from the invoice total."},"sku":{"type":"string","maxLength":100,"deprecated":true,"description":"Deprecated — use noIdentificacion. Legacy alias for the concepto NoIdentificacion; ignored when noIdentificacion is present."}},"required":["productCode","unitCode","description","quantity","unitPrice"]},"minItems":1,"maxItems":500},"shipping":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"ivaRate":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[0.08]},{"type":"number","enum":[0.16]}]},"productCode":{"type":"string","pattern":"^\\d{8}$"},"unitCode":{"type":"string","minLength":1,"maxLength":5}},"required":["amount"]},"pricesIncludeTax":{"type":"boolean","default":true,"description":"Whether unitPrice already includes transferred taxes (IVA/IEPS traslados). Included prices are divided by (1 + iepsRate) * (1 + ivaRate). Retained taxes (ivaRetRate/iepsRetRate/isrRetRate) are never treated as included — they are computed on the derived base and subtracted from the total."},"cartDiscount":{"type":"number","minimum":0},"informacionGlobal":{"type":"object","properties":{"periodicidad":{"type":"string","enum":["01","02","03","04","05"],"description":"01 diario · 02 semanal · 03 quincenal · 04 mensual · 05 bimestral"},"meses":{"type":"string","pattern":"^(0[1-9]|1[0-8])$"},"anio":{"type":"integer","minimum":2022,"maximum":2100}},"required":["periodicidad","meses","anio"],"description":"Required (and only allowed) for global invoices — receptor XAXX010101000"}},"required":["merchantId","formaPago","usoCfdi","receiver","items"]},"CreditNoteCreate":{"type":"object","properties":{"merchantId":{"type":"string","minLength":1},"relatedInvoiceId":{"type":"string","minLength":1,"description":"Id of the stamped ingreso invoice (inv_…) this credit note relates to. Use this OR relatedUuid."},"relatedUuid":{"type":"string","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"SAT UUID of an ingreso CFDI stamped outside this API. Requires an explicit receiver."},"tipoRelacion":{"type":"string","enum":["01","03"],"default":"01","description":"SAT c_TipoRelacion: 01 nota de crédito de los documentos relacionados · 03 devolución de mercancía"},"usoCfdi":{"type":"string","minLength":2,"maxLength":4,"default":"G02"},"formaPago":{"type":"string","pattern":"^\\d{2,3}$","description":"How the refund is given (03 transferencia, 01 efectivo, …); 15 condonación or 99 when no money moves"},"folio":{"type":"string","pattern":"^[^|]{1,40}$","example":"RET-1001","description":"Optional display folio stamped on the CFDI (e.g. your return reference). The internal numeric folio is still assigned."},"receiver":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"name":{"type":"string","minLength":1,"maxLength":300},"zip":{"type":"string","pattern":"^\\d{5}$"},"regimenFiscal":{"type":"string","pattern":"^\\d{3}$"}},"required":["rfc","name","zip","regimenFiscal"],"description":"Defaults to the related invoice's receiver when relatedInvoiceId is used; required with relatedUuid"},"items":{"type":"array","items":{"type":"object","properties":{"productCode":{"type":"string","pattern":"^\\d{8}$"},"unitCode":{"type":"string","minLength":1,"maxLength":5},"unit":{"type":"string","maxLength":20},"description":{"type":"string","minLength":1,"maxLength":1000},"noIdentificacion":{"type":"string","pattern":"^[^|]{1,100}$","example":"PN-4821-B","description":"Concepto NoIdentificacion (Anexo 20): part number, product identifier, SKU or equivalent. Printed verbatim on the PDF under the description. Max 100 characters, no '|'."},"pedimentos":{"type":"array","items":{"type":"string","pattern":"^\\s*(\\d{2})\\s*(\\d{2})\\s*(\\d{4})\\s*(\\d{7})\\s*$"},"minItems":1,"maxItems":100,"example":["25  47  3807  5001234"],"description":"Pedimento numbers for this concepto (Anexo 20 InformacionAduanera), for first-hand sales of imported goods. Each is 15 digits — year (2), aduana (2), patente (4), consecutivo (7) — with or without spaces; emitted in the SAT's 21-character form with two spaces between groups. One node per pedimento, duplicates dropped."},"quantity":{"type":"number","exclusiveMinimum":0},"unitPrice":{"type":"number","exclusiveMinimum":0},"taxable":{"type":"boolean"},"ivaRate":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[0.08]},{"type":"number","enum":[0.16]}]},"iepsRate":{"type":"number","minimum":0,"maximum":3,"description":"Transferred IEPS rate as a fraction (e.g. 0.265). IEPS is calculated before IVA and included in the IVA base."},"ivaRetRate":{"type":"number","minimum":0,"maximum":0.16,"description":"Retained (withheld) IVA rate as a fraction of the pre-tax line base, e.g. 0.04 for freight. 0.106667 represents two thirds of 16% IVA only when no IEPS enlarges the IVA base. Adds a Retención to the concepto and subtracts the amount from the invoice total. Unlike transferred taxes, retentions are never considered included in unitPrice."},"iepsRetRate":{"type":"number","minimum":0,"maximum":3,"description":"Retained (withheld) IEPS rate as a fraction. Adds a Retención to the concepto and subtracts the amount from the invoice total."},"isrRetRate":{"type":"number","minimum":0,"maximum":0.35,"description":"Retained (withheld) ISR rate as a fraction, e.g. 0.10 for honorarios/arrendamiento to personas morales or 0.0125 for RESICO. ISR is retention-only in CFDI — there is no transferred ISR. The amount is subtracted from the invoice total."},"sku":{"type":"string","maxLength":100,"deprecated":true,"description":"Deprecated — use noIdentificacion. Legacy alias for the concepto NoIdentificacion; ignored when noIdentificacion is present."}},"required":["productCode","unitCode","description","quantity","unitPrice"]},"minItems":1,"maxItems":500,"description":"The returned goods, or one concept for the credited amount"},"pricesIncludeTax":{"type":"boolean","default":true}},"required":["merchantId","formaPago","items"]},"Payment":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment"]},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"invoiceId":{"type":"string"},"uuid":{"type":["string","null"]},"numParcialidad":{"type":"number"},"monto":{"type":"number"},"formaPago":{"type":"string"},"fechaPago":{"type":"string"},"saldoAnterior":{"type":"number"},"saldoInsoluto":{"type":"number"},"currency":{"type":"string"},"files":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","ready","failed"]}},"required":["status"]},"cancellation":{},"stampedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","object","livemode","status","invoiceId","uuid","numParcialidad","monto","formaPago","fechaPago","saldoAnterior","saldoInsoluto","currency","files","stampedAt","createdAt"]},"PaymentCreate":{"type":"object","properties":{"monto":{"type":"number","exclusiveMinimum":0},"formaPago":{"type":"string","pattern":"^\\d{2,3}$"},"fechaPago":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"},"numParcialidad":{"type":"integer","exclusiveMinimum":0,"description":"Auto-assigned when omitted; validated against the sequence when provided"}},"required":["monto","formaPago"]},"Nomina":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["nomina"]},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"merchantId":{"type":"string"},"uuid":{"type":["string","null"]},"serie":{"type":"string"},"folio":{"type":["number","null"]},"folioText":{"type":["string","null"]},"tipoNomina":{"type":"string","enum":["O","E"]},"fechaPago":{"type":"string"},"fechaInicialPago":{"type":"string"},"fechaFinalPago":{"type":"string"},"numDiasPagados":{"type":"number"},"employee":{"type":"object","properties":{"rfc":{"type":"string"},"nombre":{"type":"string"},"curp":{"type":"string"},"numEmpleado":{"type":"string"},"puesto":{"type":["string","null"]},"departamento":{"type":["string","null"]}},"required":["rfc","nombre","curp","numEmpleado","puesto","departamento"]},"percepciones":{"type":"array","items":{}},"deducciones":{"type":"array","items":{}},"otrosPagos":{"type":"array","items":{}},"incapacidades":{"type":"array","items":{}},"totalPercepciones":{"type":"number"},"totalDeducciones":{"type":"number"},"totalOtrosPagos":{"type":"number"},"subtotal":{"type":"number"},"discount":{"type":"number"},"total":{"type":"number","description":"Neto pagado al empleado"},"currency":{"type":"string"},"files":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","ready","failed"]},"xmlUrl":{"type":"string"},"pdfUrl":{"type":"string"},"zipUrl":{"type":"string"}},"required":["status"]},"cancellation":{},"stampedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","object","livemode","status","merchantId","uuid","serie","folio","folioText","tipoNomina","fechaPago","fechaInicialPago","fechaFinalPago","numDiasPagados","employee","percepciones","deducciones","otrosPagos","incapacidades","totalPercepciones","totalDeducciones","totalOtrosPagos","subtotal","discount","total","currency","files","stampedAt","createdAt"]},"NominaCreate":{"type":"object","properties":{"merchantId":{"type":"string","minLength":1},"folio":{"type":"string","pattern":"^[^|]{1,40}$","example":"2026-Q17-0042","description":"Optional display folio stamped on the CFDI (e.g. your payroll run + employee reference). The internal numeric folio is still assigned."},"tipoNomina":{"type":"string","enum":["O","E"],"default":"O","description":"O ordinaria (regular period) · E extraordinaria (aguinaldo, PTU, finiquito, …)"},"fechaPago":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the employee was paid"},"fechaInicialPago":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day of the pay period"},"fechaFinalPago":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day of the pay period"},"numDiasPagados":{"type":"number","minimum":0.001,"maximum":36160,"description":"Days paid in the period (up to 3 decimals)"},"registroPatronal":{"type":"string","pattern":"^[A-Z]\\d{10}$","description":"IMSS registro patronal (11 chars, e.g. B5510768108). Required for tipoContrato 01–08 and forbidden for 09/10/99 (NOM42/43)."},"rfcPatronOrigen":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"curpPatron":{"type":"string","pattern":"^[A-Z][AEIOUX][A-Z]{2}\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])[HM](AS|BC|BS|CC|CS|CH|CL|CM|DF|DG|GT|GR|HG|JC|MC|MN|MS|NT|NL|OC|PL|QT|QR|SP|SL|SR|TC|TS|TL|VZ|YN|ZS|NE)[B-DF-HJ-NP-TV-Z]{3}[0-9A-Z]\\d$","description":"Only when the issuing merchant is a persona física"},"entidadSNCF":{"type":"object","properties":{"origenRecurso":{"type":"string","enum":["IP","IF","IM"],"description":"IP ingresos propios · IF ingresos federales · IM mixtos"},"montoRecursoPropio":{"type":"number","minimum":0,"maximum":999999999999,"description":"Required when origenRecurso is IM"}},"required":["origenRecurso"],"description":"Only for entidades adheridas al Sistema Nacional de Coordinación Fiscal"},"employee":{"$ref":"#/components/schemas/NominaEmployee"},"percepciones":{"type":"array","items":{"type":"object","properties":{"tipoPercepcion":{"type":"string","pattern":"^\\d{3}$","description":"c_TipoPercepcion — 001 sueldos, 002 aguinaldo, 019 horas extra, 021 prima vacacional, …"},"clave":{"type":"string","minLength":3,"maxLength":15,"pattern":"^[^|]*$","description":"Employer's own concept code"},"concepto":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|]*$"},"importeGravado":{"type":"number","minimum":0,"maximum":999999999999},"importeExento":{"type":"number","minimum":0,"maximum":999999999999},"horasExtra":{"type":"array","items":{"type":"object","properties":{"dias":{"type":"integer","minimum":1},"tipoHoras":{"type":"string","pattern":"^\\d{2}$","description":"c_TipoHoras — 01 dobles, 02 triples, 03 simples"},"horasExtra":{"type":"integer","minimum":1},"importePagado":{"type":"number","minimum":0,"maximum":999999999999}},"required":["dias","tipoHoras","horasExtra","importePagado"]},"maxItems":50,"description":"Detail for tipoPercepcion 019"},"accionesOTitulos":{"type":"object","properties":{"valorMercado":{"type":"number","exclusiveMinimum":0},"precioAlOtorgarse":{"type":"number","exclusiveMinimum":0}},"required":["valorMercado","precioAlOtorgarse"]}},"required":["tipoPercepcion","clave","concepto","importeGravado","importeExento"]},"maxItems":500},"separacionIndemnizacion":{"type":"object","properties":{"totalPagado":{"type":"number","minimum":0,"maximum":999999999999},"numAniosServicio":{"type":"integer","minimum":0,"maximum":99},"ultimoSueldoMensOrd":{"type":"number","minimum":0,"maximum":999999999999},"ingresoAcumulable":{"type":"number","minimum":0,"maximum":999999999999},"ingresoNoAcumulable":{"type":"number","minimum":0,"maximum":999999999999}},"required":["totalPagado","numAniosServicio","ultimoSueldoMensOrd","ingresoAcumulable","ingresoNoAcumulable"],"description":"Required when percepciones include tipo 022, 023 or 025"},"jubilacionPensionRetiro":{"type":"object","properties":{"totalUnaExhibicion":{"type":"number","minimum":0,"maximum":999999999999,"description":"With percepción 039"},"totalParcialidad":{"type":"number","minimum":0,"maximum":999999999999,"description":"With percepción 044"},"montoDiario":{"type":"number","minimum":0,"maximum":999999999999,"description":"With percepción 044"},"ingresoAcumulable":{"type":"number","minimum":0,"maximum":999999999999},"ingresoNoAcumulable":{"type":"number","minimum":0,"maximum":999999999999}},"required":["ingresoAcumulable","ingresoNoAcumulable"],"description":"Required when percepciones include tipo 039 or 044"},"deducciones":{"type":"array","items":{"type":"object","properties":{"tipoDeduccion":{"type":"string","pattern":"^\\d{3}$","description":"c_TipoDeduccion — 001 seguridad social, 002 ISR, 004 otros, …"},"clave":{"type":"string","minLength":3,"maxLength":15,"pattern":"^[^|]*$"},"concepto":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|]*$"},"importe":{"type":"number","exclusiveMinimum":0,"maximum":999999999999,"description":"Must be > 0 (NOM96)"}},"required":["tipoDeduccion","clave","concepto","importe"]},"maxItems":500},"otrosPagos":{"type":"array","items":{"type":"object","properties":{"tipoOtroPago":{"type":"string","pattern":"^\\d{3}$","description":"c_TipoOtroPago — 002 subsidio para el empleo, 004 compensación saldos a favor, 999 otros, …"},"clave":{"type":"string","minLength":3,"maxLength":15,"pattern":"^[^|]*$"},"concepto":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|]*$"},"importe":{"type":"number","minimum":0,"maximum":999999999999},"subsidioAlEmpleo":{"type":"object","properties":{"subsidioCausado":{"type":"number","minimum":0,"maximum":999999999999}},"required":["subsidioCausado"],"description":"Required for tipoOtroPago 002"},"compensacionSaldosAFavor":{"type":"object","properties":{"saldoAFavor":{"type":"number","minimum":0,"maximum":999999999999},"anio":{"type":"integer","minimum":2016,"maximum":2100},"remanenteSalFav":{"type":"number","minimum":0,"maximum":999999999999}},"required":["saldoAFavor","anio","remanenteSalFav"],"description":"Required for tipoOtroPago 004"}},"required":["tipoOtroPago","clave","concepto","importe"]},"maxItems":100},"incapacidades":{"type":"array","items":{"type":"object","properties":{"diasIncapacidad":{"type":"integer","minimum":1},"tipoIncapacidad":{"type":"string","pattern":"^\\d{2}$","description":"c_TipoIncapacidad — 01 riesgo de trabajo, 02 enfermedad, 03 maternidad, 04 licencia hijos con cáncer"},"importeMonetario":{"type":"number","minimum":0,"maximum":999999999999}},"required":["diasIncapacidad","tipoIncapacidad"]},"maxItems":50}},"required":["merchantId","fechaPago","fechaInicialPago","fechaFinalPago","numDiasPagados","employee"]},"NominaEmployee":{"type":"object","properties":{"rfc":{"type":"string","pattern":"^[A-ZÑ&]{4}\\d{6}[A-Z0-9]{3}$"},"name":{"type":"string","minLength":1,"maxLength":300,"description":"Exactly as in the employee's Constancia de Situación Fiscal (uppercase, no accents)"},"zip":{"type":"string","pattern":"^\\d{5}$","description":"Employee's domicilio fiscal postal code"},"regimenFiscal":{"type":"string","enum":["605"],"default":"605","description":"Always 605 Sueldos y Salarios — the SAT rejects any other value on a nómina (NOM11)"},"curp":{"type":"string","pattern":"^[A-Z][AEIOUX][A-Z]{2}\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])[HM](AS|BC|BS|CC|CS|CH|CL|CM|DF|DG|GT|GR|HG|JC|MC|MN|MS|NT|NL|OC|PL|QT|QR|SP|SL|SR|TC|TS|TL|VZ|YN|ZS|NE)[B-DF-HJ-NP-TV-Z]{3}[0-9A-Z]\\d$"},"numSeguridadSocial":{"type":"string","pattern":"^\\d{11}$","description":"IMSS Número de Seguridad Social — 11 digits. Required together with registroPatronal (NOM44)."},"fechaInicioRelLaboral":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"antiguedad":{"type":"string","pattern":"^P(([1-9]\\d{0,3})|0)W$|^P([1-9]\\d?Y)?(([1-9]|1[012])M)?(0|[1-9]|[12]\\d|3[01])D$","description":"Seniority. Computed in weeks from fechaInicioRelLaboral to fechaFinalPago when omitted (e.g. P438W)."},"tipoContrato":{"type":"string","pattern":"^\\d{2}$","description":"c_TipoContrato — GET /v1/catalogs/nomina/tipo-contrato (01 indeterminado, …)"},"sindicalizado":{"type":"boolean"},"tipoJornada":{"type":"string","pattern":"^\\d{2}$","description":"c_TipoJornada (01 diurna, 02 nocturna, 03 mixta, …)"},"tipoRegimen":{"type":"string","pattern":"^\\d{2}$","description":"c_TipoRegimen — 02 sueldos, 03 jubilados, 09 asimilados honorarios, 11 asimilados otros, …"},"numEmpleado":{"type":"string","minLength":1,"maxLength":15,"pattern":"^[^|]*$","description":"Employer's employee number"},"departamento":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|]*$"},"puesto":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^|]*$"},"riesgoPuesto":{"type":"string","pattern":"^[1-5]$|^99$","description":"c_RiesgoPuesto IMSS class 1–5 (99 not applicable)"},"periodicidadPago":{"type":"string","pattern":"^\\d{2}$","description":"c_PeriodicidadPago — 01 diario, 02 semanal, 04 quincenal, 05 mensual, 99 otra, …"},"banco":{"type":"string","pattern":"^\\d{3}$","description":"c_Banco — required with a 10/11/16-digit cuentaBancaria, omitted with an 18-digit CLABE"},"cuentaBancaria":{"type":"string","pattern":"^(\\d{10}|\\d{11}|\\d{16}|\\d{18})$","description":"Bank account: 10, 11, 16 digits or 18-digit CLABE"},"salarioBaseCotApor":{"type":"number","minimum":0,"maximum":999999999999,"description":"Salario base de cotización (IMSS)"},"salarioDiarioIntegrado":{"type":"number","minimum":0,"maximum":999999999999},"claveEntFed":{"type":"string","pattern":"^[A-Z]{3}$","description":"c_Estado where the employee rendered the service (JAL, CMX, NLE, …)"},"subcontratacion":{"type":"array","items":{"type":"object","properties":{"rfcLabora":{"type":"string","pattern":"^[A-ZÑ&]{3,4}\\d{6}[A-Z0-9]{3}$"},"porcentajeTiempo":{"type":"number","minimum":0.001,"maximum":100}},"required":["rfcLabora","porcentajeTiempo"]},"maxItems":50}},"required":["rfc","name","zip","curp","tipoContrato","tipoRegimen","numEmpleado","periodicidadPago","claveEntFed"]},"CancelRequest":{"type":"object","properties":{"motivo":{"type":"string","enum":["01","02","03","04"],"description":"01 errores con relación (requires folioSustitucion) · 02 errores sin relación · 03 no se llevó a cabo · 04 operación nominativa relacionada a global"},"folioSustitucion":{"type":"string","format":"uuid"}},"required":["motivo"]},"WebhookEventTypeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/WebhookEventType"},"object":{"type":"string","enum":["invoice","payment","nomina"]},"description":{"type":"string"}},"required":["type","object","description"]}}},"required":["object","data"]},"WebhookEventType":{"type":"string","enum":["invoice.stamped","invoice.stamp_failed","invoice.cancelled","payment.stamped","payment.stamp_failed","payment.cancelled","nomina.stamped","nomina.stamp_failed","nomina.cancelled"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_endpoint"]},"livemode":{"type":"boolean"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"status":{"type":"string","enum":["enabled","disabled"]},"disabledReason":{"type":["string","null"],"enum":["user","consecutive_failures",null]},"consecutiveFailures":{"type":"integer"},"failingSince":{"type":["string","null"]},"secret":{"type":"string","description":"whsec_… signing secret — present ONLY in the create and rotate_secret responses. Store it; it cannot be retrieved again."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","object","livemode","url","description","events","status","disabledReason","consecutiveFailures","failingSince","createdAt","updatedAt"]},"WebhookEndpointCreate":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"HTTPS URL that receives the signed POST. http:// is accepted for test-mode endpoints only. Private/loopback hosts are refused.","example":"https://example.com/webhooks/cfdi"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"minItems":1,"maxItems":9,"description":"Event types this endpoint receives. Duplicates are collapsed."},"description":{"type":"string","maxLength":200,"example":"ERP producción"}},"required":["url","events"]},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"HTTPS URL that receives the signed POST. http:// is accepted for test-mode endpoints only. Private/loopback hosts are refused.","example":"https://example.com/webhooks/cfdi"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"minItems":1,"maxItems":9,"description":"Event types this endpoint receives. Duplicates are collapsed."},"description":{"type":["string","null"],"maxLength":200},"status":{"type":"string","enum":["enabled","disabled"],"description":"Re-enabling an endpoint that was auto-disabled after 72 h of failures resets its failure counters; pending deliveries resume."}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_delivery"]},"livemode":{"type":"boolean"},"endpointId":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"status":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"attempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"],"description":"When the next retry is due (pending deliveries only)."},"lastAttemptAt":{"type":["string","null"]},"lastStatusCode":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastDurationMs":{"type":["integer","null"]},"lastResponseBody":{"type":["string","null"],"description":"First 1 KB of the endpoint's last response."},"deliveredAt":{"type":["string","null"]},"createdAt":{"type":"string"},"event":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["event"]},"type":{"type":"string"},"livemode":{"type":"boolean"},"created":{"type":"integer"},"data":{"type":"object","additionalProperties":{}}},"required":["id","object","type","livemode","created","data"],"description":"The event body as sent (file URLs are presigned per attempt, so they are omitted here). Detail responses only."}},"required":["id","object","livemode","endpointId","eventId","eventType","status","attempts","nextAttemptAt","lastAttemptAt","lastStatusCode","lastError","lastDurationMs","lastResponseBody","deliveredAt","createdAt"]},"WebhookDeliveryStatus":{"type":"string","enum":["pending","succeeded","failed"]},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Meta"],"summary":"Liveness probe","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}}}}},"/ready":{"get":{"tags":["Meta"],"summary":"Readiness probe (DB + Redis)","responses":{"200":{"description":"Dependencies reachable","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready"]},"db":{"type":"boolean"},"redis":{"type":"boolean"}},"required":["status","db","redis"]}}}},"503":{"description":"A dependency is unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["degraded"]},"db":{"type":"boolean"},"redis":{"type":"boolean"}},"required":["status","db","redis"]}}}}}}},"/v1/balance":{"get":{"tags":["Billing"],"summary":"Current prepaid balance","security":[{"apiKey":[]}],"responses":{"200":{"description":"Prepaid saldo for the authenticated account + mode","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["balance"]},"livemode":{"type":"boolean"},"balanceCentavos":{"type":"integer"},"currency":{"type":"string","enum":["MXN"]},"pricePerTimbreCentavos":{"type":"integer"},"timbresRemaining":{"type":"integer"},"autoRecharge":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholdCentavos":{"type":["integer","null"]},"amountCentavos":{"type":["integer","null"]},"paused":{"type":"boolean"},"lastError":{"type":["string","null"]}},"required":["enabled","thresholdCentavos","amountCentavos","paused","lastError"]}},"required":["object","livemode","balanceCentavos","currency","pricePerTimbreCentavos","timbresRemaining","autoRecharge"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/billing/checkout_sessions":{"post":{"tags":["Billing"],"summary":"Create a Stripe Checkout session to top up saldo","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCentavos":{"type":"integer","minimum":10000,"maximum":5000000}},"required":["amountCentavos"]}}}},"responses":{"201":{"description":"Hosted Checkout session created — redirect the buyer to `url`","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["checkout_session"]},"url":{"type":"string"},"purchaseId":{"type":"string"},"checkoutSessionId":{"type":"string"},"amountCentavos":{"type":"integer"},"currency":{"type":"string","enum":["MXN"]}},"required":["object","url","purchaseId","checkoutSessionId","amountCentavos","currency"]}}}},"503":{"description":"Billing not configured"}}}},"/v1/billing/portal_sessions":{"post":{"tags":["Billing"],"summary":"Create a Stripe Billing Portal session (receipts, payment methods)","security":[{"apiKey":[]}],"responses":{"201":{"description":"Portal session created — redirect the user to `url`","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["portal_session"]},"url":{"type":"string"}},"required":["object","url"]}}}},"503":{"description":"Billing not configured"}}}},"/v1/billing/usage":{"get":{"tags":["Billing"],"summary":"Monthly usage (timbres stamped + centavos spent)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":24,"default":12},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Usage per month, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["usage_month"]},"month":{"type":"string"},"livemode":{"type":"boolean"},"timbres":{"type":"integer"},"spentCentavos":{"type":"integer"}},"required":["object","month","livemode","timbres","spentCentavos"]}}},"required":["object","data"]}}}}}}},"/v1/billing/transactions":{"get":{"tags":["Billing"],"summary":"List balance transactions (the credit ledger)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string","enum":["purchase","consume","refund","recharge","adjustment","seed"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Ledger entries, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["transaction"]},"livemode":{"type":"boolean"},"type":{"type":"string","enum":["purchase","consume","refund","recharge","adjustment","seed"]},"deltaCentavos":{"type":"integer"},"balanceAfterCentavos":{"type":"integer"},"referenceType":{"type":["string","null"]},"referenceId":{"type":["string","null"]},"note":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","object","livemode","type","deltaCentavos","balanceAfterCentavos","referenceType","referenceId","note","createdAt"]}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]}}}}}}},"/v1/merchants":{"post":{"tags":["Merchants"],"summary":"Create a merchant (emisor)","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCreate"}}}},"responses":{"201":{"description":"Merchant created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"description":"Validation error"}}},"get":{"tags":["Merchants"],"summary":"List merchants","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string","enum":["active","archived","all"],"default":"active","description":"Which merchants to return. Defaults to active only; archived ones are hidden unless asked for."},"required":false,"description":"Which merchants to return. Defaults to active only; archived ones are hidden unless asked for.","name":"status","in":"query"}],"responses":{"200":{"description":"Merchant list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantList"}}}}}}},"/v1/merchants/{id}":{"get":{"tags":["Merchants"],"summary":"Retrieve a merchant (includes CSD metadata/vigencia)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"Not found"}}},"patch":{"tags":["Merchants"],"summary":"Update a merchant","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdate"}}}},"responses":{"200":{"description":"Merchant updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"Not found"}}},"delete":{"tags":["Merchants"],"summary":"Delete a merchant (soft)","description":"Removes the merchant from every list and lookup; not reversible through the API. To hide an old merchant while keeping it retrievable, archive it instead. Deletion is API-only — the dashboard exposes archive.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Merchant deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["merchant"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]}}}},"404":{"description":"Not found"}}}},"/v1/merchants/{id}/archive":{"post":{"tags":["Merchants"],"summary":"Archive a merchant","description":"Hides the merchant from the default list and blocks new invoices/credit notes from it. Existing documents stay readable and REPs/cancellations on them still work. Reversible; idempotent.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"Not found"}}}},"/v1/merchants/{id}/unarchive":{"post":{"tags":["Merchants"],"summary":"Restore an archived merchant","description":"Makes an archived merchant active again. Idempotent.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"Not found"}}}},"/v1/merchants/{id}/csd":{"post":{"tags":["Merchants"],"summary":"Upload a merchant CSD","description":"Validates locally (vigencia, cer/key correspondence, password, CSD-vs-FIEL), encrypts at rest, registers with the PAC.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CsdUpload"}}}},"responses":{"201":{"description":"CSD stored and registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Csd"}}}},"400":{"description":"Validation error (subcode identifies the CSD problem)"},"404":{"description":"Not found"},"503":{"description":"PAC unavailable"}}},"put":{"tags":["Merchants"],"summary":"Replace a merchant CSD","description":"Validates locally (vigencia, cer/key correspondence, password, CSD-vs-FIEL), encrypts at rest, registers with the PAC.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CsdUpload"}}}},"responses":{"200":{"description":"CSD stored and registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Csd"}}}},"400":{"description":"Validation error (subcode identifies the CSD problem)"},"404":{"description":"Not found"},"503":{"description":"PAC unavailable"}}},"get":{"tags":["Merchants"],"summary":"CSD metadata (vigencia)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"CSD metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Csd"}}}},"404":{"description":"Merchant or CSD not found"}}}},"/v1/merchants/{id}/logo":{"put":{"tags":["Merchants"],"summary":"Upload or replace the merchant logo","description":"Optional PNG/JPEG/WebP image shown in the header of rendered invoice PDFs. Without a logo the PDF shows only the razón social.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoUpload"}}}},"responses":{"200":{"description":"Logo stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"description":"Not a PNG/JPEG/WebP image, or over 500 KB"},"404":{"description":"Not found"}}},"delete":{"tags":["Merchants"],"summary":"Remove the merchant logo","description":"PDFs rendered afterwards show only the razón social.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Logo removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"Not found"}}}},"/v1/invoices":{"post":{"tags":["Invoices"],"summary":"Stamp an income invoice (CFDI 4.0)","description":"Queue-mediated synchronous stamping: waits up to 20 s for the SAT UUID (201); degrades to 202 under extreme load. Requires an Idempotency-Key header. Items support transferred IVA/IEPS (ivaRate/iepsRate) and retained ISR/IVA/IEPS (isrRetRate/ivaRetRate/iepsRetRate); retained amounts are subtracted from the total. Use items[].noIdentificacion for the concepto NoIdentificacion (part number, product id, SKU); items[].sku is a deprecated alias. Use items[].pedimentos for imported goods' pedimento numbers (InformacionAduanera).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key per logical request (e.g. your order id). Replayed responses carry Idempotency-Replayed: true."},"required":true,"description":"Unique key per logical request (e.g. your order id). Replayed responses carry Idempotency-Replayed: true.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Stamped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"202":{"description":"Still stamping (extreme load) — poll GET /v1/invoices/{id}"},"400":{"description":"Validation error"},"402":{"description":"Insufficient credits / monthly cap"},"409":{"description":"Same Idempotency-Key currently in flight"},"422":{"description":"SAT rejection or idempotency key reuse"},"503":{"description":"PAC unavailable"}}},"get":{"tags":["Invoices"],"summary":"List invoices","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"merchantId","in":"query"},{"schema":{"type":"string","enum":["nominal","global","credit_note"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"uuid","in":"query"},{"schema":{"type":"string","enum":["PUE","PPD"]},"required":false,"name":"metodoPago","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdFrom","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdTo","in":"query"}],"responses":{"200":{"description":"Invoice list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]}}}}}}},"/v1/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"description":"Not found"}}}},"/v1/credit_notes":{"post":{"tags":["Credit notes"],"summary":"Stamp a credit note (CFDI 4.0 egreso) for a return or refund","description":"Same queue-mediated synchronous stamping as invoices: waits up to 20 s for the SAT UUID (201); degrades to 202 under extreme load. The credit note is an invoice resource with kind=credit_note — retrieve it via GET /v1/invoices/{id} and list with GET /v1/invoices?kind=credit_note. Requires an Idempotency-Key header.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key per logical request (e.g. your return id). Replayed responses carry Idempotency-Replayed: true."},"required":true,"description":"Unique key per logical request (e.g. your return id). Replayed responses carry Idempotency-Replayed: true.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNoteCreate"}}}},"responses":{"201":{"description":"Stamped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"202":{"description":"Still stamping (extreme load) — poll GET /v1/invoices/{id}"},"400":{"description":"Validation error"},"402":{"description":"Insufficient credits / monthly cap"},"404":{"description":"Merchant or related invoice not found"},"409":{"description":"Same Idempotency-Key currently in flight"},"422":{"description":"SAT rejection or idempotency key reuse"},"503":{"description":"PAC unavailable"}}}},"/v1/invoices/{id}/payments":{"post":{"tags":["Payments (REP)"],"summary":"Stamp a payment complement (REP 2.0) against a PPD invoice","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCreate"}}}},"responses":{"201":{"description":"REP stamped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"202":{"description":"Still stamping — poll GET /v1/payments/{id}"},"400":{"description":"Validation error (overpay, sequencing, non-PPD, …)"},"402":{"description":"Insufficient credits"},"404":{"description":"Invoice not found"},"422":{"description":"SAT rejection / idempotency reuse"}}}},"/v1/payments/{id}":{"get":{"tags":["Payments (REP)"],"summary":"Retrieve a payment complement","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Not found"}}}},"/v1/payments":{"get":{"tags":["Payments (REP)"],"summary":"List payment complements","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"merchantId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"invoiceId","in":"query"},{"schema":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"uuid","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdFrom","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdTo","in":"query"}],"responses":{"200":{"description":"Payment list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]}}}}}}},"/v1/nominas":{"post":{"tags":["Nómina"],"summary":"Stamp a payroll receipt (CFDI 4.0 nómina + complemento Nómina 1.2)","description":"One receipt per employee per pay period. Send the detail rows — percepciones, deducciones, otros pagos, incapacidades — and the employee's data; the API derives every SAT total (TotalPercepciones, TotalGravado/Exento, TotalDeducciones, ISR retenido, SubTotal, Descuento, Total) and fixes the Comprobante values the SAT mandates (TipoDeComprobante N, PUE, no FormaPago, UsoCFDI CN01, concepto 84111505). Same queue-mediated synchronous stamping as invoices: waits up to 20 s for the SAT UUID (201); degrades to 202 under extreme load. Requires an Idempotency-Key header.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key per logical request (e.g. payroll run + employee id). Replayed responses carry Idempotency-Replayed: true."},"required":true,"description":"Unique key per logical request (e.g. payroll run + employee id). Replayed responses carry Idempotency-Replayed: true.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NominaCreate"}}}},"responses":{"201":{"description":"Stamped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nomina"}}}},"202":{"description":"Still stamping (extreme load) — poll GET /v1/nominas/{id}"},"400":{"description":"Validation error (SAT cross-field rules, unknown catalog claves, …)"},"402":{"description":"Insufficient credits / monthly cap"},"404":{"description":"Merchant not found"},"409":{"description":"Same Idempotency-Key currently in flight"},"422":{"description":"SAT rejection or idempotency key reuse"},"503":{"description":"PAC unavailable"}}},"get":{"tags":["Nómina"],"summary":"List payroll receipts","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"merchantId","in":"query"},{"schema":{"type":"string","enum":["stamping","stamped","stamp_failed","cancel_pending","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"uuid","in":"query"},{"schema":{"type":"string","pattern":"^[A-ZÑ&]{4}\\d{6}[A-Z0-9]{3}$","description":"Filter to one employee"},"required":false,"description":"Filter to one employee","name":"employeeRfc","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Pay date on or after (YYYY-MM-DD)"},"required":false,"description":"Pay date on or after (YYYY-MM-DD)","name":"fechaPagoFrom","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Pay date on or before (YYYY-MM-DD)"},"required":false,"description":"Pay date on or before (YYYY-MM-DD)","name":"fechaPagoTo","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdFrom","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdTo","in":"query"}],"responses":{"200":{"description":"Nómina list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Nomina"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]}}}}}}},"/v1/nominas/{id}":{"get":{"tags":["Nómina"],"summary":"Retrieve a payroll receipt","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Nómina","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nomina"}}}},"404":{"description":"Not found"}}}},"/v1/invoices/{id}/cancel":{"post":{"tags":["Invoices"],"summary":"Cancel a stamped invoice before SAT","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"}}}},"responses":{"202":{"description":"Cancellation processed — status + acuse on the resource"},"400":{"description":"Validation error"},"402":{"description":"Insufficient credits"},"404":{"description":"Not found"},"422":{"description":"SAT rejected the cancellation"},"503":{"description":"PAC unavailable"}}}},"/v1/payments/{id}/cancel":{"post":{"tags":["Payments (REP)"],"summary":"Cancel a stamped payment complement before SAT","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"}}}},"responses":{"202":{"description":"Cancellation processed — status + acuse on the resource"},"400":{"description":"Validation error"},"402":{"description":"Insufficient credits"},"404":{"description":"Not found"},"422":{"description":"SAT rejected the cancellation"},"503":{"description":"PAC unavailable"}}}},"/v1/nominas/{id}/cancel":{"post":{"tags":["Nómina"],"summary":"Cancel a stamped nómina receipt before SAT","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"}}}},"responses":{"202":{"description":"Cancellation processed — status + acuse on the resource"},"400":{"description":"Validation error"},"402":{"description":"Insufficient credits"},"404":{"description":"Not found"},"422":{"description":"SAT rejected the cancellation"},"503":{"description":"PAC unavailable"}}}},"/v1/catalogs/products":{"get":{"tags":["Catalogs"],"summary":"Search SAT product/service claves (c_ClaveProdServ)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search SAT product/service claves (c_ClaveProdServ)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"}},"required":["clave","nombre"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/catalogs/units":{"get":{"tags":["Catalogs"],"summary":"Search SAT unit claves (c_ClaveUnidad)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search SAT unit claves (c_ClaveUnidad)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"},"simbolo":{"type":["string","null"]}},"required":["clave","nombre","simbolo"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/catalogs/usos-cfdi":{"get":{"tags":["Catalogs"],"summary":"SAT usos de CFDI (c_UsoCFDI)","security":[{"apiKey":[]}],"responses":{"200":{"description":"SAT usos de CFDI (c_UsoCFDI)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"},"fisica":{"type":"boolean"},"moral":{"type":"boolean"}},"required":["clave","nombre","fisica","moral"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/catalogs/regimenes":{"get":{"tags":["Catalogs"],"summary":"SAT regímenes fiscales (c_RegimenFiscal)","security":[{"apiKey":[]}],"responses":{"200":{"description":"SAT regímenes fiscales (c_RegimenFiscal)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"},"fisica":{"type":"boolean"},"moral":{"type":"boolean"}},"required":["clave","nombre","fisica","moral"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/catalogs/formas-pago":{"get":{"tags":["Catalogs"],"summary":"SAT formas de pago (c_FormaPago)","security":[{"apiKey":[]}],"responses":{"200":{"description":"SAT formas de pago (c_FormaPago)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"}},"required":["clave","nombre"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/catalogs/nomina/{catalog}":{"get":{"tags":["Catalogs"],"summary":"SAT Nómina 1.2 catalogs (c_TipoPercepcion, c_TipoDeduccion, c_TipoContrato, c_Banco, …)","description":"One catalog per call: tipo-nomina (c_TipoNomina) · tipo-contrato (c_TipoContrato) · tipo-jornada (c_TipoJornada) · tipo-regimen (c_TipoRegimen) · periodicidad-pago (c_PeriodicidadPago) · riesgo-puesto (c_RiesgoPuesto) · tipo-percepcion (c_TipoPercepcion) · tipo-deduccion (c_TipoDeduccion) · tipo-otro-pago (c_TipoOtroPago) · tipo-incapacidad (c_TipoIncapacidad) · tipo-horas (c_TipoHoras) · origen-recurso (c_OrigenRecurso) · estado (c_Estado (entidades federativas de México)) · banco (c_Banco). Optional ?keyword= filters by clave or nombre.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["tipo-nomina","tipo-contrato","tipo-jornada","tipo-regimen","periodicidad-pago","riesgo-puesto","tipo-percepcion","tipo-deduccion","tipo-otro-pago","tipo-incapacidad","tipo-horas","origen-recurso","estado","banco"]},"required":true,"name":"catalog","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Catalog entries","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"clave":{"type":"string"},"nombre":{"type":"string"}},"required":["clave","nombre"]}}},"required":["object","data"]}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/webhook_event_types":{"get":{"tags":["Webhooks"],"summary":"List the event types an endpoint can subscribe to","security":[{"apiKey":[]}],"responses":{"200":{"description":"Event type catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventTypeList"}}}}}}},"/v1/webhook_endpoints":{"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Registers a URL to receive signed POSTs for the selected events. The response carries the `whsec_…` signing secret exactly once — verify every delivery's `CFDI-Signature` with it (see the webhooks guide).","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Endpoint created (secret included)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Validation error (invalid URL, unknown event, too many endpoints)"}}},"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"}],"responses":{"200":{"description":"Endpoint list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}}}}},"/v1/webhook_endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a webhook endpoint","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"description":"Not found"}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Change the URL, the subscribed events, the description, or enable/disable deliveries.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"Endpoint updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Validation error"},"404":{"description":"Not found"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Stops all deliveries immediately (pending retries included). The delivery log stays readable by id.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_endpoint"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]}}}},"404":{"description":"Not found"}}}},"/v1/webhook_endpoints/{id}/rotate_secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret","description":"Issues a new `whsec_…` secret (returned once). Deliveries are signed with BOTH the new and the previous secret for 24 hours, so you can roll your verifier over without dropping events.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint with the new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"description":"Not found"}}}},"/v1/webhook_endpoints/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test event","description":"Delivers a `webhook_endpoint.test` event to this endpoint right now (single attempt, 10 s timeout) and returns the recorded delivery — status code, latency and the first KB of your response. Works on disabled endpoints too.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Test delivery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"404":{"description":"Not found"}}}},"/v1/webhook_endpoints/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List deliveries of an endpoint","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Delivery list (newest first)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"404":{"description":"Not found"}}}},"/v1/webhook_deliveries/{id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a delivery (includes the event body)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"404":{"description":"Not found"}}}},"/v1/webhook_deliveries/{id}/retry":{"post":{"tags":["Webhooks"],"summary":"Replay a delivery","description":"Re-queues a failed (or pending) delivery for immediate attempt with a fresh retry budget. Succeeded deliveries can be replayed too — your handler must be idempotent on `CFDI-Delivery` / event id anyway.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Delivery re-queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"Endpoint deleted or disabled"},"404":{"description":"Not found"}}}}},"webhooks":{}}