# Meta (/docs/referencia/meta) Base: `https://api.facturia.cl/v1`. Todos los endpoints de este capítulo se autentican con `Authorization: Bearer` salvo que se diga lo contrario, y el sobre de error es el de [Errores](/docs/errores). | Método | Ruta | Qué hace | | ------ | -------------------------------------- | -------------------------------------------------------------------------------------------------- | | `GET` | [`/jobs/{job_id}`](#get-jobs-job-id) | Devuelve un job asíncrono (solicitud de folios, envío, cesión, sincronización de RCV, importación) | | `GET` | [`/mandato_terms`](#get-mandato-terms) | El texto y la versión vigente del mandato | | `GET` | [`/error_codes`](#get-error-codes) | El diccionario de errores legible por máquina (sin autenticación) | ## `GET /jobs/{job_id}` [#get-jobs-job-id] **Devuelve un job asíncrono (solicitud de folios, envío, cesión, sincronización de RCV, importación)** Un solo endpoint para toda operación asíncrona que arranca la API. Lee `type` primero: decide la forma de `result` y qué scope puede leer el job (el scope que INICIA ese tipo de job, más el scope de lectura del sujeto sobre el que actúa — una llave con `documents:read` puede mirar un envío, y se le niega una declaración tributaria). `Facturia-Poll-After` dice cuándo volver a preguntar, en segundos, y está AUSENTE una vez que `status` es `succeeded` o `failed`: ya no queda nada que observar. No consultes más rápido de lo que dice — nada de esta superficie puede terminar dentro del intervalo de 10 segundos con que la cola toma un job. `mode` viene en el objeto, y un job creado en el otro modo no existe para esta credencial: la respuesta es `404`, no `403` (§4.2). ```bash curl -sS https://api.facturia.cl/v1/jobs/job_01K2R8B4V6WQ2X ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | --------- | ---- | --------- | ------ | ----- | | `job_id` | path | sí | string | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | El job. | Job | | `400` | Código `empresa_header_forbidden` — esta operación es de nivel cuenta (un job pertenece a la cuenta de la llave, no a una empresa); un header `Facturia-Empresa` en ella se rechaza. | ErrorResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `404` | No existe ese objeto bajo esta llave. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /mandato_terms` [#get-mandato-terms] **El texto y la versión vigente del mandato** El texto que el §7.3 te dice que presentes antes de postear una aceptación. Sin autenticación, por la misma razón que `GET /error_codes`: el cuerpo es una constante sin datos de ningún cliente. LEE `status` PRIMERO. `draft` significa que el texto no ha terminado la revisión legal y todavía no obliga — no se lo presentes a un representante legal como los términos que está firmando. Se deriva del propio banner de revisión del documento, así que pasa a `active` el día en que la revisión termina y no el día en que alguien se acuerda de cambiar una constante. Este endpoint entrega solo las palabras. Registrar una aceptación es `POST /empresas/\{empresa_id\}/mandato`. `annexes[]` trae los documentos que el propio encabezado del contrato llama «parte integrante» —precios, datos personales, matriz de automatización— con su Markdown, porque una página que le pide a alguien que acepte un contrato tiene que poder mostrárselo entero (ticket #519). `content_hash` sigue cubriendo solo `text`: esos son los bytes que registra una aceptación. `?version=` pide una versión específica. Omítelo para el texto vigente — a quien se le olvide el parámetro nunca se le puede entregar un borrador. Úsalo para leer el borrador de lo que viene antes de que obligue a nadie, y para pedir la versión exacta que registró una aceptación antigua (el `terms_url` del recibo del mandato hace justamente eso). Un valor desconocido es `400 invalid_field`. ```bash curl -sS https://api.facturia.cl/v1/mandato_terms ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | --------- | ----- | --------- | ------ | ------------------------------------------------------------------- | | `version` | query | — | string | Una versión de `available_versions`. Si se omite, el texto vigente. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | El texto del mandato. | object | | `400` | Entrada mal formada o incompleta. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /error_codes` [#get-error-codes] **El diccionario de errores legible por máquina (sin autenticación)** Todos los códigos que esta API puede poner en un `error.code`, más los códigos de rechazo del SII que aparecen dentro de `rejection_reasons[]` de un documento. Se distinguen por `type`: una fila `rejection` no es una respuesta y lleva `http_status: null`. `retriable` responde sobre la solicitud IDÉNTICA: `rate_limit_exceeded` es reintentable porque esperar lo arregla, `totals_mismatch` no. Construye tu política de reintentos sobre ese campo, no sobre el código HTTP. Sin credencial y sin límite de tasa: el cuerpo es una constante y no lleva datos de ningún cliente. ```bash curl -sS https://api.facturia.cl/v1/error_codes ``` **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `200` | Todos los códigos de error de Facturia, su contraparte del SII y si conviene reintentar. | lista de ErrorCode | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse |