Abrir una cuenta para recibir

Abre una cuenta de la empresa en una moneda, si tu empresa tiene esa moneda activada. Hay una por moneda: si ya existe, responde 200 con esa misma cuenta y already_existed: true, nunca abre otra. Exige Idempotency-Key y firma. 201 si se abrió; 202 si aún no se confirma: repite con la misma clave.

Dato	Valor
Método y ruta	`POST /v1/receiving-accounts`
Servidor	`https://widget.fital.xyz`
`operationId`	`createReceivingAccount`
Acceso	Llave con el scope `accounts:write`
Firma de petición	Obligatoria en producción y en la cuenta de prueba. El simulador público no la valida. Ver Firma de petición
Idempotencia	Obligatoria, con `Idempotency-Key`. Ver Idempotencia

Hay una cuenta por moneda. Si ya existe, responde 200 con esa misma cuenta y already_existed: true; nunca abre otra.
202 significa que el alta aún no se confirma: los datos llegan en null. No compartas nada todavía. Repite con la misma clave.

Encabezados de la petición

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer` y tu llave.
`Content-Type`	Sí	`application/json`.
`Idempotency-Key`	Sí	Clave única de esta operación, de 8 a 200 caracteres. Repetirla con el mismo cuerpo devuelve la misma respuesta durante 7 días. Con otro cuerpo da `422 idempotency_key_reused`, también pasado ese plazo.
`X-Fital-Timestamp`	Sí	Hora Unix en segundos. Se acepta hasta 300 s de diferencia.
`X-Fital-Signature`	Sí	Firma `v1=` de la petición con el secreto de firma de la llave.
`X-Fital-Scenario`	No	Sólo simuladores: elige la respuesta que quieres practicar.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
`currency`	texto	Sí	Moneda de la cuenta: `USD`, `EUR`, `BRL`, `GBP` o `COP`. No distingue mayúsculas. MXN no se abre aquí: tu CLABE ya aparece en `GET /v1/receiving-accounts`.

{
  "currency": "USD"
}

Respuestas correctas

200 Correcto

Campo	Tipo	Obligatorio	Descripción
`account_number`	texto o `null`	Sí	Número de cuenta. null si no aplica a esta cuenta.
`already_existed`	booleano	Sí	`true` si la empresa ya tenía una cuenta activa en esa moneda y esta es la misma: nunca se abre una segunda.
`bank`	texto o `null`	Sí	Banco de la cuenta. null si no aplica a esta cuenta.
`bic`	texto o `null`	Sí	Código BIC. null si no aplica a esta cuenta.
`br_code`	texto o `null`	Sí	Código BR para pagar por PIX, en cuentas BRL. null si no aplica a esta cuenta.
`bre_b_key`	texto o `null`	Sí	Llave Bre-B, en cuentas COP. null si no aplica a esta cuenta.
`clabe`	texto o `null`	Sí	CLABE de 18 dígitos. null si no aplica a esta cuenta.
`currency`	texto o `null`	Sí	Moneda que recibe la cuenta.
`holder`	texto o `null`	Sí	Titular de la cuenta. null si no aplica a esta cuenta.
`iban`	texto o `null`	Sí	IBAN. null si no aplica a esta cuenta.
`pix_key`	texto o `null`	Sí	Llave PIX, en cuentas BRL. null si no aplica a esta cuenta.
`routing_number`	texto o `null`	Sí	Número de ruta bancaria. null si no aplica a esta cuenta.
`sort_code`	texto o `null`	Sí	Sort code, en cuentas GBP. null si no aplica a esta cuenta.
`status`	texto	Sí	Estado de la cuenta. `processing`: El alta aún no se confirma: repite con la misma clave. Los datos llegan en null. `active`: Ya recibe fondos.

Valores de `status`

Valor	Significado
`processing`	El alta aún no se confirma: repite con la misma clave. Los datos llegan en `null`.
`active`	Ya recibe fondos.

{
  "account_number": "900000000012",
  "already_existed": true,
  "bank": "Banco de ejemplo",
  "bic": null,
  "br_code": null,
  "bre_b_key": null,
  "clabe": null,
  "currency": "USD",
  "holder": "EMPRESA FICTICIA SA DE CV",
  "iban": null,
  "pix_key": null,
  "routing_number": "999999999",
  "sort_code": null,
  "status": "active"
}

201 Creado

Misma forma que la respuesta anterior.

{
  "account_number": "900000000012",
  "already_existed": false,
  "bank": "Banco de ejemplo",
  "bic": null,
  "br_code": null,
  "bre_b_key": null,
  "clabe": null,
  "currency": "USD",
  "holder": "EMPRESA FICTICIA SA DE CV",
  "iban": null,
  "pix_key": null,
  "routing_number": "999999999",
  "sort_code": null,
  "status": "active"
}

202 Aceptado: el resultado final llega después

Misma forma que la respuesta anterior.

{
  "account_number": null,
  "already_existed": false,
  "bank": null,
  "bic": null,
  "br_code": null,
  "bre_b_key": null,
  "clabe": null,
  "currency": "USD",
  "holder": null,
  "iban": null,
  "pix_key": null,
  "routing_number": null,
  "sort_code": null,
  "status": "processing"
}

Encabezados de la respuesta

Encabezado	Contenido
`X-Request-Id`	Identificador de la petición. Cítalo con soporte.
`Idempotent-Replayed`	`true` si la respuesta repite una anterior con esa clave.
`Retry-After`	Segundos a esperar, con `429`, con `409 idempotency_in_progress` y a veces con `503`.

Errores

Todos usan la forma de Errores: error.code, message, request_id, details, retryable y docs_url. Decide por code.

HTTP	Código	Cuándo sale	`retryable`
400	`invalid_request`	Algún parámetro o campo no cumple el esquema. Mira `details.fields`.	`false`
400	`idempotency_key_required`	Falta `Idempotency-Key`.	`false`
400	`idempotency_key_invalid`	La clave no mide entre 8 y 200 caracteres, o viene duplicada.	`false`
401	`invalid_api_key`	La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.	`false`
401	`wrong_environment`	La llave es de otro ambiente.	`false`
401	`invalid_signature`	Falta la firma, no coincide o tiene más de 5 minutos.	`false`
403	`account_restricted`	La cuenta tiene una restricción.	`false`
403	`not_enabled`	Esa moneda no está activada para tu empresa. No se abrió nada.	`false`
403	`forbidden_scope`	La llave no tiene el scope de esta operación. `details.required_scope` lo nombra.	`false`
403	`ip_not_allowed`	La IP de origen no está activa en la lista de esa llave.	`false`
403	`kyb_required`	La empresa no tiene KYB aprobado o aún no está inscrita.	`false`
403	`account_not_active`	La cuenta no está activa.	`false`
409	`receiving_account_in_progress`	Otra alta de esa moneda sigue en curso. Reintenta en unos segundos.	`true`
409	`idempotency_in_progress`	Una petición anterior con esa clave sigue en curso. Llega con `Retry-After`.	`true`
413	`invalid_request`	El cuerpo supera 64 KB.	`false`
422	`in_review`	Una revisión de tu cuenta frena la operación.	`true`
422	`currency_not_supported`	Esa moneda no se abre por API. `MXN` responde esto: tu CLABE ya aparece en `GET /v1/receiving-accounts`.	`false`
422	`receiving_account_rejected`	La cuenta no se pudo abrir. No se reintenta sola.	`false`
422	`idempotency_key_reused`	Usaste esa clave con otro cuerpo, también pasados 7 días.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
500	`internal_error`	Fallo nuestro. El resultado de la petición no se conoce.	`true`
503	`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:

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

401 invalid_api_key:

{
  "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 account_restricted:

{
  "error": {
    "code": "account_restricted",
    "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted"
  }
}

409 receiving_account_in_progress:

{
  "error": {
    "code": "receiving_account_in_progress",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#receiving_account_in_progress"
  }
}

413 invalid_request:

{
  "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"
  }
}

422 in_review:

{
  "error": {
    "code": "in_review",
    "message": "La operación está en revisión",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review"
  }
}

429 rate_limited:

{
  "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:

{
  "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:

{
  "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

Ante un timeout o una conexión cortada, repite con la misma clave.

409 receiving_account_in_progress: Sí, con espera
409 idempotency_in_progress: Espera Retry-After y repite con la misma clave.
422 in_review: Mira retryable. Con true, repite con la misma clave cuando la revisión se levante. Con false, el rechazo quedó registrado y esa clave lo repite: usa una clave nueva tras la revisión.
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 y Límites.

Muestras

Variables de estas muestras: simulador público, sin cuenta

Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público:

export FITAL_API="https://widget.fital.xyz/explorar/v1"
export FITAL_KEY="sk_test_sandbox_publica"
export FITAL_SIGNING_SECRET="secreto_de_firma_de_prueba_publico"

En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los id de ejemplo por los tuyos. Ver Ambientes.

op-abrir-cuenta-para-recibir.sh

CUERPO='{"currency":"USD"}'
CLAVE="ejemplo-abrir-cuenta-para-recibir"
TS=$(date +%s)
HASH=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -r | cut -d' ' -f1)
FIRMA=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/receiving-accounts "$HASH" "$CLAVE" \
  | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$FITAL_API/receiving-accounts" \
  -H "Authorization: Bearer $FITAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -H "X-Fital-Timestamp: $TS" \
  -H "X-Fital-Signature: v1=$FIRMA" \
  -d "$CUERPO"

Guías

Ver esta página en Markdown

Abrir una cuenta para recibir

Encabezados de la peticiónCopiar enlace

CuerpoCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Valores de statusCopiar enlace

201 CreadoCopiar enlace

202 Aceptado: el resultado final llega despuésCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página