Referencia de la API

API de CivicFlow

Una API REST predecible y webhooks firmados para incidencias, equipos, categorías y vecinos: la misma API sobre la que construimos nuestras apps.

Leer las guías Estado de la API

URL base https://api.civicflow.site/v2 v2 · Estable OpenAPI 3.1

En esta página

Introducción

La API se organiza en recursos con URL predecibles. Las peticiones y respuestas son JSON sobre HTTPS, las marcas de tiempo siguen ISO 8601 en UTC y todos los listados usan la misma paginación por cursor.

Cada espacio de trabajo tiene un entorno de producción y otro de pruebas con claves de API distintas. Los datos de pruebas nunca se muestran a los vecinos.

Protocolo: REST sobre HTTPS (TLS 1.3)
Formato: JSON, UTF-8
Especificación: OpenAPI 3.1
Eventos: Webhooks firmados

openapi.yaml está disponible en tu espacio, en Ajustes → Desarrolladores.

Autenticación

Autentícate con una clave de API secreta enviada como token Bearer. Los administradores crean las claves en Ajustes → Desarrolladores; cada clave tiene un nombre, un entorno y un conjunto de permisos (scopes), y puede rotarse o revocarse en cualquier momento.

Shell Authorization header

1curl https://api.civicflow.site/v2/incidents \2  -H "Authorization: Bearer $CIVICFLOW_KEY"

Permisos (scopes)
Permiso	Permite
`incidents:read`	Leer incidencias, historial y metadatos de adjuntos
`incidents:write`	Crear, actualizar, asignar y resolver incidencias
`comments:write`	Publicar notas internas y respuestas a vecinos
`attachments:write`	Subir y eliminar adjuntos
`teams:read`	Leer equipos, miembros y zonas de servicio
`categories:write`	Crear y actualizar categorías y políticas de SLA
`webhooks:manage`	Crear, probar y eliminar endpoints de webhooks
`residents:read`	Leer y exportar perfiles de vecinos (datos personales)
`residents:erase`	Anonimizar vecinos para atender solicitudes de supresión

Límites de uso

Los límites se aplican por espacio de trabajo y entorno, con un margen de ráfaga adicional. Cada respuesta indica tu cupo actual; si lo superas, la API devuelve 429 con una cabecera Retry-After.

Límites por plan
Plan	Peticiones / minuto	Ráfaga	Acceso
Starter	60	10	Endpoints de solo lectura
Growth	600	100	Lectura y escritura
Enterprise	desde 3.000	A medida	Lectura y escritura, límites a medida

Cabeceras de respuesta

X-RateLimit-Limit: Peticiones permitidas en la ventana actual
X-RateLimit-Remaining: Peticiones restantes en la ventana actual
X-RateLimit-Reset: Hora Unix en la que se reinicia la ventana
Retry-After: Segundos de espera antes de reintentar (solo con 429)

Paginación

Los listados devuelven hasta limit elementos (25 por defecto, 100 como máximo) y un next_cursor. Pásalo como cursor para obtener la página siguiente; cuando has_more sea false, habrás llegado al final. Los cursores se mantienen estables mientras paginas, aunque lleguen incidencias nuevas.

Shell GET /v2/incidents

1# First page2curl "https://api.civicflow.site/v2/incidents?limit=50" \3  -H "Authorization: Bearer $CIVICFLOW_KEY"45# Next page: pass next_cursor from the previous response6curl "https://api.civicflow.site/v2/incidents?limit=50&cursor=c_8f3a91d2" \7  -H "Authorization: Bearer $CIVICFLOW_KEY"

Errores

CivicFlow usa los códigos de estado HTTP habituales. Los errores incluyen siempre un code legible por máquinas, un message legible por personas y un request_id que puedes indicar al contactar con soporte.

Códigos de error
Estado	Código	Significado
400	`invalid_request`	La petición está mal formada, p. ej. JSON no válido o un parámetro desconocido.
401	`unauthenticated`	Falta la clave de API, está revocada o no es válida.
403	`insufficient_scope`	La clave es válida, pero no tiene permiso para esta acción.
404	`not_found`	El recurso no existe en este espacio de trabajo.
409	`conflict`	La petición entra en conflicto con el estado actual, p. ej. resolver una incidencia ya resuelta.
422	`validation_failed`	La validación ha fallado; consulta los errores por campo en details.
429	`rate_limited`	Se ha superado el límite de uso; reintenta tras el intervalo de Retry-After.
500	`internal_error`	Algo ha fallado por nuestra parte. Puedes reintentar con espera progresiva.

JSON 422 Unprocessable Entity

1{2  "error": {3    "code": "validation_failed",4    "message": "location is required for category lighting",5    "details": [{ "field": "location", "issue": "missing" }],6    "request_id": "req_7c41e09b2a"7  }8}

Versiones y obsolescencia

La versión mayor forma parte de la URL (/v2). Dentro de una versión solo hacemos cambios aditivos: endpoints nuevos, parámetros opcionales, campos y tipos de evento nuevos. Diseña clientes que ignoren los campos desconocidos.

Los cambios incompatibles solo llegan en una nueva versión mayor.
Los endpoints obsoletos siguen funcionando al menos 12 meses y devuelven las cabeceras Deprecation y Sunset.
Avisamos a los administradores por correo y en el espacio, y las llamadas obsoletas aparecen en el informe de uso de la API.
La API v1 está obsoleta y se retirará el 31 de marzo de 2027.

Endpoints

Todos los recursos siguen los mismos patrones. El listado de incidencias se documenta por completo más abajo; el resto está en openapi.yaml.

Incidencias

GET /v2/incidents Listar incidencias, filtradas y ordenadas Documentado abajo
POST /v2/incidents Crear una incidencia en nombre de un vecino o sistema
GET /v2/incidents/{id} Obtener una incidencia con todo su historial
PATCH /v2/incidents/{id} Actualizar estado, prioridad, categoría o ubicación
POST /v2/incidents/{id}/assign Asignar una incidencia a un equipo o persona
POST /v2/incidents/{id}/resolve Resolver una incidencia con una nota y fotos de prueba

Comentarios

GET /v2/incidents/{id}/comments Listar notas internas y respuestas a vecinos
POST /v2/incidents/{id}/comments Añadir una nota interna o responder al vecino
DELETE /v2/comments/{id} Eliminar una nota interna

Adjuntos

GET /v2/incidents/{id}/attachments Listar fotos y archivos de una incidencia
POST /v2/incidents/{id}/attachments Subir una foto o archivo (hasta 25 MB)
DELETE /v2/attachments/{id} Eliminar un adjunto

Equipos

GET /v2/teams Listar equipos y brigadas de campo
GET /v2/teams/{id} Obtener un equipo con sus miembros y zona de servicio
PATCH /v2/teams/{id} Actualizar miembros, turnos o zona de servicio de un equipo

Webhooks

GET /v2/webhooks Listar endpoints de webhooks
POST /v2/webhooks Registrar un endpoint de webhook para los eventos elegidos
POST /v2/webhooks/{id}/test Enviar un evento de prueba firmado a un endpoint
DELETE /v2/webhooks/{id} Eliminar un endpoint de webhook

Vecinos

GET /v2/residents/{id} Obtener el perfil de un vecino
GET /v2/residents/{id}/export Exportar todo lo que se guarda de un vecino (solicitud de acceso)
POST /v2/residents/{id}/erase Anonimizar a un vecino (solicitud de supresión)

Listar incidencias

GET /v2/incidents

Devuelve las incidencias del espacio de trabajo, de la más reciente a la más antigua. Requiere el permiso incidents:read. Puedes combinar filtros libremente: se aplican con Y lógico.

Parámetros de consulta

Parámetros de consulta de GET /v2/incidents
Parámetro	Tipo	Descripción
`status`	string	Filtra por estado: open, urgent, assigned o resolved. Separa varios con comas.
`category`	string	Clave de categoría, p. ej. lighting.
`district`	string	Clave de distrito, p. ej. north.
`team`	string	Solo incidencias asignadas a este id de equipo.
`updated_since`	timestamp	Solo incidencias actualizadas en esta marca de tiempo ISO 8601 o después.
`sort`	string	created_at, -created_at (por defecto), priority o sla_due_at.
`limit`	integer	Elementos por página, de 1 a 100. Por defecto, 25.
`cursor`	string	El next_cursor de una página anterior.

Ejemplo de petición

GET /v2/incidents

1curl "https://api.civicflow.site/v2/incidents?status=open,urgent&district=north&limit=2" \2  -H "Authorization: Bearer $CIVICFLOW_KEY"

Ejemplo de respuesta

JSON 200 OK

1{2  "data": [3    {4      "id": "CF-4821",5      "title": "Streetlight outage",6      "category": "lighting",7      "status": "urgent",8      "priority": "high",9      "district": "north",10      "location": { "address": "Linden St & 4th Ave", "lat": 52.3791, "lng": 4.8994 },11      "assigned_team": "elec-4",12      "created_at": "2026-10-08T09:12:44Z",13      "sla_due_at": "2026-10-08T21:12:00Z"14    },15    {16      "id": "CF-4833",17      "title": "Hydrant leak",18      "category": "water",19      "status": "urgent",20      "priority": "high",21      "district": "north",22      "location": { "address": "Birch Ln", "lat": 52.3804, "lng": 4.9051 },23      "assigned_team": null,24      "created_at": "2026-10-08T08:47:10Z",25      "sla_due_at": "2026-10-08T12:47:10Z"26    }27  ],28  "has_more": true,29  "next_cursor": "c_8f3a91d2"30}

Webhooks

Registra un endpoint HTTPS y elige los eventos que recibe. Los envíos son peticiones POST con JSON; responde con cualquier 2xx en menos de 10 segundos. Los envíos fallidos se reintentan con espera exponencial durante un máximo de 24 horas, y cada intento queda en el registro de envíos.

Eventos de webhook
Evento	Se envía cuando
`incident.created`	Un vecino, un empleado o una integración comunica una incidencia nueva.
`incident.assigned`	Una incidencia se asigna o reasigna a un equipo o persona.
`incident.status_changed`	Cambia el estado de una incidencia. Incluye previous_status.
`incident.resolved`	Se resuelve una incidencia, con nota de resolución y fotos de prueba.
`comment.created`	Se añade una nota interna o una respuesta del vecino.

Verifica las firmas

Cada envío incluye la cabecera CivicFlow-Signature con una marca de tiempo y un HMAC-SHA256 de timestamp.body, firmado con el secreto del endpoint. Verifícala con el cuerpo original de la petición y rechaza los envíos de hace más de cinco minutos.

JavaScript verify-signature.js

1import crypto from "node:crypto";23// header: "t=1791460023,v1=5f2b…"; rawBody: the unparsed request body4export function verifySignature(header, rawBody, secret) {5  const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));6  const expected = crypto7    .createHmac("sha256", secret)8    .update(`${t}.${rawBody}`)9    .digest("hex");10  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;11  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));12}

SDK

Clientes oficiales y tipados que gestionan por ti la autenticación, la paginación y los reintentos.

Node.js
3.4.0

Tipos de TypeScript para cada recurso. Node 18 o posterior.

$ npm install @civicflow/node
Python
1.2.1

Clientes síncronos y asíncronos con anotaciones de tipo. Python 3.9 o posterior.

$ pip install civicflow
Go
Próximamente

Un módulo idiomático de Go está en beta privada con dos clientes.

Novedades

1 de octubre de 2026

v2.8

Sincronización incremental de incidencias

Nuevo filtro updated_since en GET /v2/incidents y campo previous_status en los eventos incident.status_changed.
9 de septiembre de 2026

v2.7

Adjuntos más grandes

Los adjuntos admiten ahora hasta 25 MB (antes, 10 MB). Las subidas de más de 5 MB usan sesiones reanudables.
12 de agosto de 2026

v2.6

API de vecinos y SDK de Python 1.0

Nuevos endpoints para exportar y anonimizar vecinos en solicitudes de acceso y supresión. El SDK de Python alcanza la versión 1.0.

¿Estás creando una integración?

Lee las guías de configuración y conceptos, consulta la disponibilidad de la API en directo o revisa cómo protegemos tus datos.

Documentación Estado de la API Seguridad

API de CivicFlow

Introducción

Autenticación

Límites de uso

Cabeceras de respuesta

Paginación

Errores

Versiones y obsolescencia

Endpoints

Incidencias

Comentarios

Adjuntos

Equipos

Categorías

Webhooks

Vecinos

Listar incidencias

Parámetros de consulta

Ejemplo de petición

Ejemplo de respuesta

Webhooks

Verifica las firmas

SDK

Node.js

Python

Go

Novedades

Sincronización incremental de incidencias

Adjuntos más grandes

API de vecinos y SDK de Python 1.0

¿Estás creando una integración?