Flux Partners API – Partners Gateway
Esta API expone un gateway estable para que partners consuman servicios financieros a través de Flux. Flux controla autenticación, auditoría, idempotencia y normalización hacia Partners.
Base URLs
Producción
https://globalflux.io/v1/api/partners
Local
http://localhost:8000/api/partners
Autenticación
Incluye tu API Key de Flux (no la de Partners). Flux se encarga del token bearer hacia Partners.
X-API-Key: <FLUX_API_KEY>
Accept: application/json
Content-Type: application/json
GET Catálogo de bancos (SPEI)
/api/partners/banks
cURL
curl -X GET "http://localhost:8000/api/partners/banks" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell (Invoke-RestMethod)
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/banks" `
-Headers $headers
Retorna listado paginado de instituciones SPEI.
GET Cuentas del cliente
/api/partners/clients/{clientId}/accounts
cURL
curl -X GET "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/accounts" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/accounts" `
-Headers $headers
POST Crear cuenta privada
/api/partners/clients/{clientId}/private-accounts
Body JSON
{
"bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
"owner_id": "205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"client_bank_adapter_id": "9c40bd38-e68d-41c5-9baa-ad6508aa3cc0",
"client_id": "205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"account_id": "00000000-0000-0000-0000-000000000000"
}
PowerShell
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
}
$body = @'
{
"bank_id":"9d84b03a-28d1-4898-a69c-38824239e2b1",
"owner_id":"205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"client_bank_adapter_id":"9c40bd38-e68d-41c5-9baa-ad6508aa3cc0",
"client_id":"205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"account_id":"00000000-0000-0000-0000-000000000000"
}
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/private-accounts" `
-Headers $headers -Body $body
GET Listar instrumentos
/api/partners/clients/{clientId}/instruments?customer_id=&page=&per_page=
cURL
curl -X GET "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/instruments?page=1&per_page=50" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/instruments?page=1&per_page=50" `
-Headers $headers
GET Obtener instrumento
/api/partners/clients/{clientId}/instruments/{instrumentId}
cURL
curl -X GET "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/instruments/<instrumentId>" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/instruments/<instrumentId>" `
-Headers $headers
POST Registrar instrumento
/api/partners/clients/{clientId}/instruments
Body JSON (debit_card)
{
"instrumentKind": "debit_card",
"source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
"client_id": "205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"type": "RECEIVER",
"rfc": "ND",
"alias": "Tarjeta ABC123",
"debit_card": {
"destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
"card_number": "5579072268574100",
"holder_name": "John Smith"
}
}
PowerShell
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
}
$body = @'
{
"instrumentKind":"debit_card",
"source_bank_id":"9d84b03a-28d1-4898-a69c-38824239e2b1",
"client_id":"205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"type":"RECEIVER",
"rfc":"ND",
"alias":"Tarjeta ABC123",
"debit_card":{
"destination_bank_id":"3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
"card_number":"5579072268574100",
"holder_name":"John Smith"
}
}
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/instruments" `
-Headers $headers -Body $body
POST Money Out (Transferencia)
/api/partners/transactions/money-out
Body JSON
{
"client_id": "205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"source_instrument_id": "<source_instrument_uuid>",
"destination_instrument_id": "<destination_instrument_uuid>",
"transaction_request": {
"external_reference": "INV-0001",
"description": "Pago proveedor",
"amount": "100.00",
"currency": "MXN"
}
}
PowerShell (Idempotency-Key)
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
"Idempotency-Key"="<uuid-v5-o-uuid>"
}
$body = @'
{
"client_id":"205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"source_instrument_id":"<source_instrument_uuid>",
"destination_instrument_id":"<destination_instrument_uuid>",
"transaction_request":{
"external_reference":"INV-0001",
"description":"Pago proveedor",
"amount":"100.00",
"currency":"MXN"
}
}
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/partners/transactions/money-out" `
-Headers $headers -Body $body
Recomendación: genera un Idempotency-Key por operación para reintentos seguros.
POST Refund
/api/partners/clients/{clientId}/transactions/{transactionId}/refund
Body JSON
{
"amount": "100.00",
"description": "Invalid amount"
}
PowerShell
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
}
$body = @'
{ "amount":"100.00", "description":"Invalid amount" }
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/transactions/<transactionId>/refund" `
-Headers $headers -Body $body
GET Listar webhooks
/api/partners/clients/{clientId}/webhooks
cURL
curl -X GET "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks" `
-Headers $headers
POST Crear webhook
/api/partners/clients/{clientId}/webhooks
Body JSON
{
"client_id": "205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"url": "https://tu-dominio.com/webhooks/money-in",
"token": "secretToken0123",
"webhook_type": "MONEY_IN"
}
PowerShell
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
}
$body = @'
{
"client_id":"205ae70f-ab7e-4b8d-85be-ac16f47c8983",
"url":"https://tu-dominio.com/webhooks/money-in",
"token":"secretToken0123",
"webhook_type":"MONEY_IN"
}
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks" `
-Headers $headers -Body $body
GET Consultar webhook
/api/partners/clients/{clientId}/webhooks/{id}
cURL
curl -X GET "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks/<webhookId>" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method GET `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks/<webhookId>" `
-Headers $headers
PATCH Actualizar webhook
/api/partners/clients/{clientId}/webhooks/{id}
Body JSON (ejemplo)
{
"url": "https://example.com/new-webhook",
"webhook_status": "ACTIVE"
}
PowerShell
$headers = @{
"X-API-Key"="<FLUX_API_KEY>"
"Content-Type"="application/json"
}
$body = @'
{ "url":"https://example.com/new-webhook", "webhook_status":"ACTIVE" }
'@
Invoke-RestMethod -Method PATCH `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks/<webhookId>" `
-Headers $headers -Body $body
DELETE Eliminar webhook
/api/partners/clients/{clientId}/webhooks/{id}
cURL
curl -X DELETE "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks/<webhookId>" ^ -H "X-API-Key: <FLUX_API_KEY>"
PowerShell
$headers = @{ "X-API-Key"="<FLUX_API_KEY>" }
Invoke-RestMethod -Method DELETE `
-Uri "http://localhost:8000/api/partners/clients/205ae70f-ab7e-4b8d-85be-ac16f47c8983/webhooks/<webhookId>" `
-Headers $headers
POST Webhook entrante (Partners → Flux)
/api/webhooks/money-in
Este endpoint es de entrada y no va bajo /partners. Partners lo llama directamente.
Headers
X-Webhook-Token: <Partners_WEBHOOK_TOKEN> Content-Type: application/json
PowerShell (ejemplo)
$headers = @{
"X-Webhook-Token"="<Partners_WEBHOOK_TOKEN>"
"Content-Type"="application/json"
}
$body = @'
{ "id_msg":"<uuid>", "msg_name":"MONEY_IN", "body":{ "amount":"10.00", "currency":"MXN" } }
'@
Invoke-RestMethod -Method POST `
-Uri "http://localhost:8000/api/webhooks/money-in" `
-Headers $headers -Body $body
Notas operativas
Buenas prácticas para operación en producción
Recomendaciones
- Usa Idempotency-Key para money-out (reintentos seguros).
- Protege X-API-Key por partner y aplica rate limiting.
- Loguea request-id / correlation-id por cada request.
- Registra auditoría: request/response (sin exponer secretos).