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 recibe403 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/jsonen 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, responde409 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" } } }400datos inválidos ·401key inválida ·403sin permiso ·404no existe en tu institución ·409estado o versión en conflicto.- Límite: 300 requests por minuto por key. Al pasarlo responde
429 RATE_LIMITEDcon el headerRetry-Afteren 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 creadaorder.updated— Orden modificadaorder.cancelled— Orden canceladapayment.received— Pago recibido por Mercado Pagopayment.recorded— Pago registrado a manopayment.refunded— Pago devueltopayment.refunded_partial— Devolución parcialpayment.charged_back— Contracargopayment.voided— Pago anuladocontact.created— Contacto creadocontact.updated— Contacto modificadocontact.deleted— Contacto eliminadobatch.sent— Liquidación enviadaevent.created— Evento creadoevent.published— Evento publicadoevent.updated— Evento modificadoevent.archived— Evento archivadotickets.issued— Entradas emitidasticket.cancelled— Entrada canceladaticket.transferred— Entrada transferidaticket.admitted— Entrada escaneada en la puertaticket.unadmitted— Ingreso deshechoinvoice.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é
2xxen 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
idy 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
pingde prueba.
¿Dudas? Escribinos a hola@parriot.io. Ver también los Términos y condiciones.
