# OpenAPI y JSON Schema (/docs/referencia/openapi)



El contrato de la API está publicado como un documento OpenAPI 3.1. La disponibilidad de los tipos de documento se detalla abajo.

## URLs [#urls]

| Recurso                                | URL                                               |
| -------------------------------------- | ------------------------------------------------- |
| Explorador interactivo                 | [/docs/referencia/api](/docs/referencia/api)      |
| Spec OpenAPI (URL estable, versionada) | `https://sifende.com.py/openapi/v1.json`          |
| JSON Schema de un modelo               | `https://sifende.com.py/schemas/v1/{Modelo}.json` |

Las tres son públicas: no hace falta API key para leerlas.

El [Explorador de la API](/docs/referencia/api) se genera desde este mismo spec: trae el schema completo de cada endpoint, ejemplos en cURL, JavaScript, Python y Java, y un playground para probar las llamadas con tu API key.

<Callout type="info">
  Para fijar en tu build usá `https://sifende.com.py/openapi/v1.json`. El `v1` es la versión de la API — la misma del prefijo `/api/v1/` — y no cambia mientras no haya una v2. Ver [Versionado](/docs/referencia/versionado).
</Callout>

## Nombres de JSON Schema [#nombres-de-json-schema]

Reemplazá `{Modelo}` por el nombre exacto, respetando mayúsculas y sufijos. Estos identificadores forman parte de las URLs públicas:

| Modelo                                 | Nombre para la URL                                                    |
| -------------------------------------- | --------------------------------------------------------------------- |
| Factura electrónica                    | `FacturaElectronicaRequest`                                           |
| Nota de crédito                        | `NotaCreditoElectronicaRequest`                                       |
| Nota de débito                         | `NotaDebitoElectronicaRequest`                                        |
| Nota de remisión                       | `NotaRemisionElectronicaRequest`                                      |
| Receptor de emisión                    | `ReceptorDTO`                                                         |
| Ítem de FE/NCE/NDE                     | `ItemDTO`                                                             |
| Ítem de NRE                            | `ItemRemisionDTO`                                                     |
| Condición de pago                      | `CondicionPagoDTO`                                                    |
| Cuota y plazo estructurado             | `CuotaCreditoDTO`, `PlazoEstructuradoDTO`                             |
| Compras públicas                       | `ComprasPublicasDTO`                                                  |
| Documento asociado de FE/NCE/NDE       | `DocumentoAsociadoDTO`                                                |
| Documento asociado de NRE              | `DocumentoAsociadoRemisionDTO`                                        |
| Transporte y locales de NRE            | `TransporteRemisionDTO`, `LocalRemisionDTO`                           |
| Vehículo, transportista y carga de NRE | `VehiculoRemisionDTO`, `TransportistaRemisionDTO`, `CargaRemisionDTO` |
| Nominación y su receptor               | `EventoNominacionRequest`, `ReceptorNominadoRequest`                  |
| Cancelación                            | `CancelacionRequest`                                                  |
| Inutilización                          | `EventoInutilizacionRequest`                                          |
| Respuesta de emisión                   | `DocumentoElectronicoEmisionResponseDTO`                              |
| Estado del documento                   | `DocumentoElectronicoStatusDTO`                                       |
| Respuesta de evento                    | `EventoSifenDTO`                                                      |

Por ejemplo, el schema de una FE está en `https://sifende.com.py/schemas/v1/FacturaElectronicaRequest.json`. Cada schema incluye sus dependencias en `$defs`; no necesitás descargar el receptor o los ítems por separado para resolver esas referencias.

Para obtener todos los nombres disponibles en la versión publicada:

```bash
curl --fail --silent --show-error https://sifende.com.py/openapi/v1.json \
  | jq -r '.components.schemas | keys[]'
```

Un nombre inexistente devuelve `404`. La presencia de un schema no habilita por sí sola una operación: verificá la disponibilidad en el modelo correspondiente.

## Validar una solicitud antes de mandarla [#validar-una-solicitud-antes-de-mandarla]

El spec expresa requisitos condicionales como `if`/`then` de JSON Schema, así que un validador puede verificarlos localmente sin llamar a la API. La validación local no sustituye las reglas de negocio de la API, como la elegibilidad de una nominación o la correspondencia entre el RUC fusionado y el CDC. El caso más común es el receptor:

```json
{
  "allOf": [
    {
      "if": {
        "properties": { "tipoContribuyente": { "const": "CONTRIBUYENTE" } },
        "required": ["tipoContribuyente"]
      },
      "then": { "required": ["tipoContribuyenteReceptor", "digitoVerificador"] }
    },
    {
      "if": {
        "properties": { "tipoContribuyente": { "const": "NO_CONTRIBUYENTE" } },
        "required": ["tipoContribuyente"]
      },
      "then": { "required": ["tipoDocumento"] }
    }
  ]
}
```

La validación local permite detectar si mandás un receptor `CONTRIBUYENTE` sin `tipoContribuyenteReceptor` antes de llamar a la API. Ver [Modelo Receptor](/docs/referencia/modelos/receptor).

## Generar un cliente [#generar-un-cliente]

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://sifende.com.py/openapi/v1.json \
  -g typescript-fetch \
  -o ./sifende-client
```

El spec usa OpenAPI 3.1 (JSON Schema 2020-12). Un generador que sólo soporte 3.0 puede ignorar `if`/`then` y `const`: la estructura sale bien, pero las reglas condicionales se pierden y hay que validarlas aparte.

## Cómo está organizado [#cómo-está-organizado]

* **`tipoDocumento` es el discriminador.** Se admiten `FACTURA_ELECTRONICA`, `AUTOFACTURA_ELECTRONICA`, `NOTA_DE_CREDITO_ELECTRONICA`, `NOTA_DE_DEBITO_ELECTRONICA` y `NOTA_DE_REMISION_ELECTRONICA`; no envíes otros tipos.
* **Los valores de enumeración son los que la API deserializa** (`CONTRIBUYENTE`, no `"CONTRIBUYENTE - Contribuyente"`). El catálogo completo, con las descripciones, está en [`GET /api/v1/public/enums`](/docs/referencia/catalogos/enumeraciones).
* **Cada operación incluye sus respuestas de error**, con el formato Problem Details y ejemplos. Ver [Errores](/docs/referencia/errores).
* **El spec cubre la API de integración, la [API integradora](/docs/referencia/integradores) y los catálogos públicos.** Para configurar tu cuenta, seguí las [guías del panel](/docs/panel).

## Para agentes de IA [#para-agentes-de-ia]

`https://sifende.com.py/llms-full.txt` sirve la documentación completa **con el spec incluido** en un solo archivo, pensado para cargarlo como contexto. Es el punto de partida recomendado si estás integrando con un agente: la prosa da el contexto y el spec da el contrato exacto, incluidos los campos condicionales.
