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.
Actualizado el
La API integradora es para los socios integradores: los ERP, sistemas de gestión y estudios que venden Sifende a sus clientes con planes propios. Con ella, tu sistema hace por API lo que hoy hacés en el portal de socios: dar de alta un cliente, asignarle plan, cargar su certificado, configurar establecimientos, webhooks y personalización, y crearle las API keys con las que va a emitir.
La API integradora no emite documentos. Cada cliente emite con su propia API key sk_…, que podés crear con esta API. Ver Autenticación.
Crear la key integradora
Un usuario ADMIN del integrador la crea en el portal de socios, en API integradora → Crear key. La key completa empieza con ik_ y se muestra una sola vez; Sifende guarda sólo su hash.
- La key es del integrador, no de quien la creó: sigue funcionando aunque esa persona deje el equipo.
- No tiene ambiente. Los recursos que lo tienen (API keys y webhooks del cliente) lo reciben en el body.
- Rotar invalida la anterior al instante. Para cambiarla sin corte, creá otra, configurala y revocá la anterior.
- Lo que hagas con la key queda en la auditoría del portal a nombre de quien la creó, marcado como hecho por API.
Autenticación
Authorization: Bearer ik_...Todos los endpoints viven bajo https://api.sifende.com.py/api/v1/integrador. Son para llamar desde tu servidor: no aceptan pedidos desde el navegador (sin CORS), y la key no debe viajar en una app ni en un frontend.
Una key integradora no abre la API de emisión ni el portal, y una API key de cliente (sk_…) no abre la API integradora.
Alcance
La key ve sólo a los clientes atribuidos a tu integrador. Si un cliente deja de estar atribuido (porque se fue o porque se desactivó el integrador), la API responde 404 para él, igual que para uno inexistente. Las mismas reglas del portal valen acá: los errores, límites y validaciones son los mismos.
Respuestas
Las respuestas exitosas vienen en el envelope ApiResponse:
{
"data": { "...": "..." },
"timestamp": "2026-11-13T10:15:00-03:00",
"errors": null
}Los DELETE responden 204 No Content. Las descargas (documentos de la solicitud de certificado y el formulario F1) devuelven el archivo.
Errores
Los errores de operación usan Problem Details y suman un campo codigo con el motivo:
| Status | codigo | Qué significa |
|---|---|---|
401 | — | Key ausente, inválida o revocada. El cuerpo es {"error": "API key integradora inválida o revocada"} |
403 | SOLO_INTEGRADOR | El socio dueño de la key no es integrador. Ver solo-integrador |
409 | SOCIO_INACTIVO | El integrador está inactivo. Ver socio-inactivo |
409 | TITULAR_YA_ASIGNADO | Se invitó al titular de un cliente que ya tiene uno. Ver titular-ya-asignado |
400 | — | Validación del body; el detalle indica el campo |
404 | CONTRIBUYENTE_NO_ENCONTRADO | El cliente no existe o no está atribuido a tu integrador |
Siguientes pasos
- Endpoints: la lista completa con ejemplos.
- Explorador de la API: cada endpoint con sus schemas y un playground, en la sección API integradora.
- Guía: dar de alta un cliente por API: el flujo de punta a punta.
Administrar webhooks por API
CRUD de webhooks con API key: /api/v1/contribuyente/webhooks para registrar la URL, elegir eventos, rotar el secreto y consultar las entregas sin entrar al panel.
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.