WAGMI recibe catálogo y facturas por endpoints versionados. Cada request entra firmado, con idempotencia, bandeja de revisión y auditoría antes de afectar contabilidad o reportes del cliente.
V1 vive hoy bajo /api/integrations/v1/toi porque el primer conector aprobado usa ese namespace. El contrato es reutilizable para otros POS aprobados; las rutas genéricas se publicarán cuando exista un segundo conector real.
Esta es la ruta completa para que un POS externo conecte con WAGMI sin acceso a base de datos. V1 ya fue validado con un primer conector aprobado; cualquier otro POS requiere sandbox, mapeo y aprobación de conector equivalente antes de producción.
Para abrir sandbox no necesitamos base de datos, SQL, usuarios internos ni pantallas privadas. Necesitamos muestras sanitizadas representativas para validar el contrato.
Este ejemplo valida conexión y muestra cómo firmar un envío sin usar credenciales productivas ni acceso a la base de datos.
export WAGMI_BASE_URL="https://wagmi.do"
export WAGMI_API_KEY="<sandbox_api_key>"
export WAGMI_WEBHOOK_SECRET="<sandbox_webhook_secret>"
curl -s "$WAGMI_BASE_URL/api/integrations/v1/toi/health" \
-H "Authorization: Bearer $WAGMI_API_KEY"
body='{"categories":[{"externalId":"sandbox-bebidas","name":"Bebidas","active":true}]}'
timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
idempotency_key="sandbox-category-smoke-001"
signature="$(printf "%s.%s.%s" "$timestamp" "$idempotency_key" "$body" | openssl dgst -sha256 -hmac "$WAGMI_WEBHOOK_SECRET" -binary | xxd -p -c 256)"
curl -s "$WAGMI_BASE_URL/api/integrations/v1/toi/categories/batch" \
-H "Authorization: Bearer $WAGMI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-WAGMI-Timestamp: $timestamp" \
-H "X-WAGMI-Idempotency-Key: $idempotency_key" \
-H "X-WAGMI-Signature: sha256=$signature" \
--data "$body"Los partners deben corregir 400/401/403 antes de reintentar. Sólo 429/5xx se reintentan con backoff.
Contrato público para partners POS.
Resumen humano del contrato. El OpenAPI JSON es la fuente importable para Swagger/Postman.
Confirmar que la API key está activa y ver capacidades de la conexión.
Crear o actualizar categorías externas.
Crear o actualizar productos externos para reporting, margen e imports.
Recibir facturas cerradas del POS externo en revisión contable/fiscal.
Anular una factura externa en revisión sin borrar evidencia.
Estos campos son los que más rompen integraciones cuando no se definen temprano. Mantenerlos estables evita duplicados, mezcla de sucursales y errores contables.
Antes de entregar credenciales sandbox o productivas, validamos muestras sanitizadas, target aprobado y branchExternalId exacto en una conexión sandbox separada. El partner no recibe acceso a base de datos y sandbox y producción requieren aprobación humana.
GET /health valida la llave y la conexión. Sólo requiere Bearer; no firma HMAC ni idempotency key.
Categorías, productos, facturas y anulaciones requieren firma e idempotencia.
{
"source": "TOI",
"sentAt": "2026-05-12T10:10:00-04:00",
"invoices": [
{
"externalId": "inv-1001",
"number": "1001",
"issuedAt": "2026-05-12T10:09:00-04:00",
"branchExternalId": "SUCURSAL-SANDBOX-001",
"channel": "DINE_IN",
"customer": {
"externalId": "cust-1",
"name": "Cliente final",
"rnc": null,
"phone": null,
"email": null
},
"fiscal": {
"fiscalSource": "NONE",
"ncf": null,
"ecf": null,
"ncfType": null
},
"currency": "DOP",
"subtotal": 480,
"discount": 0,
"tax": 86.4,
"tip": 48,
"total": 614.4,
"lines": [
{
"externalLineId": "line-1",
"productExternalId": "prod-classic-smash",
"name": "Classic Smash",
"quantity": 1,
"unitPrice": 480,
"discount": 0,
"tax": 86.4,
"total": 566.4
}
],
"payments": [
{
"method": "CASH",
"amount": 614.4,
"receivedAt": "2026-05-12T10:09:30-04:00"
}
]
}
]
}Muestras canónicas para validar sandbox antes de credenciales productivas.
{
"source": "TOI",
"sentAt": "2026-05-12T10:00:00-04:00",
"categories": [
{
"externalId": "cat-burgers",
"name": "Burgers",
"parentExternalId": null,
"active": true,
"sortOrder": 10
}
]
}{
"source": "TOI",
"sentAt": "2026-05-12T10:05:00-04:00",
"products": [
{
"externalId": "prod-classic-smash",
"sku": "SMASH-001",
"name": "Classic Smash",
"categoryExternalId": "cat-burgers",
"priceSell": 480,
"taxRate": 0.18,
"active": true,
"trackStock": false,
"imageUrl": null,
"barcodes": []
}
]
}{
"source": "TOI",
"sentAt": "2026-05-12T10:10:00-04:00",
"invoices": [
{
"externalId": "inv-1001",
"number": "1001",
"issuedAt": "2026-05-12T10:09:00-04:00",
"branchExternalId": "SUCURSAL-SANDBOX-001",
"channel": "DINE_IN",
"customer": {
"externalId": "cust-1",
"name": "Cliente final",
"rnc": null,
"phone": null,
"email": null
},
"fiscal": {
"fiscalSource": "NONE",
"ncf": null,
"ecf": null,
"ncfType": null
},
"currency": "DOP",
"subtotal": 480,
"discount": 0,
"tax": 86.4,
"tip": 48,
"total": 614.4,
"lines": [
{
"externalLineId": "line-1",
"productExternalId": "prod-classic-smash",
"name": "Classic Smash",
"quantity": 1,
"unitPrice": 480,
"discount": 0,
"tax": 86.4,
"total": 566.4
}
],
"payments": [
{
"method": "CASH",
"amount": 614.4,
"receivedAt": "2026-05-12T10:09:30-04:00"
}
]
}
]
}{
"externalId": "inv-1001",
"voidedAt": "2026-05-12T10:30:00-04:00",
"reason": "Anulada en POS externo",
"creditNote": null
}Si un partner reintenta el mismo evento, debe mantener la misma `X-WAGMI-Idempotency-Key` y el mismo body. Si el body cambia con la misma llave, WAGMI responde error controlado para evitar duplicados o corrupción de imports.
La activación productiva se habilita sólo cuando estos puntos están verdes. Si algo falta, seguimos en sandbox.