# BIND ERP API · sandbox local

Sandbox para validar la integración del MVP **BIND-first** de Balam **sin tocar producción**.
Está pensado para que tú (Johann), Pedro (Balam) o un futuro dev puedan:

1. Entender la forma real del API de BIND ERP antes de tener el API key.
2. Probar el cliente tipado contra un mock que replica los headers, el formato OData y el rate-limit observable de BIND.
3. Cuando Pedro entregue las credenciales reales, **cambiar dos variables de entorno** y apuntar el mismo código a `https://api.bind.com.mx` sin reescribir nada.

> ✅ **ACTUALIZACIÓN 6-jul-2026 — validación contra el API real EJECUTADA.**
> Con el token entregado por Pedro (usuario de Arturo Rosas) se corrió la validación
> técnica de solo lectura (117 peticiones GET). Resultados completos, tabla de
> cobertura de endpoints, inventario de campos y veredicto del saldo en
> **[VALIDACION-API.md](VALIDACION-API.md)**. Los hallazgos clave ya están
> reconciliados en el cliente (`types.real.ts`, `BindClient` con `idStyle`).
> El mock conserva el schema aproximado previo — sigue siendo útil para CI/demo,
> pero el contrato real es el de `types.real.ts`.

---

## TL;DR del API de BIND (reconciliado con la validación del 6-jul)

| Tema | Hallazgo |
|---|---|
| **Base URL** | `https://api.bind.com.mx` ✅ confirmado |
| **Estilo** | REST con filtros OData v3 (`$filter`, `$top`≤100, `$skip`, `$orderby`). ⚠️ `$select` NO funciona (500); conteo total inaccesible; **GET por ID es REST `/{id}`, no `(guid'...')`** |
| **Auth** | ✅ **Solo** `Authorization: Bearer <token>` — la `Ocp-Apim-Subscription-Key` no se requiere. ⚠️ Token inválido → **500** (no 401) |
| **Origen del API key** | Cuenta BIND → Perfil de usuario → pestaña *Integraciones* (el de Balam salió del usuario de **Arturo Rosas**) |
| **Rate limit** | **20,000 peticiones / día** — no observable en headers; llevar contador local |
| **Sandbox oficial** | **No existe.** Este mock local sigue siendo la única red de pruebas sin efecto fiscal |
| **PAC para CFDI** | Integrado en BIND; el PDF del CFDI se descarga vía `GET /api/Invoices/{id}/pdf` ✅ |
| **Recursos confirmados (200)** | `Invoices`, **`Clients`** (no Customers), **`Quotes`**, `Products`, `Currencies`, `Warehouses`, `Locations`, `Activities`, `PriceLists`, `Orders`, `Providers`, `Banks`, `BankAccounts`, `Users` |
| **Recursos que NO existen** | **`Payments`** (≈20 nombres probados → 404 — el acumulado pagado viene DENTRO de cada factura), `Customers`, `Series`, `CreditNotes`, `Companies`… |
| **Saldo por factura** | ✅ **Plan A operativo:** `Total − Payments − CreditNotes` en la misma fila de `/api/Invoices` (verificado aritméticamente) |

### Por qué un sandbox propio y no Postman

- BIND solo tiene producción → cualquier `POST` real toca facturas reales con consecuencias fiscales.
- El contrato exacto está detrás de login → necesitamos un lugar donde ir **acumulando lo que aprendemos** del API real conforme Pedro nos dé acceso.
- Tener el contrato en código (TypeScript + tipos) hace que **el motor de cobranza del MVP se pueda probar con CI** sin depender de la red.
- Cuando llegue Belvo / BUK en Fase 2 esta misma estructura sirve como plantilla.

---

## Cómo correrlo

Requiere Node 20+.

```powershell
# 1) Instalar deps
cd bind-api-sandbox
npm install

# 2) Levantar el mock en una terminal
npm run mock
# -> [bind-mock] escuchando en http://localhost:4010

# 3) Correr la demo end-to-end en otra terminal
npm run demo
```

La demo ejecuta 5 escenarios alineados al MVP:

| # | Escenario | Qué demuestra |
|---|---|---|
| 1 | Listar clientes activos | Cómo se construye la query OData base del dashboard |
| 2 | Facturas vencidas (`Status eq 'overdue' and DueDate lt ...`) | El motor de cobranza |
| 3 | CxC agregada por cliente (MXN) | KPI directivo del dashboard |
| 4 | Factura USD a cliente extranjero | Regla sin-IVA + TC fijado al emitir |
| 5 | Intento de `POST /Activities` en modo read-only | El guardrail que evita escribir a BIND prod por accidente |

Output esperado (verificado):

```
── 2. Facturas vencidas — motor de cobranza
┌─────────┬──────────┬────────────┬──────────────┬──────────┬─────────┐
│ Folio    │ Cliente    │ DueDate      │ Currency │ Balance │
│ 'A-0003' │ '22222222' │ '2026-04-01' │ 'MXN'    │ 20880   │
│ 'A-0005' │ '11111111' │ '2026-05-20' │ 'MXN'    │ 62640   │

── 5. Intento de escritura en read-only (debe BLOQUEARSE)
   ✅ Guardrail OK: Read-only mode bloqueó POST /api/Activities. Cambia BIND_MODE=write...

Stats del cliente
{ requestsToday: 6, quota: 20000, remaining: 19994, mode: 'read-only' }
```

### Apuntar a producción (token real)

Solo cambiar variables de entorno — el código no se modifica (el cliente detecta
el estilo de ID; contra el API real usa `/{id}`):

```powershell
$env:BIND_BASE_URL = "https://api.bind.com.mx"
$env:BIND_API_TOKEN = "<token del perfil de Arturo — NUNCA versionarlo>"
$env:BIND_MODE = "read-only"   # mantenlo así hasta tener autorización para escribir
npm run demo
```

> ⚠️ La demo fue escrita contra el schema del mock (`types.ts` aproximados);
> contra producción algunos escenarios no aplican (p. ej. `Customers` → 404 real).
> Para explorar el API real usa el script de validación:
>
> ```powershell
> npm run validate:real   # solo GET, presupuesto de peticiones, reporte sanitizado
> ```

---

## Mapeo a la arquitectura de Balam

Este sandbox es el prototipo de lo que en el repo principal vivirá en `packages/integrations/bind/`:

```
balam/
└── packages/
    └── integrations/
        └── bind/
            ├── BindClient.ts      ← este sandbox lo prototipa
            ├── types.ts            ← este sandbox lo prototipa
            ├── odata.ts            ← este sandbox lo prototipa
            └── README.md
apps/
└── worker/
    └── src/
        └── modules/
            └── bind-sync/          ← consume BindClient, escribe a Postgres,
                                       respeta tenant_id + outbox pattern
```

El cliente está pensado para encajar con los principios del proyecto (ver `01 - ARQUITECTURA-TECNICA.md`):

- **Modo seguro por default** (`read-only`): bloquea `POST/PUT/PATCH/DELETE` en código. Cumple §1 "La plataforma no escribe a BIND en MVP".
- **Dry-run** opcional: imprime el request sin enviarlo (cumple §1 punto 2 "Modo dry-run disponible en cualquier acción con efecto externo").
- **Idempotencia preparada**: el método `addActivity` está aislado para que cuando se autorice escritura, sea fácil envolverlo con `idempotency_key`.
- **Quota awareness**: el cliente lleva un contador local de requests del día y avisa cuando se acerca al límite de 20K.
- **Retries con backoff** en 429 y 5xx, respetando `Retry-After`.

---

## Decisiones de discovery que este sandbox **acelera**

Estos son los puntos del `03_Anexo_Tecnico_Integraciones_Discovery_Balam.docx` y del `04_Checklist_Accesos_Datos_Dependencias_Balam.docx` que dejan de estar "pendientes de validar" en cuanto se ejecuta esta prueba con un API key real:

| Item del discovery | Cómo lo cierra este sandbox |
|---|---|
| Tipo de autenticación, headers requeridos | Ya implementado en `BindClient`: dos headers, listos para producción |
| Estructura de URLs por recurso | Confirmada (`/api/{Recurso}` + OData) y probada en mock |
| Operaciones de lectura: clientes, facturas, pagos | Demo las ejerce todas. Una vez con API key, basta correr `BIND_BASE_URL=https://api.bind.com.mx npm run demo` |
| Filtros y paginación (`$filter`, `$top`, `$skip`) | Validados contra mock con la misma sintaxis que documenta BIND |
| Estrategia de pruebas sin sandbox | **Esta es la respuesta**: mock local + cliente tipado + modos read-only / dry-run / write |
| Rate limits | El cliente cuenta requests; el mock simula `?simulate=throttle` para probar el backoff |

---

## Pendientes para cerrar con Pedro (sugerencia de mail)

> Pedro, para destrabar la integración con BIND necesitamos:
>
> 1. **API key** generado desde *Perfil → Integraciones* en la cuenta de Balam, idealmente con permisos **solo lectura** primero.
> 2. **Subscription Key** si el plan de Balam la requiere (algunos planes en Azure API Management la piden además del Bearer).
> 3. Confirmación del **plan contratado** — para saber si 20K req/día aplica o si está reducido.
> 4. **Schema exacto** del recurso `Invoices` (especialmente nombres de campos `UUID`, `Folio`, `Status`, `Balance`). Una llamada de ejemplo con una factura real anonimizada serviría: `GET /api/Invoices?$top=1`.
> 5. ¿Existe endpoint para descargar **XML/PDF del CFDI**? Por la doc parece que sí, pero falta confirmar la ruta exacta.
>
> Con (1)–(2) podemos correr el sandbox apuntando a `https://api.bind.com.mx` y validar lo demás de un jalón sin necesidad de otra llamada.

---

## Limitaciones honestas de este sandbox

- **El schema del MOCK (`types.ts`) sigue siendo la aproximación previa** — el contrato
  confirmado contra producción vive en **`src/client/types.real.ts`** y en
  [VALIDACION-API.md](VALIDACION-API.md). Pendiente (opcional): regenerar el seed del
  mock con los shapes reales para que la demo ejercite el contrato confirmado.
- **El mock acepta cualquier Bearer**, solo valida que exista. No es un servidor de auth real.
- **El mock implementa el GET por ID estilo OData `(guid'...')`** — el API real usa `/{id}`;
  el cliente lo resuelve con `idStyle`, el mock quedó intacto.
- **El parser de OData del mock solo cubre lo que el cliente genera** (`eq, ne, gt, lt, ge, le, and, or`, paréntesis).
- **No reproduce la lógica de `$expand`** — y el API real ni siquiera soporta `$select`, así que el payload completo es la norma.

Cuando alguno de estos límites se vuelva una piedra en el zapato, se extiende. Hoy es deliberadamente mínimo.