Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yofacturo.es/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

All API endpoints are relative to: 
https://app.yofacturo.es
The staging environment is available at https://staging.app.yofacturo.es. Use it for integration testing before going live.

​
Versioning

The current stable version is v1. All v1 endpoints are prefixed with /api/v1/. There are no version negotiation headers — the version is part of the URL path.

​
Request format

  • Content type: application/json
  • Encoding: UTF-8
  • All timestamps must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
  • Dates (without time) must be YYYY-MM-DD

​
Response format

All responses return JSON. Successful responses that return a single resource use a data envelope: 
{
  "data": {
    "id": 123,
    "status": "received",
    ...
  }
}
List responses include a meta object with pagination info: 
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 87,
    "per_page": 25
  }
}
The POST /api/v1/invoice_batches endpoint may additionally include an errors key alongside data when some invoices in the batch fail validation (partial success): 
{
  "data": { ... },
  "errors": {
    "inv-bad-001": ["Issued on cannot be blank", "Invoice number cannot be blank"]
  }
}
The errors object is keyed by external_invoice_id.

​
Pagination

List endpoints accept two query parameters:
ParameterTypeDefaultMaxDescription
pageinteger1—Page number (1-indexed)
per_pageinteger25100Results per page

​
Idempotency

POST /api/v1/invoice_batches requires an Idempotency-Key header containing a valid UUID v4. Resubmitting the same key within the idempotency window returns the cached response without re-processing the batch. 
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

​
Rate limiting

Protected endpoints enforce rate limits per organization. When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait. 
HTTP/1.1 429 Too Many Requests
Retry-After: 30

​
Error responses

All errors follow a consistent envelope: 
{
  "error": {
    "code": "string",
    "message": "Human-readable description"
  }
}

​
Error codes

HTTP statusCodeDescription
400bad_requestMissing or invalid required parameter
401unauthorizedMissing, invalid, or expired authentication
404not_foundResource not found within the current organization
422missing_idempotency_keyIdempotency-Key header is absent
422invalid_idempotency_keyIdempotency-Key is not a valid UUID
422validation_failedRequest body failed validation (see message for details)
429rate_limit_exceededToo many requests — check Retry-After header