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.