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 cuatro 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.

Validar un request antes de mandarlo

El spec expresa los requisitos condicionales como if/then de JSON Schema, así que un validador los verifica localmente sin llamar a la API. 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"] }
    }
  ]
}

Esa regla vive en el validador de la API. Publicarla en el schema es lo que evita el error más frecuente al integrar: mandar un receptor CONTRIBUYENTE sin tipoContribuyenteReceptor y descubrirlo recién con un 400. Ver Modelo Receptor.

JSON Schema suelto

Si sólo querés validar un request body, /schemas/v1/{Modelo}.json devuelve ese modelo como JSON Schema 2020-12 autocontenido, con las dependencias inlineadas en $defs:

curl https://sifende.com.py/schemas/v1/FacturaElectronicaRequest.json

Modelos útiles: FacturaElectronicaRequest, NotaCreditoElectronicaRequest, NotaDebitoElectronicaRequest, ReceptorDTO, ItemDTO, ProblemDetail.

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. Actualmente se admiten FACTURA_ELECTRONICA, NOTA_DE_CREDITO_ELECTRONICA y NOTA_DE_DEBITO_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.
• Los errores están en components/responses, con el schema ProblemDetail y ejemplos reales de cada familia. Ver Errores.
• El spec cubre la API de integración y los catálogos públicos, nada más. Los endpoints del panel web (los que se autentican con Keycloak) y los internos no se publican: no son parte del contrato que ofrecemos a terceros. Si estás construyendo un frontend sobre Sifende, esos endpoints siguen documentados en Endpoints de Sesión.

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.