API Documentos Contables

Descripción: Esta API permite la sincronizacion de documentos contables entre SERPI y la plataforma que lo requiera permitiendo tener un manejo estandar entre las dos herramientas.

Autorización: Se requiere autenticación para todas las solicitudes. Las credenciales de autenticación deben ser incluidas en la cabecera de todas las solicitudes a través del campo Authorization utilizando el token de acceso entregado SERPI ERP.

Beneficio:

Tipos de peticiones: GET, POST, PUT

¿Cómo funciona?

• Tenga en cuenta que un mismo token no puede ser consumidos de manera simultanea, por lo cual puede programar que la siguiente API sea consumida cuando el resultado de la anterior sea exitoso.
• En términos de tiempo, para hacer seguimiento a su operación puede hacer un consumo cada 5 minutos de la información.

Métodos

<Tabs> <Tab name = "API Consulta Tipos de Documento"> GET/users

EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable/GetTipoDocumento

Headers

Header	Descripción
secretkey	Secretkey proporcionada al cliente para consumos de las APIs

Authorization:

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Parámetros

Parámetro	Tipo de dato	Requerido	Descripción
Límite	int	No	Este parámetro indica la cantidad de resultados que se deben devolver en una sola página
Página	int	No	Este parámetro indica el número de la página que se debe devolver. Por ejemplo, si se establece en 3, se devolverán los resultados de la tercera página

Response

{
    "success": true,
    "code": 200,
    "errors": null,
    "message": "2 registro(s) encontrados",
    "result": [
        {
            "id": 1,
            "categoriaDocumento": "NC",
            "prefijo": "RCA",
            "descripcion": "RECIBO DE CAJA"
        },
        {
            "id": 2,
            "categoriaDocumento": "NC",
            "prefijo": "NCC",
            "descripcion": "NOTA CONTABLE"
        }
    ]
}

{
    "success": true,
    "code": 204,
    "message": "No se encontraron registros",
}

Campo de resultados

Campo	Tipo de dato	Descripción Campo Tipo de dato Descripción id int Corresponde al identificador del tipo de documento categoriaDocumento string Categoría del tipo de documento prefijo string Prefijo del tipo de documento descripcion string Descripción del tipo de documento </Tab> <Tab name = "API Consultar Documentos Contables"> POST /users EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable/ConsultarDocumentoContables?limite=10&pagina=1 Headers Header Descripción secretkey Secretkey proporcionada al cliente para consumos de las APIs Body: { "tiposDocumentos": [15,16], "numeroDesde": null, "numeroHasta": null, "fechaDesde": "2023-01-01", "fechaHasta": "2023-01-31" } Campos del request Campo Tipo Requerido Descripción tiposDocumentos Array [Int] SI Array de enteros. Son los Ids de los tipos de documentos (Api Consulta tipos documento) numeroDesde int NO Numero inicial para filtrar por rango de números de documentos numeroHasta int NO Numero final para filtrar por rango de números de documentos fechaDesde string SI Fecha inicial para filtrar por rango de fecha del documento fechaHasta bool SI Fecha final para filtrar por rango de fecha del documento Authorization: Usar Bearer. Ejemplo “bearer {{token}}”. {{token}} Token de autorizacion generado por SerpiERP Response { "success": true, "code": 200, "errors": null, "message": "1 registro(s) encontrados", "result": [ { "id": 111, "categoriaDocumento": "CCO", "prefijo": "COM", "numeroDoc": 1, "nitTerceroEnc": "1234567890", "nombreTerceroEnc": "ALEJANDRA LOPEZ LOPEZ", "fechaDocumento": "2023-03-01", "detalles": [ { "cuenta": 52954501, "nitTerceroDet": "1234567890", "nombreTerceroDet": "ALEJANDRA LOPEZ LOPEZ", "naturaleza": "D", "crucePrefijo": null, "cruceNumero": null, "fechaVencimiento": null, "valor": 67900.00000, "baseImpuesto": 0.00000, "cuota": 0, "detalle": "SERV DE TRANSP INFORMAL", "idCentroCosto": 3, "idSubcentroCosto": 4, "idCentroOperacion": 1, "idProyecto": null, "idActividad": null, "idSucursal": null }, { "cuenta": 23359501, "nitTerceroDet": "1234567890", "nombreTerceroDet": "ALEJANDRA LOPEZ LOPEZ", "naturaleza": "C", "crucePrefijo": "COM", "cruceNumero": 3272, "fechaVencimiento": null, "valor": 67900.00000, "baseImpuesto": 0.00000, "cuota": 0, "detalle": "SERV DE TRANSP INFORMAL", "idCentroCosto": null, "idSubcentroCosto": null, "idCentroOperacion": 1, "idProyecto": null, "idActividad": null, "idSucursal": null } ] } ] } { "success": true, "code": 204, "message": "No se encontraron registros", } Campos del resultado Campo Tipo de Dato Descripción id int Corresponde al id del registro contable categoriaDocumento string Categoría del tipo de documento prefijo string Prefijo del tipo de documento numeroDoc Int Numero del documento contable nitTerceroEnc string Numero de identificación del tercero del documento contable nombreTerceroEnc string Nombre del tercero del documento contable fechaDocumento string Fecha del documento contable detalles Array[ObjetoDetalle]* Array de objetos de los detalles del documento contable ObjetoDetalle: Campo Tipo de Dato Descripción cuenta Int Auxiliar o numero de cuenta contable del movimiento nitTerceroDet string Numero de identificación del tercero del detalle nombreTerceroDet string Nombre del tercero del detalle naturaleza string Naturaleza del movimiento (C=Credito, D=Debito) crucePrefijo string Prefijo del documento cruce cruceNumero Int Numero del documento cruce fechaVencimiento string Fecha de vencimiento del movimiento valor decimal Valor del movimiento baseImpuesto decimal Valor base de impuesto cuota Int Numero de cuota, para documentos que manejan contabilización de cuotas detalle string Comentarios del movimiento idCentroCosto Int Id del centro de costo del movimiento idSubcentroCosto Int Id del subcentro de costo del movimiento idCentroOperacion Int Id del centro de operacion del movimiento idProyecto Int Id del proyecto del movimiento idActividad Int Id de la actividad del movimiento idSucursal Int Id de la sucursal del tercero del movimiento </Tab> <Tab name = "API Crear"> PUT/users EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable Headers Header Descripción secretkey Secretkey proporcionada al cliente para consumos de las APIs Authorization: Usar Bearer. Ejemplo “bearer {{token}}”. {{token}} Token de autorizacion generado por SerpiERP Body: [ { "categoriaDocumento": "CCO", "prefijo": "COM", "numeroDoc": 2, "nitTerceroEnc": "123456789", "fechaDocumento": "2023-03-01", "detalles": [ { "cuenta": 52954501, "nitTerceroDet": "123456789", "naturaleza": "D", "crucePrefijo": null, "cruceNumero": null, "fechaVencimiento": null, "valor": 67900.00000, "baseImpuesto": 0.00000, "cuota": 0, "detalle": "SERV DE TRANSP INFORMAL", "idCentroCosto": 3, "idSubcentroCosto": 4, "idCentroOperacion": 1, "idProyecto": null, "idActividad": null, "idSucursal": null }, { "cuenta": 23359501, "nitTerceroDet": "123456789", "naturaleza": "C", "crucePrefijo": "COM", "cruceNumero": 1, "fechaVencimiento": null, "valor": 67900.00000, "baseImpuesto": 0.00000, "cuota": 0, "detalle": "SERV DE TRANSP INFORMAL", "idCentroCosto": null, "idSubcentroCosto": null, "idCentroOperacion": 1, "idProyecto": null, "idActividad": null, "idSucursal": null } ] } ] Campos resultado Campo Tipo Requerido Descripción categoriaDocumento string SI Categoría del tipo de documento prefijo string SI Prefijo del tipo de documento numeroDoc Int SI Numero del documento contable nitTerceroEnc string SI Numero de identificación del tercero del documento contable fechaDocumento string SI Fecha del documento contable detalles Array[ObjetoDetalle]* SI Array de objetos de los detalles del documento contable ObjetoDetalle: Campo Tipo Requerido Descripción cuenta Int SI Auxiliar o numero de cuenta contable del movimiento nitTerceroDet string SI Numero de identificación del tercero del detalle naturaleza string SI Naturaleza del movimiento (C=Credito, D=Debito) crucePrefijo string NO Prefijo del documento cruce cruceNumero Int NO Numero del documento cruce fechaVencimiento string NO Fecha de vencimiento del movimiento valor decimal SI Valor del movimiento baseImpuesto decimal NO Valor base de impuesto cuota Int NO Numero de cuota, para documentos que manejan contabilización de cuotas detalle string NO Comentarios del movimiento idCentroCosto Int NO Id del centro de costo del movimiento idSubcentroCosto Int NO Id del subcentro de costo del movimiento idCentroOperacion Int NO Id del centro de operacion del movimiento idProyecto Int NO Id del proyecto del movimiento idActividad Int NO Id de la actividad del movimiento idSucursal Int NO Id de la sucursal del tercero del movimiento Authorization: Usar Bearer. Ejemplo “bearer {{token}}”. {{token}} Token de autorizacion generado por SerpiERP Response { "success": true, "code": 201, "errors": [], "message": "Se crearon 10 de 10 documentos contables" } </Tab> 77777777777 <Tab name = "API Eliminar"> PUT/users EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable Headers Header Descripción secretkey Secretkey proporcionada al cliente para consumos de las APIs Authorization: Usar Bearer. Ejemplo “bearer {{token}}”. {{token}} Token de autorizacion generado por SerpiERP Body: { "idTipoDocumento": 6, "numeroDesde": 1, "numeroHasta": 10000, "fechaDesde": "2023-03-01", "fechaHasta": "2023-03-31" } Campos Solicitados Campo Tipo Requerido Descripción idTipoDocumento int SI Id del tipo de documento numeroDesde int SI Numero inicial para filtrar por rango de números de documentos numeroHasta int SI Numero final para filtrar por rango de números de documentos fechaDesde string SI Fecha inicial para filtrar por rango de fecha del documento fechaHasta bool SI Fecha final para filtrar por rango de fecha del documento Authorization: Usar Bearer. Ejemplo “bearer {{token}}”. {{token}} Token de autorizacion generado por SerpiERP Response { "success": true, "code": 200, "errors": [], "message": "Se eliminaron 10 de 10 documentos contables " } </Tab> </Tabs> ¿Cómo consumir la API? <Tabs> <Tab name = "Java"> Request OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("text/plain"); RequestBody body = RequestBody.create(mediaType, ""); Request request = new Request.Builder() .url("https:///www.apis.serpi.com.co/api/v1/DocumentoContable") .method("GET", body) .addHeader("secretkey", "{Secret Key}") .addHeader("Authorization", "{Bearer Token}") .build(); Response response = client.newCall(request).execute(); Response { "code": 200, "error": null, "msg": "Information found for the current month", "data": [ { "operation": "", "description": "", "items": "", "date": "" } ] } </Tab> <Tab name = "Python"> Request import requests url = "https://www.apis.serpi.com.co/api/v1/DocumentoContable" payload = {} headers = { 'secretkey': '{Secret Key}', 'Authorization': '{Bearer Token}' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) Response { "code": 200, "error": null, "msg": "Information found for the current month", "data": [ { "operation": "", "description": "", "items": "", "date": "" } ] } </Tab> <Tab name = "Php"> Request <?php require_once 'HTTP/Request2.php'; $request = new HTTP_Request2(); $request->setUrl('https://www.apis.serpi.com.co/api/v1/DocumentoContable'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'secretkey' => '{Secret Key}', 'Authorization' => '{Bearer Token}' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } Response { "code": 200, "error": null, "msg": "Information found for the current month", "data": [ { "operation": "", "description": "", "items": "", "date": "" } ] } </Tab> </Tabs> Códigos de estado HTTP Código Descripción 200 La solicitud ha sido exitosa 201 La solicitud ha tenido éxito y ha llevado a la creación de un recurso 204 La solicitud se ha completado correctamente, pero no hay contenido para devolver en la respuesta 400 El servidor no puede o no procesará la petición debido a algo que es percibido como un error del cliente 401 La solicitud requiere autenticación, pero el cliente no ha proporcionado credenciales válidas o no está autorizado para acceder al recurso 403 El servidor ha entendido la solicitud, pero se niega a cumplirla debido a que el cliente no tiene permisos para acceder al recurso 404 El recurso solicitado no se ha encontrado en el servidor 500 Internal Server Error 503 El servidor no está disponible actualmente debido a una sobrecarga o mantenimiento temporal