{"openapi":"3.0.3","info":{"title":"API de facturaci\u00f3n","version":"1.0.0","description":"Emite y consulta CFDI 4.0. Autenticaci\u00f3n con llave: `Authorization: Bearer fk_\u2026`.\n\n**Idempotencia:** env\u00eda `referencia` \u00fanica por operaci\u00f3n; repetirla devuelve el comprobante existente (`duplicado: true`).\n\n**Pruebas:** un emisor en modo pruebas no consume timbres ni tiene validez fiscal.\n\n**Errores:** 401 llave inv\u00e1lida \u00b7 402 sin timbres \u00b7 403 cuenta suspendida \u00b7 404 no existe \u00b7 409 estado no permitido \u00b7 422 datos inv\u00e1lidos \u00b7 429 l\u00edmite (120\/min)."},"servers":[{"url":"https:\/\/pruebas.facturas.xmlsync.com\/api\/v1"}],"security":[{"bearerAuth":[]}],"paths":{"\/emisores":{"get":{"summary":"Emisores de tu cuenta","responses":{"200":{"description":"Lista","content":{"application\/json":{"schema":{"type":"object","properties":{"emisores":{"type":"array","items":{"$ref":"#\/components\/schemas\/Emisor"}}}}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/productos":{"get":{"summary":"Cat\u00e1logo de productos y servicios de un emisor","parameters":[{"name":"emisor","in":"query","required":true,"schema":{"type":"string"},"description":"RFC del emisor"}],"responses":{"200":{"description":"Productos activos del emisor (clave SAT, unidad, descripci\u00f3n, precio, IVA y retenciones)"},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/facturas":{"post":{"summary":"Emitir factura de ingreso","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FacturaIn"}}}},"responses":{"201":{"description":"Timbrada","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"202":{"description":"En proceso o incierto: consulta el estatus antes de reintentar","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"200":{"description":"Duplicado: ya exist\u00eda con esa referencia","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/pagos":{"post":{"summary":"Emitir complemento de pago (REP 2.0)","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PagoIn"}}}},"responses":{"201":{"description":"Timbrado","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes":{"get":{"summary":"Listar comprobantes","parameters":[{"name":"referencia","in":"query","schema":{"type":"string"}},{"name":"estatus","in":"query","schema":{"type":"string","enum":["timbrado","error","incierto","cancelado","cancelando","enviando"]}},{"name":"uuid","in":"query","schema":{"type":"string"}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["I","P","E"]}}],"responses":{"200":{"description":"Lista"}}}},"\/comprobantes\/{id}":{"get":{"summary":"Consultar un comprobante","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Comprobante","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes\/{id}\/xml":{"get":{"summary":"Descargar XML timbrado","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"XML","content":{"application\/xml":{"schema":{"type":"string"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes\/{id}\/pdf":{"get":{"summary":"Descargar PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PDF","content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes\/{id}\/notas":{"post":{"summary":"Emitir nota de cr\u00e9dito sobre una factura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["forma_pago","tipo_relacion","conceptos"],"properties":{"referencia":{"type":"string"},"forma_pago":{"type":"string","example":"03"},"tipo_relacion":{"type":"string","enum":["01","03"]},"conceptos":{"type":"array","items":{"$ref":"#\/components\/schemas\/Concepto"}}}}}}},"responses":{"201":{"description":"Timbrada","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes\/{id}\/cancelar":{"post":{"summary":"Solicitar cancelaci\u00f3n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["motivo"],"properties":{"motivo":{"type":"string","enum":["01","02","03","04"]},"sustituto":{"type":"string","description":"UUID que lo sustituye (obligatorio con motivo 01)"}}}}}},"responses":{"200":{"description":"Estatus actualizado","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/comprobantes\/{id}\/reintentar":{"post":{"summary":"Reintentar un comprobante con estatus error","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resultado","content":{"application\/json":{"schema":{"type":"object","properties":{"comprobante":{"$ref":"#\/components\/schemas\/Comprobante"}}}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"mensaje":{"type":"string"},"errores":{"type":"object"}}},"Emisor":{"type":"object","properties":{"rfc":{"type":"string"},"razon_social":{"type":"string"},"regimen_fiscal":{"type":"string"},"cp_expedicion":{"type":"string"},"listo_para_timbrar":{"type":"boolean"},"entorno":{"type":"string","enum":["pruebas","produccion"]},"serie":{"type":"string"},"siguiente_folio":{"type":"integer"}}},"Concepto":{"type":"object","required":["clave_prod_serv","clave_unidad","descripcion","cantidad","valor_unitario","iva"],"properties":{"clave_prod_serv":{"type":"string","example":"84111506"},"clave_unidad":{"type":"string","example":"E48"},"descripcion":{"type":"string"},"cantidad":{"type":"number"},"valor_unitario":{"type":"number"},"iva":{"type":"string","enum":["16","0","exento","no"]},"retencion_isr":{"type":"number","description":"Porcentaje de ISR retenido (0\u201335), p. ej. 10 o 1.25. No aplica a \u00abno objeto\u00bb. Si se omite y el cliente (mismo RFC) tiene retenci\u00f3n por defecto en la plataforma, se aplica esa; si se manda (incluso 0), manda este valor.","nullable":true},"retencion_iva":{"type":"number","description":"Porcentaje de IVA retenido (0\u201316), p. ej. 10.666667. Solo con IVA 16 %.","nullable":true}}},"Cliente":{"type":"object","required":["rfc"],"properties":{"rfc":{"type":"string"},"razon_social":{"type":"string"},"cp":{"type":"string"},"regimen_fiscal":{"type":"string"},"uso_cfdi":{"type":"string","example":"G03"},"email":{"type":"string"}}},"FacturaIn":{"type":"object","required":["emisor","forma_pago","metodo_pago","cliente","conceptos"],"properties":{"emisor":{"type":"string","description":"RFC del emisor"},"referencia":{"type":"string","description":"Identificador \u00fanico de tu operaci\u00f3n (idempotencia)"},"forma_pago":{"type":"string","example":"03"},"metodo_pago":{"type":"string","enum":["PUE","PPD"]},"moneda":{"type":"string","enum":["MXN","USD"],"default":"MXN"},"tipo_cambio":{"type":"number","description":"Obligatorio con USD: pesos por d\u00f3lar del d\u00eda (el SAT lo valida contra el DOF)."},"cliente":{"$ref":"#\/components\/schemas\/Cliente"},"global":{"type":"object","description":"Solo con p\u00fablico en general (XAXX010101000)","properties":{"periodicidad":{"type":"string"},"meses":{"type":"string"},"anio":{"type":"string"}}},"conceptos":{"type":"array","items":{"$ref":"#\/components\/schemas\/Concepto"}}}},"PagoIn":{"type":"object","required":["emisor","fecha_pago","forma_pago","cliente","doctos"],"properties":{"emisor":{"type":"string"},"referencia":{"type":"string"},"fecha_pago":{"type":"string","format":"date"},"forma_pago":{"type":"string"},"num_operacion":{"type":"string"},"cliente":{"$ref":"#\/components\/schemas\/Cliente"},"doctos":{"type":"array","items":{"type":"object","required":["uuid","parcialidad","saldo_anterior","importe_pagado","objeto_imp"],"properties":{"uuid":{"type":"string"},"serie":{"type":"string"},"folio":{"type":"string"},"parcialidad":{"type":"integer"},"saldo_anterior":{"type":"number"},"importe_pagado":{"type":"number"},"objeto_imp":{"type":"string","enum":["01","02"]}}}}}},"Comprobante":{"type":"object","properties":{"id":{"type":"integer"},"estatus":{"type":"string"},"uuid":{"type":"string","nullable":true},"serie":{"type":"string"},"folio":{"type":"integer"},"moneda":{"type":"string"},"tipo_cambio":{"type":"number"},"subtotal":{"type":"number"},"iva":{"type":"number"},"retenciones":{"type":"object","properties":{"isr":{"type":"number"},"iva":{"type":"number"}}},"total":{"type":"number","description":"subtotal + iva \u2212 retenciones"},"xml_url":{"type":"string"},"pdf_url":{"type":"string"},"duplicado":{"type":"boolean"}}}}}}