{
    "info": {
        "_postman_id": "8de073e0-ce6b-4807-b46b-548ce11eb9c9",
        "name": "Sistema Facturación Perú · API de socios v1",
        "description": "Para programadores y empresas de software con muchos clientes propios. Tú das de alta a tus clientes como empresas\nde Sistema Facturación Perú, las pagas con bolsas prepago de comprobantes y emites con cada una usando su **API v1**\n(https://sistemafacturacionperu.com/desarrolladores/referencia/).\n\n- Base: `https://api.sistemafacturacionperu.com/socios/v1` (nunca en el subdominio de una empresa).\n- Autenticación: OAuth 2 «client_credentials». Pide un token con `POST /token` (tu `client_id` y `client_secret`) y\n  úsalo en `Authorization: Bearer sfp_pat_…`. Dura 1 hora. Nunca en la URL.\n- Éxito: `{ \"success\": true, \"data\": …, \"meta\"?: … }`. Error: `{ \"success\": false, \"code\": \"…\", \"message\": \"…\", \"errors\"?: {…} }`\n  (el mismo formato de la API v1).\n- Todo `POST` y `PATCH` acepta `Idempotency-Key`: el reintento con el mismo cuerpo devuelve la misma respuesta con\n  `Idempotent-Replayed: true`; la misma clave con otro cuerpo responde 409 `idempotencia_distinta`.\n- Límites: 120 llamadas por minuto por token (`X-RateLimit-Limit`, `X-RateLimit-Remaining`; al pasarte, 429 con\n  `Retry-After`) y 10 intentos de token por minuto por IP y por `client_id`.\n- Una empresa que no es tuya responde 404 (nunca se revela que existe).\n\nBolsas (con IGV, 6 meses de validez, se consume primero la que vence antes): 3.300 = S/ 180; 5.500 = S/ 285;\n10.000 = S/ 480. Descuenta 1 cada comprobante, resumen diario, baja y guía que sale por **nuestro PSE**; lo que la\nempresa envía con su propio usuario SOL no descuenta. Cuota: S/ 9 al mes con IGV por cada empresa que emitió.\n\nGuía completa: https://sistemafacturacionperu.com/desarrolladores/socios/",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
        "version": "1.0.0"
    },
    "auth": {
        "type": "bearer",
        "bearer": [
            {
                "key": "token",
                "value": "{{api_key}}",
                "type": "string"
            }
        ]
    },
    "variable": [
        {
            "key": "base_url",
            "value": "https://api.sistemafacturacionperu.com/socios/v1",
            "type": "string",
            "description": "Siempre este host"
        },
        {
            "key": "api_key",
            "value": "",
            "type": "string",
            "description": "El token sfp_pat_ que devuelve POST /token (dura 1 hora)"
        },
        {
            "key": "client_id",
            "value": "sfp_partner_TU_CLIENT_ID",
            "type": "string",
            "description": "Tu credencial de socio (para POST /token)"
        },
        {
            "key": "client_secret",
            "value": "",
            "type": "string",
            "description": "Tu secreto de socio: guárdalo solo en tu servidor"
        }
    ],
    "item": [
        {
            "name": "Autenticación",
            "item": [
                {
                    "name": "Pedir un token de acceso (client_credentials)",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/token",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "token"
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"grant_type\": \"client_credentials\",\n    \"client_id\": \"sfp_partner_k2j4h6g8f0d2s4a6q8w0e2r4\",\n    \"client_secret\": \"sfp_secret_…\"\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "Manda tu `client_id` y `client_secret` en `Authorization: Basic base64(client_id:client_secret)` o en el cuerpo\n(JSON o formulario). El token dura 1 hora: pide otro cuando venza (401 `token_vencido`).",
                        "auth": {
                            "type": "noauth"
                        }
                    }
                }
            ]
        },
        {
            "name": "Empresas",
            "description": "Tus clientes como empresas de Sistema Facturación Perú.",
            "item": [
                {
                    "name": "Listar tus empresas",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/empresas",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas"
                            ],
                            "query": [
                                {
                                    "key": "estado",
                                    "disabled": true
                                },
                                {
                                    "key": "ruc",
                                    "disabled": true
                                },
                                {
                                    "key": "page",
                                    "value": "1",
                                    "disabled": true
                                },
                                {
                                    "key": "per_page",
                                    "value": "20",
                                    "disabled": true
                                }
                            ]
                        },
                        "description": "El estado es el último conocido; `GET /empresas/{id}` lo vuelve a leer."
                    }
                },
                {
                    "name": "Dar de alta una empresa",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/empresas",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas"
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"ruc\": \"20601030013\",\n    \"razon_social\": \"FERRETERIA EL TORNILLO S.A.C.\",\n    \"nombre_comercial\": \"El Tornillo\",\n    \"subdominio\": \"eltornillo\",\n    \"regimen_tributario\": \"rmt\",\n    \"direccion\": {\n        \"direccion\": \"Av. Grau 123, Lima\",\n        \"ubigeo\": \"150101\"\n    },\n    \"administrador\": {\n        \"nombre\": \"Ana Quispe\",\n        \"correo\": \"ana@tornillo.pe\",\n        \"celular\": \"987654321\"\n    },\n    \"certificado\": {\n        \"pfx_base64\": \"MIIK…\",\n        \"clave\": \"clave-del-pfx\"\n    },\n    \"sol\": {\n        \"usuario\": \"FACTURAS1\",\n        \"clave\": \"clave-sol\"\n    }\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "Responde 201 al instante con `estado: creando`; la empresa queda creada en 1 a 3 minutos (consulta\n`GET /empresas/{id}` o espera el webhook `empresa.lista`). Entra con el plan «Socio»: emitir y consultar + API.\n\n- Sin `administrador.contrasena`, el administrador recibe el correo de bienvenida con el enlace para crearla.\n- Con `certificado` y `sol` la empresa pasa a producción y envía directo a SUNAT con su SOL (no descuenta de tu\n  bolsa). Con `envio: pse` (o sin SOL) envía por nuestro PSE, que activamos nosotros, y descuenta de tu bolsa.\n- Como toda empresa nueva, emite cuando su Ficha RUC queda verificada (`pendientes: ficha_ruc`): el\n  administrador la sube en Configuración › Empresa › Régimen tributario."
                    }
                },
                {
                    "name": "Ver una empresa (vuelve a leer su estado)",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        }
                    }
                },
                {
                    "name": "Cambiar contacto, nombre comercial, dirección, certificado, usuario SOL o forma de envío",
                    "request": {
                        "method": "PATCH",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"contacto\": {\n        \"nombre\": \"Rosa\",\n        \"correo\": \"rosa@cliente.pe\"\n    },\n    \"certificado\": {\n        \"pfx_base64\": \"MIIK…\",\n        \"clave\": \"clave\"\n    },\n    \"sol\": {\n        \"usuario\": \"FACTURAS1\",\n        \"clave\": \"clave-sol\"\n    }\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "El RUC, la razón social y el correo del administrador no se cambian por aquí (422)."
                    }
                },
                {
                    "name": "Comprobantes del mes por tipo y lo que descontó de tu bolsa",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/uso",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "uso"
                            ],
                            "query": [
                                {
                                    "key": "mes",
                                    "description": "AAAA-MM (por defecto, el actual)",
                                    "disabled": true
                                }
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        }
                    }
                },
                {
                    "name": "Pausar la emisión por API de una empresa",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/suspender",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "suspender"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"motivo\": \"Cliente con pagos pendientes\"\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "Decisión tuya (por ejemplo, tu cliente no te pagó). Su API v1 responde 423 `suspendida_por_socio` al emitir;\nconsultar sigue funcionando y su web no cambia. Avisa con `empresa.suspendida`."
                    }
                },
                {
                    "name": "Volver a permitir la emisión por API",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/reactivar",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "reactivar"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        }
                    }
                }
            ]
        },
        {
            "name": "Claves",
            "description": "Claves de la API v1 (sfp_live_) de cada empresa, para emitir.",
            "item": [
                {
                    "name": "Listar las claves v1 de la empresa (sin la clave)",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/claves",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "claves"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        }
                    }
                },
                {
                    "name": "Crear una clave v1 (sfp_live_) para emitir con esa empresa",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/claves",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "claves"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                }
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"nombre\": \"Mi sistema · producción\",\n    \"establecimiento\": \"0000\"\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "La clave se muestra UNA sola vez. Sin `permisos`, trae los de emitir y consultar."
                    }
                },
                {
                    "name": "Revocar una clave",
                    "request": {
                        "method": "DELETE",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/empresas/:id/claves/:keyId",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "empresas",
                                ":id",
                                "claves",
                                ":keyId"
                            ],
                            "variable": [
                                {
                                    "key": "id",
                                    "description": "El id de la empresa en esta API (el de GET /empresas)"
                                },
                                {
                                    "key": "keyId"
                                }
                            ]
                        }
                    }
                }
            ]
        },
        {
            "name": "Saldo",
            "description": "Bolsas, consumos, recargas y cuotas.",
            "item": [
                {
                    "name": "Tu saldo, tus bolsas, vencimientos y cuotas pendientes",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/saldo",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "saldo"
                            ]
                        }
                    }
                },
                {
                    "name": "Consumos y recargas, del más nuevo al más viejo",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/movimientos",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "movimientos"
                            ],
                            "query": [
                                {
                                    "key": "tipo",
                                    "value": "consumo",
                                    "disabled": true
                                },
                                {
                                    "key": "empresa_id",
                                    "disabled": true
                                },
                                {
                                    "key": "desde",
                                    "disabled": true
                                },
                                {
                                    "key": "hasta",
                                    "disabled": true
                                },
                                {
                                    "key": "page",
                                    "value": "1",
                                    "disabled": true
                                },
                                {
                                    "key": "per_page",
                                    "value": "20",
                                    "disabled": true
                                }
                            ]
                        }
                    }
                }
            ]
        },
        {
            "name": "Webhooks",
            "item": [
                {
                    "name": "Listar tus webhooks (y los eventos disponibles en meta)",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/webhooks",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "webhooks"
                            ]
                        }
                    }
                },
                {
                    "name": "Registrar un webhook",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/webhooks",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "webhooks"
                            ]
                        },
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"url\": \"https://tusistema.pe/webhooks/sfp\",\n    \"eventos\": [\n        \"empresa.lista\",\n        \"saldo.bajo\",\n        \"saldo.agotado\",\n        \"cuota.vencida\"\n    ]\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "description": "Solo https a un dominio público. El secreto `whsec_…` se muestra una vez; con él verificas `X-SFP-Signature`."
                    }
                },
                {
                    "name": "Borrar un webhook (y su historial)",
                    "request": {
                        "method": "DELETE",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/webhooks/:id",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "webhooks",
                                ":id"
                            ],
                            "variable": [
                                {
                                    "key": "id"
                                }
                            ]
                        }
                    }
                },
                {
                    "name": "Entregas de un webhook",
                    "request": {
                        "method": "GET",
                        "header": [],
                        "url": {
                            "raw": "{{base_url}}/webhooks/:id/entregas",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "webhooks",
                                ":id",
                                "entregas"
                            ],
                            "query": [
                                {
                                    "key": "page",
                                    "value": "1",
                                    "disabled": true
                                },
                                {
                                    "key": "per_page",
                                    "value": "20",
                                    "disabled": true
                                }
                            ],
                            "variable": [
                                {
                                    "key": "id"
                                }
                            ]
                        }
                    }
                },
                {
                    "name": "Reenviar una entrega ya",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Idempotency-Key",
                                "value": "{{$guid}}",
                                "description": "Única por operación: un reintento con la misma clave no emite dos veces."
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/webhooks/entregas/:id/reenviar",
                            "host": [
                                "{{base_url}}"
                            ],
                            "path": [
                                "webhooks",
                                "entregas",
                                ":id",
                                "reenviar"
                            ],
                            "variable": [
                                {
                                    "key": "id"
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}