| name | ms-plaid Plaid integration |
| description | Microservicio ms-plaid — Link token, variables PLAID_*, flujo hacia items y enlaces a documentación Plaid. Usar al cambiar integración Plaid, endpoints o configuración. |
ms-plaid y Plaid
Cliente Go (plaid-go)
- Módulo:
github.com/plaid/plaid-go/v41 (versión fijada en services/ms-plaid/go.mod; alinear con el README de instalación).
- Actualizar:
cd services/ms-plaid && go get github.com/plaid/plaid-go/v41@latest && go mod tidy.
- La librería sigue la API Plaid 2020-09-14; tras un major de
plaid-go, revisar el constructor de LinkTokenCreateRequest y enums (CountryCode, Products) por posibles cambios generados desde OpenAPI.
Ubicación del código
- Servicio:
services/ms-plaid/
- Handler Link:
internal/handlers/plaid_link.go — POST /v1/users/{userId}/plaid/link-token
- Items (tras exchange):
internal/handlers/plaid_item.go — /v1/users/{userId}/plaid-item
- Cliente Plaid y request:
internal/plaidclient/
- Sesiones en BD: tabla
plaid_link_sessions (migración migrations/0007_plaid_link_sessions.sql)
Flujo end-to-end
- La app llama a POST
/v1/users/{userId}/plaid/link-token (identidad del usuario debe validarse en el API gateway; aquí se confía en userId de la ruta).
- El backend llama a Plaid
/link/token/create y devuelve link_token, expiration, request_id.
- Se inserta una fila en
plaid_link_sessions con expires_at, plaid_request_id, plaid_environment, initial_products. No se persiste el link_token.
- El cliente abre Plaid Link con ese token; al terminar recibe un
public_token.
- Paso siguiente (otro endpoint o el actual POST
plaid-item): intercambiar con Plaid /item/public_token/exchange y guardar item_id + access_token en plaid_items (ya soportado por el POST existente de plaid-item).
Origen de configuración
- Local: en
.env.dev define CONFIG_SOURCE=env, DATABASE_URL, PLAID_CLIENT_ID y SANDBOX_SECRET (el “Sandbox secret” del dashboard; opcionalmente PLAID_SECRET si prefieres ese nombre). Opcional: PLAID_ENV (sandbox, production, …). make run carga el archivo.
- AWS: quita
CONFIG_SOURCE=env en el task/container y define AWS_SECRET_ID con el JSON (database_url, http_port, plaid_client_id, plaid_secret o sandbox_secret, plaid_env opcional). Si la Lambda define PLAID_ENV, sobrescribe plaid_env del JSON (útil para alternar sin editar el secreto; también se puede fijar vía environment_variables de lambda_http_services en Terraform).
Configuración Plaid (MVP)
- Credenciales: env local
PLAID_CLIENT_ID + SANDBOX_SECRET (o PLAID_SECRET). En Secrets Manager: plaid_client_id y plaid_secret o sandbox_secret.
- Entorno API Plaid (
sandbox vs production): variable PLAID_ENV o clave plaid_env en el JSON. Si ambos faltan, el default es sandbox (applyPlaidMVPDefaults en internal/config/config.go). En production el secret del dashboard debe ser el de production, no el de sandbox.
- Link customization: el nombre exacto (como en el Dashboard → Link → Link customization) se envía vía
PLAID_LINK_CUSTOMIZATION_NAME o link_customization_name en el JSON. Si está vacío, la API de Plaid usa la customization default.
- Resto del Link (idioma, países, productos, días de transacciones, sin webhook/redirect por defecto): constantes
mvpPlaid* en internal/config/config.go → applyPlaidMVPDefaults.
Sin client id y secret (vía SANDBOX_SECRET o PLAID_SECRET), el link-token responde 503.
El body opcional del POST link-token sigue pudiendo enviar webhook_url y redirect_uri por petición.
Body opcional del link-token
CreateLinkTokenBody: redirect_uri, webhook_url — sustituyen a la config para esa petición.
Regenerar artefactos
- OpenAPI / Swagger: desde
services/ms-plaid, make swag
- Código SQL:
make sqlc (tras cambiar sql/queries/ o sql/schema.sql)
Documentación Plaid útil
Notas de cumplimiento / buenas prácticas
client_user_id debe ser un ID interno estable (en este MS: el userId numérico como string), no email ni teléfono.- Registrar
redirect_uri y webhooks en el dashboard de Plaid.
- Algunos flujos nuevos pueden requerir
user_id de /user/create en lugar del objeto user; revisar el contrato de vuestra cuenta si Plaid lo exige.
Pruebas
go test ./... en services/ms-plaid- Tests del servicio de link:
internal/services/plaid_link_test.go (mock del cliente Plaid y del repo)
