{
  "info": {
    "name": "TimbraMX API",
    "description": "Timbrar, consultar y cancelar CFDI 4.0 con TimbraMX. Configura las variables de colección base_url y api_key (tu key de sandbox o producción) antes de correr las peticiones.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://app.timbra-mx.com/api/v1"
    },
    {
      "key": "api_key",
      "value": "tu_api_key_de_sandbox"
    }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-Api-Key"
      },
      {
        "key": "value",
        "value": "{{api_key}}"
      },
      {
        "key": "in",
        "value": "header"
      }
    ]
  },
  "item": [
    {
      "name": "Facturas",
      "item": [
        {
          "name": "Validar sin timbrar",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"xml\": \"PHNmZGk6Q29tcHJvYmFudGUgeG1sbnM6Y2ZkaT0i...\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas/validar",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                "validar"
              ]
            },
            "description": "Valida el XML (modo relay) contra el XSD del SAT y reglas de negocio, sin timbrar ni gastar un intento con el PAC."
          }
        },
        {
          "name": "Timbrar - Modo relay",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"xml\": \"PHNmZGk6Q29tcHJvYmFudGUgeG1sbnM6Y2ZkaT0i...\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas"
              ]
            },
            "description": "Timbra un CFDI que tú ya sellaste con tu propio CSD (XML en base64)."
          }
        },
        {
          "name": "Timbrar - Modo sellar",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"receptorRfc\": \"XAXX010101000\",\n  \"serie\": \"F\",\n  \"formaPago\": \"03\",\n  \"metodoPago\": \"PUE\",\n  \"moneda\": \"MXN\",\n  \"conceptos\": [\n    {\n      \"claveProdServ\": \"81112101\",\n      \"claveUnidad\": \"E48\",\n      \"descripcion\": \"Servicio de consultoría\",\n      \"cantidad\": 1,\n      \"valorUnitario\": 1000,\n      \"impuestos\": [\n        { \"impuesto\": \"002\", \"categoria\": \"traslado\", \"tipoFactor\": \"Tasa\", \"tasaIva\": 0.16 }\n      ]\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas"
              ]
            },
            "description": "TimbraMX arma, sella (con el CSD ya subido al portal) y timbra el CFDI a partir de datos estructurados. Solo Ingreso simple en v1."
          }
        },
        {
          "name": "Timbrar con Idempotency-Key",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "mi-clave-unica-001"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"xml\": \"PHNmZGk6Q29tcHJvYmFudGUgeG1sbnM6Y2ZkaT0i...\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas"
              ]
            },
            "description": "Reintenta la misma petición con la misma clave para probar el comportamiento idempotente (200 con idempotente:true en vez de timbrar dos veces)."
          }
        },
        {
          "name": "Listar facturas",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas?pagina=1&limite=20",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas"
              ],
              "query": [
                {
                  "key": "pagina",
                  "value": "1"
                },
                {
                  "key": "limite",
                  "value": "20"
                },
                {
                  "key": "estado",
                  "value": "",
                  "disabled": true,
                  "description": "Filtra por estado exacto."
                },
                {
                  "key": "uuid",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el UUID fiscal."
                },
                {
                  "key": "rfc",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el RFC."
                },
                {
                  "key": "desde",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion minima, YYYY-MM-DD."
                },
                {
                  "key": "hasta",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion maxima, YYYY-MM-DD."
                }
              ]
            }
          }
        },
        {
          "name": "Consultar factura por id",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar XML crudo",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id/xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "xml"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "Regresa el archivo XML directo (application/xml), no envuelto en JSON."
          }
        },
        {
          "name": "Consultar estatus ante el SAT",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id/estatus-sat",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "estatus-sat"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "Consulta en vivo ante el SAT si el CFDI sigue vigente o ya fue cancelado."
          }
        },
        {
          "name": "Descargar PDF",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id/pdf",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "pdf"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "Regresa el archivo PDF directo (application/pdf), no un JSON."
          }
        },
        {
          "name": "Consultar acuse de cancelacion",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id/acuse",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "acuse"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "Solo existe si la factura ya fue cancelada (404 si no)."
          }
        },
        {
          "name": "Consultar saldo",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/saldo",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                "saldo"
              ]
            }
          }
        },
        {
          "name": "Cancelar CFDI",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"motivo\": \"02\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas/:id/cancelar",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "cancelar"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "motivo: catálogo SAT c_MotivoCancelacion (01 con relación, requiere uuidReemplazo; 02 sin relación; 03 no se llevó a cabo; 04 factura global nominativa)."
          }
        },
        {
          "name": "Consultar estatus de cancelación",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/facturas/:id/estatus-cancelacion",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "estatus-cancelacion"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Generar nota de crédito",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"importe\": 1160.00,\n  \"descripcion\": \"Devolución de mercancía\",\n  \"serie\": \"NC\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/facturas/:id/nota-credito",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "facturas",
                ":id",
                "nota-credito"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            },
            "description": "Acredita, total o parcialmente, una factura de Ingreso ya timbrada. La forma de pago se copia de la original; método de pago siempre PUE."
          }
        }
      ]
    },
    {
      "name": "Complementos de pago",
      "item": [
        {
          "name": "Timbrar complemento de pago",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"receptorRfc\": \"COE850101AB1\",\n  \"serie\": \"PAGOS\",\n  \"pagos\": [\n    {\n      \"fechaPago\": \"2026-09-15T12:00:00\",\n      \"formaPago\": \"03\",\n      \"moneda\": \"MXN\",\n      \"documentos\": [\n        { \"facturaUuid\": \"3F9A1C2E-4B7D-4E3A-9C2F-8B1D6A5E7F90\", \"impPagado\": 12500.00 }\n      ]\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/complementos-pago",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago"
              ]
            },
            "description": "Las facturas a cubrir se identifican por su UUID fiscal (deben ser PPD, timbradas y del mismo receptor)."
          }
        },
        {
          "name": "Listar complementos de pago",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/complementos-pago?pagina=1&limite=20",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago"
              ],
              "query": [
                {
                  "key": "pagina",
                  "value": "1"
                },
                {
                  "key": "limite",
                  "value": "20"
                },
                {
                  "key": "estado",
                  "value": "",
                  "disabled": true,
                  "description": "Filtra por estado exacto."
                },
                {
                  "key": "uuid",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el UUID fiscal."
                },
                {
                  "key": "rfc",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el RFC."
                },
                {
                  "key": "desde",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion minima, YYYY-MM-DD."
                },
                {
                  "key": "hasta",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion maxima, YYYY-MM-DD."
                }
              ]
            }
          }
        },
        {
          "name": "Consultar complemento por id",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/complementos-pago/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar XML del complemento",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/complementos-pago/:id/xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago",
                ":id",
                "xml"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar PDF del complemento",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/complementos-pago/:id/pdf",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago",
                ":id",
                "pdf"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Cancelar complemento de pago",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"motivo\": \"02\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/complementos-pago/:id/cancelar",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago",
                ":id",
                "cancelar"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Consultar estatus de cancelación",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/complementos-pago/:id/estatus-cancelacion",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "complementos-pago",
                ":id",
                "estatus-cancelacion"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Nómina",
      "item": [
        {
          "name": "Timbrar recibo de nómina",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"receptorRfc\": \"MARL900101AB2\",\n  \"serie\": \"NOM\",\n  \"nomina\": {\n    \"tipoNomina\": \"O\",\n    \"fechaPago\": \"2026-09-15\",\n    \"fechaInicialPago\": \"2026-09-01\",\n    \"fechaFinalPago\": \"2026-09-15\",\n    \"numDiasPagados\": \"15\",\n    \"totalPercepciones\": \"7500.00\",\n    \"receptor\": {\n      \"curp\": \"MARL900101HDFRZS02\",\n      \"tipoContrato\": \"01\",\n      \"tipoRegimen\": \"02\",\n      \"numEmpleado\": \"1\",\n      \"periodicidadPago\": \"04\",\n      \"claveEntFed\": \"JAL\"\n    },\n    \"percepciones\": {\n      \"totalGravado\": \"7500.00\",\n      \"totalExento\": \"0.00\",\n      \"percepciones\": [\n        { \"tipoPercepcion\": \"001\", \"clave\": \"001\", \"concepto\": \"Sueldos\", \"importeGravado\": \"7500.00\", \"importeExento\": \"0.00\" }\n      ]\n    }\n  }\n}"
            },
            "url": {
              "raw": "{{base_url}}/nomina",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina"
              ]
            },
            "description": "Arma, sella y timbra el CFDI de Nómina 1.2 en un solo paso. Los campos numéricos dentro de 'nomina' viajan como string, no number."
          }
        },
        {
          "name": "Listar recibos de nómina",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/nomina?pagina=1&limite=20",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina"
              ],
              "query": [
                {
                  "key": "pagina",
                  "value": "1"
                },
                {
                  "key": "limite",
                  "value": "20"
                },
                {
                  "key": "estado",
                  "value": "",
                  "disabled": true,
                  "description": "Filtra por estado exacto."
                },
                {
                  "key": "uuid",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el UUID fiscal."
                },
                {
                  "key": "rfc",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el RFC."
                },
                {
                  "key": "desde",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion minima, YYYY-MM-DD."
                },
                {
                  "key": "hasta",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion maxima, YYYY-MM-DD."
                }
              ]
            }
          }
        },
        {
          "name": "Consultar recibo por id",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/nomina/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar XML del recibo",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/nomina/:id/xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina",
                ":id",
                "xml"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar PDF del recibo",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/nomina/:id/pdf",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina",
                ":id",
                "pdf"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Cancelar recibo de nómina",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"motivo\": \"02\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/nomina/:id/cancelar",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina",
                ":id",
                "cancelar"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Consultar estatus de cancelación",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/nomina/:id/estatus-cancelacion",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "nomina",
                ":id",
                "estatus-cancelacion"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Retenciones",
      "item": [
        {
          "name": "Timbrar retención (dividendos)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"tipoOperacion\": \"dividendos\",\n  \"serie\": \"RET\",\n  \"rfcContraparte\": \"MARL900101AB2\",\n  \"nombreContraparte\": \"Luis Martinez Rodriguez\",\n  \"codigoPostalContraparte\": \"44100\",\n  \"fechaOperacion\": \"2026-09-15\",\n  \"montoOperacion\": 50000,\n  \"cveRetenc\": \"14\",\n  \"mesPeriodo\": 9,\n  \"ejercicio\": 2026,\n  \"impRetenidos\": [\n    { \"impuesto\": \"001\", \"montoRet\": 5000, \"tipoPagoRet\": \"02\" }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/retenciones",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones"
              ]
            },
            "description": "Alcance v1: solo dividendos, enajenacion_acciones y pagos_extranjero. Con RFC genérico XAXX010101000, nombreContraparte debe ser exactamente 'PÚBLICO EN GENERAL' (con acento)."
          }
        },
        {
          "name": "Listar retenciones",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/retenciones?pagina=1&limite=20",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones"
              ],
              "query": [
                {
                  "key": "pagina",
                  "value": "1"
                },
                {
                  "key": "limite",
                  "value": "20"
                },
                {
                  "key": "tipo",
                  "value": "",
                  "disabled": true,
                  "description": "dividendos | enajenacion_acciones | pagos_extranjero."
                },
                {
                  "key": "estado",
                  "value": "",
                  "disabled": true,
                  "description": "Filtra por estado exacto."
                },
                {
                  "key": "uuid",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el UUID fiscal."
                },
                {
                  "key": "rfc",
                  "value": "",
                  "disabled": true,
                  "description": "Busqueda parcial (contains) sobre el RFC."
                },
                {
                  "key": "desde",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion minima, YYYY-MM-DD."
                },
                {
                  "key": "hasta",
                  "value": "",
                  "disabled": true,
                  "description": "Fecha de creacion maxima, YYYY-MM-DD."
                }
              ]
            }
          }
        },
        {
          "name": "Consultar retención por id",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/retenciones/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar XML de la retención",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/retenciones/:id/xml",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones",
                ":id",
                "xml"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Descargar PDF de la retención",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/retenciones/:id/pdf",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones",
                ":id",
                "pdf"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Cancelar retención",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"motivo\": \"02\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/retenciones/:id/cancelar",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones",
                ":id",
                "cancelar"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        },
        {
          "name": "Consultar estatus de cancelación",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/retenciones/:id/estatus-cancelacion",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "retenciones",
                ":id",
                "estatus-cancelacion"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": ""
                }
              ]
            }
          }
        }
      ]
    }
  ]
}