# Dar de alta un cliente por API (integradores) (/docs/guias/alta-cliente-integrador)



Esta guía es para socios **integradores**. Al terminarla, tu sistema da de alta a un cliente y lo deja emitiendo sin que nadie lo cargue a mano en el portal. Antes, creá una key integradora `ik_…` en el portal de socios (**API integradora**, sólo ADMIN). Ver [API integradora](/docs/referencia/integradores).

```bash
export SIFENDE_INTEGRADOR_KEY="ik_..."
export BASE="https://api.sifende.com.py/api/v1/integrador"
```

## 1. Consultar el padrón [#1-consultar-el-padrón]

```bash
curl "$BASE/padron/80012345" -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY"
```

Usá la respuesta para completar razón social, tipo, dirección y actividades del alta. Si tenés el usuario y la clave de Marangatu del cliente, `POST /autoconfiguracion` trae los mismos datos y los de facturación electrónica.

## 2. Dar de alta al cliente [#2-dar-de-alta-al-cliente]

```bash
curl -X POST "$BASE/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"
  }'
```

Guardá el `contribuyenteId` de la respuesta: es el `{id}` de todos los pasos siguientes.

Sin `correoTitular`, el cliente queda **sin titular**: nadie del cliente entra al panel y vos lo administrás todo. Cuando quieras darle acceso, invitalo con `POST /clientes/{id}/titular`.

## 3. Definir pagador y plan [#3-definir-pagador-y-plan]

Un cliente nuevo paga él mismo. Si vas a pagar vos, definí el pagador **antes** de asignar el plan: así el primer ciclo entra en tu factura mensual consolidada en lugar de cobrársele al cliente.

```bash
curl -X PUT "$BASE/clientes/$ID/pagador" \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pagador": "INTEGRADOR"}'
```

Después elegí el plan. `planId` y `versionEsperada` son el `planId` y el `versionId` de `GET /planes`:

```bash
curl "$BASE/planes" -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY"

curl -X PUT "$BASE/clientes/$ID/plan" \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"planId": 12, "versionEsperada": 3}'
```

Un cambio de pagador en un cliente que ya tiene un ciclo en curso rige desde la próxima renovación.

## 4. Configurar la parte fiscal [#4-configurar-la-parte-fiscal]

Si el cliente ya tiene certificado, subilo con su CSC:

```bash
curl -X POST "$BASE/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"
```

Después cargá establecimientos y puntos de expedición en `/clientes/{id}/establecimientos`, y el timbrado con `PUT /clientes/{id}/configuracion-fiscal/timbrado`. `GET /clientes/{id}/configuracion-fiscal` te dice qué falta.

Si no tiene certificado, prepará la solicitud en `/clientes/{id}/solicitud-certificado`. El formulario F1 lo firma el titular: `POST …/firma` le envía el pedido, así que el cliente necesita titular para este paso.

## 5. Registrar el webhook [#5-registrar-el-webhook]

```bash
curl -X POST "$BASE/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": "DEV"
  }'
```

Guardá el secreto de la respuesta para [verificar la firma](/docs/referencia/webhooks). Se muestra una sola vez.

## 6. Crear la API key de emisión [#6-crear-la-api-key-de-emisión]

```bash
curl -X POST "$BASE/clientes/$ID/api-keys" \
  -H "Authorization: Bearer $SIFENDE_INTEGRADOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "ERP - pruebas", "ambiente": "DEV"}'
```

La respuesta trae `key` (`sk_test_…`) completa una sola vez. Con esa key el cliente emite por la [API de integración](/docs/guias/factura-electronica), igual que cualquier contribuyente.

## 7. Pasar a producción [#7-pasar-a-producción]

Cuando las pruebas estén bien, llamá a `POST /clientes/{id}/configuracion-fiscal/pasar-a-produccion` con `rucConfirmacion` (el RUC del cliente, sin DV). Si todavía no cargaste timbrado y CSC de producción, mandalos en el mismo body: `numeroTimbrado`, `fechaInicioTimbrado`, `idCsc` y `csc`. Después creá una key y un webhook con `"ambiente": "PROD"`. Ver [Ir a producción](/docs/guias/ir-a-produccion) para la lista de control.

## Si el cliente se va [#si-el-cliente-se-va]

Si el cliente deja tu integrador, la key integradora deja de verlo (`404`) y **se desactivan las API keys que creaste para él**: tu sistema deja de poder emitir en su nombre. Deja de estar a tu cargo como pagador y, si estaba en un plan tuyo, pasa al plan inicial. Lo mismo pasa con todos tus clientes si se desactiva el integrador.
