API REST — v1

Documentación de API

Accede a tus facturas y clientes programáticamente. Disponible en el plan Business.

Autenticación

Todas las solicitudes deben incluir tu clave API en el encabezado Authorization . Crea y administra tus claves en Cuenta → Claves API.

curl https://paycivo.com/api/v1/invoices \
  -H "Authorization: Bearer pv_live_YOUR_KEY_HERE"

URL Base

https://paycivo.com/api/v1

Todas las respuestas son JSON. El cuerpo de las solicitudes debe incluir Content-Type: application/json.

Códigos de error

Nombre	Descripción
200	OK — solicitud exitosa
201	Creado — recurso creado correctamente
400	Solicitud incorrecta — campos faltantes o inválidos
401	No autorizado — clave API faltante o inválida
403	Prohibido — función no disponible en tu plan
404	No encontrado — el recurso no existe
500	Error del servidor — algo salió mal en nuestro lado

Endpoints

GET/api/v1/invoices— Listar Facturas

Devuelve una lista paginada de facturas del usuario autenticado.

Parámetros

Nombre	Tipo	Requerido	Descripción
status	string	opcional	Filtrar por estado: draft \| sent \| paid \| overdue
limit	number	opcional	Máximo de resultados (defecto 50, máximo 100)
offset	number	opcional	Desplazamiento de paginación (defecto 0)

Respuesta de ejemplo

{
  "data": [ { "id": "...", "invoice_number": "INV-2026-0001", "status": "paid", "total": 1500, ... } ],
  "total": 24,
  "limit": 50,
  "offset": 0
}

GET/api/v1/invoices/:id— Obtener Factura

Devuelve una sola factura por ID.

Parámetros

Nombre	Tipo	Requerido	Descripción
:id	string	requerido	El UUID de la factura

Respuesta de ejemplo

{ "data": { "id": "...", "invoice_number": "INV-2026-0001", "status": "paid", ... } }

PATCH/api/v1/invoices/:id— Actualizar Factura

Actualiza el estado, notas o fecha de vencimiento de una factura.

Parámetros

Nombre	Tipo	Requerido	Descripción
:id	string	requerido	El UUID de la factura
status	string	opcional	Nuevo estado: draft \| sent \| paid \| overdue
notes	string	opcional	Notas actualizadas
due_date	string	opcional	Nueva fecha de vencimiento (AAAA-MM-DD)

Respuesta de ejemplo

{ "data": { "id": "...", "status": "paid", ... } }

POST/api/v1/invoices— Crear Factura

Crea una nueva factura.

Parámetros

Nombre	Tipo	Requerido	Descripción
invoice_number	string	requerido	Número único de factura (ej. INV-2026-0001)
issue_date	string	requerido	Fecha de emisión (AAAA-MM-DD)
due_date	string	requerido	Fecha de vencimiento (AAAA-MM-DD)
line_items	array	requerido	Arreglo de { description, quantity, rate }
client_id	string	opcional	UUID del cliente (de /api/v1/clients)
tax_rate	number	opcional	Porcentaje de impuesto (ej. 8.5)
discount_percent	number	opcional	Porcentaje de descuento (ej. 10)
currency	string	opcional	Código de moneda ISO (defecto USD)
notes	string	opcional	Notas opcionales

Respuesta de ejemplo

{ "data": { "id": "...", "invoice_number": "INV-2026-0001", "status": "draft", "total": 1500, ... } }

GET/api/v1/clients— Listar Clientes

Devuelve una lista paginada de clientes.

Parámetros

Nombre	Tipo	Requerido	Descripción
limit	number	opcional	Máximo de resultados (defecto 50, máximo 100)
offset	number	opcional	Desplazamiento de paginación (defecto 0)

Respuesta de ejemplo

{
  "data": [ { "id": "...", "name": "Acme Corp", "email": "billing@acme.com", ... } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

GET/api/v1/clients/:id— Obtener Cliente

Devuelve un solo cliente por ID.

Parámetros

Nombre	Tipo	Requerido	Descripción
:id	string	requerido	El UUID del cliente

Respuesta de ejemplo

{ "data": { "id": "...", "name": "Acme Corp", "email": "billing@acme.com", ... } }

¿Listo para construir?

Regístrate en Paycivo Business y obtén tu clave API en minutos.

Comenzar gratis →

¿Preguntas? Escríbenos a support@paycivo.com