Parriot

API y webhooks

Última actualización: 10 de octubre de 2026

La API REST de Parriot te deja leer y escribir contactos, cuotas, pagos, eventos y entradas desde tu propio sistema. Los webhooks te avisan al instante cuando algo cambia.

1. Autenticación

Creá una API key en Configuración → Desarrolladores (solo administradores). El token empieza con prt_ y se muestra una sola vez. Mandalo en cada request:

curl https://www.parriot.io/api/v1/contacts \
  -H "Authorization: Bearer prt_…"
  • Lectura: solo GET. Escritura: todos los métodos. Una key de lectura que intenta escribir recibe 403 INSUFFICIENT_SCOPE.
  • La key actúa como administrador en nombre de quien la creó. Si esa persona deja de ser administradora, se revoca la key o vence, responde 401 INVALID_API_KEY.
  • Las keys no pueden administrar keys, webhooks ni las conexiones con Mercado Pago y ARCA (403 PANEL_ONLY).
  • Todo lo que hace una key queda en el historial de actividad como “API”.

2. Convenciones

  • JSON en request y response; mandá Content-Type: application/json en los POST/PATCH.
  • Montos en centavos (enteros): 150000 = $1.500,00.
  • Fechas en ISO 8601 UTC; los períodos de liquidación como AAAA-MM.
  • Listas paginadas con ?page=1&pageSize=25 (máx. 100). Respuesta: { data, page, pageSize, total }.
  • Los recursos editables traen version: mandala en el PATCH. Si alguien lo cambió antes, responde 409 VERSION_CONFLICT: volvé a leer y reintentá.

3. Recursos

  • Contactos — /api/v1/contacts. Alumnos y responsables: listar, buscar, crear, editar, eliminar, vincular responsables (/contacts/{id}/guardians).
  • Conceptos y descuentos — /api/v1/items · /api/v1/discounts. Cuotas y cargos con sus asignaciones; descuentos y becas.
  • Liquidaciones — /api/v1/batches. Crear la liquidación del mes, editar líneas, enviarla (/send) o cancelarla.
  • Órdenes — /api/v1/orders. Deudas por contacto: crear, editar, cancelar, reenviar el aviso.
  • Pagos — /api/v1/payments. Listar, registrar pagos manuales, anular (/void) y devolver (/refund).
  • Eventos — /api/v1/events. Eventos, tipos de entrada, combos, campos del comprador, ventas manuales, cortesías, publicar y archivar.
  • Entradas — /api/v1/events/{id}/tickets · /api/v1/tickets/{id}. Listar entradas de un evento; cancelar, habilitar, transferir o deshacer un ingreso.
  • Puerta — /api/v1/door/events. Manifiesto, escaneos y estadísticas de ingreso en vivo.
  • Facturas — /api/v1/payments/{id}/invoices · /api/v1/fiscal-invoices/{id}. Facturas y notas de crédito de ARCA de un pago: listar, emitir a mano, reintentar (/retry) y bajar el PDF (/pdf).

4. Errores y límites

Toda respuesta con error tiene la misma forma; fields aparece en los errores de validación:

{ "error": { "code": "VALIDATION_ERROR", "message": "Revisá los datos marcados.", "fields": { "email": "Email inválido" } } }
  • 400 datos inválidos · 401 key inválida · 403 sin permiso · 404 no existe en tu institución · 409 estado o versión en conflicto.
  • Límite: 300 requests por minuto por key. Al pasarlo responde 429 RATE_LIMITED con el header Retry-After en segundos.

5. Webhooks

En Configuración → Desarrolladores cargá una URL https pública y elegí los eventos. Parriot hace un POST con este cuerpo:

{
  "id": "6f1c…",                 // id del evento: usalo para no procesar dos veces
  "type": "payment.received",
  "createdAt": "2026-10-06T18:42:10.000Z",
  "actor": { "type": "user", "apiKeyId": null },
  "data": { "object": "payment", "id": "b2e9…", "changes": { … } }
}

changes es informativo: para el estado actual pedí el recurso por la API. Si la acción la hizo una API key, viene actor.apiKeyId: sirve para ignorar los cambios que hizo tu propio sistema.

Eventos disponibles:

  • order.created — Orden creada
  • order.updated — Orden modificada
  • order.cancelled — Orden cancelada
  • payment.received — Pago recibido por Mercado Pago
  • payment.recorded — Pago registrado a mano
  • payment.refunded — Pago devuelto
  • payment.refunded_partial — Devolución parcial
  • payment.charged_back — Contracargo
  • payment.voided — Pago anulado
  • contact.created — Contacto creado
  • contact.updated — Contacto modificado
  • contact.deleted — Contacto eliminado
  • batch.sent — Liquidación enviada
  • event.created — Evento creado
  • event.published — Evento publicado
  • event.updated — Evento modificado
  • event.archived — Evento archivado
  • tickets.issued — Entradas emitidas
  • ticket.cancelled — Entrada cancelada
  • ticket.transferred — Entrada transferida
  • ticket.admitted — Entrada escaneada en la puerta
  • ticket.unadmitted — Ingreso deshecho
  • invoice.issued — Factura o nota de crédito emitida en ARCA

6. Verificar la firma

Cada envío trae Parriot-Signature: t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de <t>.<cuerpo crudo> con el secreto whsec_… del webhook. También vienen Parriot-Event-Id y Parriot-Event-Type.

import { createHmac, timingSafeEqual } from "node:crypto";

// raw = cuerpo crudo (string), sin parsear. secret = whsec_…
export function verifyParriot(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 min de tolerancia
  const expected = createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Si rotás el secreto, el anterior deja de firmar al instante: actualizalo en tu sistema enseguida.

7. Entregas y reintentos

  • Respondé 2xx en menos de 10 segundos; procesá en segundo plano si tarda más. No seguimos redirects.
  • Si falla, reintentamos hasta 8 veces: a 1, 5, 30 y 60 minutos, y después a 3, 6 y 12 horas (~22 h en total). Después queda como fallido y lo podés reenviar desde el panel.
  • Puede llegar más de una vez y sin orden garantizado: descartá duplicados por id y compará createdAt.
  • Desde el panel ves los últimos 50 envíos de cada webhook con el código HTTP, el error y el payload, y podés mandar un ping de prueba.

¿Dudas? Escribinos a hola@parriot.io. Ver también los Términos y condiciones.