Convenciones de la API

La API es REST sobre HTTPS. Todas las peticiones y respuestas usan JSON. La URL base es https://api.yo-facturo.com con el prefijo /api/v1/.

Operaciones CRUD

La mayoría de los recursos exponen el mismo conjunto de operaciones estándar.

Formato de las respuestas

Toda respuesta es un objeto JSON con el campo booleano success (siempre presente). En una respuesta exitosa, el recurso (o la lista) viene en el campo data. Los endpoints CRUD incluyen además enlaces de navegación HATEOAS en el campo links.

{
  "success": true,
  "data": { "_id": "...", "name": "..." },
  "links": { "self": { "href": "...", "method": "GET" } }
}

Ante un error, success es false y la respuesta incluye un mensaje en error y un identificador en code. Los errores de validación incluyen además un array errors con el detalle por campo.

{
  "success": false,
  "error": "El campo 'name' es obligatorio",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "field": "name", "message": "Campo obligatorio" }
  ]
}

Paginación

El endpoint de listado acepta query params para controlar la paginación.

El parámetro canónico para el tamaño de página es per_page. Algunos endpoints aceptan además limit como alias equivalente; ante la duda, usá siempre per_page.

Dentro del campo data, la respuesta de un listado trae el array items junto con los metadatos de paginación: total, page, per_page, total_pages, has_next y has_prev.

{
  "success": true,
  "data": {
    "items": [ { "_id": "...", "name": "..." } ],
    "total": 134,
    "page": 1,
    "per_page": 20,
    "total_pages": 7,
    "has_next": true,
    "has_prev": false
  }
}

Para recorrer todas las páginas de un listado, incrementá el parámetro page mientras el campo has_next de la respuesta sea true.

El listado devuelve también un bloque _meta con los campos por los que se puede ordenar (sortable_fields), el orden aplicado en la respuesta (current_sort) y su dirección (sort_direction).

Búsqueda, orden y filtros

El endpoint de listado acepta además los siguientes query params:

Cualquier otro query param se interpreta como filtro por igualdad de ese campo.

curl "https://api.yo-facturo.com/api/v1/products/list/?per_page=50&sort=name&sort_dir=1&fields=_id,name" \
  -H "X-API-Key: TU_TOKEN"

Operaciones en lote (bulk)

Para procesar varios registros en una sola petición.

La respuesta de un bulk informa, por cada item, si tuvo éxito o el error, más un resumen (total, success_count, error_count).

curl -X POST https://api.yo-facturo.com/api/v1/products/bulk/create/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "Producto A"}, {"name": "Producto B"}]}'

Fechas

Todas las fechas se envían y se reciben en formato ISO 8601. La API interpreta y devuelve las fechas en la zona horaria configurada en la cuenta del tenant.

2026-05-21T13:32:23Z

Actualización parcial

El método PUT sobre /api/v1/<recurso>/<id>/ actualiza únicamente los campos enviados en el body. Los campos omitidos se mantienen sin cambios. Para borrar el valor de un campo, enviá null de forma explícita.

curl -X PUT https://api.yo-facturo.com/api/v1/products/PRODUCT_ID/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price": 1500, "description": null}'

Versionado

La API está versionada en la URL mediante el prefijo /api/v1/. Una versión nueva, de existir, se publicaría bajo un prefijo distinto; la v1 se mantiene estable y compatible hacia atrás.

Idempotencia y reintentos

Las operaciones GET, PUT y DELETE son idempotentes: repetir la misma petición no cambia el resultado, por lo que es seguro reintentarlas ante un error de red. Los POST de creación no son idempotentes: si una petición termina en timeout, antes de reintentar conviene consultar (con un GET de listado o filtro) si el recurso ya se creó.

Para la emisión de comprobantes electrónicos AFIP, evitá reintentar a ciegas: un reintento podría generar un comprobante duplicado. Verificá primero el estado del comprobante antes de volver a emitir.

La API es solo de tipo "pull": tu integración consulta los datos cuando los necesita. No hay webhooks salientes ni notificaciones push desde la API.

Flujo de ejemplo

Un flujo completo de facturación encadena varias llamadas: el identificador (_id) que devuelve una respuesta se usa como entrada de la siguiente.

1. Crear un cliente

La respuesta trae el cliente en data._id; guardá ese valor.

curl -X POST https://api.yo-facturo.com/api/v1/customers/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme S.A.", "doc_type": "CUIT", "doc_number": "30123456789"}'

# Respuesta: { "success": true, "data": { "_id": "CUSTOMER_ID", ... } }

2. Crear un producto

curl -X POST https://api.yo-facturo.com/api/v1/products/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Servicio mensual", "price": 1500}'

# Respuesta: { "success": true, "data": { "_id": "PRODUCT_ID", ... } }

3. Registrar la venta

Se usa el CUSTOMER_ID y el PRODUCT_ID de los pasos anteriores.

curl -X POST https://api.yo-facturo.com/api/v1/sales/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "items": [
      {
        "publication_id": "PRODUCT_ID",
        "publication_type": "product",
        "quantity": 1,
        "price": 1500
      }
    ]
  }'

# Respuesta: { "success": true, "data": { "_id": "SALE_ID", ... } }

4. Emitir la factura electrónica

Con el SALE_ID se emite el comprobante electrónico ante AFIP.

curl -X POST https://api.yo-facturo.com/api/v1/bill/receipts/invoice/ \
  -H "X-API-Key: TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sale_id": "SALE_ID"}'

# Respuesta: { "success": true, "data": { "_id": "...", "cae": "...", ... } }

El listado exacto de recursos y sus rutas está en la sección Recursos (/dev/resources/).