# Endpoints de la API integradora (/docs/referencia/integradores/endpoints)



Todas las rutas van bajo `https://api.sifende.com.py/api/v1/integrador` y usan `Authorization: Bearer ik_...`. `{id}` es el `contribuyenteId` del cliente. Ver [API integradora](/docs/referencia/integradores) para la autenticación, el alcance y los errores. Los schemas completos de cada endpoint están en el [explorador de la API](/docs/referencia/api), en la sección **API integradora**.

## Planes y datos para el alta [#planes-y-datos-para-el-alta]

| Método y ruta             | Qué hace                                                                                        |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `GET /planes`             | Lista los planes de tu integrador                                                               |
| `GET /padron/{documento}` | Consulta un RUC o cédula en el padrón, para precargar el alta                                   |
| `POST /autoconfiguracion` | Trae de Marangatu los datos del contribuyente para precargar el alta (body: `usuario`, `clave`) |

## Clientes [#clientes]

| Método y ruta                     | Qué hace                                                                                 |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET /clientes?q=&page=0&size=20` | Lista tu cartera. `q` busca por RUC, razón social o nombre de fantasía; `size` hasta 100 |
| `POST /clientes`                  | Da de alta un cliente, con o sin titular                                                 |
| `GET /clientes/{id}`              | Detalle del cliente                                                                      |
| `GET /clientes/{id}/titular`      | Estado de la invitación al titular                                                       |
| `POST /clientes/{id}/titular`     | Invita al titular, o reenvía la invitación                                               |
| `GET /clientes/{id}/plan`         | Plan actual, plan programado y pagador                                                   |
| `PUT /clientes/{id}/plan`         | Cambia el plan                                                                           |
| `PUT /clientes/{id}/pagador`      | Cambia quién paga: `INTEGRADOR` o `CLIENTE`                                              |

### Alta [#alta]

```bash
curl -X POST https://api.sifende.com.py/api/v1/integrador/clientes \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ruc": "80012345",
    "dv": "6",
    "razonSocial": "Ferretería El Clavo S.A.",
    "tipoContribuyente": "JU",
    "email": "administracion@elclavo.com.py",
    "telefono": "0981123456"
  }'
```

| Campo                                                                               | Requerido | Notas                                              |
| ----------------------------------------------------------------------------------- | --------- | -------------------------------------------------- |
| `ruc`                                                                               | Sí        | Sólo dígitos, sin el dígito verificador            |
| `dv`                                                                                | Sí        | Un dígito                                          |
| `razonSocial`                                                                       | Sí        | Hasta 255 caracteres                               |
| `nombreFantasia`                                                                    | No        | Vacío o 4+ caracteres                              |
| `tipoContribuyente`                                                                 | Sí        | `FI` (persona física) o `JU` (persona jurídica)    |
| `email`, `telefono`                                                                 | Sí        | Contacto del contribuyente                         |
| `direccion`, `actividadesEconomicasCodigos`, `estadoRuc`, `esFacturadorElectronico` | No        | Los podés tomar de `GET /padron/{documento}`       |
| `correoTitular`                                                                     | No        | Si lo mandás, Sifende invita al titular por correo |

Responde `201 Created` con el cliente. El RUC se valida contra el padrón de la DNIT.

### Con o sin titular [#con-o-sin-titular]

El **titular** es la persona del cliente que entra al panel de Sifende. El cliente puede funcionar sin titular: lo configurás y emite con sus API keys aunque nadie del cliente tenga usuario. Cuando quieras darle acceso, invitalo:

```bash
curl -X POST https://api.sifende.com.py/api/v1/integrador/clientes/$ID/titular \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correoTitular": "duenho@elclavo.com.py"}'
```

Si el cliente ya tiene titular, responde `409` con `codigo` `TITULAR_YA_ASIGNADO`.

### Plan y pagador [#plan-y-pagador]

```json
PUT /clientes/{id}/plan
{"planId": 12, "versionEsperada": 3}
```

`planId` y `versionEsperada` son el `planId` y el `versionId` de un plan de `GET /planes`. Si Sifende cambió el plan después de que lo leíste, el cambio se rechaza: volvé a leer los planes y reintentá.

```json
PUT /clientes/{id}/pagador
{"pagador": "CLIENTE"}
```

Un cliente nuevo paga él mismo. Si vas a pagar vos, cambiá el pagador antes de asignar el plan, para que el primer ciclo no se le cobre al cliente. Con un ciclo en curso, el cambio rige desde la próxima renovación y `GET /clientes/{id}/plan` lo muestra como programado.

## Configuración fiscal [#configuración-fiscal]

| Método y ruta                                                 | Qué hace                                                        |
| ------------------------------------------------------------- | --------------------------------------------------------------- |
| `GET /clientes/{id}/configuracion-fiscal`                     | Estado de certificado, timbrado y CSC                           |
| `POST /clientes/{id}/configuracion-fiscal/certificado`        | Carga el `.p12` (multipart: `file`, `password`, `idCsc`, `csc`) |
| `PUT /clientes/{id}/configuracion-fiscal/timbrado`            | Guarda el timbrado de producción                                |
| `PUT /clientes/{id}/configuracion-fiscal/csc`                 | Guarda el CSC de producción                                     |
| `POST /clientes/{id}/configuracion-fiscal/pasar-a-produccion` | Pasa el cliente a producción                                    |

```bash
curl -X POST https://api.sifende.com.py/api/v1/integrador/clientes/$ID/configuracion-fiscal/certificado \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -F "file=@certificado.p12" \
  -F "password=$P12_PASSWORD" \
  -F "idCsc=1" \
  -F "csc=$CSC"
```

## Establecimientos [#establecimientos]

| Método y ruta                                                                         | Qué hace                                      |
| ------------------------------------------------------------------------------------- | --------------------------------------------- |
| `GET /clientes/{id}/establecimientos`                                                 | Lista establecimientos y puntos de expedición |
| `POST /clientes/{id}/establecimientos`                                                | Crea un establecimiento                       |
| `PUT /clientes/{id}/establecimientos/{establecimientoId}`                             | Actualiza un establecimiento                  |
| `POST /clientes/{id}/establecimientos/{establecimientoId}/puntos-expedicion`          | Crea un punto de expedición                   |
| `PUT /clientes/{id}/establecimientos/{establecimientoId}/puntos-expedicion/{puntoId}` | Actualiza un punto de expedición              |

## Solicitud de certificado [#solicitud-de-certificado]

Si el cliente todavía no tiene certificado, podés preparar la solicitud. La **firma del formulario F1 sigue siendo del titular**: la API le envía el pedido de firma, pero no puede firmar por él.

| Método y ruta                                                          | Qué hace                                            |
| ---------------------------------------------------------------------- | --------------------------------------------------- |
| `GET /clientes/{id}/solicitud-certificado`                             | Estado del trámite                                  |
| `POST /clientes/{id}/solicitud-certificado`                            | Crea la solicitud                                   |
| `PUT /clientes/{id}/solicitud-certificado`                             | Guarda los datos de la solicitud                    |
| `POST /clientes/{id}/solicitud-certificado/documentos`                 | Adjunta un documento (multipart: `tipo`, `archivo`) |
| `POST /clientes/{id}/solicitud-certificado/documentos/marangatu`       | Importa documentos desde Marangatu                  |
| `GET /clientes/{id}/solicitud-certificado/documentos/{documentoId}`    | Descarga un documento                               |
| `DELETE /clientes/{id}/solicitud-certificado/documentos/{documentoId}` | Quita un documento                                  |
| `GET /clientes/{id}/solicitud-certificado/formulario-f1`               | Descarga el F1 en PDF                               |
| `POST /clientes/{id}/solicitud-certificado/firma`                      | Envía el pedido de firma del F1                     |
| `POST /clientes/{id}/solicitud-certificado/enviar`                     | Envía la solicitud                                  |
| `POST /clientes/{id}/solicitud-certificado/cancelar`                   | Cancela la solicitud                                |

## Personalización [#personalización]

| Método y ruta                                | Qué hace                            |
| -------------------------------------------- | ----------------------------------- |
| `GET /clientes/{id}/personalizacion`         | Marca, colores y datos de la cuenta |
| `PUT /clientes/{id}/personalizacion`         | Actualiza la personalización        |
| `PUT /clientes/{id}/personalizacion/cuenta`  | Actualiza los datos de la cuenta    |
| `POST /clientes/{id}/personalizacion/logo`   | Sube el logo (multipart: `file`)    |
| `DELETE /clientes/{id}/personalizacion/logo` | Borra el logo                       |

## Webhooks del cliente [#webhooks-del-cliente]

Los mismos webhooks de la [referencia de webhooks](/docs/referencia/webhooks), administrados por vos para cada cliente: mismos eventos, firma, reintentos y reglas de URL.

| Método y ruta                                               | Qué hace                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /clientes/{id}/webhooks`                               | Lista los webhooks del cliente                                |
| `POST /clientes/{id}/webhooks`                              | Crea un webhook y devuelve su secreto                         |
| `GET /clientes/{id}/webhooks/{webhookId}`                   | Consulta un webhook                                           |
| `PUT /clientes/{id}/webhooks/{webhookId}`                   | Actualiza URL, eventos y estado                               |
| `DELETE /clientes/{id}/webhooks/{webhookId}`                | Elimina el webhook                                            |
| `POST /clientes/{id}/webhooks/{webhookId}/rotar`            | Genera un secreto nuevo                                       |
| `GET /clientes/{id}/webhooks/entregas`                      | Entregas, filtrables por `webhookId`, `estado` y `tipoEvento` |
| `GET /clientes/{id}/webhooks/entregas/{entregaId}/intentos` | Intentos de una entrega                                       |

```bash
curl -X POST https://api.sifende.com.py/api/v1/integrador/clientes/$ID/webhooks \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.ejemplo.com.py/sifende/webhook",
    "eventos": ["documento.aprobado", "documento.rechazado"],
    "ambiente": "PROD"
  }'
```

`ambiente` es obligatorio (`SANDBOX`, `DEV` o `PROD`) porque la key integradora no tiene ambiente. El secreto se devuelve una sola vez.

## API keys del cliente [#api-keys-del-cliente]

Las claves `sk_…` con las que el cliente emite. Ves y administrás sólo las que creó tu integrador.

| Método y ruta                                   | Qué hace                                               |
| ----------------------------------------------- | ------------------------------------------------------ |
| `GET /clientes/{id}/api-keys`                   | Lista las keys creadas por tu integrador               |
| `POST /clientes/{id}/api-keys`                  | Crea una key y devuelve el valor completo              |
| `POST /clientes/{id}/api-keys/{apiKeyId}/rotar` | Rota la key; la anterior deja de funcionar al instante |
| `DELETE /clientes/{id}/api-keys/{apiKeyId}`     | Revoca la key                                          |

```json
POST /clientes/{id}/api-keys
{"nombre": "ERP - caja central", "ambiente": "PROD"}
```

La respuesta trae `key` con el valor completo; se muestra una sola vez. `expiraEn` es opcional.
