Nouron Pass isotipoNouron Pass
ES
Reservar mi lugar

Documentación

Inicio rápido: tu primer pago con la API

Con una llave de agente de práctica puedes comprobar la conexión con GET /v1/me, pedir un pago con POST /v1/spends y leer el resultado: un rechazo por regla llega como respuesta normal, no como error.

Antes de empezar

  • Una llave de agente de práctica (np_test_agent_…). Se crea en la consola, en Llaves de API, cuando se abre tu acceso. Se muestra una sola vez.
  • Un agente con reglas: el monto máximo por pago y los destinos permitidos.
  • Un cliente HTTP. Los ejemplos usan curl y la dirección base que publica openapi.json.

Paso 1: comprueba la conexión

GET /v1/me dice quién eres para la API: la llave, el agente y el entorno. Si responde 200, la llave funciona.

Comprobar la llave
curl https://api.nouronpass.com/v1/me \
  -H "Authorization: Bearer $NOURON_API_KEY"

Un 401 con invalid_api_key o missing_api_key significa que la llave está mal escrita o no llega; mira la página de errores.

Paso 2: pide un pago

POST /v1/spends pide un pago. amount es el MÁXIMO que el agente acepta pagar; el vendedor fija el monto final. La cabecera Idempotency-Key es obligatoria: si repites la llamada con la misma llave, no se paga dos veces.

Pedir un pago
curl -X POST https://api.nouronpass.com/v1/spends \
  -H "Authorization: Bearer $NOURON_API_KEY" \
  -H "Idempotency-Key: 7c1f0a52-3e9d-4c1b-9b3e-a41d0b6f2c11" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5.00",
    "destination": "registry.npmjs.org",
    "resource": {
      "url": "https://registry.npmjs.org/-/pro/private-packages/month",
      "method": "GET"
    }
  }'

Cada intento nuevo usa una llave de idempotencia nueva; un reintento de la misma llamada usa la misma.

Paso 3: lee el resultado

La respuesta es un pago con un status. Decide por status, decline_reason y next_action, nunca por el texto de message.

Respuesta (resumida)
{  "id": "spd_9a2f1a7c0d4e5b3a8c6d7e0f1a2b3c4d",  "status": "settled",  "amount": "5.00",  "amount_settled": "4.80",  "destination": "registry.npmjs.org",  "decline_reason": null,  "next_action": {    "code": "none"  }}
Estado
EstadoQué significa
`pending_approval`Supera el umbral del dueño y espera su aprobación. No lo repitas: consúltalo con GET /v1/spends/{id}.
`approved`Pasó las reglas y tiene cupo reservado; todavía no se envió.
`processing`Se envió y no hay resultado todavía. Consúltalo más tarde.
`settled`Pagado. Trae el resultado de la compra y el recibo firmado.
`declined`Una regla lo detuvo. Es una decisión, no un error: lee decline_reason.
`failed`Se aprobó pero el pago falló; no se movió dinero. Un intento nuevo exige una llave de idempotencia nueva.
`expired`Nadie aprobó a tiempo y el pago venció.
`cancelled`El agente lo canceló antes de enviarlo.

Un rechazo por regla no es un error

Cuando una regla del dueño detiene un pago, la API responde con HTTP 201 y un pago con status: declined y un motivo estable en decline_reason. Así curl -f no se rompe y un modelo no lo confunde con una falla.

Si algo falla

Un error de verdad (JSON mal escrito, llave inválida, recurso inexistente) llega con un estado HTTP 4xx o 5xx y el mismo sobre en todos los casos. Lee estos campos:

  • error.code: el código estable. Decide por él.
  • error.retry: no no repitas, as_is repite la misma petición con la misma llave de idempotencia, after_fixing corrige primero lo que dicen message y param.
  • error.outcome_unknown: si es true, el pago pudo haberse hecho; no repitas con otra llave, consulta el pago.
  • request_id: dalo a soporte si necesitas ayuda.
Un error (400)
{  "ok": false,  "status": 400,  "request_id": "req_3z6y1wUd",  "error": {    "type": "invalid_request_error",    "code": "invalid_amount_format",    "message": "«abc» no es un monto válido. Usa un número positivo como texto con hasta 6 decimales, por ejemplo \"4.80\".",    "param": "amount",    "retry": "after_fixing",    "retry_after_ms": null,    "outcome_unknown": false  }}

Siguientes pasos