Fiskaly Upsert Taxpayer

Description

This module allows registering or updating a taxpayer in Fiskaly. The taxpayer is the main tax entity that issues invoices. The mandatory tax data must be provided: name/business name, NIF/CIF and tax territory.

The tax territory determines the applicable electronic invoicing system:

• SPAIN_OTHER: Rest of Spain, uses Verifactu
• ARABA, BIZKAIA, GIPUZKOA: Basque Country, uses TicketBAI
• NAVARRE: Navarre
• CANARY_ISLANDS: Canary Islands
• CEUTA, MELILLA: Autonomous cities

If no taxpayer_id is provided, a UUIDv4 is automatically generated. The module uses the PUT (upsert) operation.

The module is of type hidden (hidden in the main interface).

Configuration

Parameter	Type	Required	Description
credentials_id	credentials	Yes	Fiskaly credential
taxpayer_id	text	No	UUID of the taxpayer (auto-generated if empty)
name	text	Yes	Taxpayer name or business name
tax_number	text	Yes	Taxpayer NIF / CIF
territory	select	Yes	Tax territory: SPAIN_OTHER, ARABA, BIZKAIA, GIPUZKOA, NAVARRE, CANARY_ISLANDS, CEUTA, MELILLA
email	text	No	Taxpayer contact email
address	textarea	No	Address in JSON: {street, city, postal_code, province}

Credentials

Requires Fiskaly type credentials with:

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

Output

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

Usage Example

Basic case

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

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

Notes

• Uses PUT (upsert): if the taxpayer already exists, it is updated
• If taxpayer_id is not provided, a UUIDv4 is automatically generated
• The territory determines whether Verifactu (rest of Spain) or TicketBAI (Basque Country) is used
• NIF/CIF and name are required
• The default territory is SPAIN_OTHER (Verifactu)
• The address field must be a valid JSON

Related Nodes

• FiskalyGetTaxpayer - Get taxpayers
• FiskalyUpsertClient - Create/update device
• FiskalyUpsertSigner - Create/update signer
• FiskalyUpsertSoftware - Register software
• FiskalyCreateInvoice - Create/update invoice