Descubrimiento de llaves en sandbox

Prueba de forma determinística el descubrimiento de llaves, alternativas, caché y fallas en el sandbox de Bre-B

Usa estos escenarios determinísticos para probar el descubrimiento de llaves sin depender de datos reales del directorio de Bre-B. Solo aplican en:

https://sandbox.api.cuentamono.com

Datos exclusivos del sandbox

Usa las identidades y cuentas de ejemplo únicamente para pruebas. Las reglas de sufijos de esta página no están disponibles en producción y no describen personas ni cuentas reales.

Prerrequisitos y scopes

Usa una cuenta tenant del sandbox y un token de acceso con el scope requerido en cada paso. Antes de probar, pídele a Mono que habilite el descubrimiento de llaves para ese tenant de sandbox:

Paso	Scope
`POST /api/v1/targets/discover`	`target_discoveries`
`GET /api/v1/banks` y `GET /api/v1/banks/{ach_code}`	`target_discoveries` o `target_discoveries:readonly`
`POST /api/v1/targets/resolve` para la alternativa 102	`target_resolutions`
`POST /api/v1/outgoing_transfers`	`outgoing_transfers`

Consulta autenticación y scopes para configurar el token.

Selecciona el escenario con `document_number`

Los últimos tres caracteres de person.document_number son el único selector. Cambiar el correo, teléfono, banco o cuenta no selecciona otro escenario.

Sufijo	Resultado
`101`	Llave de identificación exacta después de una alternativa previa de la misma persona
`102`	Sin llave exacta; una alternativa de identificación que se puede resolver
`103`	Resultado vacío; una petición idéntica repetida puede mostrar un hit de caché negativo
`104`	Directorio no disponible con HTTP `503`
Cualquier otro sufijo	El mismo resultado vacío y cacheable de `103`

El sufijo del documento es el único selector del escenario. El banco y la cuenta solicitados siguen siendo entradas válidas aunque la cuenta comience por 99; cambiar cualquiera de los dos no cambia el escenario del sandbox. Sin embargo, las respuestas determinísticas documentadas para 101 y 102 solo están garantizadas cuando el account.number solicitado no empieza por 99. Ese prefijo está reservado para destinos alternativos sintéticos, que Mono deriva de forma independiente.

102 también está reservado para resolución directa

Una llave en texto plano con forma de documento y terminada en 102 está reservada en sandbox para POST /api/v1/targets/resolve y para transferencias salientes pagadas por llave. Así, la alternativa devuelta por discovery se resuelve al mismo destino determinístico.

Coincidencia exacta: sufijo 101

Envía esta petición:

POST /api/v1/targets/discover
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "person": {
    "document_type": "CC",
    "document_number": "1192793101",
    "first_name": "Diego",
    "first_surname": "Sánchez",
    "phone": "+573104838791",
    "email": "diego@example.com"
  },
  "account": {
    "bank_code": "013",
    "number": "0013123456789",
    "type": "savings_account"
  }
}

La respuesta es:

{
  "state": "discovered",
  "state_reason": null,
  "attempts_count": 2,
  "resolution_id": "bbtgr_5tgliBmzjZ6mpQPRbQjfKj",
  "target": {
    "id": "bbtgt_5tgliBmzjZ6mpQPRbQjfKj",
    "key_type": "identification",
    "key_value": "1192793101",
    "resolution_type": "plain_key",
    "spbvi": "CRB",
    "participant_nit": "860003020",
    "creditor": {
      "type": "natural",
      "document_type": "CC",
      "document_number": "1192793101",
      "full_name": "Diego Sánchez"
    },
    "creditor_account": {
      "type": "savings_account",
      "number": "0013123456789",
      "currency_code": "COP"
    },
    "transaction_amount": null,
    "payment_id": null
  },
  "same_person_keys": [
    {
      "key_type": "alphanumeric",
      "key_value": "@BBVA3104838791",
      "bank_code": "001",
      "participant_nit": "860002964",
      "creditor_account": {
        "type": "savings_account",
        "number_last_four": "2852",
        "currency_code": "COP"
      },
      "resolution_required": true
    }
  ]
}

Para BBVA (bank_code=013), discovery prueba la plantilla alfanumérica del banco antes de la candidata de identificación. Observa la plantilla como una alternativa de la misma persona, encuentra la coincidencia exacta en el segundo intento y termina el recorrido. No prueba las candidatas posteriores de teléfono y correo.

Por eso, attempts_count depende del orden de candidatas y las plantillas del banco seleccionado; no es el número de campos de la petición. same_person_keys no es exhaustivo y solo contiene candidatas de la misma persona observadas antes de la primera coincidencia exacta.

Solo la llave exacta ganadora crea una resolución y emite target_resolution_created y target_resolution_resolved. La alternativa no emite webhooks de resolución. La entrega es asíncrona, por lo que target_resolution_created puede contener desde el inicio state=resolved.

Solo alternativa: sufijo 102

Usa el mismo payload con el documento terminado en 102:

POST /api/v1/targets/discover
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "person": {
    "document_type": "CC",
    "document_number": "1192793102",
    "first_name": "Diego",
    "first_surname": "Sánchez",
    "phone": "+573104838791",
    "email": "diego@example.com"
  },
  "account": {
    "bank_code": "013",
    "number": "0013123456789",
    "type": "savings_account"
  }
}

El recorrido completo de candidatas devuelve:

{
  "state": "not_discovered",
  "state_reason": "no_exact_target",
  "attempts_count": 4,
  "resolution_id": null,
  "target": null,
  "same_person_keys": [
    {
      "key_type": "identification",
      "key_value": "1192793102",
      "bank_code": "007",
      "participant_nit": "890903938",
      "creditor_account": {
        "type": "savings_account",
        "number_last_four": "6809",
        "currency_code": "COP"
      },
      "resolution_required": true
    }
  ]
}

Este resultado no crea una llave, resolución ni webhook de resolución. Entre las alternativas sintéticas del sandbox, únicamente esta alternativa identification terminada en 102 tiene garantizada una resolución posterior.

Resuelve y verifica la alternativa 102

Cuando el pagador seleccione la alternativa, resuelve su key_value exacto:

POST /api/v1/targets/resolve
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "format": "plain_key",
  "value": "1192793102"
}

La respuesta resuelta incluye este destino determinístico:

{
  "id": "bbtgr_6tgliBmzjZ6mpQPRbQjfKj",
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "format": "plain_key",
  "value": "1192793102",
  "state": "resolved",
  "state_reason": null,
  "target": {
    "id": "bbtgt_6tgliBmzjZ6mpQPRbQjfKj",
    "key_type": "identification",
    "key_value": "1192793102",
    "resolution_type": "plain_key",
    "spbvi": "CRB",
    "participant_nit": "890903938",
    "creditor": {
      "type": "natural",
      "document_type": "CC",
      "document_number": "1192793102",
      "full_name": "Persona Sandbox"
    },
    "creditor_account": {
      "type": "savings_account",
      "number": "99023886809",
      "currency_code": "COP"
    },
    "transaction_amount": null,
    "payment_id": null
  }
}

La identidad sintética siempre es CC / Persona Sandbox, y el resultado siempre es una llave identification para valores con forma de documento terminados en 102. Antes de pedir confirmación al pagador, verifica estas dos condiciones:

El participant_nit de la llave resuelta es 890903938, correspondiente al código ACH 007 de la alternativa.
creditor_account.number termina en el number_last_four anunciado, 6809.

No pagues la alternativa si cambió el destino ACH o la terminación de cuatro dígitos.

Resultado vacío y caché negativo: sufijo 103 o caso por defecto

Usa el sufijo 103 —o cualquier sufijo distinto de 101–104— para obtener un resultado vacío:

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "person": {
    "document_type": "CC",
    "document_number": "1192793103",
    "first_name": "Diego",
    "first_surname": "Sánchez",
    "phone": "+573104838791",
    "email": "diego@example.com"
  },
  "account": {
    "bank_code": "013",
    "number": "0013123456789",
    "type": "savings_account"
  }
}

La primera respuesta sin cachear es:

{
  "state": "not_discovered",
  "state_reason": "no_exact_target",
  "attempts_count": 4,
  "resolution_id": null,
  "target": null,
  "same_person_keys": []
}

Repite la misma petición dentro de una hora para probar el caché negativo:

{
  "state": "not_discovered",
  "state_reason": "no_exact_target",
  "attempts_count": 0,
  "resolution_id": null,
  "target": null,
  "same_person_keys": []
}

Solo se cachean los resultados not_discovered vacíos, por máximo una hora. Un sandbox compartido puede contener ya la misma huella, por lo que la primera petición que observes puede tener legítimamente attempts_count=0. Si el sandbox no dispone de HMAC para discovery, los resultados negativos no se cachean y cada petición hace el recorrido completo de candidatas.

Directorio no disponible: sufijo 104

Envía el payload normal con el documento 1192793104:

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "person": {
    "document_type": "CC",
    "document_number": "1192793104",
    "first_name": "Diego",
    "first_surname": "Sánchez",
    "phone": "+573104838791",
    "email": "diego@example.com"
  },
  "account": {
    "bank_code": "013",
    "number": "0013123456789",
    "type": "savings_account"
  }
}

Discovery aborta en el primer intento no disponible contra el directorio y devuelve HTTP 503:

{
  "code": "503 Service Unavailable",
  "errors": [
    {
      "error_code": "service_is_unavailable",
      "message": "The service is unavailable, Please try again later",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Service unavailable"
}

El error no se cachea ni crea llaves, resoluciones o webhooks. Reintenta con backoff limitado, como lo harías ante una falla transitoria en producción.

Usa la llave resultante en una transferencia

La llave exacta de 101 y la llave recién resuelta de 102 son de un solo uso. Envía el target.id seleccionado en una transferencia saliente:

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "transfers": [
    {
      "external_id": "sandbox-discovery-001",
      "target_id": "bbtgt_6tgliBmzjZ6mpQPRbQjfKj",
      "amount": {
        "amount": 10000,
        "currency": "COP"
      }
    }
  ]
}

También puedes crear una transferencia saliente por plain_key con un valor en forma de documento terminado en 102; se resolverá al mismo destino determinístico. Consulta transferencias salientes en sandbox y crear transferencias salientes.

Catálogo bancario

GET /api/v1/banks y GET /api/v1/banks/{ach_code} usan el catálogo normal del sandbox. No necesitan sufijos ni otros valores de simulación. Usa sus valores ach_code canónicos en las peticiones de discovery.