# Crear un entorno de prueba

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

Un modo de pruebas propio para una persona o un proyecto: nace con el emisor de pruebas del SAT y una llave fk_test_ (key.secret, una sola vez) que solo ve los emisores, webhooks y eventos del entorno, y que reinicia solo los suyos. Se crea con una llave de pruebas de la cuenta (no de otro entorno ni limitada a emisores). Hasta 25 por cuenta.

## 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 |
| --- | --- | --- | --- |
| `name` | string | sí | Para quién o para qué es, por ejemplo el nombre de quien lo usa. (hasta 60 caracteres) |

Ejemplo:

```json
{
  "name": "Ana"
}
```

## Con el SDK de TypeScript

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

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

const sandbox = await fiscalisto.sandboxes.create({ name: "Ana" }, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

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

sandbox = fiscalisto.sandboxes.create({"name": "Ana"}, 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();

$sandbox = $fiscalisto->sandboxes->create(['name' => 'Ana'], ['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 sandbox = await fiscalisto.Sandboxes.CreateAsync(new CreateSandboxParams { Name = "Ana" }, 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()

	sandbox, err := client.Sandboxes.Create(ctx, &fiscalisto.CreateSandboxParams{Name: "Ana"}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(sandbox.ID)
}
```

## Con el SDK de Java

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

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

var sandbox = fiscalisto.sandboxes().create(new CreateSandboxParams().setName("Ana"), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(sandbox.getId());
```

## Respuesta 201

Correcto.

Un objeto `Sandbox`:

| 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_). |
| `object` | `"sandbox"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `livemode` | `false` | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `name` | string | sí | Nombre. |
| `issuers` | integer | sí | Emisores activos en el entorno. (de -9007199254740991 a 9007199254740991) |
| `issuer` | objeto o null |  | El emisor de pruebas del SAT con que nace (solo al crearlo). |
| `issuer.id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `issuer.livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `issuer.object` | `"issuer"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer.tax_id` | string | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `issuer.legal_name` | string o null | 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.»). |
| `issuer.tax_system` | string o null | sí | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `issuer.zip` | string o null | 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. |
| `issuer.status` | `active`, `needs_certificate`, `certificate_expired`, `needs_efirma`, `archived` | sí | active: puede timbrar. needs_certificate: falta su CSD. needs_efirma: falta firmar una vez el contrato con el PAC con su e.firma (solo en producción). certificate_expired: su CSD venció. archived: archivado. |
| `issuer.requirement` | string o null | sí | Qué le falta al emisor para timbrar, y cómo dárselo. |
| `issuer.certificate` | objeto o null | sí | El sello digital (CSD) cargado: número de serie y vencimiento. |
| `issuer.certificate.serial_number` | string o null | sí | Número de serie (NoCertificado). |
| `issuer.certificate.expires_at` | string (date-time) o null | sí | Cuándo vence. |
| `issuer.sat_downloads` | objeto | sí | Si puede pedirle al SAT sus facturas (POST /v1/sat_downloads): available es true en pruebas, y en producción mientras su e.firma guardada esté vigente (efirma_expires_at). |
| `issuer.sat_downloads.available` | boolean | sí | true si puede pedir descargas al SAT ahora: siempre en pruebas; en producción con su e.firma guardada y vigente. |
| `issuer.sat_downloads.efirma_expires_at` | string (date-time) o null | sí | Cuándo vence la e.firma guardada para las descargas, o null si no hay una. |
| `issuer.employer_registration` | string o null | sí | Registro patronal ante el IMSS (RegistroPatronal), 11 caracteres. Necesario para timbrar nómina. |
| `issuer.curp` | string o null | sí | CURP, 18 caracteres. |
| `issuer.stamps_as` | string | sí | RFC con el que se timbra: el del emisor en producción y el de pruebas del SAT (EKU9003173C9) en pruebas. |
| `issuer.sandbox` | string o null | sí | El entorno de prueba (sbx_…) al que pertenece, o null si es de la cuenta. Vea /v1/sandboxes. |
| `issuer.test_clock` | objeto o null | sí | Su reloj de prueba (solo emisores de prueba): la hora que es «hoy» para él, o null si va con la hora real. Vea POST /v1/issuers/{id}/test_clock. |
| `issuer.test_clock.frozen_time` | string (date-time) | sí | La hora del reloj. |
| `issuer.created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `issuer.archived_at` | string (date-time) o null | sí | Cuándo se archivó (ya no timbra), o null. |
| `issuer.metadata` | objeto | sí | Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. |
| `key` | objeto |  | Solo al crearlo. |
| `key.id` | string | sí | Id de la llave. |
| `key.secret` | string | sí | La llave fk_test_… del entorno. Solo se ve esta vez: guárdela. |
| `created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `deleted` | boolean |  | Siempre true. |

```json
{
  "id": "sbx_4kQm8ZtR2wLp9XbN",
  "object": "sandbox",
  "livemode": false,
  "name": "Ana",
  "issuers": 1,
  "created_at": "2026-10-25T09:40:00-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.