Autenticación

La API de Sangho utiliza claves API para autenticar las solicitudes. Cada App dispone de una clave pública y una clave secreta.

Tipos de claves

Tipo	Prefijo (prod)	Prefijo (test)	Uso
Clave pública	pk_prod_	pk_test_	Solo para inicializar el SDK en el cliente
Clave secreta	sk_prod_	sk_test_	Solo para solicitudes desde el servidor — no la exponga nunca

Note

El entorno se llama prod, no live: la clave sk_prod_ es la única que desencadena transacciones reales.

Note

Sus claves pk_/sk_ son las mismas tanto si su App es una App de comerciante ordinaria como si tiene el estado de Socio de Plataforma: ese estado no añade claves nuevas, solo concede el derecho a llamar a los endpoints connect.* (marketplace). Véase Marketplace y Connect.

Uso en cabecera HTTP

Añada su clave secreta en la cabecera Authorization de cada solicitud, con el prefijo Bearer.

Sandbox frente a Producción

Las claves sk_test_ apuntan a la base de datos del Sandbox: ninguna transacción real. Las claves sk_prod_ desencadenan transacciones reales.

Important

No utilice nunca una clave sk_prod_ en el frontend ni en código JavaScript del lado del cliente. Podría quedar expuesta y comprometida.

Rotación de claves

• 1. Cree una clave nueva desde Panel → Ajustes → Claves API
• 2. Actualice la configuración de su servidor con la nueva clave
• 3. Revoque la clave anterior: queda invalidada de inmediato
• 4. Todas las solicitudes con la clave anterior devolverán 401

Idempotency Key

En las solicitudes POST críticas (PaymentIntent, Refund), añada una cabecera Idempotency-Key única, por ejemplo un UUID. Si vuelve a enviar la misma solicitud con la misma clave en un plazo de 24 h, Sangho devuelve la respuesta ya generada (con la cabecera Idempotency-Replayed: true) en lugar de crear un duplicado.

Attention

Si se reutiliza la misma clave con un cuerpo de solicitud distinto, Sangho rechaza la solicitud con un error 409 IDEMPOTENCY_CONFLICT en lugar de adivinar qué versión procesar.

Cabecera de autenticación

httpCopier

Authorization: Bearer sk_prod_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Con Idempotency Key

httpCopier

Authorization: Bearer sk_prod_xxxx
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Ejemplo de llamada autenticada

cURLNode JSPythonPHPJavaRubyRustGo

bashCopier

curl https://api.sangho.ga/v1/apps/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json"

Respuesta — Clave no válida (401)

ResponseRespuesta

jsonCopier

{
  "status": 401,
  "type": "AUTHENTICATION_ERROR",
  "code": "INVALID_API_KEY",
  "message": "Clé API invalide ou expirée.",
  "doc_url": "https://docs.sangho.ga/errors#INVALID_API_KEY",
  "request_id": "req_5d0cc04ea0664a50a14a247f"
}

Note

Obtenga sus claves desde Panel → Desarrolladores → Claves API. Las claves de prueba son visibles desde el registro, sin necesidad de KYC.