# Crear un cliente

`POST https://api.fiscalisto.com/v1/customers`

Un cliente del catálogo del emisor, con sus datos fiscales como vienen en su constancia. Un RFC que ya está en el catálogo contesta customer_exists.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado |  | Opcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra). |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `issuer` | string |  | Emisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse. |
| `tax_id` | string | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `legal_name` | string | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). (hasta 300 caracteres) |
| `tax_system` | string | sí | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `zip` | string | sí | Código postal del domicilio fiscal, 5 dígitos, como en la constancia de situación fiscal. El de un emisor es el lugar de expedición (LugarExpedicion) de sus comprobantes. |
| `email` | string o null |  | Correo del cliente (varios separados por comas), a donde van sus facturas con send_email. |
| `use` | string |  | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `foreign` | objeto o null |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). |
| `foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `ieps_taxpayer` | boolean |  | true si el cliente es contribuyente de IEPS: el IEPS va desglosado en vez de sumado al precio. |

Ejemplo:

```json
{
  "tax_id": "ICV060329BY0",
  "legal_name": "INMOBILIARIA CVA",
  "tax_system": "601",
  "zip": "33826",
  "email": "pagos@cva.example"
}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const customer = await fiscalisto.customers.create({
  tax_id: "ICV060329BY0",
  legal_name: "INMOBILIARIA CVA",
  tax_system: "601",
  zip: "33826",
  email: "pagos@cva.example",
}, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

customer = fiscalisto.customers.create({
    "tax_id": "ICV060329BY0",
    "legal_name": "INMOBILIARIA CVA",
    "tax_system": "601",
    "zip": "33826",
    "email": "pagos@cva.example",
}, idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$customer = $fiscalisto->customers->create([
    'tax_id' => 'ICV060329BY0',
    'legal_name' => 'INMOBILIARIA CVA',
    'tax_system' => '601',
    'zip' => '33826',
    'email' => 'pagos@cva.example',
], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var customer = await fiscalisto.Customers.CreateAsync(new CreateCustomerParams
{
    TaxId = "ICV060329BY0",
    LegalName = "INMOBILIARIA CVA",
    TaxSystem = "601",
    Zip = "33826",
    Email = "pagos@cva.example",
}, new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	customer, err := client.Customers.Create(ctx, &fiscalisto.CreateCustomerParams{
		TaxID:     "ICV060329BY0",
		LegalName: "INMOBILIARIA CVA",
		TaxSystem: "601",
		Zip:       "33826",
		Email:     fiscalisto.String("pagos@cva.example"),
	}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(customer.ID)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;
import com.fiscalisto.model.CreateCustomerParams;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var customer = fiscalisto.customers().create(new CreateCustomerParams()
        .setTaxId("ICV060329BY0")
        .setLegalName("INMOBILIARIA CVA")
        .setTaxSystem("601")
        .setZip("33826")
        .setEmail("pagos@cva.example"), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(customer.getId());
```

## Respuesta 201

Correcto.

Un objeto `Customer`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"customer"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer` | string | sí | El emisor (iss_…). |
| `tax_id` | string | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `legal_name` | string | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). |
| `tax_system` | string | sí | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `zip` | string | sí | Código postal del domicilio fiscal, 5 dígitos, como en la constancia de situación fiscal. El de un emisor es el lugar de expedición (LugarExpedicion) de sus comprobantes. |
| `email` | string o null | sí | Correo del cliente (varios separados por comas), a donde van sus facturas. |
| `use` | string o null | sí | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `foreign` | objeto o null | sí | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). |
| `foreign.tax_id` | string o null | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). |
| `ieps_taxpayer` | boolean | sí | true si el cliente es contribuyente de IEPS: el IEPS va desglosado en vez de sumado al precio. |
| `created_at` | string (date-time) | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `updated_at` | string (date-time) o null | sí | Cuándo cambió por última vez, ISO 8601 (-06:00). |

```json
{
  "id": "cus_OufpKqnrvx9p1",
  "object": "customer",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "tax_id": "ICV060329BY0",
  "legal_name": "INMOBILIARIA CVA",
  "tax_system": "601",
  "zip": "33826",
  "email": "pagos@cva.example",
  "use": "G03",
  "foreign": null,
  "ieps_taxpayer": false,
  "created_at": "2026-10-20T09:02:11-06:00",
  "updated_at": "2026-10-24T10:15:42-06:00"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.