Endpoints de la API integradora
Rutas de /api/v1/integrador para administrar clientes: alta, titular, plan, pagador, configuración fiscal, certificado, establecimientos, personalización, webhooks y API keys.
Actualizado el
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 para la autenticación, el alcance y los errores. Los schemas completos de cada endpoint están en el explorador de la API, en la sección API integradora.
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
| 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
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
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:
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
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á.
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
| 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 |
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
| 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
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
| 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
Los mismos webhooks de la referencia de 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 |
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
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 |
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.
API integradora
Para socios integradores: dar de alta y configurar a sus clientes desde su propio sistema con una key integradora ik_, sin cargarlos a mano en el portal.
Enumeraciones SIFEN (Endpoint)
GET /api/v1/public/enums — endpoint público que lista en tiempo real todos los valores válidos de las enumeraciones SIFEN, con su name, label y código.