Sifende
Guías

Dar de alta un cliente por API (integradores)

Flujo completo para que el sistema de un integrador dé de alta a un cliente, le asigne plan, lo configure y le entregue su API key de emisión, sin pasar por el portal.

Actualizado el

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.

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

1. Consultar el padrón

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

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

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.

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:

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

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

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

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. Se muestra una sola vez.

6. Crear la API key de emisión

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, igual que cualquier contribuyente.

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 para la lista de control.

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.

En esta página

Usamos cookies necesarias para que el sitio funcione. Con tu permiso, también usamos herramientas de analítica para entender cómo se usa el sitio y para medir nuestras campañas publicitarias. Política de privacidad