{
  "info": {
    "name": "Timbre API",
    "description": "API REST de Timbre para emisión, cancelación y consulta de CFDI 4.0 ante el SAT. Antes de usar, edita las variables baseUrl y apiKey de la colección.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "http://localhost:3033",
      "type": "string",
      "description": "URL base de la API. Cambia a tu URL de producción si aplica."
    },
    {
      "key": "apiKey",
      "value": "pk_test_REEMPLAZA_CON_TU_API_KEY",
      "type": "string",
      "description": "API key personal — solicítala al admin del panel. Usa pk_test_* para sandbox o pk_live_* para producción."
    },
    {
      "key": "issuerId",
      "value": "iss_xxx",
      "type": "string",
      "description": "ID del issuer (RFC con CSD) que vas a usar al emitir."
    },
    {
      "key": "cfdiId",
      "value": "cfdi_xxx",
      "type": "string",
      "description": "ID interno del CFDI emitido (devuelto por POST /cfdi)."
    },
    {
      "key": "uuid",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "type": "string",
      "description": "UUID del CFDI timbrado (devuelto por SAT)."
    },
    {
      "key": "rfcEmisor",
      "value": "ABC123456789",
      "type": "string",
      "description": "RFC del emisor — debe estar registrado vía AltaEmpresaWithCertificado."
    }
  ],
  "item": [
    {
      "name": "Status",
      "description": "Endpoints públicos de monitoreo y saldo.",
      "item": [
        {
          "name": "GET /health",
          "request": {
            "auth": {
              "type": "noauth"
            },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/health",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "health"
              ]
            },
            "description": "Health check público (sin auth). Verifica DB + conectividad al PAC."
          }
        },
        {
          "name": "GET /balance",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/balance",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "balance"
              ]
            },
            "description": "Saldo de timbres del cliente al que pertenece la API key."
          }
        }
      ]
    },
    {
      "name": "Issuers (RFCs / CSDs)",
      "description": "Gestión de RFCs configurados con su CSD.",
      "item": [
        {
          "name": "GET /issuers",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/issuers",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "issuers"
              ]
            },
            "description": "Lista los RFCs registrados para este cliente."
          }
        }
      ]
    },
    {
      "name": "API de timbrado",
      "description": "Endpoints para alta de empresas, timbrado y cancelación de CFDI. Útiles si ya manejas tu propio CSD y firmas el XML localmente.",
      "item": [
        {
          "name": "POST /AltaEmpresaWithCertificado",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfc\": \"{{rfcEmisor}}\",\n  \"razonSocial\": \"MI EMPRESA SA DE CV\",\n  \"cer\": \"BASE64_DEL_ARCHIVO_CER\",\n  \"key\": \"BASE64_DEL_ARCHIVO_KEY\",\n  \"contrasena\": \"csd-password\",\n  \"observaciones\": \"\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/AltaEmpresaWithCertificado",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "AltaEmpresaWithCertificado"
              ]
            },
            "description": "Da de alta una empresa nueva en el PAC subiendo su CSD. Solo una vez por RFC."
          }
        },
        {
          "name": "POST /AltaCertificado",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfc\": \"{{rfcEmisor}}\",\n  \"cer\": \"BASE64_DEL_ARCHIVO_CER\",\n  \"key\": \"BASE64_DEL_ARCHIVO_KEY\",\n  \"contrasena\": \"csd-password\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/AltaCertificado",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "AltaCertificado"
              ]
            },
            "description": "Renueva el CSD de una empresa ya dada de alta. La empresa debe haber pasado por AltaEmpresaWithCertificado."
          }
        },
        {
          "name": "POST /TimbrarSellarBase64",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"xml\": \"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48Y2ZkaTpDb21wcm9iYW50ZSAuLi4vPg==\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/TimbrarSellarBase64",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "TimbrarSellarBase64"
              ]
            },
            "description": "Timbra un CFDI 4.0 sin sellar (base64). DI lo sella con el CSD registrado. Modo live = descuenta 1 timbre del saldo si code='100'."
          }
        },
        {
          "name": "POST /TimbrarSellarBase64Test",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"xml\": \"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48Y2ZkaTpDb21wcm9iYW50ZSAuLi4vPg==\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/TimbrarSellarBase64Test",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "TimbrarSellarBase64Test"
              ]
            },
            "description": "Variante sandbox. Forzado a SAT pruebas. Nunca descuenta saldo."
          }
        },
        {
          "name": "POST /Cancelar",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfcEmisor\": \"{{rfcEmisor}}\",\n  \"uuid\": \"{{uuid}}\",\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/Cancelar",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "Cancelar"
              ]
            },
            "description": "Solicita cancelación al SAT (producción). Motivo: 01 (con relación, requiere folioSustitucion) · 02 (sin relación) · 03 (no se realizó) · 04 (factura global)."
          }
        },
        {
          "name": "POST /CancelarTest",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfcEmisor\": \"{{rfcEmisor}}\",\n  \"uuid\": \"{{uuid}}\",\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/CancelarTest",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "CancelarTest"
              ]
            },
            "description": "Sandbox de Cancelar."
          }
        },
        {
          "name": "POST /ConsultaCertificado",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfc\": \"{{rfcEmisor}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/ConsultaCertificado",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "ConsultaCertificado"
              ]
            },
            "description": "Consulta los datos del CSD registrado para un RFC (número, vigencia, expiración)."
          }
        },
        {
          "name": "POST /ConsultaEstatusSAT",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rfcEmisor\": \"{{rfcEmisor}}\",\n  \"rfcReceptor\": \"XAXX010101000\",\n  \"total\": \"116.00\",\n  \"uuid\": \"{{uuid}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/ConsultaEstatusSAT",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "ConsultaEstatusSAT"
              ]
            },
            "description": "Consulta el estatus actual de un CFDI ante el SAT (Vigente / Cancelado / En proceso)."
          }
        }
      ]
    }
  ]
}