Referencia de la API

La referencia interactiva lista todas las operaciones de /api/v1.1 con sus parámetros y esquemas. Se genera del openapi.json de la API.

Esta página recoge las convenciones que comparten todas las operaciones.

URL base y autenticación

• URL base: https://app.faxtal.com/api/v1.1.
• Todas las operaciones piden la cabecera X-API-Key, salvo GET /health. Ver Autenticación.
• Las peticiones con cuerpo envían JSON (Content-Type: application/json). Hay dos excepciones: la importación de recibidas en XML (application/xml) y la subida de documentos (multipart/form-data).

Convenciones

• Paginación: limit y offset. La respuesta trae items, total, limit y offset. Máximos y ejemplos en Conceptos.
• Fechas: YYYY-MM-DD. Las marcas de tiempo (created_at, updated_at) van en ISO 8601.
• Importes: números JSON con decimales, por ejemplo 1210.0.
• Moneda: código ISO 4217, en currency de la respuesta y en issue_data.tax_currency_code del canónico.
• Identificadores: id es opaco. Guárdalo tal como llega.
• Estados: status usa valores en minúsculas (draft, issued, sent, cancelled, queued, received). Ver Conceptos.
• Descargas: el PDF (application/pdf) y los XML (application/xml) llegan como fichero adjunto, con Content-Disposition: attachment.

Formato de error

Todas las respuestas de error usan el mismo sobre:

{
  "detail": {
    "code": "scope_missing",
    "message": "La credencial no tiene permiso para esta operación.",
    "scope": "invoices:issue",
    "request_id": "4f1c0a9e2b7d4e5f8a6b3c2d1e0f9a8b"
  }
}

• code es estable: decide con él en tu código. message es un texto para personas y puede cambiar.
• request_id identifica la petición y también llega en la cabecera X-Request-Id. Indícalo si contactas con soporte.
• Algunos errores añaden campos propios, como scope, missing o errors.
• Si la petición no cumple el esquema (un parámetro de tipo o rango incorrecto, un JSON mal formado), la API responde 422 con request_validation_error y una lista errors con field, message y type.

La referencia interactiva solo describe las respuestas correctas y un 422 con otro esquema. El sobre real de cualquier error es el de arriba.

Códigos HTTP

Código	Cuándo	code habituales
200	Lectura o acción correcta
201	Alta o actualización correcta (PUT /drafts, PUT /received-invoices, importaciones, documentos)
204	Borrado correcto, sin cuerpo
400	Petición no válida	unknown_status, empty_body
401	Falta la API key o no es válida	unauthorized
402	El plan no incluye la funcionalidad o se ha agotado su cupo	feature_outside_plan, quota_exceeded
403	La clave no tiene el permiso o la IP no está permitida	scope_missing, ip_forbidden
404	El recurso no existe o no es de tu empresa	invoice_not_found, not_found
409	El estado actual no permite la operación	invalid_status_transition, invoice_update_not_allowed, invoice_delete_not_allowed, company_not_verified
413	El contenido enviado es demasiado grande	payload_too_large, file_too_large
415	El tipo de contenido no está admitido	unsupported_media_type
422	Los datos no son válidos	request_validation_error, schema_validation_failed, missing_required_fields, validation_failed
429	Límite de peticiones superado	rate_limited
500	Error inesperado	internal_server_error
502	Un servicio externo no responde	external_service_error
503	El servicio no está disponible	service_unavailable, db_unavailable

Qué hacer con cada código está en Errores.

Ver también

• Referencia interactiva
• Autenticación
• Conceptos
• Versionado