Crear un cliente

POST

/customers

# Guarda tus datos en solicitud.json; consulta los campos debajo.
FACTUCAT_API_URL="${FACTUCAT_API_URL:-https://sandbox.factucat.com/api/v1}"

curl --fail-with-body --request POST \
  --url "$FACTUCAT_API_URL/customers" \
  --header "X-API-Key: $FACTUCAT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @'solicitud.json'

// Guarda tus datos en solicitud.json; consulta los campos debajo.
import { readFile, writeFile } from 'node:fs/promises'

const baseUrl = process.env.FACTUCAT_API_URL || "https://sandbox.factucat.com/api/v1"
const body = await readFile("solicitud.json", 'utf8')
const response = await fetch(`${baseUrl}/customers`, {
  method: "POST",
  headers: {
    'X-API-Key': process.env.FACTUCAT_API_KEY,
    'Content-Type': 'application/json',
  },
  body,
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(JSON.parse(text))

# Guarda tus datos en solicitud.json; consulta los campos debajo.
import json
import os
from pathlib import Path
import urllib.error
import urllib.request

base_url = os.environ.get("FACTUCAT_API_URL", "https://sandbox.factucat.com/api/v1")
body = Path("solicitud.json").read_bytes()
request = urllib.request.Request(
    f"{base_url}/customers",
    method="POST",
    headers={
        "X-API-Key": os.environ["FACTUCAT_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)
try:
    with urllib.request.urlopen(request) as response:
        text = response.read().decode("utf-8")
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8')}") from error
print(json.loads(text))

// Guarda tus datos en solicitud.json; consulta los campos debajo.
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  baseURL := os.Getenv("FACTUCAT_API_URL")
  if baseURL == "" { baseURL = "https://sandbox.factucat.com/api/v1" }
  body, _ := os.ReadFile("solicitud.json")
  request, err := http.NewRequest("POST", baseURL + "/customers", bytes.NewReader(body))
  if err != nil { panic(err) }
  request.Header.Set("X-API-Key", os.Getenv("FACTUCAT_API_KEY"))
  request.Header.Set("Content-Type", "application/json")
  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()
  text, _ := io.ReadAll(response.Body)
  if response.StatusCode < 200 || response.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, text))
  }
  fmt.Print(string(text))
}

Authorizations

apiKeyAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

Opcional. Reutiliza la misma clave, ruta y contenido para reintentar una operación sin repetirla. Una clave con contenido diferente devuelve 409. Sin clave, cada solicitud es independiente.

Request Body^required

application/json

object

legalName

required

string

>= 2 characters <= 200 characters

rfc

required

string

>= 12 characters <= 13 characters

postalCode

required

Any of:

string
integer

string

taxRegime

required

Any of:

string
integer

string

preferredCfdiUse

Any of:

string
null

string

>= 3 characters <= 4 characters

fiscalResidence

string

>= 3 characters <= 3 characters

taxId

string

<= 80 characters

email

string format: email

/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

whatsappPhone

string

>= 6 characters <= 30 characters

sendInvoices

boolean

default: true

invoiceLanguage

string

default: es

Allowed values: es en

currency

string

default: MXN

Allowed values: MXN USD EUR

Responses

201

Operación exitosa

application/json

object

data

required

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

userId

required

string

>= 1 characters

legalName

required

string

rfc

required

string

postalCode

required

string

taxRegime

required

string

preferredCfdiUse

string | null

fiscalResidence

string

taxId

string

email

string format: email

/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

whatsappPhone

string

sendInvoices

required

boolean

invoiceLanguage

required

string

Allowed values: es en

currency

required

string

Allowed values: MXN USD EUR

createdAt

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/

updatedAt

required

string format: date-time

meta

required

object

requestId

required

string

>= 1 characters

idempotencyKey

string

>= 1 characters

pagination

object

limit

required

integer

> 0 <= 9007199254740991

offset

required

integer

<= 9007199254740991

hasMore

required

boolean

nextCursor

string | null

400

Datos inválidos

application/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

401

API key ausente, inválida o de otro ambiente

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

403

Plan inactivo o permisos insuficientes

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

404

Recurso no encontrado

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

405

Método no permitido

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

409

Conflicto o solicitud en curso. error.reason es opcional; duplicate_rfc indica que ya existe un cliente con ese RFC en la cuenta; stamp_in_progress indica que el documento se está timbrando: consúltalo antes de reintentar.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

429

Límite de solicitudes alcanzado

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

Headers

Retry-After

integer

Segundos antes de reintentar.

500

Error interno

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

503

PAC temporalmente no disponible

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

Crear un cliente

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

400

401

403

404

405

409

429

Headers

500

503

Request Body^required