Fiskaly Upsert Taxpayer

Descripcion

Este modulo permite registrar o actualizar un contribuyente en Fiskaly. El contribuyente (taxpayer) es la entidad fiscal principal que emite facturas. Se deben proporcionar los datos fiscales obligatorios: nombre/razon social, NIF/CIF y territorio fiscal.

El territorio fiscal determina el sistema de facturacion electronica aplicable:

• SPAIN_OTHER: Resto de Espana, utiliza Verifactu
• ARABA, BIZKAIA, GIPUZKOA: Pais Vasco, utiliza TicketBAI
• NAVARRE: Navarra
• CANARY_ISLANDS: Islas Canarias
• CEUTA, MELILLA: Ciudades autonomas

Si no se proporciona un taxpayer_id, se genera automaticamente un UUIDv4. El modulo utiliza la operacion PUT (upsert).

El modulo es de tipo hidden (oculto en la interfaz principal).

Configuracion

Parametro	Tipo	Requerido	Descripcion
credentials_id	credentials	Si	Credencial Fiskaly
taxpayer_id	text	No	UUID del contribuyente (auto-generado si vacio)
name	text	Si	Nombre o razon social del contribuyente
tax_number	text	Si	NIF / CIF del contribuyente
territory	select	Si	Territorio fiscal: SPAIN_OTHER, ARABA, BIZKAIA, GIPUZKOA, NAVARRE, CANARY_ISLANDS, CEUTA, MELILLA
email	text	No	Email de contacto del contribuyente
address	textarea	No	Direccion en JSON: {street, city, postal_code, province}

Credenciales

Requiere credenciales de tipo Fiskaly con:

• api_key: API Key de Fiskaly
• api_secret: API Secret de Fiskaly

Salida

{
  "nextModule": "siguiente_modulo",
  "data": {
    "success": true,
    "taxpayer": { "...datos del contribuyente..." },
    "taxpayer_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Contribuyente \"Mi Empresa SL\" creado/actualizado exitosamente"
  }
}

Ejemplo de Uso

Caso basico

{
  "credentials_id": "mi-fiskaly",
  "name": "Mi Empresa SL",
  "tax_number": "B12345678",
  "territory": "SPAIN_OTHER",
  "email": "fiscal@miempresa.com",
  "address": "{\"street\": \"Calle Gran Via 1\", \"city\": \"Madrid\", \"postal_code\": \"28001\", \"province\": \"Madrid\"}"
}

API Utilizada

• Fiskaly SIGN ES API - PUT /taxpayers/{taxpayer_id}

Notas

• Utiliza PUT (upsert): si el contribuyente ya existe, se actualiza
• Si no se proporciona taxpayer_id, se genera un UUIDv4 automaticamente
• El territorio determina si se usa Verifactu (resto de Espana) o TicketBAI (Pais Vasco)
• El NIF/CIF y el nombre son obligatorios
• El territorio por defecto es SPAIN_OTHER (Verifactu)
• El campo address debe ser un JSON valido

Nodos Relacionados

• FiskalyGetTaxpayer - Obtener contribuyentes
• FiskalyUpsertClient - Crear/actualizar dispositivo
• FiskalyUpsertSigner - Crear/actualizar firmante
• FiskalyUpsertSoftware - Registrar software
• FiskalyCreateInvoice - Crear/actualizar factura