{
    "info": {
        "name": "FiscalCloud — API de Timbrado para Integradores",
        "description": "Colección oficial de la API de timbrado CFDI 4.0 para integradores.\n\n**Antes de empezar:**\n1. En la pestaña *Variables* de la colección captura tu `api_key` (token Bearer de tu cuenta integradora).\n2. `base_url` apunta a pruebas; cámbiala a producción cuando corresponda.\n\nDocumentación viva: {{base_url}}/../../docs/api (OpenAPI + Redoc).\n\nCada timbrado exitoso descuenta 1 timbre de tu saldo. Usa `POST /integrador/validar` (sin costo) para revisar tu comprobante antes de timbrar, y manda el encabezado `Idempotency-Key` para reintentos seguros.",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "auth": {
        "type": "bearer",
        "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ]
    },
    "variable": [
        { "key": "base_url", "value": "https://sandbox-api.fiscalcloud.mx/v1", "type": "string" },
        { "key": "api_key", "value": "", "type": "string" },
        { "key": "uuid", "value": "", "type": "string", "description": "Folio fiscal de un comprobante timbrado" },
        { "key": "emisor_id", "value": "", "type": "string", "description": "Id de tu emisor con CSD registrado (cancelación acepta emisor_rfc o emisor_id)" },
        { "key": "emisor_rfc", "value": "", "type": "string", "description": "RFC de tu emisor con CSD registrado" }
    ],
    "item": [
        {
            "name": "Cuenta",
            "item": [
                {
                    "name": "Saldo de timbres",
                    "request": {
                        "method": "GET",
                        "header": [ { "key": "Accept", "value": "application/json" } ],
                        "url": { "raw": "{{base_url}}/integrador/saldo", "host": ["{{base_url}}"], "path": ["integrador", "saldo"] },
                        "description": "Timbres disponibles de tu cuenta y próximo vencimiento de la bolsa."
                    }
                }
            ]
        },
        {
            "name": "Timbrado",
            "item": [
                {
                    "name": "Validar (dry-run, sin costo) — modo sellar",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/validar", "host": ["{{base_url}}"], "path": ["integrador", "validar"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"emisor_rfc\": \"{{emisor_rfc}}\",\n  \"comprobante\": {\n    \"tipo_comprobante\": \"I\",\n    \"moneda\": \"MXN\",\n    \"forma_pago\": \"03\",\n    \"metodo_pago\": \"PUE\",\n    \"serie\": \"A\",\n    \"folio\": \"1001\",\n    \"receptor\": {\n      \"rfc\": \"CACX7605101P8\",\n      \"nombre\": \"XOCHILT CASAS CHAVEZ\",\n      \"uso_cfdi\": \"G03\",\n      \"regimen_fiscal\": \"612\",\n      \"domicilio_fiscal_cp\": \"36257\"\n    },\n    \"conceptos\": [\n      {\n        \"clave_prod_serv\": \"84111506\",\n        \"clave_unidad\": \"E48\",\n        \"cantidad\": 1,\n        \"descripcion\": \"Servicio de consultoría\",\n        \"valor_unitario\": 1000.00,\n        \"objeto_imp\": \"02\",\n        \"impuestos\": [\n          {\n            \"tipo\": \"traslado\",\n            \"impuesto\": \"002\",\n            \"tipo_factor\": \"Tasa\",\n            \"tasa_o_cuota\": 0.16,\n            \"base\": 1000.00\n          }\n        ]\n      }\n    ]\n  }\n}"
                        },
                        "description": "Valida estructura y reglas del Anexo 20 SIN timbrar ni consumir saldo. 200 = válido; 422 = el motivo viene en data.mensaje."
                    }
                },
                {
                    "name": "Validar (dry-run) — modo relay (XML sellado)",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/validar", "host": ["{{base_url}}"], "path": ["integrador", "validar"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"xml\": \"<CFDI 4.0 YA SELLADO, en base64>\"\n}"
                        }
                    }
                },
                {
                    "name": "Timbrar — modo sellar (datos en línea)",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" },
                            { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Reintenta con la MISMA clave para no duplicar ni pagar doble." }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/timbrar", "host": ["{{base_url}}"], "path": ["integrador", "timbrar"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"emisor_rfc\": \"{{emisor_rfc}}\",\n  \"comprobante\": {\n    \"tipo_comprobante\": \"I\",\n    \"moneda\": \"MXN\",\n    \"forma_pago\": \"03\",\n    \"metodo_pago\": \"PUE\",\n    \"serie\": \"A\",\n    \"folio\": \"1001\",\n    \"receptor\": {\n      \"rfc\": \"CACX7605101P8\",\n      \"nombre\": \"XOCHILT CASAS CHAVEZ\",\n      \"uso_cfdi\": \"G03\",\n      \"regimen_fiscal\": \"612\",\n      \"domicilio_fiscal_cp\": \"36257\"\n    },\n    \"conceptos\": [\n      {\n        \"clave_prod_serv\": \"84111506\",\n        \"clave_unidad\": \"E48\",\n        \"cantidad\": 1,\n        \"descripcion\": \"Servicio de consultoría\",\n        \"valor_unitario\": 1000.00,\n        \"objeto_imp\": \"02\",\n        \"impuestos\": [\n          {\n            \"tipo\": \"traslado\",\n            \"impuesto\": \"002\",\n            \"tipo_factor\": \"Tasa\",\n            \"tasa_o_cuota\": 0.16,\n            \"base\": 1000.00\n          }\n        ]\n      }\n    ]\n  }\n}"
                        },
                        "description": "Construye, sella y timbra con el CSD del emisor registrado en tu cuenta. 201 = timbrado (descuenta 1 timbre); 200 con idempotente=true = reintento con la misma Idempotency-Key."
                    }
                },
                {
                    "name": "Timbrar — modo relay (XML sellado)",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" },
                            { "key": "Idempotency-Key", "value": "{{$guid}}" }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/timbrar", "host": ["{{base_url}}"], "path": ["integrador", "timbrar"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"xml\": \"<CFDI 4.0 YA SELLADO con tu CSD, en base64 (recomendado) o crudo>\"\n}"
                        },
                        "description": "Tú armas y sellas el CFDI con tu propio CSD; la API solo lo timbra. Nunca vemos tu llave privada."
                    }
                }
            ]
        },
        {
            "name": "Comprobantes",
            "item": [
                {
                    "name": "Listar (paginación por cursor)",
                    "request": {
                        "method": "GET",
                        "header": [ { "key": "Accept", "value": "application/json" } ],
                        "url": {
                            "raw": "{{base_url}}/integrador/comprobantes?per_page=50",
                            "host": ["{{base_url}}"],
                            "path": ["integrador", "comprobantes"],
                            "query": [
                                { "key": "per_page", "value": "50", "description": "1–100" },
                                { "key": "cursor", "value": "", "description": "next_cursor de la página anterior", "disabled": true }
                            ]
                        }
                    }
                },
                {
                    "name": "Consultar por UUID",
                    "request": {
                        "method": "GET",
                        "header": [ { "key": "Accept", "value": "application/json" } ],
                        "url": { "raw": "{{base_url}}/integrador/comprobantes/{{uuid}}", "host": ["{{base_url}}"], "path": ["integrador", "comprobantes", "{{uuid}}"] }
                    }
                },
                {
                    "name": "Estatus ante el SAT",
                    "request": {
                        "method": "GET",
                        "header": [ { "key": "Accept", "value": "application/json" } ],
                        "url": { "raw": "{{base_url}}/integrador/comprobantes/{{uuid}}/estatus-sat", "host": ["{{base_url}}"], "path": ["integrador", "comprobantes", "{{uuid}}", "estatus-sat"] },
                        "description": "Consulta EN VIVO ante el SAT (vigente/cancelado/cancelable). Requiere el CSD del emisor registrado en tu cuenta."
                    }
                },
                {
                    "name": "Descargar XML timbrado",
                    "request": {
                        "method": "GET",
                        "url": { "raw": "{{base_url}}/integrador/comprobantes/{{uuid}}/xml", "host": ["{{base_url}}"], "path": ["integrador", "comprobantes", "{{uuid}}", "xml"] }
                    }
                },
                {
                    "name": "Descargar PDF (representación impresa)",
                    "request": {
                        "method": "GET",
                        "url": { "raw": "{{base_url}}/integrador/comprobantes/{{uuid}}/pdf", "host": ["{{base_url}}"], "path": ["integrador", "comprobantes", "{{uuid}}", "pdf"] },
                        "description": "En Postman usa \"Send and Download\" para guardar el archivo."
                    }
                },
                {
                    "name": "Descargar acuse de cancelación",
                    "request": {
                        "method": "GET",
                        "url": { "raw": "{{base_url}}/integrador/comprobantes/{{uuid}}/acuse", "host": ["{{base_url}}"], "path": ["integrador", "comprobantes", "{{uuid}}", "acuse"] },
                        "description": "Disponible una vez cancelado el comprobante (404 mientras no exista)."
                    }
                }
            ]
        },
        {
            "name": "Cancelación",
            "item": [
                {
                    "name": "Cancelar ante el SAT",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/cancelar", "host": ["{{base_url}}"], "path": ["integrador", "cancelar"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"uuid\": \"{{uuid}}\",\n  \"motivo\": \"02\",\n  \"folio_sustitucion\": null\n}"
                        },
                        "description": "Motivos (c_MotivoCancelacion): 01 errores con relación (exige folio_sustitucion), 02 errores sin relación, 03 no se llevó a cabo, 04 global nominativa. Requiere el CSD del emisor registrado."
                    }
                },
                {
                    "name": "Solicitudes pendientes (como receptor)",
                    "request": {
                        "method": "GET",
                        "header": [ { "key": "Accept", "value": "application/json" } ],
                        "url": {
                            "raw": "{{base_url}}/integrador/cancelaciones/pendientes?emisor_id={{emisor_id}}",
                            "host": ["{{base_url}}"],
                            "path": ["integrador", "cancelaciones", "pendientes"],
                            "query": [ { "key": "emisor_id", "value": "{{emisor_id}}" } ]
                        },
                        "description": "CFDIs que OTROS contribuyentes quieren cancelar y esperan la aceptación de tu empresa como receptor."
                    }
                },
                {
                    "name": "Aceptar o rechazar una solicitud",
                    "request": {
                        "method": "POST",
                        "header": [
                            { "key": "Accept", "value": "application/json" },
                            { "key": "Content-Type", "value": "application/json" }
                        ],
                        "url": { "raw": "{{base_url}}/integrador/cancelaciones/responder", "host": ["{{base_url}}"], "path": ["integrador", "cancelaciones", "responder"] },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"uuid\": \"{{uuid}}\",\n  \"emisor_id\": {{emisor_id}},\n  \"respuesta\": \"aceptar\"\n}"
                        }
                    }
                }
            ]
        }
    ]
}