Nouron Pass isotipoNouron Pass
PT
Reservar minha vaga

Documentação

Início rápido: seu primeiro pagamento com a API

Com uma chave de agente de prática você confere a conexão com GET /v1/me, pede um pagamento com POST /v1/spends e lê o resultado: uma recusa por regra chega como resposta normal, não como erro.

Antes de começar

  • Uma chave de agente de prática (np_test_agent_…). É criada no console, em Chaves de API, quando seu acesso é aberto. Aparece uma única vez.
  • Um agente com regras: o valor máximo por pagamento e os destinos permitidos.
  • Um cliente HTTP. Os exemplos usam curl e o endereço base que o openapi.json publica.

Passo 1: confira a conexão

GET /v1/me diz quem você é para a API: a chave, o agente e o ambiente. Se responder 200, a chave funciona.

Conferir a chave
curl https://api.nouronpass.com/v1/me \
  -H "Authorization: Bearer $NOURON_API_KEY"

Um 401 com invalid_api_key ou missing_api_key significa que a chave está mal escrita ou não chega; veja a página de erros.

Passo 2: peça um pagamento

POST /v1/spends pede um pagamento. amount é o valor MÁXIMO que o agente aceita pagar; o vendedor fixa o valor final. O cabeçalho Idempotency-Key é obrigatório: se você repetir a chamada com a mesma chave, não se paga duas vezes.

Pedir um pagamento
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 tentativa nova usa uma chave de idempotência nova; uma repetição da mesma chamada usa a mesma.

Passo 3: leia o resultado

A resposta é um pagamento com um status. Decida por status, decline_reason e next_action, nunca pelo texto de message.

Resposta (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
EstadoO que significa
`pending_approval`Supera o limite do dono e espera a aprovação dele. Não repita: consulte com GET /v1/spends/{id}.
`approved`Passou pelas regras e tem limite reservado; ainda não foi enviado.
`processing`Foi enviado e ainda não há resultado. Consulte mais tarde.
`settled`Pago. Traz o resultado da compra e o recibo assinado.
`declined`Uma regra o impediu. É uma decisão, não um erro: leia decline_reason.
`failed`Foi aprovado, mas o pagamento falhou; nenhum dinheiro foi movido. Uma nova tentativa exige uma chave de idempotência nova.
`expired`Ninguém aprovou a tempo e o pagamento venceu.
`cancelled`O agente cancelou antes de enviar.

Uma recusa por regra não é um erro

Quando uma regra do dono impede um pagamento, a API responde com HTTP 201 e um pagamento com status: declined e um motivo estável em decline_reason. Assim curl -f não quebra e um modelo não confunde isso com uma falha.

Se algo falhar

Um erro de verdade (JSON mal escrito, chave inválida, recurso inexistente) chega com um status HTTP 4xx ou 5xx e o mesmo envelope em todos os casos. Leia estes campos:

  • error.code: o código estável. Decida por ele.
  • error.retry: no não repita, as_is repita a mesma requisição com a mesma chave de idempotência, after_fixing corrija primeiro o que dizem message e param.
  • error.outcome_unknown: se for true, o pagamento pode ter sido feito; não repita com outra chave, consulte o pagamento.
  • request_id: informe ao suporte se precisar de ajuda.
Um erro (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  }}

Próximos passos