# Autenticación y ambientes

<!-- Fuente: https://docs.efipay.co/authentication -->

---

- [Autenticación y ambientes](#autenticacion)
  - [Cómo autenticas cada llamada](#como)
  - [Prueba y producción](#ambientes)
  - [Qué necesitas antes de empezar](#requisitos)
  - [Sucursal (`office`)](#office)
  - [Token de webhooks](#webhook-token)
  - [Errores de autenticación](#errores)

## Cómo autenticas cada llamada [#como]

Todas las llamadas a la API van con tu token en el header `Authorization`:

```bash
curl -X GET \
'/api/v1/offices/get' \
-H 'Authorization: Bearer TU_TOKEN' \
-H 'Content-type: application/json'
```

La URL base de la API es **`https://sag.efipay.co/api/v1`**. Todos los endpoints de
esta documentación cuelgan de ahí.

| Ambiente | Host | Cuándo lo usas |
| - | - | - |
| **Producción** | `https://sag.efipay.co/api/v1` | Siempre que integres de verdad, con token de prueba o de producción |
| QA | `https://sag-qa.efipay.co/api/v1` | Solo si te pedimos probar contra QA en un acompañamiento |

:::caution
**Usa `sag.efipay.co`.** `sag-qa.efipay.co` es nuestro ambiente interno de
pruebas: puede reiniciarse o quedarse abajo sin aviso. Para construir y probar tu
integración, apunta a `sag.efipay.co` con un **token de prueba**: ahí no se mueve
dinero y el servicio tiene la disponibilidad de producción.
:::

:::note
Esta documentación se publica en los dos ambientes y **muestra el host del
ambiente en el que la estás leyendo**. Si copiaste una URL desde la doc de QA, te llevaste
el host de QA sin darte cuenta. Ahora mismo estás leyendo la de
**`https://sag.efipay.co`**.
:::

Genera y revoca tus tokens en el panel, en
[Documentación → API key](https://sag.efipay.co/documentacion/api-key). El token se
muestra **una sola vez**: guárdalo en tu gestor de secretos, no en el código.

:::danger
Un token da acceso a cobrar en nombre de tu comercio. Nunca lo pongas en
código de frontend, en un repositorio, ni en una aplicación móvil. Todas las llamadas
se hacen desde tu servidor.
:::

## Prueba y producción [#ambientes]

Hay **dos tipos de token** y el tipo decide en qué ambiente ocurre todo:

| | Token de prueba | Token de producción |
| - | - | - |
| Para qué | Construir y probar tu integración | Cobrar de verdad |
| Movimiento de dinero | Ninguno | Real |
| Resultado de un pago | Lo decides tú con las [tarjetas de prueba](/sandbox) | Lo decide la red |
| Se ve en tu reporte | Sí, marcado como prueba | Sí |
| Se abona a tu cuenta virtual | No | Sí |

**No cambies de URL para probar.** Dentro de un mismo host es la misma API; lo que
decide si el dinero se mueve es el token. Un cobro creado con token de prueba solo se
puede consultar y pagar con token de prueba, y viceversa: los dos ambientes de datos no se
ven entre sí.

:::note
Al listar transacciones, el ambiente lo decide el token
(`api-access:test` o `api-access:production`), no un query param. Si envías
`production`, se ignora. Es la causa número uno de «no aparece mi transacción»:
estás consultando con el token del otro ambiente.
:::

:::caution
Las [reservas de cupo](/mit-pre-authorization) en
modalidad `api` **solo funcionan con token de producción**: retienen fondos reales y
no hay forma de simular una retención que después puedas cobrar o liberar.
:::

## Qué necesitas antes de empezar [#requisitos]

1. **Una cuenta de comercio activa.** Si tu comercio está deshabilitado o su estado no
   es activo o en revisión, la API responde `403` en todo.
2. **Un token**, de prueba para empezar.
3. **El id de tu sucursal**, que piden casi todos los endpoints que crean algo.

## Sucursal (`office`) [#office]

Muchos endpoints piden un campo `office` con el id de una de tus sucursales: generar un
pago, crear un plan, un suscriptor, un cupón. Obtén el tuyo con
[`GET /api/v1/offices/get`](/commercio#get) y guárdalo en tu
configuración; no cambia.

Si tu comercio tiene una sola sucursal, siempre será ese id.

## Token de webhooks [#webhook-token]

Es **distinto** del token de la API y tiene un solo propósito: verificar que un webhook
que recibes viene de nosotros y no de un tercero. Lo encuentras en el mismo lugar del
panel.

| | |
| - | - |
| Alcance | **Uno por comercio.** No hay uno por sede: todas las sedes firman con el mismo token |
| Ambientes | **El mismo para prueba y producción.** No se puede tener uno distinto por ambiente |
| Rotación | Hoy **no se puede rotar** desde el panel |

Nunca lo envíes en una petición; solo se usa para calcular la firma de los webhooks que
recibes. Ver [Webhooks](/webhooks).

:::danger
Como el token es único y no rotable, **trátalo como un secreto de larga
vida**: guárdalo en tu gestor de secretos, no lo dejes en el repositorio y no lo
registres en logs. Si crees que se filtró, escríbenos: la rotación hay que coordinarla.
:::

## Errores de autenticación [#errores]

| Código | Significa | Qué revisar |
| - | - | - |
| `401` | No llegó el token, o no es válido | El header `Authorization: Bearer ...`. Que no lo hayas revocado |
| `403` | El token es válido pero no puede operar | Que tu comercio esté activo y habilitado, y que el usuario del token esté activo |
| `404` en un recurso que sí creaste | Estás mirando el otro ambiente | Que el token sea del mismo tipo con el que creaste el recurso |

:::tip
Respuesta de una llamada autenticada correctamente
:::

Código de respuesta: 200

:::danger
Token ausente o inválido
:::

Código de respuesta: 401

```json
{
    "message": "Unauthenticated."
}
```

:::danger
Comercio o usuario que no puede operar
:::

Código de respuesta: 403

```json
{
    "message": "Unauthorized"
}
```