{
  "info": {
    "name": "FactuSmart API — Facturación Electrónica SUNAT",
    "description": "Colección oficial de la API de facturación de FactuSmart.\n\nCÓMO EMPEZAR:\n1. Edita las variables de la colección (pestaña Variables): pon tu `api_key` (la de tu panel, pestaña Configuración) y `url_base` (la que aparece junto a tu API key). Opcional: `ruc` si tu cuenta tiene varios RUCs.\n2. Corre \"Ping\" para confirmar que tu API key funciona.\n3. Corre \"Emitir factura (mínimo)\" para tu primera emisión en sandbox.\n\nLa API key viaja en el header X-API-Key (ya configurado a nivel de colección).\n\nDocumentación completa: https://factusmart.pe/api-facturacion-electronica/docs",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "url_base", "value": "https://s2.factusmart.pe", "type": "string" },
    { "key": "api_key", "value": "PEGA_AQUI_TU_API_KEY", "type": "string" },
    { "key": "ruc", "value": "20123456789", "type": "string" },
    { "key": "external_id", "value": "", "type": "string" }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "X-API-Key", "type": "string" },
      { "key": "value", "value": "{{api_key}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "item": [
    {
      "name": "Ping (probar conexión)",
      "request": {
        "method": "GET",
        "url": { "raw": "{{url_base}}/api/v1/issuer/ping", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "ping"] },
        "description": "Confirma que tu API key es válida y devuelve tus créditos. No consume crédito."
      }
    },
    {
      "name": "Estado de la cuenta (saldo y RUCs)",
      "request": {
        "method": "GET",
        "url": { "raw": "{{url_base}}/api/v1/issuer/account", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "account"] },
        "description": "Saldo de créditos, total recargado, consumido y RUCs de tu cuenta. No consume crédito."
      }
    },
    {
      "name": "Listar mis RUCs",
      "request": {
        "method": "GET",
        "url": { "raw": "{{url_base}}/api/v1/issuer/rucs", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "rucs"] },
        "description": "Lista los RUCs enlazados a tu cuenta con su entorno (demo/producción) y estado (activo/desactivado). No consume crédito."
      }
    },
    {
      "name": "Crear un RUC nuevo",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/rucs", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "rucs"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"20609999991\",\n  \"empresa\": \"Mi Cliente SAC\",\n  \"correo\": \"contacto@micliente.pe\",\n  \"clave\": \"una-clave-de-al-menos-6-caracteres\"\n}"
        },
        "description": "Crea un RUC nuevo (nace en modo prueba). Es seguro reintentar con el mismo RUC: si ya es tuyo, devuelve sus datos en vez de duplicarlo. No consume crédito (los créditos se descuentan por comprobante emitido, no por RUC creado)."
      }
    },
    {
      "name": "Activar / desactivar un RUC",
      "request": {
        "method": "PATCH",
        "header": [{ "key": "Content-Type", "value": "application/json" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/rucs/{{ruc}}/activation", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "rucs", "{{ruc}}", "activation"] },
        "body": { "mode": "raw", "raw": "{\n  \"activo\": false\n}" },
        "description": "Cambia 'activo' a false para desactivar (bloquea emisión, consulta y descarga de ese RUC) o a true para reactivar. Reversible, no borra datos."
      }
    },
    {
      "name": "Series del RUC",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/series?ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "series"],
          "query": [{ "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Series reales del RUC (FA01, BA01...). Normalmente no necesitas enviar la serie al emitir; se resuelve sola."
      }
    },
    {
      "name": "Emitir factura (mínimo)",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "venta-000123" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/documents", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"{{ruc}}\",\n  \"numero_documento\": \"#\",\n  \"fecha_de_emision\": \"2026-07-08\",\n  \"hora_de_emision\": \"10:30:00\",\n  \"codigo_tipo_operacion\": \"0101\",\n  \"codigo_tipo_documento\": \"01\",\n  \"codigo_tipo_moneda\": \"PEN\",\n  \"datos_del_cliente_o_receptor\": {\n    \"codigo_tipo_documento_identidad\": \"6\",\n    \"numero_documento\": \"20131312955\"\n  },\n  \"totales\": {\n    \"total_operaciones_gravadas\": 100.00,\n    \"total_igv\": 18.00,\n    \"total_impuestos\": 18.00,\n    \"total_valor\": 100.00,\n    \"total_venta\": 118.00\n  },\n  \"items\": [\n    {\n      \"codigo_interno\": \"PROD-001\",\n      \"descripcion\": \"Servicio de consultoría\",\n      \"unidad_de_medida\": \"NIU\",\n      \"cantidad\": 1,\n      \"valor_unitario\": 100.00,\n      \"codigo_tipo_precio\": \"01\",\n      \"precio_unitario\": 118.00,\n      \"codigo_tipo_afectacion_igv\": \"10\",\n      \"total_base_igv\": 100.00,\n      \"porcentaje_igv\": 18,\n      \"total_igv\": 18.00,\n      \"total_impuestos\": 18.00,\n      \"total_valor_item\": 100.00,\n      \"total_item\": 118.00\n    }\n  ]\n}"
        },
        "description": "Factura mínima: sin serie (se resuelve sola), cliente con solo RUC/DNI (autocompleta nombre y dirección). Cambia el Idempotency-Key por cada venta nueva."
      }
    },
    {
      "name": "Emitir boleta",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "boleta-000123" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/documents", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"{{ruc}}\",\n  \"numero_documento\": \"#\",\n  \"fecha_de_emision\": \"2026-07-08\",\n  \"hora_de_emision\": \"10:30:00\",\n  \"codigo_tipo_operacion\": \"0101\",\n  \"codigo_tipo_documento\": \"03\",\n  \"codigo_tipo_moneda\": \"PEN\",\n  \"datos_del_cliente_o_receptor\": {\n    \"codigo_tipo_documento_identidad\": \"1\",\n    \"numero_documento\": \"77344962\"\n  },\n  \"totales\": {\n    \"total_operaciones_gravadas\": 50.00,\n    \"total_igv\": 9.00,\n    \"total_impuestos\": 9.00,\n    \"total_valor\": 50.00,\n    \"total_venta\": 59.00\n  },\n  \"items\": [\n    {\n      \"codigo_interno\": \"PROD-002\",\n      \"descripcion\": \"Producto de prueba\",\n      \"unidad_de_medida\": \"NIU\",\n      \"cantidad\": 1,\n      \"valor_unitario\": 50.00,\n      \"codigo_tipo_precio\": \"01\",\n      \"precio_unitario\": 59.00,\n      \"codigo_tipo_afectacion_igv\": \"10\",\n      \"total_base_igv\": 50.00,\n      \"porcentaje_igv\": 18,\n      \"total_igv\": 9.00,\n      \"total_impuestos\": 9.00,\n      \"total_valor_item\": 50.00,\n      \"total_item\": 59.00\n    }\n  ]\n}"
        },
        "description": "Boleta (codigo_tipo_documento 03). Cliente con DNI (tipo 1)."
      }
    },
    {
      "name": "Emitir factura con detracción",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "detraccion-000123" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/documents", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"{{ruc}}\",\n  \"numero_documento\": \"#\",\n  \"fecha_de_emision\": \"2026-07-08\",\n  \"hora_de_emision\": \"10:30:00\",\n  \"codigo_tipo_operacion\": \"1001\",\n  \"codigo_tipo_documento\": \"01\",\n  \"codigo_tipo_moneda\": \"PEN\",\n  \"datos_del_cliente_o_receptor\": {\n    \"codigo_tipo_documento_identidad\": \"6\",\n    \"numero_documento\": \"20131312955\"\n  },\n  \"totales\": {\n    \"total_operaciones_gravadas\": 1000.00,\n    \"total_igv\": 180.00,\n    \"total_impuestos\": 180.00,\n    \"total_valor\": 1000.00,\n    \"total_venta\": 1180.00\n  },\n  \"detraccion\": {\n    \"codigo_tipo_detraccion\": \"022\",\n    \"porcentaje\": 12,\n    \"monto\": 141.60,\n    \"codigo_metodo_pago\": \"001\",\n    \"cuenta_bancaria\": \"00-000-000000\"\n  },\n  \"items\": [\n    {\n      \"codigo_interno\": \"SERV-001\",\n      \"descripcion\": \"Servicio empresarial sujeto a detracción\",\n      \"unidad_de_medida\": \"ZZ\",\n      \"cantidad\": 1,\n      \"valor_unitario\": 1000.00,\n      \"codigo_tipo_precio\": \"01\",\n      \"precio_unitario\": 1180.00,\n      \"codigo_tipo_afectacion_igv\": \"10\",\n      \"total_base_igv\": 1000.00,\n      \"porcentaje_igv\": 18,\n      \"total_igv\": 180.00,\n      \"total_impuestos\": 180.00,\n      \"total_valor_item\": 1000.00,\n      \"total_item\": 1180.00\n    }\n  ]\n}"
        },
        "description": "Factura con detracción (operación 1001). La detracción aplica desde S/ 700. La leyenda 2006 se agrega sola."
      }
    },
    {
      "name": "Emitir nota de crédito",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "nc-000123" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/documents", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"{{ruc}}\",\n  \"serie_documento\": \"FN01\",\n  \"numero_documento\": \"#\",\n  \"fecha_de_emision\": \"2026-07-08\",\n  \"hora_de_emision\": \"10:45:00\",\n  \"codigo_tipo_documento\": \"07\",\n  \"codigo_tipo_nota\": \"01\",\n  \"motivo_o_sustento_de_nota\": \"Anulación de la operación\",\n  \"documento_afectado\": {\n    \"serie_documento\": \"FA01\",\n    \"numero_documento\": \"1\",\n    \"codigo_tipo_documento\": \"01\"\n  },\n  \"codigo_tipo_moneda\": \"PEN\",\n  \"datos_del_cliente_o_receptor\": {\n    \"codigo_tipo_documento_identidad\": \"6\",\n    \"numero_documento\": \"20131312955\"\n  },\n  \"totales\": {\n    \"total_operaciones_gravadas\": 100.00,\n    \"total_igv\": 18.00,\n    \"total_impuestos\": 18.00,\n    \"total_valor\": 100.00,\n    \"total_venta\": 118.00\n  },\n  \"items\": [\n    {\n      \"codigo_interno\": \"PROD-001\",\n      \"descripcion\": \"Servicio de consultoría\",\n      \"unidad_de_medida\": \"NIU\",\n      \"cantidad\": 1,\n      \"valor_unitario\": 100.00,\n      \"codigo_tipo_precio\": \"01\",\n      \"precio_unitario\": 118.00,\n      \"codigo_tipo_afectacion_igv\": \"10\",\n      \"total_base_igv\": 100.00,\n      \"porcentaje_igv\": 18,\n      \"total_igv\": 18.00,\n      \"total_impuestos\": 18.00,\n      \"total_valor_item\": 100.00,\n      \"total_item\": 118.00\n    }\n  ]\n}"
        },
        "description": "Nota de crédito (07). ES EL ÚNICO CASO donde sí se envía la serie: FN01 para notas de factura, BN01 para notas de boleta. Débito = 08."
      }
    },
    {
      "name": "Consultar estado de un comprobante",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents/{{external_id}}?ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents", "{{external_id}}"],
          "query": [{ "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Estado del comprobante (usa el external_id que devolvió la emisión). No consume crédito."
      }
    },
    {
      "name": "Listar comprobantes atascados (estado 01)",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents?estado=01&ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents"],
          "query": [{ "key": "estado", "value": "01" }, { "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Lista los comprobantes que NO llegaron a ser aceptados por SUNAT, cada uno con el motivo exacto (sunat.codigo + sunat.descripcion) y qué hacer. Quita el filtro 'estado' para verlos todos. Si hay más de 'limite' (máx. 100), la respuesta trae 'siguiente_cursor' — mándalo como '?antes_de=' en la siguiente llamada para paginar. No consume crédito."
      }
    },
    {
      "name": "Historial de un comprobante",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents/{{external_id}}/historial?ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents", "{{external_id}}", "historial"],
          "query": [{ "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Línea de tiempo completa: cada intento de envío y qué respondió SUNAT en cada uno (creado, enviado, aceptado, rechazado, error, reintento). No consume crédito."
      }
    },
    {
      "name": "Reenviar a SUNAT",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }],
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents/{{external_id}}/reenviar",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents", "{{external_id}}", "reenviar"]
        },
        "body": { "mode": "raw", "raw": "{\n  \"ruc\": \"{{ruc}}\"\n}" },
        "description": "Reintenta el envío de un comprobante que quedó en estado 01. NO consume crédito (ya se cobró al emitirlo). Útil cuando SUNAT estaba caída o dio timeout. Si el error es de configuración (0111, 0102) o de numeración (1033), reenviar no ayuda — corrige la causa primero."
      }
    },
    {
      "name": "Consultar estado real en SUNAT",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }],
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents/{{external_id}}/consultar-sunat",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents", "{{external_id}}", "consultar-sunat"]
        },
        "body": { "mode": "raw", "raw": "{\n  \"ruc\": \"{{ruc}}\"\n}" },
        "description": "Le pregunta a SUNAT en vivo el estado real del comprobante y lo sincroniza. Úsalo cuando el envío quedó en el aire y no sabes si SUNAT alcanzó a aceptarlo. No consume crédito."
      }
    },
    {
      "name": "Descargar PDF",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/documents/{{external_id}}/pdf?ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "documents", "{{external_id}}", "pdf"],
          "query": [{ "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Descarga el PDF. Cambia 'pdf' por 'xml' (XML firmado) o 'cdr' (constancia SUNAT). No consume crédito."
      }
    },
    {
      "name": "Anular comprobante",
      "request": {
        "method": "POST",
        "header": [{ "key": "Content-Type", "value": "application/json" }],
        "url": { "raw": "{{url_base}}/api/v1/issuer/anulaciones", "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "anulaciones"] },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"ruc\": \"{{ruc}}\",\n  \"fecha_de_emision_de_documentos\": \"08-07-2026\",\n  \"documentos\": [\n    {\n      \"external_id\": \"{{external_id}}\",\n      \"motivo_anulacion\": \"Error en el comprobante\"\n    }\n  ]\n}"
        },
        "description": "Comunicación de baja (asíncrona): devuelve un ticket. `fecha_de_emision_de_documentos` en formato DD-MM-YYYY (la fecha de emisión de los comprobantes a anular). Consulta el resultado con 'Estado de anulación'."
      }
    },
    {
      "name": "Estado de anulación",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{url_base}}/api/v1/issuer/anulaciones/TICKET_AQUI/status?ruc={{ruc}}",
          "host": ["{{url_base}}"], "path": ["api", "v1", "issuer", "anulaciones", "TICKET_AQUI", "status"],
          "query": [{ "key": "ruc", "value": "{{ruc}}" }]
        },
        "description": "Reemplaza TICKET_AQUI por el ticket que devolvió la anulación."
      }
    }
  ]
}