REST API

DTEM API

Integra DTEM usando una simple y poderosa API.

API Docs Permite Automatizar los procesos de Factura Electr贸nica con una simple y poderosa API. La API a utilizar es de tipo REST.

En esta documentaci贸n se asume el conocimiento previo de los conceptos de la arquitectura REST.

API resources disponibles

Para ver una Lista de los recursos disponibles de la API se debe ver API resources.

Uso B谩sico

Las llamadas a la API deben tener el prefijo del contexto (Nombre app) correspondientes a emisi贸n o recepci贸n de DTE. Por ejemplo

/dtem/emision/Documento/

Ejemplo de una llamada v谩lida utilizando con URL:

curl "https://www.example.com/dtem/emision/Documento"

La API usa JSON para serializar los datos. Es importante mencionar que No es necesario especificar .json al final de una URL API.

Autenticaci贸n

La mayor铆a de las APIS requieren autentificaci贸n, o s贸lo retornar谩n datos publicos cuando no se provea autentificaci贸n.

Para aquellos casos donde no es requerida la autenticaci贸n, ser谩 mensionado en la documentaci贸n. para cada endpoint. Por ejemplo:

Formas de autentificaci贸n

  • OAuth2 tokens
  • Personal access tokens
  • Session cookie

Si la informaci贸n de autenticaci贸n no es v谩lida o se omite, aparecer谩 un mensaje de error devuelto con el c贸digo de estado 401:

{
  "message": "401 Unauthorized"
}

Ejemplo de uso del token OAuth2 en un encabezado:

curl --header "Authorization: Bearer OAUTH-TOKEN" https://www.example.com/dtem/emision/Documento

Personal access tokens

Puede usar un token de acceso personal para autenticarse con la API pas谩ndolo en el par谩metro private_token o el encabezado Private-Token.

When signing in to the main GitLab application, a _gitlab_session cookie is set. The API will use this cookie for authentication if it is present, but using the API to generate a new session cookie is currently not supported. The primary user of this authentication method is the web frontend of GitLab itself, which can use the API as the authenticated user to get a list of their projects, for example, without needing to explicitly pass an access token.

You can also use personal access tokens with OAuth-compliant headers:

curl --header "Authorization: Bearer <your_access_token>" https://www.example.com/dtem/emision/Documento

C贸digos de estado

La API est谩 dise帽ada para devolver diferentes c贸digos de estado seg煤n el contexto y acci贸n. De esta forma, si una solicitud produce un error, la persona que llama puede obtener comprensi贸n de lo que sali贸 mal.

La siguiente tabla ofrece una descripci贸n general del comportamiento general de las funciones de la API.

Metodos Descripci贸n
GET Accesa uno o mas recursos y retorna el resultado como JSON.
POST Retorna 201 Created Si el recurso es creado correctamente, y devuelve el recurso reci茅n creado como JSON.
GET / PUT Retorna 200 OK Si se accede al recurso o si se modifica con 茅xito. El resultado (modificado) se devuelve como JSON.
DELETE Retorna 204 No Content Si el recurso se elimin贸 correctamente.

La siguiente tabla muestra los posibles c贸digos de retorno para solicitudes a la API.

Valores Retornados Descripci贸n
200 OK Cuando las solicitudes GET o PUT fueron exitosas, y los recursos en s铆 mismos se devuelven como JSON.
204 No Content Como el caso de DELETE u otros, cuando el servidor ha cumplido con 茅xito la solicitud y no hay contenido adicional para enviar en el cuerpo de la carga 煤til de respuesta.
201 Created Cuando la solicitud POST se realiz贸 correctamente, y el recurso creado se devuelve como JSON.
304 Not Modified Indica que el recurso no se ha modificado desde la 煤ltima solicitud.
400 Bad Request Cuando falta un atributo requerido de la solicitud de API, por ejemplo, no se envia tipo del documento a crear.
401 Unauthorized Cuando el usuario no est谩 autenticado, se necesita un token de usuario v谩lido.
403 Forbidden Cuando la solicitud no est谩 permitida, por ejemplo, el usuario no puede eliminar un documento ya enviado al SII.
404 Not Found Cuando No se pudo acceder a un recurso, por ejemplo, no se pudo encontrar un documento a modificar.
405 Method Not Allowed Metodo o Solicutud no soportada. Cuando se trata de usar un metodo no definido para la API.
409 Conflict Existe un recurso en conflicto, por ejemplo, crear un documento con que ya existe
412 Indica que la solicitud fue denegada. Puede suceder si se proporciona el encabezado para modificar, al intentar eliminar un recurso, que se esta modificando en el medio.
422 Unprocessable La entidad no pudo ser procesada.
500 Server Error Al manejar la solicitud, algo sali贸 mal en el lado del servidor.

Validaci贸n de datos e informes de errores.

Al trabajar con la API, puede encontrar errores de validaci贸n, en cuyo caso la API responder谩 con un estado HTTP 400. Tales errores aparecen en dos casos:

  • Falta un atributo requerido de la solicitud de API, por ejemplo, no se envia el rut del receptor del documento.
  • Y cuando un atributo no pas贸 la validaci贸n, por ejemplo, la raz贸n social del receptor es demasiado larga.

Cuando falta un atributo requerido, obtendr谩 algo como:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message":"400 (Bad request) \"title\" not given"
}

Cuando se produce un error de validaci贸n, los mensajes de error ser谩n diferentes. Ellos traer谩n los detalles de los errores de validaci贸n:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
     "message": {
         "razonrecep": [
             "is too long (maximum is 255 characters)"
         ]
     }
 }