API de acciones

Expone verbos, no filas. No lista clientes, no lee facturas, no publica tablas. Lo único que sabe hacer es ejercer una acción declarada como pública, con la autorización que su dueño encendió, y contarte con precisión qué pasó.

Autenticación

Una clave del workspace, no una sesión de persona: autentica una integración. Authorization: Bearer nk_…. La clave nace acotada a unos alcances y con caducidad; se ve una sola vez, al crearla.

Idempotencia

Manda Idempotency-Key con un valor único por encargo. Un reintento por timeout con la misma clave no vuelve a ejecutar: contesta duplicate con lo que pasó la primera vez. Sin esa cabecera, un reintento es un encargo nuevo. La protección dura 24 h.

Tres desenlaces, no dos

done — hecho. refused — no se hizo, y por qué. pending_approval (202) — queda esperando una firma y puede terminar horas después; te avisamos por webhook cuando se resuelva. Un contrato de dos desenlaces obliga a que el tercero se disfrace de otro.

curl -X POST https://niiko.org/api/v1/actions/miira.lead_create \
  -H "Authorization: Bearer nk_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "01890a5d-ac96-774b-bcce-b302099a8057",
  "source": "web_form"
}'