OpenAPI y JSON Schema

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

URLs

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

El Explorador de la 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.

Nombres de JSON Schema

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

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:

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

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:

{
  "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.

Generar un cliente

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á armado

• 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.
• Cada operación incluye sus respuestas de error, con el formato Problem Details y ejemplos. Ver Errores.
• El spec cubre la API de integración y los catálogos públicos. Para configurar tu cuenta, seguí las guías del panel.

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.