Criar um pedido de aprovação (API de intents)

Um sistema cria um pedido (intent) para que uma pessoa aprove ou recuse uma operação concreta. A pessoa vê os valores exatos e decide com a passkey ou, se o tipo o permitir, no telemóvel.

O pedido

curl -sS -X POST https://identity.example.com/v1/intents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-INV-42-attempt-1" \
  -d '{"operationType":"invoice.pay","subjectEmail":"ana@example.com",
       "externalReference":"INV-42","expiresInSeconds":900,
       "fields":{"amount":{"amount":"1250.00","currency":"EUR"}}}'

• Indique a pessoa com exatamente um de subjectUserId ou subjectEmail.
• Idempotency-Key é obrigatório: 1 a 256 caracteres ASCII visíveis, único por operação do seu lado.
• Valores: texto para text, integer, decimal e date (sem números de vírgula flutuante), booleanos JSON, {"amount","currency"} para montantes e a chave da opção para escolhas.

A resposta

• 201 com Location na primeira criação.
• 200 com Idempotent-Replayed: true quando repete com a mesma chave e o mesmo corpo.
• 409 com a mesma chave e um corpo diferente.
• O corpo traz intentJson (o documento que a pessoa vê), intentDigest e comparisonCode.

Mostre o código de comparação

No modo typed (o predefinido), o telemóvel esconde o código e a pessoa escreve os seis algarismos de comparisonCode. A sua aplicação tem de mostrar comparisonCode junto à operação, senão a pessoa não consegue aprovar no telemóvel.

Repetições

Repita em erros de rede, 429 e 5xx com a mesma chave e espera exponencial. Nunca gere uma chave nova para a mesma operação.

Limites

Validade de 60 segundos até ao máximo do tipo (omissão 900 s, máximo 24 h). No máximo 20 pedidos pendentes por pessoa e 1000 por cliente; o seguinte dá 429.

Dados pessoais

Não ponha nos campos nem em externalReference mais dados pessoais do que a aprovação precisa.