{"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), REPs, cancellations, SAT catalogs."},"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"},"createdAt":{"type":"string"}},"required":["id","object","livemode","rfc","legalName","regimenFiscal","zip","serie","defaultClaveProdServ","defaultClaveUnidad","csd","logoUrl","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"]},"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":{"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}}},"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},"sku":{"type":"string","maxLength":100},"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}},"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},"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},"sku":{"type":"string","maxLength":100},"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}},"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"]},"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"]}},"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"}},"required":["object","livemode","balanceCentavos","currency","pricePerTimbreCentavos","timbresRemaining"]}}}},"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"}],"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)","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}/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.","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/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/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"}}}}},"webhooks":{}}