# Emitir un evento de prueba

POST /sandbox/v1/webhooks/trigger

Emite un evento ficticio del tipo que pidas hacia tus destinos de sandbox, con firma y entrega reales. Sirve para probar tu receptor sin crear operaciones. Sólo existe en sandbox: en producción da 404.

| Dato | Valor |
|---|---|
| Método y ruta | `POST /sandbox/v1/webhooks/trigger` |
| Servidor | `https://widget.fital.xyz/sandbox` |
| `operationId` | `triggerSandboxWebhook` |
| Acceso | Llave con el scope `webhooks:read` |
| Firma de petición | No aplica |
| Idempotencia | No aplica |
| Ambiente | Sólo existe en la cuenta de prueba. En producción responde `404` |

- Sin clave de idempotencia y sin firma de petición: cada llamada emite otro evento. Necesita el scope `webhooks:read`.
- `data` tiene la forma real de ese tipo de evento, con datos ficticios, más `simulated: true` y `livemode: false`. Ver el [catálogo de eventos](/docs/webhooks/eventos/).

## Encabezados de la petición

| Encabezado | Obligatorio | Descripción |
|---|---|---|
| `Authorization` | Sí | `Bearer` y tu llave. |
| `Content-Type` | Sí | `application/json`. |
| `X-Fital-Scenario` | No | Sólo simuladores: elige la respuesta que quieres practicar. |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `resource_id` | texto | No | Recurso al que se refiere. Sin este campo se usa uno ficticio. |
| `type` | texto | Sí | Tipo de evento a emitir. `payment.processing`: El pago se aceptó y sigue en curso, o se reabrió. `payment.in_review`: El pago está en revisión. No lo repitas. `payment.completed`: El pago se confirmó. `payment.failed`: El pago no se hizo y no queda dinero en tránsito. `payment.returned`: El pago se devolvió. Puede llegar después de `payment.completed`. `payment.canceled`: El pago se canceló. `deposit.received`: El dinero ya está acreditado. `deposit.in_review`: El depósito está en revisión. `deposit.returned`: El depósito se devolvió. `collection.paid`: El cobro se pagó. En `efectivo`, la tienda ya confirmó el pago y el abono a tu cuenta llega después. `collection.expired`: El cobro venció sin pago. `security.ip_allowlist.changed`: Cambió la lista de IP de una llave de producción. `system.egress_ips.changing`: Cambiará una IP de salida de webhooks. Actualiza tu firewall antes de `effective_at`. |

```json
{
  "type": "payment.completed"
}
```

### Valores de `type`

Ver el [catálogo de eventos](/docs/webhooks/eventos/).

## Respuestas correctas

### 202 Aceptado: el resultado final llega después

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `event_id` | texto | Sí | Identificador del evento emitido. |
| `resource_id` | texto | Sí | Recurso del evento. |
| `sequence` | entero | Sí | Orden dentro del recurso. |

```json
{
  "event_id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ",
  "livemode": false,
  "resource_id": "sim_7f3a9c21d4e8b605",
  "sequence": 1
}
```

## Encabezados de la respuesta

| Encabezado | Contenido |
|---|---|
| `X-Request-Id` | Identificador de la petición. Cítalo con soporte. |
| `Retry-After` | Segundos a esperar, con `429` y a veces con `503`. |

## Errores

Todos usan la forma de [Errores](/docs/errores/): `error.code`, `message`, `request_id`, `details`, `retryable` y `docs_url`. Decide por `code`.

| HTTP | Código | Cuándo sale | `retryable` |
|---|---|---|---|
| 400 | [`invalid_request`](/docs/errores/#invalid_request) | Algún parámetro o campo no cumple el esquema. Mira `details.fields`. | `false` |
| 401 | [`invalid_api_key`](/docs/errores/#invalid_api_key) | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | `false` |
| 401 | [`wrong_environment`](/docs/errores/#wrong_environment) | La llave es de otro ambiente. | `false` |
| 403 | [`forbidden_scope`](/docs/errores/#forbidden_scope) | La llave no tiene el scope de esta operación. `details.required_scope` lo nombra. | `false` |
| 403 | [`ip_not_allowed`](/docs/errores/#ip_not_allowed) | La IP de origen no está activa en la lista de esa llave. | `false` |
| 413 | [`invalid_request`](/docs/errores/#invalid_request) | El cuerpo supera 64 KB. | `false` |
| 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` |
| 500 | [`internal_error`](/docs/errores/#internal_error) | Fallo nuestro. El resultado de la petición no se conoce. | `true` |
| 503 | [`service_unavailable`](/docs/errores/#service_unavailable) | El servicio no está disponible por ahora. El resultado de la petición no se conoce. | `true` |

### Ejemplos de error

`400 invalid_request`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "fields": {
        "resource_id": "Valor inválido"
      }
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}
```

`401 invalid_api_key`:

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Credencial inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key"
  }
}
```

`403 forbidden_scope`:

```json
{
  "error": {
    "code": "forbidden_scope",
    "message": "La llave no tiene permiso para esta operación",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "required_scope": "webhooks:read"
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
  }
}
```

`413 invalid_request`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}
```

`429 rate_limited`:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Demasiadas peticiones",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited"
  }
}
```

`500 internal_error`:

```json
{
  "error": {
    "code": "internal_error",
    "message": "Error interno",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error"
  }
}
```

`503 service_unavailable`:

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "Servicio no disponible",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable"
  }
}
```

## Reintentos

No lleva clave de idempotencia y no mueve dinero: repetirla es seguro.

- `429 rate_limited`: Espera lo que indique `Retry-After` y repite.
- `500 internal_error`: Repite con espera exponencial.
- `503 service_unavailable`: Repite con espera exponencial. Respeta `Retry-After` si viene.

Ver [Reintentos](/docs/recetas/reintentos/) y [Límites](/docs/limites/).

## Muestras

**Variables de estas muestras: cuenta de prueba, con tu llave**

Define esto en tu terminal, con tu llave de prueba:

```bash
export FITAL_API="https://widget.fital.xyz/sandbox/v1"
export FITAL_KEY="sk_test_fital_..."
```

Sustituye los `id` de ejemplo por los tuyos. Ver [Inicio rápido de la cuenta de prueba](/docs/sandbox/inicio-rapido/).

```bash
CUERPO='{"type":"payment.completed"}'
curl -sS -X POST "$FITAL_API/webhooks/trigger" \
  -H "Authorization: Bearer $FITAL_KEY" \
  -H "Content-Type: application/json" \
  -d "$CUERPO"
```

```js
const cuerpo = JSON.stringify({"type":"payment.completed"});
const r = await fetch(`${process.env.FITAL_API}/webhooks/trigger`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FITAL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: cuerpo,
});
console.log(r.status, await r.json());
```

```python
import json, os, urllib.error, urllib.request
cuerpo = json.dumps({"type":"payment.completed"}).encode()
pet = urllib.request.Request(os.environ["FITAL_API"] + "/webhooks/trigger", method="POST", data=cuerpo,
    headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"],
             "Content-Type": "application/json"})
try:
    with urllib.request.urlopen(pet) as r:
        print(r.status, json.load(r))
except urllib.error.HTTPError as e:
    print(e.code, e.read().decode())
```

```php
<?php
$cuerpo = '{"type":"payment.completed"}';
$c = curl_init(getenv('FITAL_API') . '/webhooks/trigger');
curl_setopt_array($c, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('FITAL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => $cuerpo,
]);
echo curl_exec($c), "\n";
```

## Guías

- [Inicio rápido de webhooks](/docs/webhooks/inicio-rapido/)
- [Cuenta de prueba](/docs/sandbox/cuenta-de-prueba/)
- [Lista de migración](/docs/migracion/)
- [Catálogo de eventos](/docs/webhooks/eventos/)