# API integradora (/docs/referencia/integradores)



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.

<Callout type="info">
  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](/docs/referencia/autenticacion).
</Callout>

## Crear la key integradora [#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 [#autenticación]

```http
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 [#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 [#respuestas]

Las respuestas exitosas vienen en el envelope `ApiResponse`:

```json
{
  "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 [#errores]

Los errores de operación usan [Problem Details](/docs/referencia/errores) 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`](/docs/solucion-problemas/solo-integrador)                   |
| `409`  | `SOCIO_INACTIVO`              | El integrador está inactivo. Ver [`socio-inactivo`](/docs/solucion-problemas/socio-inactivo)                                   |
| `409`  | `TITULAR_YA_ASIGNADO`         | Se invitó al titular de un cliente que ya tiene uno. Ver [`titular-ya-asignado`](/docs/solucion-problemas/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 [#siguientes-pasos]

* [Endpoints](/docs/referencia/integradores/endpoints): la lista completa con ejemplos.
* [Explorador de la API](/docs/referencia/api): cada endpoint con sus schemas y un playground, en la sección **API integradora**.
* [Guía: dar de alta un cliente por API](/docs/guias/alta-cliente-integrador): el flujo de punta a punta.
