Ventanilla única del IVA (OSS)

La ventanilla única del IVA permite declarar en un solo modelo, el 369 trimestral, el IVA de las ventas de servicios electrónicos (y, en el régimen de la Unión, de las ventas a distancia de bienes) a consumidores finales de otros Estados miembros. Cada venta lleva el IVA del país donde está el consumidor, no el de tu organización.

Con la API, tu aplicación emite esas facturas con taxSystem: "EU_OSS". UTILIA OS comprueba las reglas, resuelve el tipo de IVA del país del consumidor en la fecha de la venta, lo congela en la factura y deja la operación lista para el modelo 369 de tu organización. El alta en la ventanilla única (el modelo 035) y su periodo los registra tu organización en UTILIA OS, no tu aplicación.

Plan, permisos y disponibilidad

• Disponibilidad: la función está en «Próximamente». Antes que nada se comprueba si está disponible para tu organización; si no, 403 FEATURE_COMING_SOON. No es un bloqueo de plan ni de permisos, así que no se resuelve ampliando el plan ni concediendo permisos: no lo reintentes. En los SDK se reconoce con isFeatureComingSoonError (is_feature_coming_soon_error en Python). Ver Funciones que llegan próximamente.
• Plan: el aplicativo Finanzas, como el resto de las facturas.
• Permisos de la aplicación: los de siempre. Emitir exige crm:invoices:write y crm:invoices:issue, y consultar los tipos de IVA, crm:invoices:read. No hay permisos nuevos.

Qué régimen usa tu organización

El régimen lo decide dónde está establecida tu organización, no tu aplicación. Cada factura EU_OSS lleva en ossScheme el régimen con el que se emitió.

Algunos detalles de cada régimen:

• Régimen exterior. Los consumidores de Canarias tributan por el IGIC, y los de Ceuta y Melilla por el IPSI: no van por la ventanilla única. Si tu organización tiene vigente el régimen exterior, una venta de servicios a un consumidor de la Unión, también de la península, tiene que ir con EU_OSS. Con otro sistema, 400 OSS_DESTINATION_VAT_REQUIRED.
• Régimen de la Unión: el umbral. Se suman, sin IVA, los servicios de telecomunicaciones, radiodifusión y electrónicos a consumidores de otros Estados miembros y las ventas a distancia de bienes, del año en curso y del anterior. La venta que cruza el umbral ya va con el IVA del país del consumidor.
• Régimen de la Unión: la opción. Se ejerce en el modelo 036 y dura al menos dos años naturales.
• Régimen de la Unión, sin umbral ni opción. La venta va con IVA español, y una factura EU_OSS da 400 OSS_DESTINATION_NOT_APPLICABLE.
• Régimen de la Unión, con umbral superado u opción vigente. Una factura con IVA español a un consumidor de otro Estado da 400 OSS_THRESHOLD_EXCEEDED (umbral superado) u OSS_DESTINATION_VAT_REQUIRED (opción vigente). El mensaje dice si hay que darse de alta antes en la ventanilla única.
• Sin periodo de alta vigente en la fecha de la venta, 400 OSS_NOT_REGISTERED.
• Régimen y régimen fiscal de la organización. Si no cuadran (por ejemplo, un régimen exterior en una organización de la península), 400 OSS_SCHEME_REGIME_MISMATCH.

Ventas por tiendas de aplicaciones

Si vendes tu aplicación o sus suscripciones a través de una tienda (App Store, Google Play u otra) que cobra al cliente o fija las condiciones, la ley presume que la tienda vende en nombre propio. La venta al consumidor es de la tienda, no tuya:

• No factures esas ventas como ventas a consumidores ni por la ventanilla única: la tienda es quien repercute el IVA al consumidor.
• Lo que tú facturas es la venta a la tienda, entre empresas y fuera de la ventanilla única.
• Por la ventanilla única solo van tus ventas directas: las que cobras en tu web o con tu propia pasarela de pago.

UTILIA OS no puede saber por qué canal se hizo cada venta: decidirlo es responsabilidad de tu aplicación.

Requisitos de una factura EU_OSS

La factura imprime «IVA del país del consumidor (ventanilla única)», el rótulo de cada tipo («IVA Francia 20 %») y «Estado miembro de consumo: Francia». Las simplificadas y las ordinarias van en series separadas, y conviene numerar estas ventas en una serie propia de tu aplicación con seriesCode.

El tipo de IVA de cada línea

Tu aplicación no fija el porcentaje. En cada línea EU_VAT indica la clase del tipo con vatRateClass y UTILIA OS resuelve el porcentaje del país del consumidor para esa clase en la fecha de expedición:

ossSupplyType dice qué vendes: SERVICES, el valor por defecto, o GOODS, una venta a distancia de bienes, solo en el régimen de la Unión.

Cada Estado solo tiene algunas clases. Si el país no tiene tipo para esa clase en esa fecha, la respuesta es 400 OSS_RATE_NOT_AVAILABLE con lineNumber: nunca se factura al 0 % por defecto. El porcentaje queda congelado en la línea (taxRate): aunque el país cambie su tipo después, la factura y sus rectificativas conservan el que se aplicó. Con pricesIncludeTax: true, la base se calcula con ese porcentaje.

Consultar los tipos vigentes

Para calcular tus precios antes de facturar, pide los tipos del país y la fecha. Lo que devuelve esta consulta es lo que se aplicará al emitir.

{
  "date": "2026-10-15",
  "rates": [
    {
      "countryCode": "FR",
      "vatCountryCode": "FR",
      "countryName": "Francia",
      "rateClass": "STANDARD",
      "rateClassLabel": "tipo general",
      "percentage": 20,
      "validFrom": "2014-01-01",
      "validTo": null,
      "label": "Francia: tipo general",
      "sourceRef": "https://ec.europa.eu/taxation_customs/tedb/"
    }
  ]
}

datequery

Fecha AAAA-MM-DD. Por defecto, hoy en la zona horaria de tu organización. Para una factura es su fecha de expedición.

countryquery

Estado miembro en ISO 3166-1 alfa-2 (Grecia es GR). Sin él, los 27. Un país que no es de la Unión da 400 OSS_COUNTRY_NOT_ALLOWED.

rates[].vatCountryCodestringobligatorio

Código del Estado en el sistema IVA de la Unión: coincide con countryCode salvo Grecia (EL).

rates[].rateClassenumobligatorio

La clase, el valor que mandas en vatRateClass.

rates[].percentagenumberobligatorio

Porcentaje exacto del tipo.

rates[].validFrom / validTostringobligatorio

Vigencia, inclusiva. validTo es nulo si sigue vigente.

rates[].sourceRefstringobligatorio

Fuente oficial del tipo.

La prueba de la ubicación del consumidor

La norma exige que conserves dos elementos de prueba no contradictorios de dónde está el consumidor. Tu aplicación los conoce; UTILIA OS solo guarda de cada uno su tipo, el país que se deduce de él y, si es España, la región. Nunca la dirección IP, la dirección postal, el número de cuenta ni el teléfono.

consumerResidence.evidenceItems[].typeenumobligatorio

BILLING_ADDRESS (dirección de facturación), IP_GEOLOCATION (dirección IP o geolocalización), BANK_ACCOUNT (datos bancarios), MOBILE_COUNTRY_CODE (código de país de la tarjeta SIM), FIXED_LINE (línea fija) u OTHER_COMMERCIAL (otra información comercialmente relevante).

consumerResidence.evidenceItems[].countryCodestringobligatorio

País que se deduce del elemento, ISO 3166-1 alfa-2 (Grecia es GR). Solo el país.

consumerResidence.evidenceItems[].regionenum

Solo con countryCode ES: PENINSULA_BALEARES, CANARIAS, CEUTA o MELILLA.

consumerResidence.evidenceItems[].thirdPartyboolean

El elemento lo facilitó un tercero que interviene en el cobro (por ejemplo, tu pasarela de pago), distinto de ti y del consumidor.

Las reglas, que UTILIA OS comprueba en cada factura:

• Dos elementos de tipos distintos, todos con el país de consumo. Entre 1 y 10 elementos en total.
• Un solo elemento facilitado por un tercero (thirdParty: true) basta únicamente en el régimen de la Unión y si las ventas de tu organización a consumidores de otros Estados no pasan de 100.000 € este año ni el anterior. En el régimen exterior siempre hacen falta dos.
• Consumidor de España (régimen exterior). El código de país del móvil y el banco español no distinguen Canarias, Ceuta y Melilla de la península. Por eso, al menos un elemento (el código postal de facturación o la geolocalización) debe llevar region: "PENINSULA_BALEARES" y ninguno otra región. Los que no distinguen la región van sin ella.
• Si la prueba no basta o se contradice, 400 OSS_LOCATION_EVIDENCE_INSUFFICIENT. evidenceItems fuera de EU_OSS da 400 VALIDATION_ERROR.

La prueba se conserva con la factura para el registro de la ventanilla única y no se devuelve nunca: ni en la respuesta, ni en metadata, ni en los avisos.

Ejemplo: organización canaria que vende a un consumidor de Francia

Tu organización está establecida en Canarias y tiene vigente el régimen exterior. Un consumidor de París paga 47,99 € con tu pasarela.

curl -X POST https://os.utilia.ai/api/external/v1/invoices \
  -H "X-Api-Key: utl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SIMPLIFIED",
    "user": { "externalId": "user_01HXYZ", "email": "camille@example.fr" },
    "taxSystem": "EU_OSS",
    "pricesIncludeTax": true,
    "lines": [
      { "name": "Plan Profesional", "quantity": 1, "unitPrice": 47.99, "taxType": "EU_VAT", "vatRateClass": "STANDARD" }
    ],
    "consumerResidence": {
      "region": "OTHER_EU",
      "countryCode": "FR",
      "evidenceItems": [
        { "type": "BILLING_ADDRESS", "countryCode": "FR" },
        { "type": "BANK_ACCOUNT", "countryCode": "FR", "thirdParty": true }
      ]
    },
    "payment": { "method": "CARD", "reference": "pi_3QossFR" },
    "seriesCode": "APPT",
    "idempotencyKey": "pedido-fr-1"
  }'

La respuesta trae la factura con el tipo de Francia resuelto y congelado (20 %: base 39,99 € y cuota 8,00 €):

{
  "id": "ckoss1234567890",
  "invoiceNumber": "APPT-202600001",
  "type": "SIMPLIFIED",
  "seriesCode": "APPT",
  "taxSystem": "EU_OSS",
  "consumerCountryCode": "FR",
  "ossScheme": "OSS_NON_UNION_SCHEME",
  "status": "PAID",
  "legalMentions": [
    "Factura simplificada (RD 1619/2012 art. 7)",
    "IVA del país del consumidor (ventanilla única)",
    "Estado miembro de consumo: Francia",
    "Tipo aplicado: IVA Francia 20 % (IVA incluido)"
  ],
  "pricesIncludeTax": true,
  "paymentRegistered": true,
  "totalAmount": 47.99,
  "paidAmount": 47.99,
  "currency": "eur",
  "idempotent": false
}

En el detalle (GET /external/v1/invoices/:id), cada línea trae taxRate: 20, vatRateClass: "STANDARD" y ossSupplyType: "SERVICES", y cada tramo de impuestos, su vatRateClass.

Si el consumidor estuviera en la península, la factura sería igual con region: "PENINSULA_BALEARES" (sin countryCode) y una prueba con país ES, uno de cuyos elementos lleve region: "PENINSULA_BALEARES": IVA español al 21 % por la ventanilla única, con consumerCountryCode: "ES".

Rectificativas

Se emiten por la ruta de siempre, POST /external/v1/invoices/:id/rectifications, sin campos nuevos:

• La rectificativa de una factura EU_OSS hereda su sistema, su país de consumo, su régimen y los porcentajes congelados de cada línea, aunque el país haya cambiado su tipo después.
• Va a la serie de rectificativas (R-).
• Si la ventanilla única no está disponible para tu organización, la rectificativa de una factura EU_OSS también responde 403 FEATURE_COMING_SOON.
• En el modelo 369, tu organización compensa las rectificativas del mismo trimestre y declara las de trimestres anteriores como correcciones, hasta tres años después.

Suscripciones

POST y PATCH /external/v1/subscriptions admiten lo mismo: taxSystem: "EU_OSS", consumerResidence con evidenceItems y líneas EU_VAT con vatRateClass y ossSupplyType.

• La residencia de una suscripción solo admite OTHER_EU y PENINSULA_BALEARES, y no usa evidence (texto libre).
• Cada cuota es una venta distinta: el generador vuelve a comprobar el periodo de alta vigente y resuelve el tipo de IVA en la fecha de esa cuota.
• Si el consumidor cambia de país, actualiza consumerResidence con PATCH.
• El detalle trae consumerCountryCode, y cada factura generada, su taxSystem, su consumerCountryCode y su ossScheme.

Respuestas y avisos

• Respuestas. Cada factura, EU_OSS o no, trae taxSystem, consumerCountryCode (nulo si no hay consumidor de otro país) y ossScheme (nulo fuera de EU_OSS). Cada línea trae vatRateClass y ossSupplyType, nulos fuera de EU_VAT.
• Avisos. El objeto invoice de los avisos INVOICE_* lleva taxSystem, consumerCountryCode y ossScheme. En la difusión de las facturas que emite tu equipo, consumerCountryCode llega nulo. Los avisos no llevan líneas ni la prueba de la ubicación. Ver Avisos.

Errores

Todos llegan antes de numerar: un rechazo no consume número. Los códigos están tipados en los SDK (INVOICE_ERROR_CODES e InvoiceErrorCode). El catálogo completo está en Errores, identificador de petición y reintentos.

Siguiente paso

• FacturasEl alta, las series y el resto del contrato de las facturas.
• Facturar con tu propia pasarelaFactura ya cobrada, devolución y rectificativa.