Steuerformular

Die Steuerdaten Ihres Kunden, schon bei der Eingabe mit denselben Regeln validiert, die Cord bei der Rechnungsstellung anwendet.

Das Fiscal Element erfasst die Steuerdaten des Rechnungsempfängers: an wen die Rechnung geht. Es validiert im Browser mit demselben Code, mit dem der Server von Cord vor dem Speichern validiert. Was das Formular akzeptiert, ist also genau das, was Cord akzeptiert. Ein RFC mit falsch eingegebener Prüfziffer fällt schon bei der Eingabe auf und nicht erst Tage später, wenn die Stempelung ihn ablehnt.

Welche Felder es abfragt und was es validiert

Land	Felder	Regeln
Mexiko (`MX`)	RFC, Name oder Firmenname, Steuerregime, CFDI-Verwendung, steuerliche Postleitzahl	Format, Datum und Prüfziffer des RFC. Der RFC-Typ (12 Zeichen: juristische Person; 13: natürliche Person) filtert die zulässigen Steuerregime und Verwendungen. `XAXX010101000` und `XEXX010101000` (allgemeine Öffentlichkeit und Ausländer) legen das Steuerregime `616` und die Verwendung `S01` fest. Hinweis, wenn der Firmenname einer juristischen Person den Rechtsformzusatz enthält („S.A. de C.V.“). Postleitzahl mit 5 Ziffern.
Spanien (`ES`)	NIF / CIF, Name oder Firmenname, Postleitzahl	Kontrollbuchstabe von NIF und NIE sowie Kontrollziffer des CIF. Postleitzahl mit 5 Ziffern.
Vereinigte Staaten (`US`)	EIN, rechtlicher Name, ZIP	Gültige EIN. ZIP mit 5 Ziffern oder `12345-6789`.
Anderes Land	Steuernummer, Name	Es wird nur geprüft, ob die Angaben vorhanden sind, mit einem Hinweis `unsupported_country`.

Steuerregime im Katalog: 601, 603, 605, 606, 612, 616, 620, 621 und 626. CFDI-Verwendungen: G01, G03, I01, I02, I04, I08, S01 und CP01.

Ist die Eingabe gültig, ist das Ergebnis der normalisierte Rechnungsempfänger:

{
  "country": "MX",
  "tax_id": "EKU9003173C9",
  "legal_name": "ESCUELA KEMPER URGATE",
  "regimen_fiscal": "601",
  "uso_cfdi": "G03",
  "cp_fiscal": "42501"
}

Außerhalb Mexikos kommen regimen_fiscal und uso_cfdi als null zurück.

Web Component: `<cord-fiscal-form>`

Der Import von @flouviahq/elements registriert <cord-fiscal-form> zusammen mit <cord-quote> und <cord-invoice>.

<script type="module" src="https://unpkg.com/@flouviahq/elements/dist/index.mjs"></script>

<form id="signup" method="post" action="/clients">
  <cord-fiscal-form name="recipient" country="MX" lang="en"></cord-fiscal-form>
  <button type="submit">Save</button>
</form>

Es ist ein formularassoziiertes Element: Innerhalb eines <form> liefert es seinen Wert unter seinem Attribut name (den normalisierten Rechnungsempfänger als JSON) und blockiert das Absenden, solange Fehler bestehen – genau wie ein <input required>. Der Browser zeigt den ersten Fehler neben dem Feld an, das ihn verursacht. In Safari vor Version 16.4, das diese API nicht hat, funktioniert das Formular, nimmt aber nicht am Absenden teil: Lesen Sie value selbst aus.

Attribut	Werte
`country`	`MX` (Standard), `ES`, `US` oder ein anderer ISO-Code. Eine Änderung behält das bereits Eingegebene bei.
`lang`	`es`, `en`, `pt`, `fr` oder `de`; jeder andere Wert fällt auf `en` zurück. Ohne Angabe das `lang` Ihrer Seite.
`name`	Der Name, unter dem es seinen Wert an das Formular liefert.

Eigenschaft oder Methode	Was sie tut
`value`	Der normalisierte Rechnungsempfänger, wenn gültig; andernfalls `null`.
`state`	Der vollständige Zustand: Werte, berührte Felder, sichtbare Fehler, verfügbare Steuerregime und Verwendungen.
`setValues(data)`	Lädt Anfangswerte, zum Beispiel aus einem bereits gespeicherten Kunden.
`submit()`	Zeigt alle Fehler an und gibt den Rechnungsempfänger zurück, wenn er gültig ist, sonst `null`.

<script type="module">
  const fiscal = document.querySelector('cord-fiscal-form');
  fiscal.setValues({ tax_id: 'EKU9003173C9', legal_name: 'ESCUELA KEMPER URGATE', cp_fiscal: '42501' });

  fiscal.addEventListener('fiscalvalid', (e) => {
    console.log('Recipient ready:', e.detail);
  });
  fiscal.addEventListener('fiscalchange', (e) => {
    console.log('Visible errors:', e.detail.visibleErrors);
  });
</script>

Ereignis	`detail`
`fiscalchange`	Der vollständige Zustand, bei jeder Änderung.
`fiscalvalid`	Der normalisierte Rechnungsempfänger, jedes Mal, wenn er gültig wird.

Fehler werden nur bei Feldern angezeigt, die die Person bereits berührt hat, oder nach submit() bei allen.

Styling

Das Formular lebt in einem Shadow DOM. Sie passen es mit Parts und Variablen an:

cord-fiscal-form::part(label) { font-weight: 500; }
cord-fiscal-form::part(input) { min-height: 48px; }
cord-fiscal-form::part(error) { font-size: 13px; }

cord-fiscal-form {
  --cord-color-primary: #0a192f;
  --cord-border-radius: 10px;
}

Part	Element
`field`	Der Container jedes Felds.
`label`	Die Beschriftung.
`input`	Das Textfeld oder die Auswahlliste.
`error`	Die Fehlermeldung eines Felds.
`warning`	Der Hinweis eines Felds (zum Beispiel der Rechtsformzusatz im Firmennamen).

Variablen: --cord-font-family, --cord-color-text, --cord-color-text-secondary, --cord-color-input, --cord-color-primary, --cord-color-danger und --cord-border-radius.

React: `<CordFiscalForm>` und `<CordBuilder fiscal>`

import { CordFiscalForm } from '@flouviahq/elements/react';

export function TaxDetails({ onReady }: { onReady: (recipient: unknown) => void }) {
  return (
    <CordFiscalForm
      country="MX"
      locale="en"
      title="Billing details"
      initial={{ tax_id: 'EKU9003173C9' }}
      onValid={onReady}
    />
  );
}

Prop	Detail
`country`	Standardmäßig `MX`.
`initial`	Anfangswerte.
`locale`	`es`, `en`, `pt`, `fr` oder `de`.
`title`	Überschrift des Abschnitts.
`onValid`	Wird mit dem normalisierten Rechnungsempfänger aufgerufen, jedes Mal, wenn er gültig wird.
`className`, `style`	Für den Container.

Im Builder fügt fiscal den Abschnitt hinzu, und der Rechnungsempfänger wird mit dem Angebot übertragen:

<CordProvider publishableKey="pk_test_...">
  <CordBuilder fiscal />
</CordProvider>

Das Land stammt aus der Steuerkonfiguration Ihrer Organisation. Ist der Rechnungsempfänger nicht gültig, sendet der Builder nicht ab und markiert die fehlerhaften Felder. Wenn Sie den Zustand selbst steuern möchten, gibt useFiscalForm() denselben Zustand zurück wie die Komponente.

Vue: `useCordFiscalForm`

<script setup>
import { useCordFiscalForm } from '@flouviahq/elements/vue';

const { state, form } = useCordFiscalForm({ country: 'MX' });

function save() {
  const recipient = form.submit();
  if (recipient) console.log(recipient);
}
</script>

<template>
  <label>
    RFC
    <input :value="state.values.tax_id" @input="form.set('tax_id', $event.target.value)" @blur="form.touch('tax_id')" />
  </label>
  <p v-for="e in state.visibleErrors" :key="e.field">{{ e.field }}: {{ e.code }}</p>
  <button @click="save">Save</button>
</template>

state ist eine ShallowRef mit dem Zustand des Formulars; form ist das Headless-Formular (set, touch, submit). Um die Texte der einzelnen Fehler darzustellen, verwenden Sie fiscalText() aus @flouviahq/elements/headless.

Validierungscodes

Code	Bedeutung
`required`	Die Angabe fehlt.
`too_long`	Überschreitet das Maximum (20 Zeichen für die Steuernummer, 300 für den Namen).
`invalid_tax_id`	Die Steuernummer ist für das Land nicht gültig.
`invalid_postal_code`	Die Postleitzahl entspricht nicht dem Format des Landes.
`regimen_not_for_persona`	Das Steuerregime passt nicht zum RFC-Typ.
`uso_not_for_persona`	Die CFDI-Verwendung passt nicht zum RFC-Typ.
`generic_requires_616_s01`	Ein generischer RFC erfordert das Steuerregime `616` und die Verwendung `S01`.
`legal_name_has_regime_suffix`	Hinweis: Der Firmenname enthält den Rechtsformzusatz.
`unsupported_country`	Hinweis: Für dieses Land wird nur geprüft, ob die Angabe vorhanden ist.

Auf der Serverseite

POST /api/v1/cotizaciones akzeptiert den Rechnungsempfänger in cliente.fiscal. Ist er nicht gültig, antwortet die API mit 400, code: "invalid_fiscal_data" und der Liste in issues:

{
  "error": "Los datos fiscales del cliente no son válidos.",
  "code": "invalid_fiscal_data",
  "issues": [{ "field": "tax_id", "code": "invalid_tax_id" }]
}

@flouviahq/node exportiert validateFiscalReceptor(), validRfc(), validSpainTaxId() und validEin(), damit Sie auf Ihrem Server mit demselben Code validieren können.
Der MCP-Server hat das Tool validar_datos_fiscales.