Formulaire fiscal

Les informations fiscales de votre client, validées pendant la saisie avec les mêmes règles que celles utilisées par Cord pour facturer.

Le Fiscal Element saisit les informations fiscales du destinataire : la personne ou l’entreprise facturée. Il valide dans le navigateur avec le même code que celui qu’utilise le serveur de Cord avant d’enregistrer, de sorte que ce que le formulaire accepte est exactement ce que Cord accepte. Un RFC dont le chiffre de contrôle est mal saisi est détecté au moment de la frappe, et non des jours plus tard, lorsque le timbrage le rejette.

Champs demandés et validations

Pays	Champs	Règles
Mexique (`MX`)	RFC, nom ou raison sociale, régime fiscal, usage du CFDI, code postal fiscal	Format, date et chiffre de contrôle du RFC. Le type de RFC (12 caractères, personne morale ; 13, personne physique) filtre les régimes et les usages applicables. `XAXX010101000` et `XEXX010101000` (grand public et étrangers) imposent le régime `616` et l’usage `S01`. Avertissement si la raison sociale d’une personne morale contient la forme juridique (« S.A. de C.V. »). Code postal à 5 chiffres.
Espagne (`ES`)	NIF / CIF, nom ou raison sociale, code postal	Lettre de contrôle du NIF et du NIE, et chiffre de contrôle du CIF. Code postal à 5 chiffres.
États-Unis (`US`)	EIN, dénomination légale, ZIP	EIN valide. ZIP à 5 chiffres ou au format `12345-6789`.
Autre pays	Identifiant fiscal, nom	Seule leur présence est vérifiée, avec un avertissement `unsupported_country`.

Régimes du catalogue : 601, 603, 605, 606, 612, 616, 620, 621 et 626. Usages du CFDI : G01, G03, I01, I02, I04, I08, S01 et CP01.

Lorsqu’il est valide, le résultat est le destinataire normalisé :

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

En dehors du Mexique, regimen_fiscal et uso_cfdi valent null.

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

Importer @flouviahq/elements enregistre <cord-fiscal-form> en même temps que <cord-quote> et <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>

C’est un élément associé aux formulaires : à l’intérieur d’un <form>, il fournit sa valeur sous son attribut name (le JSON du destinataire normalisé) et bloque l’envoi tant qu’il y a des erreurs, comme un <input required>. Le navigateur affiche la première erreur à côté du champ qui la provoque. Dans Safari antérieur à la version 16.4, qui ne dispose pas de cette API, le formulaire fonctionne mais ne participe pas à l’envoi : lisez value vous-même.

Attribut	Valeurs
`country`	`MX` (par défaut), `ES`, `US` ou un autre code ISO. Le modifier conserve ce qui a déjà été saisi.
`lang`	`es`, `en`, `pt`, `fr` ou `de` ; toute autre valeur revient à `en`. Sans cet attribut, le `lang` de votre page.
`name`	Le nom sous lequel il fournit sa valeur au formulaire.

Propriété ou méthode	Effet
`value`	Le destinataire normalisé s’il est valide ; sinon, `null`.
`state`	L’état complet : valeurs, champs touchés, erreurs visibles, régimes et usages disponibles.
`setValues(data)`	Charge des valeurs initiales, par exemple celles d’un client déjà enregistré.
`submit()`	Affiche toutes les erreurs et renvoie le destinataire s’il est valide, ou `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>

Événement	`detail`
`fiscalchange`	L’état complet, à chaque modification.
`fiscalvalid`	Le destinataire normalisé, chaque fois qu’il devient valide.

Les erreurs ne s’affichent que sur les champs que la personne a déjà touchés, ou sur tous les champs après submit().

Styles

Le formulaire vit dans un Shadow DOM. Il se personnalise avec des parties et des variables :

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;
}

Partie	Élément
`field`	Le conteneur de chaque champ.
`label`	Le libellé.
`input`	Le champ de texte ou le sélecteur.
`error`	Le message d’erreur d’un champ.
`warning`	L’avertissement d’un champ (par exemple, la forme juridique dans la raison sociale).

Variables : --cord-font-family, --cord-color-text, --cord-color-text-secondary, --cord-color-input, --cord-color-primary, --cord-color-danger et --cord-border-radius.

React : `<CordFiscalForm>` et `<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	Détail
`country`	`MX` par défaut.
`initial`	Valeurs initiales.
`locale`	`es`, `en`, `pt`, `fr` ou `de`.
`title`	Titre de la section.
`onValid`	Appelée avec le destinataire normalisé chaque fois qu’il devient valide.
`className`, `style`	Pour le conteneur.

Dans le Builder, fiscal ajoute la section et le destinataire est transmis avec le devis :

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

Le pays provient de la configuration fiscale de votre organisation. Si le destinataire n’est pas valide, le Builder n’envoie rien et signale les champs en erreur. Pour contrôler l’état vous-même, useFiscalForm() renvoie le même état que le composant.

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 est un ShallowRef contenant l’état du formulaire ; form est le formulaire headless (set, touch, submit). Pour afficher le texte de chaque erreur, utilisez fiscalText() de @flouviahq/elements/headless.

Codes de validation

Code	Signification
`required`	La donnée est manquante.
`too_long`	Dépasse le maximum (20 caractères pour l’identifiant, 300 pour le nom).
`invalid_tax_id`	L’identifiant fiscal n’est pas valide pour le pays.
`invalid_postal_code`	Le code postal ne respecte pas le format du pays.
`regimen_not_for_persona`	Le régime ne correspond pas au type de RFC.
`uso_not_for_persona`	L’usage du CFDI ne correspond pas au type de RFC.
`generic_requires_616_s01`	Un RFC générique exige le régime `616` et l’usage `S01`.
`legal_name_has_regime_suffix`	Avertissement : la raison sociale contient la forme juridique.
`unsupported_country`	Avertissement : pour ce pays, seule la présence de la donnée est vérifiée.

Côté serveur

POST /api/v1/cotizaciones accepte le destinataire dans cliente.fiscal. S’il n’est pas valide, la réponse est 400 avec code: "invalid_fiscal_data" et la liste dans 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 exporte validateFiscalReceptor(), validRfc(), validSpainTaxId() et validEin(), pour valider sur votre serveur avec le même code.
Le serveur MCP dispose de l’outil validar_datos_fiscales.